@deepseek-ai/dsh-api-session-controller 0.2.1-alpha.1 → 0.2.1-alpha.3

package/lib/types/agent.d.ts

@@ -21,12 +21,38 @@ export declare class ApiSessionCwdConflict extends Error {
     readonly existingCwd: string | undefined;
     constructor(sessionId: SessionId, requestedCwd: string, existingCwd: string | undefined);
 }
-/** Explicit-id creation attempted to adopt a Session under another preset. */
+/** Reuse of a Session named an Agent preset while the deployment composes no preset roster. */
 export declare class ApiSessionPresetConflict extends Error {
     readonly sessionId: SessionId;
     readonly requestedPreset: string;
-    readonly existingPreset: string | undefined;
-    constructor(sessionId: SessionId, requestedPreset: string, existingPreset: string | undefined);
+    constructor(sessionId: SessionId, requestedPreset: string);
+}
+/** Placement and Agent preset for one Session created for a new conversation. */
+export interface ApiSessionCreateRequest {
+    /** Blank Session to reuse, or the identity of a new Session when none is stored under it. */
+    readonly sessionId?: SessionId;
+    /** Directory the Session owns. */
+    readonly cwd: string;
+    /** Preset the Session runs; the configured default when omitted. */
+    readonly agentPreset?: string;
+    /**
+     * Placement rule the caller owns, such as Workspace membership and archive state.
+     * @param sessionId - existing Session named by the request.
+     * @returns whether that Session may be reused.
+     */
+    readonly reusable: (sessionId: SessionId) => boolean;
+}
+/** The Session one creation request created or reused. */
+export interface ApiSessionCreated {
+    /** Live Agent of the Session. */
+    readonly agent: Agent;
+    /** Preset the Session ran when the request finished, before a later request for the same identity; absent without a roster. */
+    readonly agentPreset: string | undefined;
+}
+/** Resolved preset and pre-publication Agent setup for one create or resume. */
+interface ApiSessionComposition {
+    readonly agentPreset?: string;
+    readonly setup: AgentSetup;
 }
 /** Failures produced while resolving one ordinary Session identity to its live Agent. */
 export type ApiSessionAgentError = RemoteError<'session/not-found' | 'session/agent-busy' | 'session/writer-held' | 'gateway/internal'>;
@@ -66,7 +92,7 @@ export declare function inspectApiSession(ctx: Context, sessionId: SessionId, si
 export declare class ApiSessionAgentController {
     private readonly ctx;
     private readonly resumes;
-    private readonly creations;
+    private readonly claims;
     private readonly selections;
     private readonly imageAdmissionChains;
     /** @param ctx - Host context carrying Agent, model, persistence, and Typert services. */
@@ -85,14 +111,23 @@ export declare class ApiSessionAgentController {
     resolveObservedAgent(observation: SessionObservation): Promise<ApiSessionAgentResult>;
     private resolve;
     /**
-     * Resolve one requested identity, creating or resuming it once.
-     * @param sessionId - requested Session identity.
-     * @param cwd - directory the Session must own.
-     * @param checkPersistedIdentity - whether to inspect a cold identity before creation.
-     * @param presetId - optional Agent preset the Session must own.
-     * @returns the matching live ordinary Agent.
+     * Create a Session for a new conversation, reusing the named blank Session
+     * while it is still reusable. A reused Session runs the requested preset, or
+     * the configured default when the request names none; the preset it recorded
+     * is not resolved, and a change is logged as `agent-preset/selected` before
+     * the Agent is published. A named Session that has started a turn, fails the
+     * caller's placement rule, or is written by another owner stays unchanged,
+     * and a new Session is created instead. Requests naming one identity run in
+     * arrival order, including their preset resolution, and check the named
+     * Session's directory and ownership before resolving the preset.
+     * @param request - optional Session to reuse, directory, preset, and placement rule.
+     * @returns the reused or created Session and the preset it ran when this request finished.
+     * @throws ApiSessionCwdConflict when the named Session belongs to another directory.
+     * @throws ApiSessionSubagentOwnership when subagent routing owns the named Session.
+     * @throws RemoteError `agent-preset/not-found` or `agent-preset/invalid` for the requested or default preset.
+     * @throws ApiSessionPresetConflict when no roster is composed and the request names a preset for a reused Session.
      */
-    ensureSession(sessionId: SessionId, cwd: string, checkPersistedIdentity: boolean, presetId?: string): Promise<Agent>;
+    createSession(request: ApiSessionCreateRequest): Promise<ApiSessionCreated>;
     /**
      * Install or return the Session-local model selection used by prompt assembly.
      * @param agent - live Agent that owns the selection.
@@ -132,14 +167,24 @@ export declare class ApiSessionAgentController {
      * @param presetId - requested preset or the configured default when omitted.
      * @returns the resolved preset identity and Agent setup callback.
      */
-    composeAgent(presetId: string | undefined): Promise<{
-        readonly agentPreset?: string;
-        readonly setup: AgentSetup;
-    }>;
+    composeAgent(presetId: string | undefined): Promise<ApiSessionComposition>;
     private liveAgent;
     private resume;
     private resumeObserved;
-    private createOrAdopt;
+    private inOrder;
+    /** @returns the reused Session, a new Session under `sessionId` when none is stored, or a new Session under a minted identity. */
+    private claim;
+    /** @returns the live blank Session under the requested preset, or undefined when it cannot be reused. */
+    private reuseLive;
+    /** Setup that re-checks blankness under the acquired writer, then records a preset change before publication. */
+    private reuseSetup;
+    /** Whether no turn has started, by the predicate the preset registry's `select` enforces. */
+    private isBlank;
+    /** Without a roster, reuse cannot apply a named preset. */
+    private assertPresetApplicable;
+    private created;
+    private createMinted;
+    private createAgent;
     private agentOptions;
     private installSelection;
     /**
@@ -148,7 +193,6 @@ export declare class ApiSessionAgentController {
      * @returns the current preset, or undefined when the capability is absent.
      */
     presetForObservation(observation: SessionObservation): string | undefined;
-    private assertPresetUnchanged;
 }
 export {};
 //# sourceMappingURL=agent.d.ts.map

package/lib/types/agent.js

@@ -51,11 +51,13 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
+import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
 import { installModelSelection } from '@deepseek-ai/dsh-agent';
+import { brandString } from '@deepseek-ai/dsh-brand';
 import { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
-import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+import { RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol';
 /** Cold Session identity absent from persistence. */
 export class ApiSessionNotFound extends Error {
 }
@@ -82,20 +84,19 @@ export class ApiSessionCwdConflict extends Error {
         this.existingCwd = existingCwd;
     }
 }
-/** Explicit-id creation attempted to adopt a Session under another preset. */
+/** Reuse of a Session named an Agent preset while the deployment composes no preset roster. */
 export class ApiSessionPresetConflict extends Error {
     sessionId;
     requestedPreset;
-    existingPreset;
-    constructor(sessionId, requestedPreset, existingPreset) {
-        super(existingPreset === undefined
-            ? `session "${sessionId}" records no agent preset and cannot be adopted under "${requestedPreset}"`
-            : `session "${sessionId}" runs agent preset "${existingPreset}", not "${requestedPreset}"`);
+    constructor(sessionId, requestedPreset) {
+        super(`the deployment composes no agent preset roster, so session "${sessionId}" cannot run preset "${requestedPreset}"`);
         this.sessionId = sessionId;
         this.requestedPreset = requestedPreset;
-        this.existingPreset = existingPreset;
     }
 }
+/** A blank Session chosen for reuse started a turn before this Host acquired its writer. */
+class ApiSessionStartedSinceObserved extends Error {
+}
 /**
  * Test whether generic Session routing must leave an identity to subagent routing.
  * @param ctx - Host context carrying the Agent ownership registry.
@@ -164,7 +165,7 @@ export async function inspectApiSession(ctx, sessionId, signal) {
 export class ApiSessionAgentController {
     ctx;
     resumes = new Map();
-    creations = new Map();
+    claims = new Map();
     selections = new WeakMap();
     imageAdmissionChains = new WeakMap();
     /** @param ctx - Host context carrying Agent, model, persistence, and Typert services. */
@@ -248,45 +249,27 @@ export class ApiSessionAgentController {
         }
     }
     /**
-     * Resolve one requested identity, creating or resuming it once.
-     * @param sessionId - requested Session identity.
-     * @param cwd - directory the Session must own.
-     * @param checkPersistedIdentity - whether to inspect a cold identity before creation.
-     * @param presetId - optional Agent preset the Session must own.
-     * @returns the matching live ordinary Agent.
+     * Create a Session for a new conversation, reusing the named blank Session
+     * while it is still reusable. A reused Session runs the requested preset, or
+     * the configured default when the request names none; the preset it recorded
+     * is not resolved, and a change is logged as `agent-preset/selected` before
+     * the Agent is published. A named Session that has started a turn, fails the
+     * caller's placement rule, or is written by another owner stays unchanged,
+     * and a new Session is created instead. Requests naming one identity run in
+     * arrival order, including their preset resolution, and check the named
+     * Session's directory and ownership before resolving the preset.
+     * @param request - optional Session to reuse, directory, preset, and placement rule.
+     * @returns the reused or created Session and the preset it ran when this request finished.
+     * @throws ApiSessionCwdConflict when the named Session belongs to another directory.
+     * @throws ApiSessionSubagentOwnership when subagent routing owns the named Session.
+     * @throws RemoteError `agent-preset/not-found` or `agent-preset/invalid` for the requested or default preset.
+     * @throws ApiSessionPresetConflict when no roster is composed and the request names a preset for a reused Session.
      */
-    async ensureSession(sessionId, cwd, checkPersistedIdentity, presetId) {
-        let creation = this.creations.get(sessionId);
-        if (creation === undefined) {
-            creation = this.createOrAdopt(sessionId, cwd, checkPersistedIdentity, presetId)
-                .catch((error) => {
-                const live = this.ctx.agents.get(sessionId);
-                if (live !== undefined) {
-                    if (hasApiSessionSubagentOwner(this.ctx, live.session, live)) {
-                        throw new ApiSessionSubagentOwnership(sessionId);
-                    }
-                    return live;
-                }
-                const attached = this.ctx.sessions.get(sessionId);
-                if (attached !== undefined && hasApiSessionSubagentOwner(this.ctx, attached, undefined)) {
-                    throw new ApiSessionSubagentOwnership(sessionId);
-                }
-                throw error;
-            })
-                .finally(() => { this.creations.delete(sessionId); });
-            this.creations.set(sessionId, creation);
-        }
-        const agent = await creation;
-        if (hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) {
-            throw new ApiSessionSubagentOwnership(sessionId);
-        }
-        if (presetId !== undefined) {
-            this.assertPresetUnchanged(sessionId, presetId, this.presetForSession(agent.session));
-        }
-        if (agent.session.header.cwd !== cwd) {
-            throw new ApiSessionCwdConflict(sessionId, cwd, agent.session.header.cwd);
-        }
-        return agent;
+    async createSession(request) {
+        const named = request.sessionId;
+        if (named === undefined)
+            return this.created(await this.createMinted(request.cwd, await this.composeAgent(request.agentPreset)));
+        return this.inOrder(named, async () => this.created(await this.claim(named, request)));
     }
     /**
      * Install or return the Session-local model selection used by prompt assembly.
@@ -451,55 +434,141 @@ export class ApiSessionAgentController {
             setup: composition.setup,
         })).agent;
     }
-    async createOrAdopt(sessionId, cwd, checkPersistedIdentity, presetId) {
+    async inOrder(sessionId, operation) {
+        const result = (this.claims.get(sessionId) ?? Promise.resolve()).then(operation);
+        const settled = result.then(() => undefined, () => undefined);
+        this.claims.set(sessionId, settled);
+        try {
+            return await result;
+        }
+        finally {
+            if (this.claims.get(sessionId) === settled)
+                this.claims.delete(sessionId);
+        }
+    }
+    /** @returns the reused Session, a new Session under `sessionId` when none is stored, or a new Session under a minted identity. */
+    async claim(sessionId, request) {
         const attached = this.ctx.sessions.get(sessionId);
         const live = this.ctx.agents.get(sessionId);
         if (attached !== undefined && hasApiSessionSubagentOwner(this.ctx, attached, live)) {
             throw new ApiSessionSubagentOwnership(sessionId);
         }
-        if (live !== undefined)
-            return live;
-        if (checkPersistedIdentity) {
+        if (live !== undefined) {
+            if (live.session.header.cwd !== request.cwd) {
+                throw new ApiSessionCwdConflict(live.id, request.cwd, live.session.header.cwd);
+            }
+            const composition = await this.composeAgent(request.agentPreset);
+            return await this.reuseLive(live, request, composition) ?? this.createMinted(request.cwd, composition);
+        }
+        let observation;
+        try {
+            observation = await this.ctx.sessionQuery.observeSession(sessionId);
+        }
+        catch (error) {
+            if (!(error instanceof SessionQueryError) || error.code !== 'SESSION_QUERY_SESSION_NOT_FOUND')
+                throw error;
+            return this.createAgent(sessionId, request.cwd, await this.composeAgent(request.agentPreset));
+        }
+        let reusable;
+        {
+            const env_3 = { stack: [], error: void 0, hasError: false };
             try {
-                const env_3 = { stack: [], error: void 0, hasError: false };
-                try {
-                    const observation = __addDisposableResource(env_3, await this.ctx.sessionQuery.observeSession(sessionId), false);
-                    if (hasApiSessionSubagentOwner(this.ctx, { header: observation.header }, undefined)) {
-                        throw new ApiSessionSubagentOwnership(sessionId);
-                    }
-                    if (observation.header.cwd !== cwd) {
-                        throw new ApiSessionCwdConflict(sessionId, cwd, observation.header.cwd);
-                    }
-                    const storedPreset = this.presetForObservation(observation);
-                    this.assertPresetUnchanged(sessionId, presetId, storedPreset);
-                    const composition = await this.composeAgent(storedPreset);
-                    return (await this.ctx.agents.resume({
-                        resumeSessionId: sessionId,
-                        agentOptions: this.agentOptions(),
-                        setup: composition.setup,
-                    })).agent;
-                }
-                catch (e_3) {
-                    env_3.error = e_3;
-                    env_3.hasError = true;
+                const observed = __addDisposableResource(env_3, observation, false);
+                if (hasApiSessionSubagentOwner(this.ctx, { header: observed.header }, undefined)) {
+                    throw new ApiSessionSubagentOwnership(sessionId);
                 }
-                finally {
-                    __disposeResources(env_3);
+                if (observed.header.cwd !== request.cwd) {
+                    throw new ApiSessionCwdConflict(sessionId, request.cwd, observed.header.cwd);
                 }
+                reusable = request.reusable(sessionId) && !observed.events.some(event => event.type === 'turn/start');
+            }
+            catch (e_3) {
+                env_3.error = e_3;
+                env_3.hasError = true;
             }
-            catch (error) {
-                if (!(error instanceof SessionQueryError)
-                    || error.code !== 'SESSION_QUERY_SESSION_NOT_FOUND')
-                    throw error;
+            finally {
+                __disposeResources(env_3);
             }
         }
+        const composition = await this.composeAgent(request.agentPreset);
+        if (!reusable)
+            return this.createMinted(request.cwd, composition);
+        this.assertPresetApplicable(sessionId, request.agentPreset);
+        try {
+            return (await this.ctx.agents.resume({
+                resumeSessionId: sessionId,
+                agentOptions: this.agentOptions(),
+                setup: this.reuseSetup(composition),
+            })).agent;
+        }
+        catch (error) {
+            if (error instanceof ApiSessionStartedSinceObserved)
+                return this.createMinted(request.cwd, composition);
+            if (!(error instanceof Error) || error.name !== 'SessionAlreadyOwnedError')
+                throw error;
+            // Another resume in this process may hold the writer for the Agent it published.
+            return this.ctx.agents.get(sessionId) === undefined
+                ? this.createMinted(request.cwd, composition)
+                : this.claim(sessionId, request);
+        }
+    }
+    /** @returns the live blank Session under the requested preset, or undefined when it cannot be reused. */
+    async reuseLive(live, request, composition) {
+        if (!request.reusable(live.id) || !this.isBlank(live.session))
+            return undefined;
+        this.assertPresetApplicable(live.id, request.agentPreset);
+        const current = this.presetForSession(live.session);
+        const presets = this.ctx.get('agentPresets');
+        const target = composition.agentPreset;
+        if (presets === undefined || target === undefined || target === current)
+            return live;
+        try {
+            await presets.select(live, target);
+        }
+        catch (error) {
+            if (remoteErrorOf(error)?.code !== 'agent-preset/locked')
+                throw error;
+            return undefined;
+        }
+        return live;
+    }
+    /** Setup that re-checks blankness under the acquired writer, then records a preset change before publication. */
+    reuseSetup(composition) {
+        return async (agentCtx, agent) => {
+            if (!this.isBlank(agent.session))
+                throw new ApiSessionStartedSinceObserved();
+            const commit = await composition.setup(agentCtx, agent);
+            const target = composition.agentPreset;
+            if (target !== undefined && this.presetForSession(agent.session) !== target) {
+                agent.session.append('agent-preset/selected', { agentPreset: target });
+            }
+            return commit;
+        };
+    }
+    /** Whether no turn has started, by the predicate the preset registry's `select` enforces. */
+    isBlank(session) {
+        const boundary = this.ctx.sessionProjections.stateOf(session, 'turnBoundary');
+        return boundary === undefined || (boundary.openTurnStartSeq === null && boundary.lastTurn === 0);
+    }
+    /** Without a roster, reuse cannot apply a named preset. */
+    assertPresetApplicable(sessionId, requested) {
+        if (requested === undefined || this.ctx.get('agentPresets') !== undefined)
+            return;
+        throw new ApiSessionPresetConflict(sessionId, requested);
+    }
+    created(agent) {
+        return { agent, agentPreset: this.presetForSession(agent.session) };
+    }
+    createMinted(cwd, composition) {
+        return this.createAgent(brandString(`session-${randomUUID()}`), cwd, composition);
+    }
+    async createAgent(sessionId, cwd, composition) {
         try {
             await mkdir(cwd, { recursive: true });
         }
         catch (error) {
             throw new Error(`failed to ensure project directory "${cwd}": ${String(error)}`, { cause: error });
         }
-        const composition = await this.composeAgent(presetId);
         return (await this.ctx.agents.create({
             sessionId,
             agentOptions: this.agentOptions(),
@@ -528,11 +597,6 @@ export class ApiSessionAgentController {
         }
         return observation.projections.values.agentPreset ?? undefined;
     }
-    assertPresetUnchanged(sessionId, requested, existing) {
-        if (requested === undefined || requested === existing)
-            return;
-        throw new ApiSessionPresetConflict(sessionId, requested, existing);
-    }
 }
 function agentModelSelection(selection) {
     return {

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

@@ -73,23 +73,26 @@ export interface ISessions {
      */
     readonly searchResultLimit: number;
     /**
-     * Create or adopt a Session on the Host.
-     * @param opts - target workspace, directory, and optional preallocated identity.
-     * @returns the catalogued identity; retain it before borrowing its binding.
+     * Create a Session for a new conversation on the Host. The Host reuses the
+     * named blank Session while it is reusable and otherwise creates another; the
+     * Session runs the named preset, or the Host default when none is named.
+     * @param opts - target workspace or directory, an optional blank Session to reuse, and an optional Agent preset.
+     * @returns the catalogued identity the Host created or reused; retain it before borrowing its binding.
      */
     create(opts?: {
         workspaceId?: WorkspaceId;
         cwd?: string;
         sessionId?: SessionId;
+        agentPreset?: string;
     }): Promise<SessionId>;
     /**
      * Resolve an already discovered direct-parent address without opening it.
      * @param id - possible addressed child id.
-     * @returns a retained or loaded-catalog address, without retaining a new selection or scope.
+     * @returns a retained, catalog-derived, or unknown-mode listed address, without retaining a new selection or scope.
      */
     subagentAddress(id: SessionId): SubagentAddress | undefined;
     /**
-     * Load all Session projections once per connection; retry an unsuccessful initial read.
+     * Read projections without starting migration; retry failed or migration-deferred reads.
      * @param sessionId - Session to inspect without opening its conversation.
      * @returns completion of the current or newly started refresh.
      */
@@ -126,6 +129,8 @@ export interface ISessions {
         atSeq?: number;
         increaseTitle?: boolean;
         onCreated?: (childId: SessionId) => void;
+        /** False refuses source migration; omission preserves the Host default. */
+        allowMigration?: boolean;
     }): Promise<SessionId>;
     /**
      * Borrow an already-retained Agent-scoped Context without extending its lifetime.

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

@@ -21,6 +21,8 @@ export interface SessionListEntry {
     parentSessionId?: SessionId;
     /** Coarse durable origin for navigation filtering; not a continuation capability. */
     origin?: 'subagent';
+    /** Format classification supplied by the Host list. */
+    formatStatus?: SessionSummary['formatStatus'];
     cwd?: string;
     /** Current host-computed projection values for list consumers. */
     projectionValues?: Readonly<Partial<SessionProjectionMap>>;

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

@@ -35,7 +35,7 @@ export interface SessionListSnapshot {
 /** 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 state: 'idle' | 'loading' | 'ready' | 'migration-required' | 'error';
     readonly error: RemoteFailure | null;
 }
 /** Instance cluster + frame entry + the session list. */
@@ -86,8 +86,9 @@ export declare class SessionManager {
     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.
+     * @param sessionId - possible child id in received Session metadata.
+     * @returns A retained address, then a catalog address, then an unknown-mode address
+     *   from a listed subagent header; undefined without that evidence.
      */
     subagentAddress(sessionId: SessionId): SubagentAddress | undefined;
     /**
@@ -130,7 +131,7 @@ export declare class SessionManager {
     /** Resident per-session projection store (create-on-demand; outlives instantiation). */
     private projectionStore;
     /**
-     * Load a complete projection baseline once per connection; retry unsuccessful reads.
+     * Read projections without starting migration; retry failed or migration-deferred reads.
      * @param sessionId - Session to inspect without opening its conversation.
      * @returns completion of the current or newly started read.
      */
@@ -154,13 +155,14 @@ export declare class SessionManager {
      * 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.
+     * @param opts - target workspace or working directory, an optional blank Session to reuse, and an optional Agent preset.
+     * @returns the create result, naming the Session the Host created or reused.
     */
     create(opts?: {
         workspaceId?: WorkspaceId;
         cwd?: string;
         sessionId?: SessionId;
+        agentPreset?: string;
     }): Promise<RemoteResult<{
         sessionId: SessionId;
     }>>;
@@ -171,12 +173,13 @@ export declare class SessionManager {
      * 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.
+     * @param opts - source session, optional exact inclusive boundary seq, and permission to start migration.
      * @returns the fork result (the child session id).
      */
     fork(opts: {
         sessionId: SessionId;
         atSeq?: SessionSeq;
+        allowMigration?: boolean;
     }): Promise<RemoteResult<{
         sessionId: SessionId;
     }>>;