861 lines
36 KiB
TypeScript
861 lines
36 KiB
TypeScript
// SessionManager: the instance cluster Map<SessionId, Session> (lazy-built, resident) + the frame
|
|
// dispatch entry + list state, constructed and held by ClientSessions (one per browser client).
|
|
// List data never enters zustand; React connects via subscribe/getListSnapshot.
|
|
|
|
import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client'
|
|
import { SessionSeq, type SessionId, type SessionSeqCursor } from '@deepseek-ai/dsh-session/types'
|
|
import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
|
|
import type {
|
|
SessionControlBaseline,
|
|
SessionControlFrame,
|
|
SessionSummary,
|
|
SessionJob as JobView,
|
|
} from '../../types.ts'
|
|
import { mergeOrderedBaseline } from '../ordered-baseline.ts'
|
|
import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
|
|
import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
|
|
import type { SessionListEntry, TitledSessionSummary } from './lineage.ts'
|
|
import { flattenLineage } from './lineage.ts'
|
|
// Type-only merge edge: the title domain's client-namespace outlet declares
|
|
// the 'title' projection key this manager projects into list rows (and any
|
|
// useProjection('title') consumer reads). Zero value imports by construction.
|
|
import type {} from '@deepseek-ai/dsh-session-title/client'
|
|
import { Notifier } from './notifier.ts'
|
|
import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
|
|
import { ProjectionValueStore } from './projection-store.ts'
|
|
import { Session } from './session.ts'
|
|
import type { SessionRemotes } from './remotes.ts'
|
|
|
|
function sessionSeqCursor(value: number): SessionSeqCursor {
|
|
return value === -1 ? -1 : SessionSeq(value)
|
|
}
|
|
|
|
/**
|
|
* List arrival lifecycle, orthogonal to the pull-activity `state` axis:
|
|
* `pending` (no successful pull yet — an empty items array means "nothing
|
|
* arrived", not "nothing exists") → `ready` (at least one pull landed).
|
|
* Monotone: `ready` never steps back — later pull failures and reconnect
|
|
* re-pulls ride the `state`/`error` axis, which is where failure is modeled
|
|
* (no `error` phase here; that would duplicate `state`).
|
|
*/
|
|
export type SessionListPhase = 'pending' | 'ready'
|
|
|
|
/** Request-local content hit returned to sidebar search consumers. */
|
|
export interface SessionSearchResultItem {
|
|
sessionId: SessionId
|
|
snippet: string
|
|
}
|
|
|
|
/** Immutable session-list snapshot for useSessionList. */
|
|
export interface SessionListSnapshot {
|
|
items: readonly SessionListEntry[]
|
|
/** Selected Session id (validated against items; masked to undefined while its session is off the list). */
|
|
current: SessionId | undefined
|
|
state: 'idle' | 'loading' | 'error'
|
|
/** Arrival lifecycle (see {@link SessionListPhase}); `state` stays the pull-activity axis. */
|
|
phase: SessionListPhase
|
|
error: RemoteFailure | null
|
|
projectionsBySession: Readonly<Record<SessionId, SessionProjectionSnapshot>>
|
|
/** Background jobs per session; an absent key is an empty set. */
|
|
jobsBySession: Readonly<Record<SessionId, readonly JobView[]>>
|
|
currentAddress: SubagentAddress | undefined
|
|
}
|
|
|
|
/** Shared projection values and the lifecycle of their explicit baseline read. */
|
|
export interface SessionProjectionSnapshot {
|
|
readonly values: Readonly<Partial<SessionProjectionMap>>
|
|
readonly state: 'idle' | 'loading' | 'ready' | 'error'
|
|
readonly error: RemoteFailure | null
|
|
}
|
|
|
|
interface ProjectionInflight {
|
|
readonly promise: Promise<void>
|
|
readonly controller: AbortController
|
|
}
|
|
|
|
type ProjectionLoad = Omit<SessionProjectionSnapshot, 'values'>
|
|
|
|
type SessionListMutation =
|
|
| { kind: 'upsert' | 'placeholder'; summary: SessionSummary }
|
|
| { kind: 'remove'; sessionId: SessionId }
|
|
| { kind: 'status'; sessionId: SessionId; running: boolean; agentAvailable: boolean }
|
|
| { kind: 'activity'; sessionId: SessionId; updatedAt: number }
|
|
/** Local first-send flip: the sender clears blank without waiting for a host frame. */
|
|
| { kind: 'engaged'; sessionId: SessionId }
|
|
|
|
/** Instance cluster + frame entry + the session list. */
|
|
export class SessionManager {
|
|
private readonly sessions = new Map<SessionId, Session>()
|
|
/** In-flight Session disposals remain here after instances leave `sessions`, so manager disposal can await quiescence. */
|
|
private readonly sessionDisposals = new Set<Promise<void>>()
|
|
/**
|
|
* Sessions that finished running while not selected — the sidebar's green
|
|
* "done" reminder (manager-owned, survives connection generations; cleared
|
|
* on select and session-removed, re-armed by the next completion).
|
|
*/
|
|
private readonly completedNotifications = new Set<SessionId>()
|
|
/** Last-observed running bits per session; the true→false edge here arms {@link completedNotifications}. */
|
|
private readonly prevRunning = new Map<SessionId, boolean>()
|
|
/** Per-session projection value stores, retained independently of instance arrival (the
|
|
* title-snapshot precedent, generalized): push frames land here whether or not the Session
|
|
* is instantiated (list rows read the 'title' key), and an instantiated Session adopts the
|
|
* same store so history-baseline seeding and frames converge on one row set. */
|
|
private readonly projectionStores = new Map<SessionId, ProjectionValueStore>()
|
|
private summaries: SessionSummary[] = []
|
|
private listState: 'idle' | 'loading' | 'error' = 'idle'
|
|
/** Arrival phase; the pending → ready edge fires on the first successful pull (see SessionListPhase). */
|
|
private listPhase: SessionListPhase = 'pending'
|
|
private listError: RemoteFailure | null = null
|
|
private listInflight: Promise<void> | null = null
|
|
/** Active list request's mutation log; its identity also fences completion after reconnect. */
|
|
private listMutations: SessionListMutation[] | null = null
|
|
private readonly addresses = new Map<SessionId, SubagentAddress>()
|
|
private readonly projectionLoads = new Map<SessionId, ProjectionLoad>()
|
|
private readonly projectionInflight = new Map<SessionId, ProjectionInflight>()
|
|
/**
|
|
* Background jobs per session, last-wins from Session Controller's control
|
|
* stream. An empty set is stored as an absent key, so absence and `[]` are
|
|
* one representation.
|
|
*/
|
|
private readonly jobsBySession = new Map<SessionId, readonly JobView[]>()
|
|
|
|
private selected: SessionId | undefined
|
|
|
|
private listSnapshotCache: SessionListSnapshot
|
|
/** Entry-identity cache (reference stability): list rebuilds reuse the previous entry
|
|
* object when every field matches — wire refreshes mint all-new summary objects, so identity
|
|
* must be recovered by value or every SessionListItem memo misses on every refresh. */
|
|
private entryCache = new Map<SessionId, SessionListEntry>()
|
|
private itemsCache: readonly SessionListEntry[] = []
|
|
private readonly notifier = new Notifier(() => {
|
|
this.listSnapshotCache = this.buildListSnapshot()
|
|
})
|
|
|
|
/**
|
|
* @param remote - generated Remote namespaces the Session cluster calls.
|
|
* @param restoredSelection - persisted real-Session selection candidate.
|
|
*/
|
|
constructor(
|
|
private readonly remote: SessionRemotes,
|
|
restoredSelection?: SessionId,
|
|
restoredAddress?: SubagentAddress,
|
|
) {
|
|
this.selected = restoredSelection
|
|
if (restoredAddress !== undefined) this.addresses.set(restoredAddress.childSessionId, restoredAddress)
|
|
this.listSnapshotCache = this.buildListSnapshot()
|
|
}
|
|
|
|
// ---- Selection ----
|
|
|
|
/**
|
|
* Select a listed Session or a retained catalog-addressed child.
|
|
* @param sessionId - listed or catalog-addressed Session id.
|
|
*/
|
|
select(sessionId: SessionId): void {
|
|
const address = this.subagentAddress(sessionId)
|
|
if (!this.summaries.some(summary => summary.sessionId === sessionId) && address === undefined) {
|
|
throw new Error(`sessions.select: unknown session ${sessionId}`)
|
|
}
|
|
if (address !== undefined) this.addresses.set(sessionId, address)
|
|
this.sessions.get(sessionId)?.configureSubagent(
|
|
address,
|
|
address === undefined
|
|
? undefined
|
|
: this.agentAvailable(address.parentSessionId),
|
|
)
|
|
this.selected = sessionId
|
|
// Looking at the session consumes its completion reminder (dot clears).
|
|
this.completedNotifications.delete(sessionId)
|
|
this.notifier.notifyNow()
|
|
}
|
|
|
|
/**
|
|
* Select a healthy child through its durable direct-parent address.
|
|
* @param address - catalog-derived parent and child ids.
|
|
*/
|
|
selectSubagent(address: SubagentAddress): void {
|
|
const entries = this.projectionStores.get(address.parentSessionId)?.values().subagentCatalog
|
|
const entry = entries?.find(candidate => candidate.id === address.childSessionId)
|
|
if (entry === undefined
|
|
|| entry.mode !== address.mode) {
|
|
throw new Error(`sessions.selectSubagent: ${address.childSessionId} is not a healthy catalog child`)
|
|
}
|
|
this.addresses.set(address.childSessionId, address)
|
|
this.sessions.get(address.childSessionId)?.configureSubagent(address, this.agentAvailable(address.parentSessionId))
|
|
this.selected = address.childSessionId
|
|
this.completedNotifications.delete(address.childSessionId)
|
|
this.notifier.notifyNow()
|
|
}
|
|
|
|
/** Clear the selection (the layout falls to the no-session view state). */
|
|
clearSelection(): void {
|
|
this.selected = undefined
|
|
this.notifier.notifyNow()
|
|
}
|
|
|
|
/**
|
|
* Resolve an address for breadcrumb navigation without retaining transport authority.
|
|
* @param sessionId - possible child id in an already-loaded catalog.
|
|
* @returns A retained or catalog-derived direct-parent address.
|
|
*/
|
|
subagentAddress(sessionId: SessionId): SubagentAddress | undefined {
|
|
const retained = this.addresses.get(sessionId)
|
|
if (retained !== undefined) return retained
|
|
for (const parentSessionId of this.projectionStores.keys()) {
|
|
const child = this.projectionStores.get(parentSessionId)?.values().subagentCatalog
|
|
?.find(entry => entry.id === sessionId)
|
|
if (child !== undefined) {
|
|
return {
|
|
parentSessionId,
|
|
childSessionId: sessionId,
|
|
mode: child.mode,
|
|
}
|
|
}
|
|
}
|
|
return undefined
|
|
}
|
|
|
|
// ---- Instance management ----
|
|
|
|
/**
|
|
* Drop a session instance (scope-prune companion: instance
|
|
* and scope share one lifecycle). The host session log is the durable
|
|
* truth — a later get() lazily rebuilds and open() backfills history.
|
|
* @param sessionId - the session to drop.
|
|
*/
|
|
async drop(sessionId: SessionId): Promise<void> {
|
|
const session = this.sessions.get(sessionId)
|
|
this.sessions.delete(sessionId)
|
|
if (session !== undefined) await this.startSessionDisposal(session)
|
|
}
|
|
|
|
/**
|
|
* Stop owned timers and every remaining Session instance.
|
|
* @returns when every Session Remote iterator has completed teardown.
|
|
*/
|
|
async dispose(): Promise<void> {
|
|
const reads = [...this.projectionInflight.values()]
|
|
for (const { controller } of reads) controller.abort()
|
|
this.projectionInflight.clear()
|
|
await Promise.all(reads.map(read => read.promise))
|
|
const sessions = [...this.sessions.values()]
|
|
this.sessions.clear()
|
|
for (const session of sessions) void this.startSessionDisposal(session)
|
|
await this.drainSessionDisposals()
|
|
}
|
|
|
|
private startSessionDisposal(session: Session): Promise<void> {
|
|
const disposal = session.dispose()
|
|
this.sessionDisposals.add(disposal)
|
|
void disposal.then(
|
|
() => { this.sessionDisposals.delete(disposal) },
|
|
() => { this.sessionDisposals.delete(disposal) },
|
|
)
|
|
return disposal
|
|
}
|
|
|
|
private async drainSessionDisposals(): Promise<void> {
|
|
while (this.sessionDisposals.size > 0) {
|
|
await Promise.allSettled([...this.sessionDisposals])
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Lazy build: return the existing instance or construct one (no auto-open —
|
|
* open is triggered by the container's select callback).
|
|
* @param sessionId - the session to get.
|
|
* @returns the resident instance.
|
|
*/
|
|
get(sessionId: SessionId): Session {
|
|
let session = this.sessions.get(sessionId)
|
|
if (session === undefined) {
|
|
session = this.createSession(sessionId)
|
|
this.sessions.set(sessionId, session)
|
|
// Sync the running and blank bits from the list snapshot into the new
|
|
// instance (consistency when the list precedes open).
|
|
const summary = this.summaries.find(s => s.sessionId === sessionId)
|
|
if (summary !== undefined) {
|
|
session.handleBlank(summary.blank)
|
|
session.handleRunning(summary.running)
|
|
} else {
|
|
const address = this.addresses.get(sessionId)
|
|
const child = address === undefined ? undefined : this.projectionStores.get(address.parentSessionId)?.values().subagentCatalog
|
|
?.find(entry => entry.id === sessionId)
|
|
if (child !== undefined) {
|
|
// A catalogued child exists only after its delegated session has
|
|
// durable history, even though child rows do not carry `blank`.
|
|
session.handleBlank(false)
|
|
session.handleRunning(false)
|
|
}
|
|
}
|
|
}
|
|
return session
|
|
}
|
|
|
|
private createSession(sessionId: SessionId): Session {
|
|
const address = this.addresses.get(sessionId)
|
|
const parentAvailable = address === undefined
|
|
? undefined
|
|
: this.agentAvailable(address.parentSessionId)
|
|
return new Session(sessionId, this.remote, {
|
|
...(address === undefined ? {} : {
|
|
address,
|
|
...parentAvailable === undefined ? {} : { parentAvailable },
|
|
}),
|
|
// The sender's local first-send flip mirrors into the list row so the
|
|
// session surfaces (lists filter on blank) before any host frame lands.
|
|
onEngaged: (engaged) => {
|
|
this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
|
|
},
|
|
projections: this.projectionStore(sessionId),
|
|
})
|
|
}
|
|
|
|
/** Resident per-session projection store (create-on-demand; outlives instantiation). */
|
|
private projectionStore(sessionId: SessionId): ProjectionValueStore {
|
|
let store = this.projectionStores.get(sessionId)
|
|
if (store === undefined) {
|
|
store = new ProjectionValueStore()
|
|
// List rows project off store keys (title); any-key changes re-enter
|
|
// the manager's own batched rebuild channel.
|
|
store.subscribeAny(() => { this.notifier.markDirty() })
|
|
this.projectionStores.set(sessionId, store)
|
|
}
|
|
return store
|
|
}
|
|
|
|
/**
|
|
* Load a complete projection baseline once per connection; retry unsuccessful reads.
|
|
* @param sessionId - Session to inspect without opening its conversation.
|
|
* @returns completion of the current or newly started read.
|
|
*/
|
|
refreshProjections(sessionId: SessionId): Promise<void> {
|
|
const existing = this.projectionInflight.get(sessionId)
|
|
if (existing !== undefined) return existing.promise
|
|
if (this.projectionLoads.get(sessionId)?.state === 'ready') return Promise.resolve()
|
|
const controller = new AbortController()
|
|
const store = this.projectionStore(sessionId)
|
|
const initialValues = store.values()
|
|
this.projectionLoads.set(sessionId, { state: 'loading', error: null })
|
|
this.notifier.markDirty()
|
|
const operation = (async () => {
|
|
try {
|
|
const result = await this.remote.session.projections({ sessionId }, controller.signal)
|
|
if (controller.signal.aborted) return
|
|
if (result.ok) {
|
|
if (result.value !== null) {
|
|
store.seed({ ...result.value, asOfSeq: sessionSeqCursor(result.value.asOfSeq) })
|
|
} else if (store.values() === initialValues) {
|
|
// A later frame proves existence independently of an earlier missing read.
|
|
store.clear()
|
|
}
|
|
this.projectionLoads.set(sessionId, { state: 'ready', error: null })
|
|
} else {
|
|
this.projectionLoads.set(sessionId, { state: 'error', error: result.error })
|
|
}
|
|
} catch (error: unknown) {
|
|
if (controller.signal.aborted) return
|
|
if (!isRemoteFailure(error)) throw error
|
|
this.projectionLoads.set(sessionId, { state: 'error', error })
|
|
} finally {
|
|
if (!controller.signal.aborted) {
|
|
this.projectionInflight.delete(sessionId)
|
|
this.notifier.markDirty()
|
|
}
|
|
}
|
|
})()
|
|
this.projectionInflight.set(sessionId, { promise: operation, controller })
|
|
return operation
|
|
}
|
|
|
|
private agentAvailable(sessionId: SessionId): boolean | undefined {
|
|
return this.summaries.find(summary => summary.sessionId === sessionId)?.agentAvailable
|
|
?? (this.listPhase === 'ready' ? false : undefined)
|
|
}
|
|
|
|
private updateParentAvailability(): void {
|
|
for (const [childId, address] of this.addresses) {
|
|
const available = this.agentAvailable(address.parentSessionId)
|
|
if (available !== undefined) this.sessions.get(childId)?.handleSubagentParentAvailable(available)
|
|
}
|
|
}
|
|
|
|
// ---- List API ----
|
|
|
|
/** Full refresh via session.list (single-flight within one Host generation). */
|
|
refreshList(): Promise<void> {
|
|
if (this.listInflight !== null) return this.listInflight
|
|
this.listState = 'loading'
|
|
this.listError = null
|
|
const established = this.summaries
|
|
const mutations: SessionListMutation[] = []
|
|
this.listMutations = mutations
|
|
this.notifier.markDirty()
|
|
this.listInflight = (async () => {
|
|
try {
|
|
const result = await this.remote.session.list({})
|
|
if (this.listMutations !== mutations) return
|
|
if (result.ok) {
|
|
const baseline: SessionSummary[] = this.listPhase === 'pending'
|
|
? [...result.value.items]
|
|
: mergeOrderedBaseline(established, result.value.items, summary => summary.sessionId)
|
|
// Seed first observations from the pull-time baseline BEFORE replaying
|
|
// in-flight mutations, then reconcile the reminders after EVERY
|
|
// replayed mutation: an edge that happens entirely between mutations
|
|
// (baseline idle → running → idle) must still arm, which a single
|
|
// sync on the folded result would collapse away.
|
|
for (const s of baseline) {
|
|
if (!this.prevRunning.has(s.sessionId)) this.prevRunning.set(s.sessionId, s.running)
|
|
}
|
|
let summaries = baseline
|
|
for (const mutation of mutations) {
|
|
summaries = applyMutation(summaries, mutation)
|
|
this.summaries = summaries
|
|
this.syncCompletedNotifications()
|
|
}
|
|
this.summaries = summaries
|
|
this.listState = 'idle'
|
|
this.listPhase = 'ready'
|
|
this.updateParentAvailability()
|
|
// Covers the empty-mutations pull (a plain baseline carries no edge).
|
|
this.syncCompletedNotifications()
|
|
// Push running/blank bits down to instantiated Sessions (the list is the authoritative summary source).
|
|
for (const s of this.summaries) {
|
|
const session = this.sessions.get(s.sessionId)
|
|
if (session === undefined) continue
|
|
session.handleBlank(s.blank)
|
|
session.handleRunning(s.running)
|
|
}
|
|
// Seed each row's projection baseline into the per-session value
|
|
// store (cold titles surface without opening the session). Per-key
|
|
// apply, not seed(): the list block is a partial baseline — the
|
|
// cold cache serves only version-matching keys — so an absent key
|
|
// must not clear; higher-seq-wins still keeps a stale list block
|
|
// from overwriting a newer push frame or tail baseline.
|
|
for (const s of result.value.items) {
|
|
const block = s.projections
|
|
if (block === undefined) continue
|
|
const store = this.projectionStore(s.sessionId)
|
|
const values = block.values as Record<string, unknown>
|
|
for (const key of Object.keys(values)) store.apply(key, values[key], sessionSeqCursor(block.asOfSeq))
|
|
}
|
|
} else {
|
|
this.listState = 'error'
|
|
this.listError = result.error
|
|
}
|
|
} catch (error) {
|
|
if (!isRemoteFailure(error)) throw error
|
|
if (this.listMutations !== mutations) return
|
|
this.listState = 'error'
|
|
this.listError = error
|
|
} finally {
|
|
if (this.listMutations === mutations) {
|
|
this.listMutations = null
|
|
this.listInflight = null
|
|
this.notifier.markDirty()
|
|
}
|
|
}
|
|
})()
|
|
return this.listInflight
|
|
}
|
|
|
|
/**
|
|
* Search visible session message content without adding transient query
|
|
* state to the list snapshot.
|
|
* @param query - non-blank literal phrase.
|
|
* @param signal - cancellation for superseded UI queries.
|
|
* @returns the Host result or a folded transport error.
|
|
*/
|
|
async search(
|
|
query: string,
|
|
signal: AbortSignal,
|
|
): Promise<RemoteResult<{ items: SessionSearchResultItem[]; hasMore: boolean }>> {
|
|
const result = await this.remote.session.search({ query }, signal)
|
|
if (!result.ok) return result
|
|
return {
|
|
ok: true,
|
|
value: {
|
|
items: [...result.value.items],
|
|
hasMore: result.value.hasMore,
|
|
},
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Contract session.create; on success merge into summaries immediately (no
|
|
* wait for the next refresh). A created session is blank by definition
|
|
* (entity birth precedes the first message).
|
|
* @param opts - target workspace or working directory, plus an optional caller-owned id.
|
|
* @returns the create result.
|
|
*/
|
|
async create(
|
|
opts: {
|
|
workspaceId?: WorkspaceId
|
|
cwd?: string
|
|
sessionId?: SessionId
|
|
} = {},
|
|
): Promise<RemoteResult<{ sessionId: SessionId }>> {
|
|
const shared = opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }
|
|
const payload = opts.workspaceId !== undefined
|
|
? { workspaceId: opts.workspaceId, ...shared }
|
|
: { ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }), ...shared }
|
|
const result = await this.remote.session.create(payload)
|
|
if (result.ok) {
|
|
this.recordMutation({ kind: 'placeholder', summary: { agentAvailable: true,
|
|
sessionId: result.value.sessionId, updatedAt: Date.now(), running: false, blank: true,
|
|
...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
|
|
} })
|
|
} else {
|
|
const publishedSessionId = workspaceAttachSessionId(result.error)
|
|
// Publication precedes attachment. The error's id is a real Session,
|
|
// so expose it immediately as Ungrouped while the caller keeps the
|
|
// prompt buffer and decides whether to retry attachment.
|
|
if (publishedSessionId !== undefined) {
|
|
this.recordMutation({ kind: 'placeholder', summary: { agentAvailable: true,
|
|
sessionId: publishedSessionId,
|
|
updatedAt: Date.now(),
|
|
running: false,
|
|
blank: true,
|
|
} })
|
|
}
|
|
}
|
|
return result
|
|
}
|
|
|
|
/**
|
|
* Contract session.fork; on success merge the child into summaries
|
|
* immediately (same synchronous-addressability guarantee as create). The
|
|
* child carries the source's history, so it is never blank; lineage rides
|
|
* parentSessionId so the list nests it under its source. A child published
|
|
* before Workspace attachment fails is also reconciled into the list.
|
|
* @param opts - source session and the optional seq anchoring the cut.
|
|
* @returns the fork result (the child session id).
|
|
*/
|
|
async fork(
|
|
opts: { sessionId: SessionId; atSeq?: SessionSeq },
|
|
): Promise<RemoteResult<{ sessionId: SessionId }>> {
|
|
const source = this.summaries.find(s => s.sessionId === opts.sessionId)
|
|
const result = await this.remote.session.fork({
|
|
sessionId: opts.sessionId,
|
|
...opts.atSeq === undefined ? {} : { atSeq: opts.atSeq },
|
|
})
|
|
const childId = result.ok
|
|
? result.value.sessionId
|
|
: workspaceAttachSessionId(result.error)
|
|
if (childId !== undefined) {
|
|
this.recordMutation({ kind: 'placeholder', summary: { agentAvailable: true,
|
|
sessionId: childId, updatedAt: Date.now(), running: false, blank: false,
|
|
parentSessionId: opts.sessionId,
|
|
...(source?.cwd !== undefined ? { cwd: source.cwd } : {}),
|
|
} })
|
|
}
|
|
return result
|
|
}
|
|
|
|
/**
|
|
* Merge a Host summary, replacing live state and filling missing metadata.
|
|
* Local create/fork placeholders only fill metadata on an existing row.
|
|
*/
|
|
private mergeSummary(summary: SessionSummary): void {
|
|
this.recordMutation({ kind: 'upsert', summary })
|
|
this.updateParentAvailability()
|
|
}
|
|
|
|
/** Apply immediately and retain for replay when a list response is in flight. */
|
|
private recordMutation(mutation: SessionListMutation): void {
|
|
this.listMutations?.push(mutation)
|
|
this.summaries = applyMutation(this.summaries, mutation)
|
|
// Eager edge reconciliation — a snapshot-build-time pass would miss consecutive status frames.
|
|
this.syncCompletedNotifications()
|
|
this.notifier.markDirty()
|
|
}
|
|
|
|
// ---- Subscription API (for useSessionList) ----
|
|
|
|
/**
|
|
* uSES subscription entry for useSessionList.
|
|
* @param listener - change callback.
|
|
* @returns the unsubscribe function.
|
|
*/
|
|
subscribe(listener: () => void): () => void {
|
|
return this.notifier.subscribe(listener)
|
|
}
|
|
|
|
/**
|
|
* Cached list snapshot (rebuilt lazily when dirty with no listeners).
|
|
* @returns the cached reference (stable until the next flush).
|
|
*/
|
|
getListSnapshot(): SessionListSnapshot {
|
|
this.notifier.ensureFresh()
|
|
return this.listSnapshotCache
|
|
}
|
|
|
|
// ---- Live control and Host-event sinks ----
|
|
|
|
/**
|
|
* Apply a complete control baseline or one later replacement frame.
|
|
* @param frame - baseline or live control replacement from Session Controller.
|
|
*/
|
|
handleControlFrame(frame: SessionControlFrame): void {
|
|
if (frame.type === 'baseline') {
|
|
this.replaceControlBaseline(frame.value)
|
|
return
|
|
}
|
|
if (frame.type === 'projection') {
|
|
this.projectionStore(frame.sessionId).apply(frame.key, frame.value, SessionSeq(frame.seq))
|
|
this.notifier.markDirty()
|
|
return
|
|
}
|
|
if (frame.jobs.length === 0) this.jobsBySession.delete(frame.sessionId)
|
|
else this.jobsBySession.set(frame.sessionId, frame.jobs)
|
|
this.notifier.markDirty()
|
|
}
|
|
|
|
private replaceControlBaseline(baseline: SessionControlBaseline): void {
|
|
this.jobsBySession.clear()
|
|
for (const [sessionId, jobs] of Object.entries(baseline.jobs)) {
|
|
if (jobs.length > 0) this.jobsBySession.set(sessionId as SessionId, jobs)
|
|
}
|
|
|
|
for (const [sessionId, block] of Object.entries(baseline.projections)) {
|
|
const store = this.projectionStore(sessionId as SessionId)
|
|
const asOfSeq = sessionSeqCursor(block.asOfSeq)
|
|
store.seed({ ...block, asOfSeq })
|
|
}
|
|
this.notifier.markDirty()
|
|
}
|
|
|
|
/**
|
|
* Apply one Session-list addition forwarded through `ctx.remote.$on`.
|
|
* @param summary - current Host summary for the added Session.
|
|
*/
|
|
handleSessionAdded(summary: SessionSummary): void {
|
|
this.mergeSummary(summary)
|
|
this.sessions.get(summary.sessionId)?.handleBlank(summary.blank)
|
|
const projections = summary.projections
|
|
if (projections !== undefined) {
|
|
const store = this.projectionStore(summary.sessionId)
|
|
for (const [key, value] of Object.entries(projections.values)) {
|
|
store.apply(key, value, sessionSeqCursor(projections.asOfSeq))
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Apply one Session removal forwarded through `ctx.remote.$on`.
|
|
* @param sessionId - removed Session identity.
|
|
*/
|
|
handleSessionRemoved(sessionId: SessionId): void {
|
|
const durableSubagent = this.subagentAddress(sessionId) !== undefined
|
|
|| this.summaries.some(summary => summary.sessionId === sessionId && summary.origin === 'subagent')
|
|
this.recordMutation(durableSubagent
|
|
? { kind: 'status', sessionId, running: false, agentAvailable: false }
|
|
: { kind: 'remove', sessionId })
|
|
if (durableSubagent) this.sessions.get(sessionId)?.handleRunning(false)
|
|
else this.sessions.get(sessionId)?.handleRemoved()
|
|
this.jobsBySession.delete(sessionId)
|
|
const catalog = this.projectionStores.get(sessionId)?.values().subagentCatalog
|
|
if (!durableSubagent && (catalog === undefined || catalog.length === 0)) {
|
|
this.projectionStores.delete(sessionId)
|
|
}
|
|
this.projectionInflight.get(sessionId)?.controller.abort()
|
|
this.projectionInflight.delete(sessionId)
|
|
this.projectionLoads.delete(sessionId)
|
|
for (const [childId, address] of this.addresses) {
|
|
if (address.parentSessionId === sessionId) {
|
|
this.sessions.get(childId)?.handleSubagentParentAvailable(false)
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Apply one live Agent running-state change.
|
|
* @param sessionId - Session whose Agent state changed.
|
|
* @param running - current Agent running state.
|
|
*/
|
|
handleSessionStatus(sessionId: SessionId, running: boolean): void {
|
|
this.recordMutation({ kind: 'status', sessionId, running, agentAvailable: true })
|
|
this.updateParentAvailability()
|
|
this.sessions.get(sessionId)?.handleRunning(running)
|
|
}
|
|
|
|
/**
|
|
* Advance Session-list activity from one user-authored durable message.
|
|
* @param sessionId - Session whose activity changed.
|
|
* @param updatedAt - durable message timestamp.
|
|
*/
|
|
handleSessionActivity(sessionId: SessionId, updatedAt: number): void {
|
|
this.recordMutation({ kind: 'activity', sessionId, updatedAt })
|
|
}
|
|
|
|
/**
|
|
* Surface one live Agent failure on an already-materialized Session.
|
|
* @param sessionId - Session whose Agent failed.
|
|
* @param message - caller-visible failure description.
|
|
*/
|
|
handleSessionError(sessionId: SessionId, message: string): void {
|
|
this.sessions.get(sessionId)?.handleAgentError(message)
|
|
}
|
|
|
|
/**
|
|
* Repair one re-established Host-event generation with queryable baselines.
|
|
* Discard old projection cuts before new queries, including cold Sessions
|
|
* absent from the process-local control baseline.
|
|
* Opened Session follow streams resume independently through API Gateway.
|
|
*/
|
|
handleConnected(): void {
|
|
for (const store of this.projectionStores.values()) store.clear()
|
|
this.listMutations = null
|
|
this.listInflight = null
|
|
void this.refreshList()
|
|
const parents = new Set(this.projectionLoads.keys())
|
|
const selectedAddress = this.selected === undefined ? undefined : this.addresses.get(this.selected)
|
|
if (selectedAddress !== undefined) parents.add(selectedAddress.parentSessionId)
|
|
if (this.selected !== undefined) parents.add(this.selected)
|
|
for (const { controller } of this.projectionInflight.values()) controller.abort()
|
|
this.projectionInflight.clear()
|
|
this.projectionLoads.clear()
|
|
for (const parentSessionId of parents) void this.refreshProjections(parentSessionId)
|
|
}
|
|
|
|
/**
|
|
* Reconcile completion reminders against the latest summaries, eagerly after
|
|
* every mutation and pull (a snapshot-build-time pass would collapse
|
|
* consecutive status frames into one observation). A running→idle edge of a
|
|
* non-selected session arms its reminder; running disarms it; removal drops
|
|
* it. First observation only records the running bit — sessions already
|
|
* idle at load get no reminder.
|
|
*/
|
|
private syncCompletedNotifications(): void {
|
|
const seen = new Set<SessionId>()
|
|
for (const s of this.summaries) {
|
|
seen.add(s.sessionId)
|
|
const prev = this.prevRunning.get(s.sessionId)
|
|
if (prev === undefined) {
|
|
this.prevRunning.set(s.sessionId, s.running)
|
|
continue
|
|
}
|
|
if (prev && !s.running) {
|
|
if (s.sessionId !== this.selected) this.completedNotifications.add(s.sessionId)
|
|
} else if (s.running) {
|
|
this.completedNotifications.delete(s.sessionId)
|
|
}
|
|
this.prevRunning.set(s.sessionId, s.running)
|
|
}
|
|
for (const id of this.prevRunning.keys()) {
|
|
if (!seen.has(id)) this.prevRunning.delete(id)
|
|
}
|
|
for (const id of this.completedNotifications) {
|
|
if (!seen.has(id)) this.completedNotifications.delete(id)
|
|
}
|
|
}
|
|
|
|
private buildListSnapshot(): SessionListSnapshot {
|
|
const merged: TitledSessionSummary[] = this.summaries.map((summary) => {
|
|
// List rows read the generic 'title' projection key (host-computed unit
|
|
// value; there is no dedicated title frame).
|
|
const projectionStore = this.projectionStores.get(summary.sessionId)
|
|
const title = projectionStore?.get('title')
|
|
const projectionValues = projectionStore?.values()
|
|
return {
|
|
...summary,
|
|
...(typeof title === 'string' && title !== '' ? { title } : {}),
|
|
...(projectionValues === undefined ? {} : { projectionValues }),
|
|
}
|
|
})
|
|
const fresh = flattenLineage(merged, this.completedNotifications)
|
|
const items = fresh.map((entry) => {
|
|
const prev = this.entryCache.get(entry.sessionId)
|
|
if (
|
|
prev !== undefined && prev.updatedAt === entry.updatedAt && prev.running === entry.running
|
|
&& prev.blank === entry.blank
|
|
&& prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd
|
|
&& prev.origin === entry.origin && prev.title === entry.title && prev.depth === entry.depth
|
|
&& prev.projectionValues === entry.projectionValues
|
|
&& prev.completed === entry.completed
|
|
) return prev
|
|
this.entryCache.set(entry.sessionId, entry)
|
|
return entry
|
|
})
|
|
const itemIds = new Set(items.map(entry => entry.sessionId))
|
|
for (const id of this.entryCache.keys()) {
|
|
if (!itemIds.has(id)) this.entryCache.delete(id)
|
|
}
|
|
const sameOrder = items.length === this.itemsCache.length && items.every((e, i) => e === this.itemsCache[i])
|
|
if (!sameOrder) this.itemsCache = items
|
|
const selected = this.selected
|
|
const current = selected !== undefined
|
|
&& (itemIds.has(selected) || this.addresses.has(selected))
|
|
? selected
|
|
: undefined
|
|
return {
|
|
items: this.itemsCache,
|
|
current,
|
|
state: this.listState,
|
|
phase: this.listPhase,
|
|
error: this.listError,
|
|
projectionsBySession: Object.fromEntries([...this.projectionStores].map(([sessionId, store]) => [
|
|
sessionId,
|
|
{ values: store.values(), state: 'idle', error: null, ...this.projectionLoads.get(sessionId) },
|
|
])),
|
|
jobsBySession: Object.fromEntries(this.jobsBySession),
|
|
currentAddress: current === undefined ? undefined : this.addresses.get(current),
|
|
}
|
|
}
|
|
}
|
|
|
|
/** Apply one list mutation without deriving display order. */
|
|
function applyMutation(summaries: readonly SessionSummary[], mutation: SessionListMutation): SessionSummary[] {
|
|
switch (mutation.kind) {
|
|
case 'upsert':
|
|
case 'placeholder': {
|
|
const existing = summaries.find(summary => summary.sessionId === mutation.summary.sessionId)
|
|
if (existing === undefined) return [mutation.summary, ...summaries]
|
|
const filled: SessionSummary = {
|
|
...existing,
|
|
// Blank only lowers: a stale true (session-added racing the local
|
|
// first send) never re-hides an already-surfaced session.
|
|
blank: existing.blank && mutation.summary.blank,
|
|
...(mutation.kind === 'upsert' ? {
|
|
agentAvailable: mutation.summary.agentAvailable,
|
|
running: mutation.summary.running,
|
|
} : {}),
|
|
...(existing.cwd === undefined && mutation.summary.cwd !== undefined ? { cwd: mutation.summary.cwd } : {}),
|
|
...(existing.parentSessionId === undefined && mutation.summary.parentSessionId !== undefined
|
|
? { parentSessionId: mutation.summary.parentSessionId } : {}),
|
|
...(existing.origin === undefined && mutation.summary.origin !== undefined
|
|
? { origin: mutation.summary.origin } : {}),
|
|
}
|
|
if (filled.cwd === existing.cwd && filled.parentSessionId === existing.parentSessionId
|
|
&& filled.origin === existing.origin && filled.blank === existing.blank
|
|
&& filled.agentAvailable === existing.agentAvailable && filled.running === existing.running
|
|
) return [...summaries]
|
|
return summaries.map(summary => summary.sessionId === mutation.summary.sessionId ? filled : summary)
|
|
}
|
|
case 'remove':
|
|
return summaries.filter(summary => summary.sessionId !== mutation.sessionId)
|
|
case 'status':
|
|
// running:true doubles as the cross-client blank flip (a blank session
|
|
// never runs, so the first running frame proves a message landed).
|
|
return summaries.map(summary => summary.sessionId === mutation.sessionId
|
|
&& (summary.running !== mutation.running
|
|
|| summary.agentAvailable !== mutation.agentAvailable || (mutation.running && summary.blank))
|
|
? { ...summary, running: mutation.running, agentAvailable: mutation.agentAvailable, blank: summary.blank && !mutation.running }
|
|
: summary)
|
|
case 'activity':
|
|
return summaries.map(summary => summary.sessionId === mutation.sessionId
|
|
&& mutation.updatedAt > summary.updatedAt
|
|
? { ...summary, updatedAt: mutation.updatedAt }
|
|
: summary)
|
|
case 'engaged':
|
|
return summaries.map(summary => summary.sessionId === mutation.sessionId && summary.blank
|
|
? { ...summary, blank: false }
|
|
: summary)
|
|
}
|
|
}
|
|
|
|
/** Temporary source-plane bridge while the Host contract and client project build independently. */
|
|
function workspaceAttachSessionId(error: RemoteFailure): SessionId | undefined {
|
|
return error.code === 'session/workspace-attach-failed' ? error.details.sessionId : undefined
|
|
}
|