@crazx/dsh-api-session-controller 0.1.2-alpha.3.zw.1

package/lib/types/client/index.js

@@ -0,0 +1,48 @@
+/** Client Session object layer, Agent scopes, and Remote lifecycle wiring. */
+import { createSessionControlStream } from "./transport.js";
+import { ClientSessions } from "./sessions/service.js";
+export { createSessionControlStream, SessionEventStream, SESSION_SEARCH_RESULT_LIMIT, SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS, } from "./transport.js";
+export { createScope, scopeOf } from "./scope.js";
+export { SessionCreateError, SessionForkError } from "./sessions/service.js";
+export { MutableSessionEventSource } from "./contract/events.js";
+/** Required Remote and Context projection services. */
+export const inject = [
+    'typert',
+    'remote',
+    'remote.commands',
+    'remote.session',
+    'remote.subagents',
+];
+/**
+ * Install Client Session state and its reconnecting control stream.
+ * @param ctx - Client Cordis context.
+ */
+export function apply(ctx) {
+    const remotes = ctx.remote;
+    const sessions = new ClientSessions(ctx, remotes);
+    ctx.remote.$on('api-session/added', (summary) => { sessions.handleSessionAdded(summary); });
+    ctx.remote.$on('api-session/removed', (sessionId) => { sessions.handleSessionRemoved(sessionId); });
+    ctx.remote.$on('api-session/status', (sessionId, running) => {
+        sessions.handleSessionStatus(sessionId, running);
+    });
+    ctx.remote.$on('api-session/activity', (sessionId, updatedAt) => {
+        sessions.handleSessionActivity(sessionId, updatedAt);
+    });
+    ctx.remote.$on('api-session/error', (sessionId, message) => {
+        sessions.handleSessionError(sessionId, message);
+    });
+    const control = createSessionControlStream(remotes, {
+        accept: (frame) => { sessions.handleControlFrame(frame); },
+        failed: (error) => { console.error('[session-controller] control stream failed:', error); },
+    });
+    control.start();
+    ctx.on('connection/reset', () => { sessions.handleConnected(); });
+    if (ctx.remote.$host.home !== undefined)
+        sessions.handleConnected();
+    ctx.typert.contexts.registerClient('agent', {
+        identity: candidate => sessions.scopeOf(candidate),
+        resolve: sessionId => sessions.resolveAgentScope(sessionId),
+    });
+    ctx.effect(() => async () => { await control.dispose(); }, 'session-controller.client.control');
+}
+//# sourceMappingURL=index.js.map

package/lib/types/client/ordered-baseline.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Merge an authoritative baseline without moving identities already visible to
+ * the client. Baseline-only identities are inserted relative to the nearest
+ * following known identity; identities absent from the baseline are removed.
+ *
+ * @param current - the established client order.
+ * @param baseline - the latest authoritative rows.
+ * @param keyOf - stable identity selector.
+ * @returns baseline-valued rows with the established relative order retained.
+ */
+export declare function mergeOrderedBaseline<T>(current: readonly T[], baseline: readonly T[], keyOf: (value: T) => unknown): T[];
+//# sourceMappingURL=ordered-baseline.d.ts.map

package/lib/types/client/ordered-baseline.js

@@ -0,0 +1,41 @@
+/**
+ * Merge an authoritative baseline without moving identities already visible to
+ * the client. Baseline-only identities are inserted relative to the nearest
+ * following known identity; identities absent from the baseline are removed.
+ *
+ * @param current - the established client order.
+ * @param baseline - the latest authoritative rows.
+ * @param keyOf - stable identity selector.
+ * @returns baseline-valued rows with the established relative order retained.
+ */
+export function mergeOrderedBaseline(current, baseline, keyOf) {
+    const baselineByKey = new Map();
+    for (const value of baseline)
+        baselineByKey.set(keyOf(value), value);
+    const merged = current
+        .map(value => baselineByKey.get(keyOf(value)))
+        .filter((value) => value !== undefined);
+    const mergedKeys = new Set(merged.map(keyOf));
+    for (let index = 0; index < baseline.length; index++) {
+        const value = baseline[index];
+        /* v8 ignore next -- dense-array guard: index is bounded by baseline.length. */
+        if (value === undefined || mergedKeys.has(keyOf(value)))
+            continue;
+        let insertion = merged.length;
+        for (let following = index + 1; following < baseline.length; following++) {
+            const candidate = baseline[following];
+            /* v8 ignore next -- dense-array guard: following is bounded by baseline.length. */
+            if (candidate === undefined)
+                continue;
+            const known = merged.findIndex(item => keyOf(item) === keyOf(candidate));
+            if (known !== -1) {
+                insertion = known;
+                break;
+            }
+        }
+        merged.splice(insertion, 0, value);
+        mergedKeys.add(keyOf(value));
+    }
+    return merged;
+}
+//# sourceMappingURL=ordered-baseline.js.map

package/lib/types/client/scope.d.ts

@@ -0,0 +1,36 @@
+import type { Context, Fiber } from '@deepseek-ai/cordis';
+import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { TypertRemoteScopeApi } from '@deepseek-ai/dsh-typert-protocol';
+/** Client Cordis Context carrying one Agent identity and its scoped Remote namespaces. */
+export type AgentContext = Omit<Context, 'remote'> & {
+    readonly remote: ClientRemote & TypertRemoteScopeApi<'agent'>;
+};
+/** A minted Agent scope and its disposal boundary. */
+export interface AgentScopeHandle {
+    /**
+     * Tagged context: scope-owned registrations and scoped dispatch both go
+     * through it (passing it as the dispatch subject routes to this agent's
+     * tagged listeners plus every untagged one).
+     */
+    ctx: AgentContext;
+    /** Backing fiber (dispose tears down every scope-owned registration). */
+    fiber: Fiber;
+}
+/**
+ * Mint an Agent scope under `ctx`: a no-op plugin fiber whose context
+ * carries the agent tag and the dispatch filter — untagged listeners are
+ * admitted globally, tagged listeners only for a matching agent.
+ * Registrations through the returned ctx dispose with the fiber.
+ * @param ctx - client root context the scope fiber mounts under.
+ * @param key - owning agent identity (the routing tag; agent id === session id).
+ * @returns the tagged context and its backing fiber.
+ */
+export declare function createScope(ctx: Context, key: SessionId): AgentScopeHandle;
+/**
+ * Read the nearest agent tag inherited by a context.
+ * @param ctx - any client context.
+ * @returns its agent identity (the session id), or undefined for root contexts.
+ */
+export declare function scopeOf(ctx: Context): SessionId | undefined;
+//# sourceMappingURL=scope.d.ts.map

package/lib/types/client/scope.js

@@ -0,0 +1,54 @@
+/**
+ * Client Agent-scope primitive: mint a Cordis context tagged with the owning
+ * Agent's identity. The mechanism mirrors the host `dsh-scope` architecture
+ * (no-op plugin fiber + context tag + `Context.filter` routing predicate);
+ * the shape deliberately diverges: the filter lives on the actx itself
+ * instead of a separate carrier object, so scoped dispatch is plain cordis —
+ * `actx.bail(actx, event, payload)` / `actx.emit(actx, ...)` — with no
+ * wrapper. The host needs a detached carrier because its dispatch subject is
+ * the business Agent object; client scope events carry only ids, so the
+ * actx is the natural subject. The second divergence stands: the scope key
+ * is the branded `SessionId` (value compared), not an object identity — the
+ * agent and its session share one id (1:1, same axis; no separate AgentId
+ * brand), and a client scope's identity IS that wire id. Third divergence,
+ * deliberate: the client scopes the Agent IDENTITY, not a live Agent object
+ * — a cold session's host Agent is already disposed while its client actx
+ * stays alive for history viewing.
+ */
+import { Context as CordisContext } from '@deepseek-ai/cordis';
+/** Context tag written by {@link createScope}. */
+const kScope = Symbol('dsh.client.scope');
+/** Shared no-op plugin backing each Agent scope fiber. */
+function agentScope() { }
+/**
+ * Mint an Agent scope under `ctx`: a no-op plugin fiber whose context
+ * carries the agent tag and the dispatch filter — untagged listeners are
+ * admitted globally, tagged listeners only for a matching agent.
+ * Registrations through the returned ctx dispose with the fiber.
+ * @param ctx - client root context the scope fiber mounts under.
+ * @param key - owning agent identity (the routing tag; agent id === session id).
+ * @returns the tagged context and its backing fiber.
+ */
+export function createScope(ctx, key) {
+    const fiber = ctx.plugin(agentScope);
+    const scoped = fiber.ctx.extend({
+        [kScope]: key,
+        [CordisContext.filter](listenerCtx) {
+            const tag = scopeOf(listenerCtx);
+            return tag === undefined || tag === key;
+        },
+    });
+    return {
+        fiber,
+        ctx: scoped,
+    };
+}
+/**
+ * Read the nearest agent tag inherited by a context.
+ * @param ctx - any client context.
+ * @returns its agent identity (the session id), or undefined for root contexts.
+ */
+export function scopeOf(ctx) {
+    return ctx[kScope];
+}
+//# sourceMappingURL=scope.js.map

package/lib/types/client/sessions/history-records.d.ts

@@ -0,0 +1,22 @@
+/** Client range access and type narrowing for aligned Session history records. */
+import type { SessionHistoryRecord } from '../../types.ts';
+import type { SessionEventLikeEntry } from '../contract/events.ts';
+/**
+ * Narrow aligned wire records to their Client event types without allocation.
+ * @param records - validated history transport records.
+ * @returns the same record array with typed inner events.
+ */
+export declare function historyEntries(records: readonly SessionHistoryRecord[]): readonly SessionEventLikeEntry[];
+/**
+ * Read the first logical sequence represented by one wire record.
+ * @param record - validated scalar event or packed Assistant delta run.
+ * @returns inclusive first Session sequence.
+ */
+export declare function historyRecordFirstSeq(record: SessionHistoryRecord): number;
+/**
+ * Read the final logical sequence represented by one wire record.
+ * @param record - validated scalar event or packed Assistant delta run.
+ * @returns inclusive final Session sequence.
+ */
+export declare function historyRecordLastSeq(record: SessionHistoryRecord): number;
+//# sourceMappingURL=history-records.d.ts.map

package/lib/types/client/sessions/history-records.js

@@ -0,0 +1,31 @@
+/** Client range access and type narrowing for aligned Session history records. */
+/**
+ * Narrow aligned wire records to their Client event types without allocation.
+ * @param records - validated history transport records.
+ * @returns the same record array with typed inner events.
+ */
+export function historyEntries(records) {
+    return records;
+}
+/**
+ * Read the first logical sequence represented by one wire record.
+ * @param record - validated scalar event or packed Assistant delta run.
+ * @returns inclusive first Session sequence.
+ */
+export function historyRecordFirstSeq(record) {
+    return record.event.seq;
+}
+/**
+ * Read the final logical sequence represented by one wire record.
+ * @param record - validated scalar event or packed Assistant delta run.
+ * @returns inclusive final Session sequence.
+ */
+export function historyRecordLastSeq(record) {
+    if (record.type === 'event')
+        return record.event.seq;
+    const length = record.event.type === 'chunkrow/tool-call-chunks'
+        ? record.event.data.args.length
+        : record.event.data.texts.length;
+    return record.event.seq + length - 1;
+}
+//# sourceMappingURL=history-records.js.map

package/lib/types/client/sessions/lineage.d.ts

@@ -0,0 +1,38 @@
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types';
+import type { SessionSummary } from '../../types.ts';
+/** Host list summary enriched with the latest Session Controller title projection. */
+export interface TitledSessionSummary extends SessionSummary {
+    title?: string;
+    /** Current host-computed projection values for list consumers. */
+    projectionValues?: Readonly<Partial<SessionProjectionMap>>;
+}
+/** One flattened session-list row with lineage depth. */
+export interface SessionListEntry {
+    sessionId: SessionId;
+    title?: string;
+    updatedAt: number;
+    running: boolean;
+    /** Empty-log bit mirrored from the summary; lists hide blank sessions (filtering stays with the consumer). */
+    blank: boolean;
+    parentSessionId?: SessionId;
+    /** Coarse durable origin for navigation filtering; not a continuation capability. */
+    origin?: 'subagent';
+    cwd?: string;
+    /** Current host-computed projection values for list consumers. */
+    projectionValues?: Readonly<Partial<SessionProjectionMap>>;
+    /** Finished running while not selected and not yet opened — the sidebar's green "done" reminder (clears on select or the next run). */
+    completed: boolean;
+    /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
+    depth: number;
+}
+/**
+ * Summaries -> flat list with lineage indentation. Root and sibling order
+ * follows the established input order; this projection never re-sorts a
+ * hydrated list from mutable timestamps.
+ * @param summaries - the host's session.list items.
+ * @param completed - sessions with a pending completion reminder (manager-owned live fact; absent = false).
+ * @returns display rows in render order.
+ */
+export declare function flattenLineage(summaries: readonly TitledSessionSummary[], completed?: ReadonlySet<SessionId>): SessionListEntry[];
+//# sourceMappingURL=lineage.d.ts.map

package/lib/types/client/sessions/lineage.js

@@ -0,0 +1,56 @@
+// flattenLineage: summaries -> flat list with lineage indentation (pure function).
+// The input order is authoritative; lineage only makes each child adjacent to its parent.
+// Orphaned lineage degrades to root level; cycles fail soft and emit as roots.
+/**
+ * Summaries -> flat list with lineage indentation. Root and sibling order
+ * follows the established input order; this projection never re-sorts a
+ * hydrated list from mutable timestamps.
+ * @param summaries - the host's session.list items.
+ * @param completed - sessions with a pending completion reminder (manager-owned live fact; absent = false).
+ * @returns display rows in render order.
+ */
+export function flattenLineage(summaries, completed) {
+    const byId = new Map();
+    for (const s of summaries)
+        byId.set(s.sessionId, s);
+    const children = new Map();
+    const roots = [];
+    for (const s of summaries) {
+        if (s.parentSessionId !== undefined && byId.has(s.parentSessionId)) {
+            const list = children.get(s.parentSessionId) ?? [];
+            list.push(s);
+            children.set(s.parentSessionId, list);
+        }
+        else {
+            roots.push(s); // root, or an orphan whose parent is absent from summaries (degrade to root, never drop)
+        }
+    }
+    const out = [];
+    const visited = new Set();
+    const walk = (s, depth) => {
+        if (visited.has(s.sessionId)) {
+            console.warn(`[session-controller] lineage cycle at ${s.sessionId}; emitting as root`);
+            return;
+        }
+        visited.add(s.sessionId);
+        out.push({
+            ...s,
+            completed: completed?.has(s.sessionId) ?? false,
+            depth,
+        });
+        const kids = children.get(s.sessionId);
+        if (kids === undefined)
+            return;
+        for (const kid of kids)
+            walk(kid, depth + 1);
+    };
+    for (const root of roots)
+        walk(root, 0);
+    // Cycle members (unreachable from any root): emit as roots so no entry is lost.
+    for (const s of summaries) {
+        if (!visited.has(s.sessionId))
+            walk(s, 0);
+    }
+    return out;
+}
+//# sourceMappingURL=lineage.js.map

package/lib/types/client/sessions/manager.d.ts

@@ -0,0 +1,280 @@
+import type { SubagentAddress, SubagentCatalog } from '@deepseek-ai/dsh-subagent/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+import type { SessionControlFrame, SessionSummary, SessionJob as JobView } from '../../types.ts';
+import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { SessionListEntry } from './lineage.ts';
+import { Session } from './session.ts';
+import type { SessionRemotes } from './remotes.ts';
+/**
+ * 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;
+    subagentsByParent: Readonly<Record<SessionId, SubagentCatalogSnapshot>>;
+    /** Background jobs per session; an absent key is an empty set. */
+    jobsBySession: Readonly<Record<SessionId, readonly JobView[]>>;
+    currentAddress: SubagentAddress | undefined;
+}
+/** One parent-addressed durable catalog projected through the sessions snapshot. */
+export type SubagentCatalogSnapshot = Omit<SubagentCatalog, 'parentAvailable'> & {
+    /** Absent until the first successful catalog read. */
+    readonly parentAvailable?: boolean;
+    state: 'loading' | 'ready' | 'error';
+    error: RemoteFailure | null;
+};
+/** Instance cluster + frame entry + the session list. */
+export declare class SessionManager {
+    private readonly remote;
+    private readonly sessions;
+    /** In-flight Session disposals remain here after instances leave `sessions`, so manager disposal can await quiescence. */
+    private readonly sessionDisposals;
+    /** Latest transient queues, retained independently of Session object materialization. */
+    private readonly queues;
+    /**
+     * 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;
+    /** Last-observed running bits per session; the true→false edge here arms {@link completedNotifications}. */
+    private readonly prevRunning;
+    /** 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;
+    private summaries;
+    private listState;
+    /** Arrival phase; the pending → ready edge fires on the first successful pull (see SessionListPhase). */
+    private listPhase;
+    private listError;
+    private listInflight;
+    /** Mutations arriving after a list request starts are replayed over its response. */
+    private listMutations;
+    private readonly addresses;
+    private readonly catalogs;
+    private readonly catalogInflight;
+    /** Catalog owners whose membership changed while a pull was in flight: one trailing refresh after it settles. */
+    private readonly catalogStale;
+    private readonly openCatalogs;
+    private readonly catalogDebounce;
+    /**
+     * 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;
+    private selected;
+    private listSnapshotCache;
+    /** 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;
+    private itemsCache;
+    private readonly notifier;
+    /**
+     * @param remote - generated Remote namespaces the Session cluster calls.
+     * @param restoredSelection - persisted real-Session selection candidate.
+     */
+    constructor(remote: SessionRemotes, restoredSelection?: SessionId, restoredAddress?: SubagentAddress);
+    /**
+     * Select a listed Session or a retained catalog-addressed child.
+     * @param sessionId - listed or catalog-addressed Session id.
+     */
+    select(sessionId: SessionId): void;
+    /**
+     * Select a healthy child through its durable direct-parent address.
+     * @param address - catalog-derived parent and child ids.
+     */
+    selectSubagent(address: SubagentAddress): void;
+    /** Clear the selection (the layout falls to the no-session view state). */
+    clearSelection(): void;
+    /**
+     * Return the durable catalog address retained for one child.
+     * @param sessionId - possible addressed child id.
+     * @returns The direct-parent address, when navigation discovered one.
+     */
+    subagentAddress(sessionId: SessionId): SubagentAddress | undefined;
+    /**
+     * 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.
+     */
+    navigationAddress(sessionId: SessionId): SubagentAddress | undefined;
+    /**
+     * 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.
+     */
+    drop(sessionId: SessionId): Promise<void>;
+    /**
+     * Stop owned timers and every remaining Session instance.
+     * @returns when every Session Remote iterator has completed teardown.
+     */
+    dispose(): Promise<void>;
+    private startSessionDisposal;
+    private drainSessionDisposals;
+    /**
+     * 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;
+    private createSession;
+    /** Resident per-session projection store (create-on-demand; outlives instantiation). */
+    private projectionStore;
+    /**
+     * Refresh one direct-child catalog, reusing its in-flight request.
+     * @param parentSessionId - catalog owner.
+     */
+    refreshSubagents(parentSessionId: SessionId): Promise<void>;
+    /**
+     * Mark whether a catalog menu is consuming live membership updates.
+     * @param parentSessionId - catalog owner.
+     * @param open - current menu state.
+     */
+    setSubagentCatalogOpen(parentSessionId: SessionId, open: boolean): void;
+    /** Full refresh via session.list (single-flight: an in-flight call is reused). */
+    refreshList(): Promise<void>;
+    /**
+     * 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.
+     */
+    search(query: string, signal: AbortSignal): Promise<RemoteResult<{
+        items: SessionSearchResultItem[];
+        hasMore: boolean;
+    }>>;
+    /**
+     * 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.
+    */
+    create(opts?: {
+        workspaceId?: WorkspaceId;
+        cwd?: string;
+        sessionId?: SessionId;
+    }): Promise<RemoteResult<{
+        sessionId: SessionId;
+    }>>;
+    /**
+     * 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).
+     */
+    fork(opts: {
+        sessionId: SessionId;
+        atSeq?: number;
+    }): Promise<RemoteResult<{
+        sessionId: SessionId;
+    }>>;
+    /**
+     * Insert-or-enrich a locally synthesized summary: a new id prepends; an
+     * existing entry only gains fields it lacks (the session-added frame and the
+     * create() echo race — whichever lands second must fill the placeholder's
+     * missing cwd/parentSessionId, never overwrite list-refresh data).
+     */
+    private mergeSummary;
+    /** Apply immediately and retain for replay when a list response is in flight. */
+    private recordMutation;
+    /**
+     * uSES subscription entry for useSessionList.
+     * @param listener - change callback.
+     * @returns the unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Cached list snapshot (rebuilt lazily when dirty with no listeners).
+     * @returns the cached reference (stable until the next flush).
+     */
+    getListSnapshot(): SessionListSnapshot;
+    /**
+     * Apply a complete control baseline or one later replacement frame.
+     * @param frame - baseline or live control replacement from Session Controller.
+     */
+    handleControlFrame(frame: SessionControlFrame): void;
+    private replaceControlBaseline;
+    /**
+     * Apply one Session-list addition forwarded through `ctx.remote.$on`.
+     * @param summary - current Host summary for the added Session.
+     */
+    handleSessionAdded(summary: SessionSummary): void;
+    /**
+     * Apply one Session removal forwarded through `ctx.remote.$on`.
+     * @param sessionId - removed Session identity.
+     */
+    handleSessionRemoved(sessionId: SessionId): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Repair one re-established Host-event generation with queryable baselines.
+     * Opened Session follow streams resume independently through API Gateway.
+     */
+    handleConnected(): void;
+    /** Debounce membership refetches while one parent catalog is selected or open. */
+    private scheduleCatalogRefresh;
+    /** Apply one Agent-driver transition to loaded and in-flight catalogs. */
+    private updateCatalogActivity;
+    /** Preserve and project a positive expandability hint after one direct subagent publishes. */
+    private markCatalogParentExpandable;
+    /** Apply one positive expandability hint to every loaded catalog containing that unique row id. */
+    private applyCatalogParentExpandable;
+    /** Fold request-local row mutations into one catalog result before publication. */
+    private withCatalogMutations;
+    /**
+     * 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;
+    private buildListSnapshot;
+}
+//# sourceMappingURL=manager.d.ts.map