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

package/lib/types/archived-session-gate.js

@@ -0,0 +1,52 @@
+/**
+ * The controller's admission gate for archived Sessions: an archived
+ * Session, or a subagent descendant of one, must not run a model step until
+ * it is restored. The work a Session still runs is reported and stopped by
+ * its owners — the Agent registry (`turn`), the job registry seam (`job`),
+ * the Subagent runtime (`subagent`), and the Schedule plugin (`schedule`) —
+ * through the Workspace registry's archive-admission events.
+ */
+/**
+ * The gate as a plugin for `ctx.plugin(...)`: it loads once the Agent
+ * registry, Session store, and Workspace registry are available and unwinds
+ * with the plugin's fiber. A late waking delivery to an archived Session — a
+ * subagent settlement, a queued follow-up — proposes a step the gate rejects,
+ * which the loop ends as `blocked` without a request; unarchiving lifts the
+ * gate for the whole lineage.
+ */
+export const ArchivedSessionGate = {
+    name: 'archived-session-gate',
+    inject: ['agents', 'sessions', 'workspaceRegistry'],
+    apply(ctx) {
+        ctx.on('agent/pre-step', (payload, next) => underArchivedSession(ctx, payload.agent)
+            ? Promise.resolve({ kind: 'reject' })
+            : next());
+    },
+};
+/**
+ * Whether the Agent's Session, or a Session above it in its subagent lineage,
+ * is archived. Lineage follows the durable header fields through
+ * subagent-origin Sessions only: a fork of an archived Session is an
+ * independent conversation.
+ * @param ctx - Host context.
+ * @param agent - the Agent proposing a step.
+ * @returns whether an archived Session owns the step.
+ */
+export function underArchivedSession(ctx, agent) {
+    const archived = ctx.workspaceRegistry.archivedSessionIds;
+    let header = agent.session.header;
+    const visited = new Set();
+    while (!visited.has(header.id)) {
+        if (archived.includes(header.id))
+            return true;
+        visited.add(header.id);
+        if (header.origin !== 'subagent' || header.parentSession === undefined)
+            return false;
+        const parent = ctx.sessions.get(header.parentSession);
+        if (parent === undefined)
+            return archived.includes(header.parentSession);
+        header = parent.header;
+    }
+    return false;
+}
+//# sourceMappingURL=archived-session-gate.js.map

package/lib/types/client/contract/session.d.ts

@@ -127,6 +127,8 @@ export interface ISession {
      * turn-jump loader. Repeated calls while a jump is paging lower its shared
      * target and return the in-flight completion; `snapshot.loadingOlder` is
      * the busy signal for the whole jump.
+     * Older pages publish together at completion, including successful pages
+     * before a later failure; live events remain independently visible.
      * @param seq - durable event seq the window must reach (a turn's `turn/start` seq).
      * @returns completion once covered, exhausted, superseded, or failed soft.
      */

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

@@ -85,21 +85,15 @@ export interface ISessions {
     /**
      * Resolve an already discovered direct-parent address without opening it.
      * @param id - possible addressed child id.
-     * @returns the retained address, when present.
+     * @returns a retained or loaded-catalog address, without retaining a new selection or scope.
      */
     subagentAddress(id: SessionId): SubagentAddress | undefined;
     /**
-     * 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;
-    /**
-     * Refresh one direct-child catalog.
-     * @param parentSessionId - catalog owner.
+     * Load all Session projections once per connection; retry an unsuccessful initial read.
+     * @param sessionId - Session to inspect without opening its conversation.
      * @returns completion of the current or newly started refresh.
      */
-    refreshSubagents(parentSessionId: SessionId): Promise<void>;
+    refreshProjections(sessionId: SessionId): Promise<void>;
     /**
      * Refresh the Host-authoritative Session list.
      * @returns completion of the current or newly started Session-list refresh.
@@ -117,12 +111,13 @@ export interface ISessions {
         hasMore: boolean;
     }>>;
     /**
-     * Fork a session from a completed-turn prefix of the source; on resolution
-     * the child is in the catalog and may be explicitly retained.
-     * @param opts - source session id, the optional event seq anchoring the
-     *   cut (the boundary is the first turn/end at or after it; an in-log
-     *   anchor in an open turn is unavailable rather than clipped backward),
-     *   and whether to increment an inherited durable title before resolving.
+     * Fork a session from an exact inclusive prefix of the source; on
+     * resolution the child is catalogued and can be explicitly retained.
+     * @param opts - source session id, the optional exact inclusive boundary
+     *   seq (a real event seq the caller already knows; a cut inside an open
+     *   turn is balanced Host-side with synthetic closers, and omission selects
+     *   the latest completed-turn prefix), and whether to increment an
+     *   inherited durable title before resolving.
      * @returns the child session id.
      * @throws when the fork fails, or when a requested child-title rename fails after creation.
      */

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

@@ -6,7 +6,7 @@ export { createScope, scopeOf } from './scope.ts';
 export type { AgentContext, AgentScopeHandle } from './scope.ts';
 export { SessionCreateError, SessionForkError } from './sessions/service.ts';
 export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts';
-export type { SessionListPhase, SessionListSnapshot, SessionSearchResultItem, SubagentCatalogSnapshot, } from './sessions/manager.ts';
+export type { SessionListPhase, SessionListSnapshot, SessionSearchResultItem, SessionProjectionSnapshot, } from './sessions/manager.ts';
 export type { Session } from './sessions/session.ts';
 export type { ProjectionsBaseline, ProjectionValueStore, SessionProjectionMap, UseProjection, } from './sessions/projection-store.ts';
 export type { BeginSubmissionInput, ISession, PendingSubmissionRetirement, ProjectionsFace, SessionFace, SubmissionHandle, } from './contract/session.ts';

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

@@ -13,7 +13,10 @@ export interface SessionListEntry {
     title?: string;
     updatedAt: number;
     running: boolean;
-    /** Empty-log bit mirrored from the summary; lists hide blank sessions (filtering stays with the consumer). */
+    /**
+     * New Session presentation and reuse eligibility, reconciled with
+     * `sessionListMetadata`; lists hide blank sessions (filtering stays with the consumer).
+     */
     blank: boolean;
     parentSessionId?: SessionId;
     /** Coarse durable origin for navigation filtering; not a continuation capability. */

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

@@ -32,8 +32,9 @@ export function flattenLineage(summaries) {
             return;
         }
         visited.add(s.sessionId);
+        const { agentAvailable: _agentAvailable, ...row } = s;
         out.push({
-            ...s,
+            ...row,
             depth,
         });
         const kids = children.get(s.sessionId);

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

@@ -1,9 +1,9 @@
 /** Host catalog, durable projection caches, and explicitly retained Client instances. */
-import type { SubagentAddress, SubagentCatalog } from '@deepseek-ai/dsh-subagent/client';
+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';
@@ -30,23 +30,29 @@ export interface SessionListSnapshot {
     /** 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[]>>;
+    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;
+    /**
+     * 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 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
@@ -61,18 +67,8 @@ export declare class SessionManager {
     /** 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 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
@@ -88,18 +84,12 @@ export declare class SessionManager {
      * @returns the resolved identity with its explicit or catalog-derived history route installed.
      */
     resolveTarget(target: SessionTarget): SessionId;
-    /**
-     * 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;
+    subagentAddress(sessionId: SessionId): SubagentAddress | undefined;
     /**
      * Withdraw an exact Client instance before running its teardown callbacks.
      * @param sessionId - identity to withdraw.
@@ -117,24 +107,36 @@ export declare class SessionManager {
     /**
      * Lazy build: return the existing instance or construct one (no auto-open —
      * 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;
+    /**
+     * 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.
+     */
+    private pruneEngagement;
+    /** Resident per-session projection store (create-on-demand; outlives instantiation). */
+    private projectionStore;
     /**
-     * Mark whether a catalog menu is consuming live membership updates.
-     * @param parentSessionId - catalog owner.
-     * @param open - current menu state.
+     * 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.
      */
-    setSubagentCatalogOpen(parentSessionId: SessionId, open: boolean): void;
+    refreshProjections(sessionId: SessionId): Promise<void>;
+    private agentAvailable;
+    private updateParentAvailability;
     /** Full refresh via session.list (single-flight within one Host generation). */
     refreshList(): Promise<void>;
     /**
@@ -164,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: {
@@ -178,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. */
@@ -214,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.
@@ -244,16 +261,6 @@ export declare class SessionManager {
      * Opened Session follow streams resume independently through API Gateway.
      */
     handleConnected(): void;
-    /** Debounce membership refetches for an explicitly consumed catalog. */
-    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;
     private buildListSnapshot;
 }
 //# sourceMappingURL=manager.d.ts.map