@deepseek-ai/dsh-api-session-controller 0.1.5-rc.2 → 0.1.6-alpha.2

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

@@ -3,7 +3,7 @@ import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-atta
 import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client';
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand';
 import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types';
-import type { PromptContentPart, QueueAction, SessionControlFrame, SessionQueuedItem, SessionRequestId } from '../../types.ts';
+import type { PromptContentPart, QueueAction, SessionRequestId } from '../../types.ts';
 import type { BeginSubmissionInput, SessionFace, SubmissionHandle } from '../contract/session.ts';
 import type { SessionSnapshot } from '../contract/snapshot.ts';
 import { MutableSessionEventSource } from '../contract/events.ts';
@@ -59,8 +59,7 @@ export declare class Session implements SessionFace {
     private jumpTargetSeq;
     /** The running jump loop's completion, shared by retargeting callers. */
     private jumpPromise;
-    /** Authoritative stream-only inbox snapshot; pending work never hits history. */
-    private readonly queueMirror;
+    private readonly stopObservingInbox;
     private readonly assistantStream;
     private running;
     private address;
@@ -81,7 +80,7 @@ export declare class Session implements SessionFace {
     /** Local submission echoes, insertion-ordered (see SessionSnapshot.pendingSubmissions). */
     private pendingSubmissions;
     /** Per-echo settlement state; `retiring` latches the first observation so a
-     *  queue frame and its durable event cannot both retire one echo. */
+     *  Inbox projection and its durable event cannot both retire one echo. */
     private readonly submissionSettlements;
     /** Owns the addressed page/follow lifecycle while this Session is open. */
     private events;
@@ -199,7 +198,7 @@ export declare class Session implements SessionFace {
     /** Jump loader: page backwards until the window covers seq (see ISession.loadThrough). */
     loadThrough(seq: SessionSeq): Promise<void>;
     /** Rebuild an opened history source after address replacement.
-     *  Invalidates any in-flight open first; queue state belongs to the independently
+     *  Invalidates any in-flight open first; projection state belongs to the independently
      *  reconnecting control stream and remains untouched. */
     resync(): Promise<void>;
     /**
@@ -213,18 +212,6 @@ export declare class Session implements SessionFace {
      * @returns the cached reference (stable until the next flush).
      */
     getSnapshot(): SessionSnapshot;
-    /**
-     * Replace every transient control value for this Session from one stream baseline.
-     * @param queue - complete pending queue for this Session.
-     */
-    replaceControl(queue: readonly SessionQueuedItem[]): void;
-    /**
-     * Apply one Session-addressed live control update.
-     * @param frame - queue replacement addressed to this Session.
-     */
-    handleControlFrame(frame: Extract<SessionControlFrame, {
-        type: 'queue';
-    }>): void;
     /**
      * Running-bit relay from the host stream (list entry and snapshot stay consistent).
      * @param running - the new running state.
@@ -273,10 +260,10 @@ export declare class Session implements SessionFace {
     private prependWindow;
     /** Append one stream-validated live event. */
     private appendLive;
-    /** Retire the matching echo when a durable browser-prompt `user/message` becomes visible. */
+    /** Observe durable acceptance even when insertion and claim share one projection notification. */
     private observeSubmissionEvent;
-    /** Retire echoes whose prompts landed in the host inbox instead of the log (running-turn submissions). */
-    private observeSubmissionQueue;
+    /** Retire local echoes when their accepted messages appear in the durable Inbox projection. */
+    private observeSubmissionInbox;
     /**
      * Latch one observed settlement and remove the echo an animation frame
      * later. The delay keeps the echo in the snapshot until the frame in which

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

@@ -8,7 +8,6 @@ import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client';
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
 import { ProjectionValueStore } from "./projection-store.js";
 import { resolvedClientTimeZone } from "../time-zone.js";
-import { SessionQueueMirror } from "./queue-mirror.js";
 import { ClientAssistantStream, } from "./assistant-stream.js";
 function projectionsBaseline(value) {
     return {
@@ -44,8 +43,7 @@ export class Session {
     jumpTargetSeq = null;
     /** The running jump loop's completion, shared by retargeting callers. */
     jumpPromise = null;
-    /** Authoritative stream-only inbox snapshot; pending work never hits history. */
-    queueMirror = new SessionQueueMirror();
+    stopObservingInbox;
     assistantStream = new ClientAssistantStream();
     running = false;
     address;
@@ -66,7 +64,7 @@ export class Session {
     /** Local submission echoes, insertion-ordered (see SessionSnapshot.pendingSubmissions). */
     pendingSubmissions = [];
     /** Per-echo settlement state; `retiring` latches the first observation so a
-     *  queue frame and its durable event cannot both retire one echo. */
+     *  Inbox projection and its durable event cannot both retire one echo. */
     submissionSettlements = new Map();
     /** Owns the addressed page/follow lifecycle while this Session is open. */
     events;
@@ -111,6 +109,9 @@ export class Session {
             this.snapshotCache = this.buildSnapshot();
         });
         this.snapshotCache = this.buildSnapshot();
+        this.stopObservingInbox = this.projections.faceOf('inbox').subscribe(() => {
+            this.observeSubmissionInbox();
+        });
     }
     /**
      * Bind the Agent-scoped context minted by ClientSessions (single write;
@@ -384,7 +385,7 @@ export class Session {
         return this.jumpPromise;
     }
     /** Rebuild an opened history source after address replacement.
-     *  Invalidates any in-flight open first; queue state belongs to the independently
+     *  Invalidates any in-flight open first; projection state belongs to the independently
      *  reconnecting control stream and remains untouched. */
     async resync() {
         if (this.openState === 'cold')
@@ -418,24 +419,6 @@ export class Session {
         return this.snapshotCache;
     }
     // ---- Manager-only entry points (@internal; never called by the UI) ----
-    /**
-     * Replace every transient control value for this Session from one stream baseline.
-     * @param queue - complete pending queue for this Session.
-     */
-    replaceControl(queue) {
-        this.queueMirror.replace(queue);
-        this.observeSubmissionQueue(queue);
-        this.notifier.markDirty();
-    }
-    /**
-     * Apply one Session-addressed live control update.
-     * @param frame - queue replacement addressed to this Session.
-     */
-    handleControlFrame(frame) {
-        this.queueMirror.replace(frame.items);
-        this.observeSubmissionQueue(frame.items);
-        this.notifier.markDirty();
-    }
     /**
      * Running-bit relay from the host stream (list entry and snapshot stay consistent).
      * @param running - the new running state.
@@ -514,6 +497,7 @@ export class Session {
      * @returns when the Remote iterator has completed teardown.
      */
     async dispose() {
+        this.stopObservingInbox();
         // Unsettled echoes retire as failed so their owners can restore or
         // release browser resources; echoes already scheduled as observed keep
         // that settlement.
@@ -635,17 +619,26 @@ export class Session {
         const awaitingFirstTurn = this.firstPromptPendingTurn;
         if (event.type === 'turn/start')
             this.firstPromptPendingTurn = false;
-        const queueChanged = this.queueMirror.acceptDurable(event);
         this.eventSource.append(entry);
         // After the feed append: the conversation assembly's animation frame is
         // registered by the feed subscribers above, so the echo-retirement frame
         // scheduled here always runs after the durable node became renderable.
         this.observeSubmissionEvent(event);
-        return queueChanged || awaitingFirstTurn !== this.firstPromptPendingTurn;
+        return awaitingFirstTurn !== this.firstPromptPendingTurn;
     }
-    /** Retire the matching echo when a durable browser-prompt `user/message` becomes visible. */
+    /** Observe durable acceptance even when insertion and claim share one projection notification. */
     observeSubmissionEvent(event) {
-        if (this.submissionSettlements.size === 0 || event.type !== 'user/message')
+        if (this.submissionSettlements.size === 0)
+            return;
+        if (event.type === 'agent/inbox/spliced') {
+            const splice = event.data;
+            if (Array.isArray(splice?.inserted)) {
+                for (const message of splice.inserted)
+                    this.observeSubmissionEvent({ type: 'user/message', data: message });
+            }
+            return;
+        }
+        if (event.type !== 'user/message')
             return;
         // Structural read: window entries may be compact history records, so the
         // fields are narrowed rather than trusted (same posture as Conversation
@@ -656,13 +649,17 @@ export class Session {
             return;
         this.scheduleObservedRetirement(source.rpcId, attachmentRefsIn(data?.content));
     }
-    /** Retire echoes whose prompts landed in the host inbox instead of the log (running-turn submissions). */
-    observeSubmissionQueue(items) {
+    /** Retire local echoes when their accepted messages appear in the durable Inbox projection. */
+    observeSubmissionInbox() {
         if (this.submissionSettlements.size === 0)
             return;
-        for (const item of items) {
-            if (item.rpcId !== undefined) {
-                this.scheduleObservedRetirement(item.rpcId, attachmentRefsIn(item.message.content));
+        const inbox = this.projections.get('inbox');
+        if (inbox === undefined)
+            return;
+        for (const message of [...inbox['next-turn'], ...inbox['next-step']]) {
+            const source = message.source;
+            if (source.kind === 'user' && 'rpcId' in source) {
+                this.scheduleObservedRetirement(source.rpcId, attachmentRefsIn(message.content));
             }
         }
     }
@@ -715,7 +712,6 @@ export class Session {
     buildSnapshot() {
         return {
             sessionId: this.sessionId,
-            queue: this.queueMirror.snapshot(),
             pendingSubmissions: this.pendingSubmissions,
             running: this.running,
             subagent: this.address === undefined

package/lib/types/client/time-zone.d.ts

@@ -1,4 +1,4 @@
-/** Browser-owned time-zone sampling for prompt RPC provenance. */
+/** Browser-owned time-zone sampling for one prompt RPC. */
 /**
  * Resolve the current browser IANA zone for one outbound operation.
  * @returns The browser-provided canonical zone.

package/lib/types/client/time-zone.js

@@ -1,4 +1,4 @@
-/** Browser-owned time-zone sampling for prompt RPC provenance. */
+/** Browser-owned time-zone sampling for one prompt RPC. */
 /**
  * Resolve the current browser IANA zone for one outbound operation.
  * @returns The browser-provided canonical zone.

package/lib/types/commands.d.ts

@@ -50,11 +50,11 @@ export declare class SessionCommandController {
      */
     attachment(request: SessionAttachmentRequest): Promise<SessionAttachmentValue>;
     /**
-     * Mutate one still-pending queue occurrence without resuming a cold Agent.
+     * Mutate one pending Inbox occurrence, restoring an ordinary cold Agent when needed.
      * @param request - Session, queue item, and requested mutation.
      * @returns acknowledgement that the queue mutation was applied.
      */
-    updateQueue(request: SessionUpdateQueueRequest): SessionUpdateQueueValue;
+    updateQueue(request: SessionUpdateQueueRequest): Promise<SessionUpdateQueueValue>;
     /**
      * Cancel one live ordinary Agent while retaining pending inbox work.
      * @param request - Session whose active Agent turn is cancelled.

package/lib/types/commands.js

@@ -221,10 +221,7 @@ export class SessionCommandController {
                     ? `session "${request.sessionId}" has not completed the turn containing event ${String(atSeq)}`
                     : `session "${request.sessionId}" has no completed turn to fork from`, { sessionId: request.sessionId });
             }
-            let cut = SessionLogOffset(boundary.seq + 1);
-            while (cut < source.events.length && source.events[cut]?.type !== 'turn/start') {
-                cut = SessionLogOffset(cut + 1);
-            }
+            const cut = SessionLogOffset(boundary.seq + 1);
             let workspace;
             try {
                 workspace = await this.forkWorkspace(source.header);
@@ -380,11 +377,11 @@ export class SessionCommandController {
         }
     }
     /**
-     * Mutate one still-pending queue occurrence without resuming a cold Agent.
+     * Mutate one pending Inbox occurrence, restoring an ordinary cold Agent when needed.
      * @param request - Session, queue item, and requested mutation.
      * @returns acknowledgement that the queue mutation was applied.
      */
-    updateQueue(request) {
+    async updateQueue(request) {
         if (request.action.kind === 'edit') {
             if (request.action.content.some(block => block.type !== 'text')) {
                 throw new RemoteError('session/attachment-invalid', 'queue edits accept text content only', { reason: 'QUEUE_EDIT_NON_TEXT' });
@@ -393,9 +390,15 @@ export class SessionCommandController {
                 throw new RemoteError('gateway/bad-request', 'queue edit content must include non-whitespace text', {});
             }
         }
-        const agent = this.ctx.agents.get(request.sessionId);
+        let agent = this.ctx.agents.get(request.sessionId);
         if (agent === undefined) {
-            throw new RemoteError('session/queue-item-not-found', 'queued item is no longer pending', { itemId: request.itemId });
+            const found = await this.agents.resolveAgent(request.sessionId);
+            if ('error' in found) {
+                if (found.error.code !== 'session/not-found')
+                    throw found.error;
+                throw new RemoteError('session/queue-item-not-found', 'queued item is no longer pending', { itemId: request.itemId });
+            }
+            agent = found.agent;
         }
         if (hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) {
             const identity = this.ctx.sessionProjections
@@ -490,6 +493,7 @@ export class SessionCommandController {
     async readSessionState(sessionId) {
         const attached = this.ctx.sessions.get(sessionId);
         if (attached !== undefined) {
+            // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
             return { id: attached.id, header: attached.header, events: attached.snapshotEvents() };
         }
         const inspected = await inspectApiSession(this.ctx, sessionId);
@@ -530,6 +534,7 @@ function hasPromptRequest(agent, requestId) {
     };
     if (agent.inbox.nextTurn.some(matches) || agent.inbox.nextStep.some(matches))
         return true;
+    // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
     return agent.session.snapshotEvents().some((event) => {
         if (event.type !== 'user/message')
             return false;

package/lib/types/control.d.ts

@@ -1,4 +1,4 @@
-/** Live Session queue, jobs, and projection state with reconnect baselines. */
+/** Live Session jobs and projection state with reconnect baselines. */
 import type { Context } from '@deepseek-ai/cordis';
 import type { SessionControlFrame } from './types.ts';
 /** Owns the Host-wide Session control stream. */

package/lib/types/control.js

@@ -1,4 +1,4 @@
-/** Live Session queue, jobs, and projection state with reconnect baselines. */
+/** Live Session jobs and projection state with reconnect baselines. */
 import { Deque } from '@deepseek-ai/dsh-deque';
 /** Owns the Host-wide Session control stream. */
 export class SessionControlController {
@@ -15,16 +15,6 @@ export class SessionControlController {
                 value: value,
                 seq,
             });
-            if (key !== 'inbox')
-                return;
-            const agent = this.ctx.agents.get(session.id);
-            if (agent?.session !== session)
-                return;
-            this.broadcast({
-                type: 'queue',
-                sessionId: session.id,
-                items: queueItemsFromInbox(value),
-            });
         });
         ctx.inject(['jobs'], (jobsCtx) => {
             jobsCtx.jobs.onJobsChanged((owner) => { this.onJobsChanged(owner); });
@@ -60,15 +50,12 @@ export class SessionControlController {
     }
     baseline() {
         const sessions = this.ctx.sessions.list();
-        const queues = Object.create(null);
         const jobs = Object.create(null);
         for (const session of sessions) {
             const agent = this.ctx.agents.get(session.id);
-            queues[session.id] = agent?.session === session ? queueItems(agent) : [];
             jobs[session.id] = this.jobsFor(agent);
         }
         return {
-            queues,
             jobs,
             projections: this.projectionBaseline(sessions),
         };
@@ -148,33 +135,6 @@ class ControlQueue {
         }
     }
 }
-function queueItems(agent) {
-    return queueItemsFromInbox({
-        'next-turn': agent.inbox.nextTurn,
-        'next-step': agent.inbox.nextStep,
-    });
-}
-function queueItemsFromInbox(inbox) {
-    return [
-        ...inbox['next-turn'].map(message => ({
-            id: message.id,
-            placement: 'queued',
-            ...promptRpcId(message),
-            message: { id: message.id, content: message.content },
-        })),
-        ...inbox['next-step'].map(message => ({
-            id: message.id,
-            placement: message.source.kind === 'user' ? 'steering' : 'context',
-            ...promptRpcId(message),
-            message: { id: message.id, content: message.content },
-        })),
-    ];
-}
-/** Prompt-RPC identity carried by a browser-submitted message's user source. */
-function promptRpcId(message) {
-    const source = message.source;
-    return source.kind === 'user' && 'rpcId' in source ? { rpcId: source.rpcId } : {};
-}
 function jobView(job) {
     return {
         id: job.id,

package/lib/types/history.js

@@ -167,6 +167,7 @@ export class SessionHistoryController {
             // Constructor seed events have no session/event notification. Normally
             // only the end-seed suffix is new; if persistence advanced after the
             // opening observation, replay everything beyond that snapshot cursor.
+            // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
             const suffix = session.snapshotEvents(snapshotCursor === undefined
                 ? session.firstLiveSeq
                 : SessionLogOffset(snapshotCursor + 1));

package/lib/types/index.d.ts

@@ -143,11 +143,11 @@ export declare class SessionController extends TypertRemoteService {
      */
     attachment(request: SessionAttachmentRequest): Promise<SessionAttachmentValue>;
     /**
-     * Mutate one still-pending queue occurrence on a live Agent.
+     * Mutate one still-pending queue occurrence, resuming a cold Agent first.
      * @param request - Session, queue item, and requested mutation.
      * @returns acknowledgement that the queue mutation was applied.
      */
-    updateQueue(request: SessionUpdateQueueRequest): SessionUpdateQueueValue;
+    updateQueue(request: SessionUpdateQueueRequest): Promise<SessionUpdateQueueValue>;
     /**
      * Cancel one active Agent turn without dropping its pending inbox.
      * @param request - Session whose active Agent turn is cancelled.

package/lib/types/index.js

@@ -281,6 +281,7 @@ let SessionController = (() => {
                 return Promise.resolve({
                     meta: attached.header,
                     inheritedEventCount: attached.inheritedEventCount,
+                    // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
                     events: attached.snapshotEvents(),
                 });
             }
@@ -402,7 +403,7 @@ let SessionController = (() => {
             return this.commands.attachment(request);
         }
         /**
-         * Mutate one still-pending queue occurrence on a live Agent.
+         * Mutate one still-pending queue occurrence, resuming a cold Agent first.
          * @param request - Session, queue item, and requested mutation.
          * @returns acknowledgement that the queue mutation was applied.
          */

package/lib/types/skill-catalog.js

@@ -159,6 +159,7 @@ let SessionSkillCatalog = (() => {
                 return {
                     skills: skills.map(skill => ({
                         name: skill.name,
+                        ...skill.path === undefined ? {} : { path: skill.path },
                         description: skill.description,
                         ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
                         modelInvocable: skill.invocation.modelInvocable,

package/lib/types/types.d.ts

@@ -172,6 +172,9 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
             readonly requestedCwd: string;
             readonly existingCwd?: string;
         };
+        'session/writer-held': {
+            readonly sessionId: SessionId;
+        };
         'session/agent-busy': {
             readonly reason: string;
         };
@@ -219,6 +222,8 @@ export interface SkillListRequest {
 }
 /** One skill available to the Session's human-facing composer. */
 export interface SkillEntry {
+    /** Absolute SKILL.md path when supplied by a filesystem provider. */
+    readonly path?: string;
     /** Kebab-case identifier referenced as `/name`. */
     readonly name: string;
     /** Short routing description. */
@@ -484,18 +489,6 @@ export type SessionFollowFrame = {
     readonly type: 'assistant-stream';
     readonly frame: SessionAssistantStreamFrame;
 };
-/** One pending inbox occurrence in the authoritative queue snapshot. */
-export interface SessionQueuedItem {
-    readonly id: MessageId;
-    readonly placement: 'queued' | 'steering' | 'context';
-    /** Prompt-RPC identity from the queued message's user source; clients retire the matching local submission echo on it. */
-    readonly rpcId?: SessionRequestId;
-    /** JSON-safe message fields consumed by pending-queue presentation. */
-    readonly message: {
-        readonly id: MessageId;
-        readonly content: readonly JsonValue[];
-    };
-}
 /** Browser-safe background-job row. */
 export interface SessionJob {
     readonly id: JobId;
@@ -508,7 +501,6 @@ export interface SessionJob {
 }
 /** Complete live control baseline emitted once per control stream generation. */
 export interface SessionControlBaseline {
-    readonly queues: Readonly<Record<SessionId, readonly SessionQueuedItem[]>>;
     readonly jobs: Readonly<Record<SessionId, readonly SessionJob[]>>;
     readonly projections: Readonly<Record<SessionId, SessionProjectionBaseline>>;
 }
@@ -523,10 +515,6 @@ export interface SessionProjectionUpdate {
 export type SessionControlFrame = {
     readonly type: 'baseline';
     readonly value: SessionControlBaseline;
-} | {
-    readonly type: 'queue';
-    readonly sessionId: SessionId;
-    readonly items: readonly SessionQueuedItem[];
 } | {
     readonly type: 'jobs';
     readonly sessionId: SessionId;