@deepseek-ai/dsh-api-session-controller 0.1.6-alpha.1 → 0.1.7-alpha.1

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

@@ -1,11 +1,14 @@
-import type { SubagentAddress, SubagentCatalog } from '@deepseek-ai/dsh-subagent/client';
+/** Host catalog, durable projection caches, and explicitly retained Client instances. */
+import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client';
 import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types';
+import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types';
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
-import type { SessionControlFrame, SessionSummary, SessionJob as JobView } from '../../types.ts';
+import type { SessionControlFrame, SessionRenameValue, SessionSummary } 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';
+import type { SessionTarget } from '../contract/sessions.ts';
 /**
  * List arrival lifecycle, orthogonal to the pull-activity `state` axis:
  * `pending` (no successful pull yet — an empty items array means "nothing
@@ -23,40 +26,33 @@ export interface SessionSearchResultItem {
 /** 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;
+    projectionsBySession: Readonly<Record<SessionId, SessionProjectionSnapshot>>;
+}
+/** 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;
 }
-/** 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).
+     * Accepted/running presentation must survive a later empty-history list
+     * response. Host-asserted running is recorded even before a row, instance, or
+     * address holds the identity — the listing that would hold it may not have
+     * landed yet — while the client-local acceptance callback requires a current
+     * holder, because it can arrive from a replaced or already-dropped Session.
      */
-    private readonly completedNotifications;
-    /** Last-observed running bits per session; the true→false edge here arms {@link completedNotifications}. */
-    private readonly prevRunning;
+    private readonly engagedSessions;
+    private disposed;
     /** 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
@@ -68,22 +64,11 @@ export declare class SessionManager {
     private listPhase;
     private listError;
     private listInflight;
-    /** Mutations arriving after a list request starts are replayed over its response. */
+    /** Active list request's mutation log; its identity also fences completion after reconnect. */
     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 readonly projectionLoads;
+    private readonly projectionInflight;
     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
@@ -91,71 +76,68 @@ export declare class SessionManager {
     private entryCache;
     private itemsCache;
     private readonly notifier;
+    /** @param remote - generated Remote namespaces used by catalog and history readers. */
+    constructor(remote: SessionRemotes);
     /**
-     * @param remote - generated Remote namespaces the Session cluster calls.
-     * @param restoredSelection - persisted real-Session selection candidate.
+     * Resolve an acquisition target without materializing a Session.
+     * @param target - known identity or durable direct-parent address.
+     * @returns the resolved identity with its explicit or catalog-derived history route installed.
      */
-    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;
+    resolveTarget(target: SessionTarget): SessionId;
     /**
      * 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;
+    subagentAddress(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.
+     * Withdraw an exact Client instance before running its teardown callbacks.
+     * @param sessionId - identity to withdraw.
+     * @param expected - instance being released; a replacement is left untouched.
+     * @returns completion of the detached instance's stream teardown.
      */
-    drop(sessionId: SessionId): Promise<void>;
+    drop(sessionId: SessionId, expected: Session): Promise<void>;
     /**
-     * Stop owned timers and every remaining Session instance.
-     * @returns when every Session Remote iterator has completed teardown.
+     * Stop catalog requests and dispose every resident Session.
+     * @returns once catalog requests and every Session stream have stopped.
      */
     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).
+     * the reference allocator opens history after binding the scope).
+     * New instances reconcile retained metadata before returning.
      * @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;
+    private effectiveBlank;
     /**
-     * Refresh one direct-child catalog, reusing its in-flight request.
-     * @param parentSessionId - catalog owner.
+     * Identities an engagement may still belong to: the given list rows, resident
+     * Session instances, and retained child addresses.
+     * @param summaries - list rows of the caller's snapshot.
+     * @returns the retained identity set.
      */
-    refreshSubagents(parentSessionId: SessionId): Promise<void>;
+    private retainedIds;
     /**
-     * Mark whether a catalog menu is consuming live membership updates.
-     * @param parentSessionId - catalog owner.
-     * @param open - current menu state.
+     * Forget one engagement that no retained identity holds.
+     * @param sessionId - identity whose engagement may be dropped.
+     * @param retained - identities from {@link retainedIds} for the caller's snapshot.
      */
-    setSubagentCatalogOpen(parentSessionId: SessionId, open: boolean): void;
-    /** Full refresh via session.list (single-flight: an in-flight call is reused). */
+    private pruneEngagement;
+    /** Resident per-session projection store (create-on-demand; outlives instantiation). */
+    private projectionStore;
+    /**
+     * 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>;
+    private agentAvailable;
+    private updateParentAvailability;
+    /** Full refresh via session.list (single-flight within one Host generation). */
     refreshList(): Promise<void>;
     /**
      * Search visible session message content without adding transient query
@@ -184,11 +166,12 @@ export declare class SessionManager {
     }>>;
     /**
      * 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.
+     * immediately (same synchronous-addressability guarantee as create).
+     * Blankness starts provisionally true so the authoritative Host summary can
+     * preserve it or lower it after an exact cut before the first `turn/start`;
+     * lineage rides parentSessionId. A child published before Workspace
+     * attachment fails is also reconciled into the list.
+     * @param opts - source session and the optional exact inclusive boundary seq.
      * @returns the fork result (the child session id).
      */
     fork(opts: {
@@ -198,10 +181,15 @@ export declare class SessionManager {
         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).
+     * Rename a Session and update its title projection without opening its history.
+     * @param sessionId - Session to rename.
+     * @param title - raw title text for Host normalization.
+     * @returns the accepted title and event position, or the Remote failure.
+     */
+    rename(sessionId: SessionId, title: string): Promise<RemoteResult<SessionRenameValue>>;
+    /**
+     * Merge a Host summary, replacing live state and filling missing metadata.
+     * Local create/fork placeholders only fill metadata on an existing row.
      */
     private mergeSummary;
     /** Apply immediately and retain for replay when a list response is in flight. */
@@ -217,6 +205,12 @@ export declare class SessionManager {
      * @returns the cached reference (stable until the next flush).
      */
     getListSnapshot(): SessionListSnapshot;
+    /**
+     * Read cached projection values for a Session that may exist only in a loaded subagent catalog.
+     * @param sessionId - Session whose control or history baseline supplied projections.
+     * @returns current values, or undefined before any projection store exists.
+     */
+    projectionValues(sessionId: SessionId): Readonly<Partial<SessionProjectionMap>> | undefined;
     /**
      * Apply a complete control baseline or one later replacement frame.
      * @param frame - baseline or live control replacement from Session Controller.
@@ -228,6 +222,15 @@ export declare class SessionManager {
      * @param summary - current Host summary for the added Session.
      */
     handleSessionAdded(summary: SessionSummary): void;
+    /**
+     * Merge one list-surface projection block by the sequence space it declares.
+     * A `sequenced` block came from the Host's live registry for an attached
+     * Session, so each key lands under higher-seq-wins against that Session's
+     * baselines and frames. A `cached` block was viewed from the persisted
+     * checkpoint by a header-only listing: its watermark is not comparable with
+     * this connection's seqs, so it only fills keys no sequenced row holds.
+     */
+    private applyListBlock;
     /**
      * Apply one Session removal forwarded through `ctx.remote.$on`.
      * @param sessionId - removed Session identity.
@@ -253,28 +256,11 @@ export declare class SessionManager {
     handleSessionError(sessionId: SessionId, message: string): void;
     /**
      * 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;
-    /** 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