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

package/lib/types/commands.js

@@ -55,6 +55,7 @@ import { randomUUID } from 'node:crypto';
 import { brandString } from '@deepseek-ai/dsh-brand';
 import { AttachmentError } from '@deepseek-ai/dsh-attachment';
 import { ReasoningEffortId, assistantStreamChunks, createUserMessage, freezeMessage, } from '@deepseek-ai/dsh-llm';
+import { buildForkSeed } from '@deepseek-ai/dsh-session/fork';
 import { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session';
 import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { SessionTitleInvalidError } from '@deepseek-ai/dsh-session-title';
@@ -65,6 +66,23 @@ import { ApiSessionCwdConflict, ApiSessionNotFound, ApiSessionPresetConflict, Ap
 function hasPromptContent(content) {
     return content.some(part => part.type !== 'text' || part.text.trim().length > 0);
 }
+/**
+ * Resolve the omitted-`atSeq` default to the latest completed-turn prefix,
+ * including standalone events before the next turn begins.
+ */
+function latestCompletedPrefixBoundary(events) {
+    const lastTurnEnd = events.findLast(event => event.type === 'turn/end');
+    if (lastTurnEnd === undefined)
+        return undefined;
+    let boundary = lastTurnEnd.seq;
+    for (const next of events.slice(boundary + 1)) {
+        if (next.type === 'turn/start' || (next.type === 'user/message' && next.surfaceOp === 'append')
+            || next.type === 'agent/inbox/spliced')
+            break;
+        boundary = next.seq;
+    }
+    return boundary;
+}
 /** Implements Session business commands delegated by the Session Controller Remote service. */
 export class SessionCommandController {
     ctx;
@@ -180,8 +198,10 @@ export class SessionCommandController {
         }
     }
     /**
-     * Create a new ordinary Session from one completed-turn prefix.
-     * @param request - source Session and optional event anchor.
+     * Create a new ordinary Session from an exact event prefix. An explicit
+     * `atSeq` is the inclusive cut; an omitted value selects the latest
+     * completed-turn prefix. An open cut receives synthetic fork closers.
+     * @param request - source Session and optional exact event boundary.
      * @returns the new Session identity.
      */
     async fork(request) {
@@ -208,20 +228,13 @@ export class SessionCommandController {
                 throw new RemoteError('gateway/internal', `fork source unavailable for session "${request.sessionId}": ${String(error)}`, {});
             }
             const source = __addDisposableResource(env_1, observed, false);
-            const lastSeq = source.events.at(-1)?.seq ?? -1;
-            const anchoredBoundary = atSeq === undefined
-                ? undefined
-                : source.events.find(event => event.type === 'turn/end' && event.seq >= atSeq);
-            const boundary = anchoredBoundary
-                ?? (atSeq === undefined || atSeq > lastSeq
-                    ? source.events.findLast(event => event.type === 'turn/end')
-                    : undefined);
-            if (boundary === undefined) {
-                throw new RemoteError('session/fork-unavailable', atSeq !== undefined && atSeq <= lastSeq
-                    ? `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 });
+            const boundary = atSeq ?? latestCompletedPrefixBoundary(source.events);
+            if (boundary === undefined || source.events[boundary]?.seq !== boundary) {
+                throw new RemoteError('session/fork-unavailable', request.atSeq === undefined
+                    ? `session "${request.sessionId}" has no completed turn to fork from`
+                    : `event ${String(request.atSeq)} does not exist in session "${request.sessionId}" (last seq: ${String(source.events.at(-1)?.seq ?? 'none')})`, { sessionId: request.sessionId });
             }
-            const cut = SessionLogOffset(boundary.seq + 1);
+            const seed = buildForkSeed(source.events, boundary);
             let workspace;
             try {
                 workspace = await this.forkWorkspace(source.header);
@@ -235,8 +248,8 @@ export class SessionCommandController {
                 const { provider, model } = this.ctx.agentDefaultModel.currentSelection();
                 await this.ctx.agents.create({
                     sessionId: childId,
-                    seed: source.events.slice(0, cut),
-                    inheritedEventCount: cut,
+                    seed,
+                    inheritedEventCount: SessionLogOffset(boundary + 1),
                     meta: {
                         ...(source.header.cwd === undefined ? {} : { cwd: source.header.cwd }),
                         parentSession: source.header.id,
@@ -377,12 +390,13 @@ 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') {
+            // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote callers can submit untyped JSON.
             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' });
             }
@@ -390,9 +404,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
@@ -465,6 +485,9 @@ export class SessionCommandController {
     rejectCreation(sessionId, error) {
         if (remoteErrorOf(error) !== undefined)
             throw error;
+        if (error instanceof Error && error.name === 'SessionAlreadyOwnedError') {
+            throw new RemoteError('session/writer-held', error.message, { sessionId });
+        }
         if (error instanceof ApiSessionPresetConflict) {
             throw new RemoteError('agent-preset/conflict', error.message, {
                 sessionId: error.sessionId,
@@ -548,33 +571,52 @@ function imageBlockIn(content, match) {
             if (match(ref))
                 return ref;
         }
-        if (block.type === 'tool-result') {
-            const nested = imageBlockIn(block.content, match);
-            if (nested !== undefined)
-                return nested;
-        }
     }
     return undefined;
 }
+/** Read only first-party declared content fields; unknown event payloads stay opaque. */
 function imageInEvent(event, match) {
     const data = event.data;
-    const direct = imageBlockIn(data.content, match);
-    if (direct !== undefined)
-        return direct;
-    const message = imageBlockIn(data.message?.content, match);
-    if (message !== undefined)
-        return message;
-    for (const inserted of data.inserted ?? []) {
-        const found = imageBlockIn(inserted.content, match);
-        if (found !== undefined)
-            return found;
-    }
-    if (event.type === 'assistant/message' || event.type === 'assistant/attempt') {
-        for (const chunk of assistantStreamChunks(event.data.stream, 'block-end')) {
-            const found = imageBlockIn([chunk.block], match);
+    // First-party event payloads can be present without their producer plugin mounted.
+    const type = event.type;
+    switch (type) {
+        case 'user/message':
+        case 'tool/ptc-dispatch':
+            return imageBlockIn(data.content, match);
+        case 'system/message':
+        case 'developer/message':
+        case 'tool/result':
+        case 'team/message/queued':
+            return imageBlockIn(data.message?.content, match);
+        case 'agent/inbox/spliced': {
+            const messages = data.inserted;
+            if (!Array.isArray(messages))
+                return undefined;
+            for (const message of messages) {
+                if (typeof message !== 'object' || message === null || Array.isArray(message))
+                    continue;
+                const found = imageBlockIn(message.content, match);
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        }
+        case 'compaction/summary':
+            return imageBlockIn(data.summary, match) ?? imageBlockIn(data.rawOutput, match);
+        case 'assistant/message': {
+            const found = imageBlockIn(data.message?.content, match);
             if (found !== undefined)
                 return found;
+            break;
         }
+        case 'assistant/attempt': break;
+        default: return undefined;
+    }
+    const assistant = event;
+    for (const chunk of assistantStreamChunks(assistant.data.stream, 'block-end')) {
+        const found = imageBlockIn([chunk.block], match);
+        if (found !== undefined)
+            return found;
     }
     return undefined;
 }

package/lib/types/control.d.ts

@@ -1,11 +1,11 @@
-/** Live Session queue, jobs, and projection state with reconnect baselines. */
+/** Live Session 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. */
 export declare class SessionControlController {
     private readonly ctx;
     private readonly streams;
-    /** @param ctx - Host context carrying live Agent, projection, and jobs services. */
+    /** @param ctx - Host context carrying live Agent and projection services. */
     constructor(ctx: Context);
     /**
      * Open one generation of Host-wide live control state.
@@ -15,8 +15,6 @@ export declare class SessionControlController {
     control(signal: AbortSignal): AsyncIterable<SessionControlFrame>;
     private baseline;
     private projectionBaseline;
-    private onJobsChanged;
-    private jobsFor;
     private broadcast;
 }
 //# sourceMappingURL=control.d.ts.map

package/lib/types/control.js

@@ -1,10 +1,10 @@
-/** Live Session queue, jobs, and projection state with reconnect baselines. */
+/** Live Session projection state with reconnect baselines. */
 import { Deque } from '@deepseek-ai/dsh-deque';
 /** Owns the Host-wide Session control stream. */
 export class SessionControlController {
     ctx;
     streams = new Set();
-    /** @param ctx - Host context carrying live Agent, projection, and jobs services. */
+    /** @param ctx - Host context carrying live Agent and projection services. */
     constructor(ctx) {
         this.ctx = ctx;
         ctx.sessionProjections.onChanged((session, key, value, seq) => {
@@ -15,24 +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); });
-        });
-        ctx.on('session/created', (session) => {
-            const jobs = this.jobsFor(this.ctx.agents.get(session.id));
-            if (jobs.length > 0)
-                this.broadcast({ type: 'jobs', sessionId: session.id, jobs });
         });
         ctx.effect(() => () => {
             for (const stream of this.streams)
@@ -60,16 +42,7 @@ 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),
         };
     }
@@ -85,23 +58,6 @@ export class SessionControlController {
         }
         return blocks;
     }
-    onJobsChanged(owner) {
-        if (owner !== undefined) {
-            this.broadcast({ type: 'jobs', sessionId: owner.id, jobs: this.jobsFor(owner) });
-            return;
-        }
-        for (const session of this.ctx.sessions.list()) {
-            this.broadcast({
-                type: 'jobs',
-                sessionId: session.id,
-                jobs: this.jobsFor(this.ctx.agents.get(session.id)),
-            });
-        }
-    }
-    jobsFor(agent) {
-        const jobs = this.ctx.get('jobs');
-        return jobs === undefined ? [] : jobs.list(agent).map(jobView);
-    }
     broadcast(frame) {
         for (const stream of this.streams)
             stream.push(frame);
@@ -148,42 +104,4 @@ 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,
-        kind: job.kind,
-        label: job.label,
-        status: job.status,
-        ...(job.detail === undefined ? {} : { detail: job.detail }),
-        startedAt: job.startedAt,
-        ...(job.finishedAt === undefined ? {} : { finishedAt: job.finishedAt }),
-    };
-}
 //# sourceMappingURL=control.js.map

package/lib/types/history.js

@@ -370,7 +370,7 @@ function validateAddress(address, header, inheritedEventCount, projections) {
             reason: 'unsupported',
         });
     }
-    if (identity.mode !== address.mode) {
+    if (address.mode !== 'unknown' && identity.mode !== address.mode) {
         throw new RemoteError('subagent/unauthorized', 'subagent mode does not match the supplied address', {
             childSessionId: address.childSessionId,
         });

package/lib/types/index.d.ts

@@ -1,12 +1,13 @@
 /** Session Remote owner: cold reads, explicit Agent commands, and live control state. */
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { nativeFileApplications, openNativeFileApplication } from '@deepseek-ai/dsh-native-command';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { type ApiSessionAgentResult } from './agent.ts';
 import { buildModelCatalog } from './catalog.ts';
-import type { ModelCatalog, SessionAttachmentRequest, SessionAttachmentValue, SessionCancelRequest, SessionCancelValue, SessionControlFrame, SessionCreateRequest, SessionCreateValue, SessionFollowFrame, SessionFollowRequest, SessionForkRequest, SessionForkValue, SessionListRequest, SessionListValue, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, SessionPageRequest, SessionPromptRequest, SessionPromptValue, SessionRenameRequest, SessionRenameValue, SessionSearchRequest, SessionSearchValue, SessionSelectModelRequest, SessionSelectModelValue, SessionUpdateQueueRequest, SessionUpdateQueueValue } from './types.ts';
+import type { ModelCatalog, SessionWorkspacePathApplication, SessionAttachmentRequest, SessionAttachmentValue, SessionCancelRequest, SessionCancelValue, SessionControlFrame, SessionCreateRequest, SessionCreateValue, SessionFollowFrame, SessionFollowRequest, SessionForkRequest, SessionForkValue, SessionListRequest, SessionListValue, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, SessionPageRequest, SessionPromptRequest, SessionPromptValue, SessionRenameRequest, SessionRenameValue, SessionSearchRequest, SessionSearchValue, SessionSelectModelRequest, SessionSelectModelValue, SessionProjectionsRequest, SessionProjectionsValue, SessionUpdateQueueRequest, SessionUpdateQueueValue } from './types.ts';
 export type * from './types.ts';
 export { ApiSessionNotFound } from './agent.ts';
 export { SessionFileReferences } from './file-references.ts';
@@ -26,6 +27,10 @@ export interface Config {
 export interface SessionControllerInternals {
     /** Native default-application handoff. */
     readonly openPath?: (path: string, signal: AbortSignal) => Promise<void>;
+    /** Native file-association query. */
+    readonly fileApplications?: typeof nativeFileApplications;
+    /** Explicit registered-application handoff. */
+    readonly openFileApplication?: typeof openNativeFileApplication;
     /** Native file-manager handoff. */
     readonly revealPath?: (path: string, signal: AbortSignal) => Promise<void>;
     /** Native handoff availability probe. */
@@ -41,6 +46,8 @@ export declare class SessionController extends TypertRemoteService {
     private readonly history;
     private readonly listState;
     private readonly openPath;
+    private readonly fileApplications;
+    private readonly openFileApplication;
     private readonly revealPath;
     private readonly canOpenPath;
     private readonly promotions;
@@ -110,13 +117,24 @@ export declare class SessionController extends TypertRemoteService {
         fileManager: 'finder' | 'explorer' | 'directory' | null;
     };
     /**
-     * Open one path prepared by a Session-aware caller on the Host desktop.
+     * Verify one path through the composed filesystem and open it on the Host desktop.
      * @param request - path after best-effort Session workspace resolution.
      * @param signal - caller lifetime; abort terminates the native command.
      * @returns confirmation after the native opener accepts the path.
-     * @throws RemoteError when the request is invalid, cancelled, or the opener fails.
+     * @throws RemoteError when the request is invalid, has no verified Host mapping, is cancelled, or the opener fails.
      */
     openWorkspacePath(request: SessionOpenWorkspacePathRequest, signal: AbortSignal): Promise<SessionOpenWorkspacePathValue>;
+    /**
+     * Query current file handlers on the serving desktop without activating an Agent.
+     * @param request - file path in Host filesystem syntax.
+     * @param signal - caller lifetime, propagated to filesystem and desktop queries.
+     * @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
+     * @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
+     */
+    workspacePathApplications(request: {
+        readonly path: string;
+    }, signal: AbortSignal): Promise<readonly SessionWorkspacePathApplication[]>;
+    private verifyDesktopPath;
     /**
      * Rename one Session after explicitly resuming it.
      * @param request - Session identity and proposed title.
@@ -124,8 +142,10 @@ export declare class SessionController extends TypertRemoteService {
      */
     rename(request: SessionRenameRequest): Promise<SessionRenameValue>;
     /**
-     * Fork one cold-readable completed-turn prefix into a new Session.
-     * @param request - source Session and optional event anchor.
+     * Fork one cold-readable exact event prefix into a new Session. An omitted
+     * boundary selects the latest completed-turn prefix; an open cut receives
+     * synthetic fork closers.
+     * @param request - source Session and optional exact inclusive event boundary.
      * @returns the new Session identity.
      */
     fork(request: SessionForkRequest): Promise<SessionForkValue>;
@@ -143,11 +163,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.
@@ -169,6 +189,13 @@ export declare class SessionController extends TypertRemoteService {
      *   frames and optional cursorless assistant-stream frames.
      */
     follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>;
+    /**
+     * Read all registered projections without activating an Agent.
+     * @param request - Session whose current values are required.
+     * @param signal - cancellation for the Session observation.
+     * @returns complete baseline, or null when the Session does not exist.
+     */
+    projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise<SessionProjectionsValue>;
     /**
      * Stream a complete live-control baseline followed by replacement frames.
      * @param signal - cancellation owned by the Remote stream carrier.