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

package/lib/types/control.js

@@ -1,10 +1,10 @@
-/** Live Session 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) => {
@@ -16,14 +16,6 @@ export class SessionControlController {
                 seq,
             });
         });
-        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)
                 stream.end();
@@ -50,13 +42,7 @@ export class SessionControlController {
     }
     baseline() {
         const sessions = this.ctx.sessions.list();
-        const jobs = Object.create(null);
-        for (const session of sessions) {
-            const agent = this.ctx.agents.get(session.id);
-            jobs[session.id] = this.jobsFor(agent);
-        }
         return {
-            jobs,
             projections: this.projectionBaseline(sessions),
         };
     }
@@ -72,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);
@@ -135,15 +104,4 @@ class ControlQueue {
         }
     }
 }
-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

@@ -115,7 +115,7 @@ export class SessionHistoryController {
             if (throughSeq >= 0 && sourceLog[throughSeq]?.seq !== throughSeq) {
                 throw new RemoteError('gateway/internal', `session log does not contain through seq ${String(throughSeq)}`, {});
             }
-            const page = paginate(sourceLog, beforeSeq, request.maxMessages ?? DEFAULT_MAX_MESSAGES, throughSeq);
+            const page = paginate(sourceLog, beforeSeq, request.maxMessages ?? DEFAULT_MAX_MESSAGES, throughSeq, request.turnWindow);
             const records = pageRecords(page.events);
             return {
                 records,
@@ -137,7 +137,7 @@ export class SessionHistoryController {
      * @returns a complete opening snapshot followed by gap-free durable events and opted-in assistant frames.
      */
     async *follow(request, signal) {
-        validateFollowRequest(request);
+        validateHistoryWindow(request);
         const { address } = request;
         const target = addressId(address);
         const buffered = new Deque();
@@ -198,7 +198,7 @@ export class SessionHistoryController {
                 signal.throwIfAborted();
                 const cursor = source.cursor;
                 snapshotCursor = cursor;
-                const page = paginate(events, undefined, request.maxMessages ?? DEFAULT_MAX_MESSAGES);
+                const page = paginate(events, undefined, request.maxMessages ?? DEFAULT_MAX_MESSAGES, cursor, request.turnWindow);
                 const assistantStream = request.assistantStream === true
                     ? this.assistantStreams.get(target)?.snapshot() ?? { revision: 0 }
                     : undefined;
@@ -327,16 +327,23 @@ function validatePageRequest(request) {
             || Object.is(request.beforeSeq, -0))) {
         throw new RemoteError('gateway/bad-request', 'beforeSeq must be a non-negative safe integer', {});
     }
-    if (request.maxMessages !== undefined
-        && (!Number.isSafeInteger(request.maxMessages) || request.maxMessages <= 0)) {
-        throw new RemoteError('gateway/bad-request', 'maxMessages must be a positive safe integer', {});
-    }
+    validateHistoryWindow(request);
 }
-function validateFollowRequest(request) {
+function validateHistoryWindow(request) {
     if (request.maxMessages !== undefined
         && (!Number.isSafeInteger(request.maxMessages) || request.maxMessages <= 0)) {
         throw new RemoteError('gateway/bad-request', 'maxMessages must be a positive safe integer', {});
     }
+    const window = request.turnWindow;
+    if (window !== undefined) {
+        if (!Number.isSafeInteger(window.minMessages) || window.minMessages <= 0
+            || window.minMessages > (request.maxMessages ?? DEFAULT_MAX_MESSAGES)) {
+            throw new RemoteError('gateway/bad-request', 'turnWindow.minMessages must be a positive safe integer no greater than maxMessages', {});
+        }
+        if (!Number.isSafeInteger(window.minTurns) || window.minTurns <= 0) {
+            throw new RemoteError('gateway/bad-request', 'turnWindow.minTurns must be a positive safe integer', {});
+        }
+    }
 }
 function addressId(address) {
     return address.kind === 'session' ? address.sessionId : address.childSessionId;
@@ -370,7 +377,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,
         });
@@ -385,12 +392,20 @@ function rejectNotFound(address) {
         childSessionId: address.childSessionId,
     });
 }
-function paginate(events, beforeSeq, maxMessages, throughSeq = events.at(-1)?.seq ?? -1) {
+function paginate(events, beforeSeq, maxMessages, throughSeq, turnWindow) {
     const end = SessionLogOffset(Math.min(throughSeq + 1, beforeSeq ?? throughSeq + 1));
     let count = 0;
+    let turns = 0;
     let cut = SessionLogOffset(0);
     for (let index = end - 1; index >= 0; index--) {
         const event = events[index];
+        if (turnWindow !== undefined && event.type === 'turn/start') {
+            turns++;
+            if (count >= turnWindow.minMessages && turns >= turnWindow.minTurns) {
+                cut = SessionLogOffset(index);
+                break;
+            }
+        }
         if (!MESSAGE_TYPES.has(event.type) || !isAppendSurfaceEvent(event))
             continue;
         count++;

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>;
@@ -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.

package/lib/types/index.js

@@ -86,9 +86,11 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { hostname } from 'node:os';
+import { resolve } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { errorChain } from '@deepseek-ai/dsh-llm';
-import { canOpenNativePath, nativeFileManager, openNativePath, revealNativePath } from '@deepseek-ai/dsh-native-command';
+import { canOpenNativePath, nativeFileManager, nativeFileApplications, openNativeFileApplication, openNativeAssociatedPath, revealNativePath } from '@deepseek-ai/dsh-native-command';
+import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { ApiSessionAgentController, inspectApiSession, } from "./agent.js";
 import { SessionCommandController } from "./commands.js";
@@ -100,6 +102,7 @@ import { buildModelCatalog } from "./catalog.js";
 import { installModelSelectionProjection } from "./model-selection-projection.js";
 import { SessionSkillCatalog } from "./skill-catalog.js";
 import { SessionMediaReferences } from "./media-references.js";
+import { ArchivedSessionGate } from "./archived-session-gate.js";
 export { ApiSessionNotFound } from "./agent.js";
 export { SessionFileReferences } from "./file-references.js";
 export { SessionSkillCatalog } from "./skill-catalog.js";
@@ -114,6 +117,7 @@ let SessionController = (() => {
     let _modelCatalog_decorators;
     let _canOpenWorkspacePath_decorators;
     let _openWorkspacePath_decorators;
+    let _workspacePathApplications_decorators;
     let _rename_decorators;
     let _fork_decorators;
     let _prompt_decorators;
@@ -122,6 +126,7 @@ let SessionController = (() => {
     let _cancel_decorators;
     let _page_decorators;
     let _follow_decorators;
+    let _projections_decorators;
     let _control_decorators;
     return class SessionController extends _classSuper {
         static {
@@ -133,6 +138,7 @@ let SessionController = (() => {
             _modelCatalog_decorators = [Remote('modelCatalog')];
             _canOpenWorkspacePath_decorators = [Remote];
             _openWorkspacePath_decorators = [Remote('openWorkspacePath')];
+            _workspacePathApplications_decorators = [Remote('workspacePathApplications')];
             _rename_decorators = [Remote('rename')];
             _fork_decorators = [Remote('fork')];
             _prompt_decorators = [Remote('prompt')];
@@ -141,6 +147,7 @@ let SessionController = (() => {
             _cancel_decorators = [Remote('cancel')];
             _page_decorators = [Remote('page')];
             _follow_decorators = [Remote({ mode: 'stream' })];
+            _projections_decorators = [Remote('projections')];
             _control_decorators = [Remote({ mode: 'stream' })];
             __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _search_decorators, { kind: "method", name: "search", static: false, private: false, access: { has: obj => "search" in obj, get: obj => obj.search }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -149,6 +156,7 @@ let SessionController = (() => {
             __esDecorate(this, null, _modelCatalog_decorators, { kind: "method", name: "modelCatalog", static: false, private: false, access: { has: obj => "modelCatalog" in obj, get: obj => obj.modelCatalog }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _canOpenWorkspacePath_decorators, { kind: "method", name: "canOpenWorkspacePath", static: false, private: false, access: { has: obj => "canOpenWorkspacePath" in obj, get: obj => obj.canOpenWorkspacePath }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _openWorkspacePath_decorators, { kind: "method", name: "openWorkspacePath", static: false, private: false, access: { has: obj => "openWorkspacePath" in obj, get: obj => obj.openWorkspacePath }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _workspacePathApplications_decorators, { kind: "method", name: "workspacePathApplications", static: false, private: false, access: { has: obj => "workspacePathApplications" in obj, get: obj => obj.workspacePathApplications }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _rename_decorators, { kind: "method", name: "rename", static: false, private: false, access: { has: obj => "rename" in obj, get: obj => obj.rename }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _fork_decorators, { kind: "method", name: "fork", static: false, private: false, access: { has: obj => "fork" in obj, get: obj => obj.fork }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _prompt_decorators, { kind: "method", name: "prompt", static: false, private: false, access: { has: obj => "prompt" in obj, get: obj => obj.prompt }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -157,6 +165,7 @@ let SessionController = (() => {
             __esDecorate(this, null, _cancel_decorators, { kind: "method", name: "cancel", static: false, private: false, access: { has: obj => "cancel" in obj, get: obj => obj.cancel }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _page_decorators, { kind: "method", name: "page", static: false, private: false, access: { has: obj => "page" in obj, get: obj => obj.page }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _follow_decorators, { kind: "method", name: "follow", static: false, private: false, access: { has: obj => "follow" in obj, get: obj => obj.follow }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _projections_decorators, { kind: "method", name: "projections", static: false, private: false, access: { has: obj => "projections" in obj, get: obj => obj.projections }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _control_decorators, { kind: "method", name: "control", static: false, private: false, access: { has: obj => "control" in obj, get: obj => obj.control }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
@@ -165,6 +174,7 @@ let SessionController = (() => {
             'agents',
             'attachments',
             'fileUploads',
+            'fs',
             'llm',
             'sessions',
             'sessionProjections',
@@ -181,6 +191,8 @@ let SessionController = (() => {
         history;
         listState;
         openPath;
+        fileApplications;
+        openFileApplication;
         revealPath;
         canOpenPath;
         promotions = new Set();
@@ -208,19 +220,32 @@ let SessionController = (() => {
             }, 'session-controller.promotions');
             this.history = new SessionHistoryController(ctx, (observation) => { this.promote(observation); });
             this.listState = new ApiSessionList(ctx);
-            this.openPath = internals.openPath ?? openNativePath;
+            this.fileApplications = internals.fileApplications ?? nativeFileApplications;
+            this.openFileApplication = internals.openFileApplication ?? openNativeFileApplication;
+            this.openPath = internals.openPath ?? openNativeAssociatedPath;
             this.revealPath = internals.revealPath ?? revealNativePath;
             this.canOpenPath = internals.canOpenPath
                 ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath()));
             ctx.plugin(SessionFileReferences);
             ctx.plugin(SessionMediaReferences);
             ctx.plugin(SessionSkillCatalog);
+            // An archived Session, or a subagent descendant of one, runs no model step
+            // until it is restored; what it still runs is stopped by the owners that
+            // answer the Workspace registry's archive-admission events.
+            ctx.plugin(ArchivedSessionGate);
             ctx.on('session/created', (session) => {
                 ctx.emit('api-session/added', this.listState.summaryFor(session));
             });
             ctx.on('session/disposed', (session) => {
                 ctx.emit('api-session/removed', session.id);
             });
+            const publishAgentAvailability = ({ agent }) => {
+                if (ctx.sessions.get(agent.id) === agent.session) {
+                    ctx.emit('api-session/added', this.listState.summaryFor(agent.session));
+                }
+            };
+            ctx.on('agent/created', publishAgentAvailability);
+            ctx.on('agent/disposed', publishAgentAvailability);
             ctx.on('agent/status', ({ agent, status }) => {
                 ctx.emit('api-session/status', agent.id, status === 'running');
             });
@@ -344,29 +369,65 @@ let SessionController = (() => {
             return { name: hostname(), available: fileManager !== null && this.canOpenPath(), fileManager };
         }
         /**
-         * 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.
          */
         async openWorkspacePath(request, signal) {
-            if (request.path.length === 0) {
-                throw new RemoteError('gateway/bad-request', 'session.openWorkspacePath requires a non-empty path', {});
-            }
-            signal.throwIfAborted();
             try {
+                const path = await this.verifyDesktopPath(request.path, signal);
                 if (request.action === 'reveal')
-                    await this.revealPath(request.path, signal);
+                    await this.revealPath(path, signal);
+                else if (request.application !== undefined)
+                    await this.openFileApplication(path, request.application, signal);
                 else
-                    await this.openPath(request.path, signal);
+                    await this.openPath(path, signal);
                 return { opened: true };
             }
             catch (error) {
                 if (signal.aborted)
                     throw new RemoteError('gateway/cancelled', 'path open was aborted', {});
-                throw new RemoteError('gateway/internal', `path open failed: ${error instanceof Error ? error.message : String(error)}`, {});
+                if (error instanceof RemoteError)
+                    throw error;
+                throw new RemoteError('gateway/internal', 'path open failed', {}, { cause: error });
+            }
+        }
+        /**
+         * 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.
+         */
+        async workspacePathApplications(request, signal) {
+            if (!this.canOpenPath())
+                return [];
+            try {
+                const path = await this.verifyDesktopPath(request.path, signal);
+                return await this.fileApplications(path, signal);
             }
+            catch (error) {
+                if (signal.aborted)
+                    throw new RemoteError('gateway/cancelled', 'application query was aborted', {});
+                if (error instanceof RemoteError)
+                    throw error;
+                throw new RemoteError('gateway/internal', 'file application query failed', {}, { cause: error });
+            }
+        }
+        async verifyDesktopPath(path, signal) {
+            if (path.length === 0)
+                throw new RemoteError('gateway/bad-request', 'A non-empty file path is required', {});
+            signal.throwIfAborted();
+            const hostPath = resolve(path);
+            const { fs } = this.ctx;
+            const mapped = fs.processPathFromHostPath(hostPath);
+            if (mapped === undefined || fs.processPath(await fs.resolve(mapped, { signal })) !== hostPath) {
+                throw new RemoteError('gateway/bad-request', 'Path has no verified Host path', {});
+            }
+            signal.throwIfAborted();
+            return hostPath;
         }
         /**
          * Rename one Session after explicitly resuming it.
@@ -377,8 +438,10 @@ let SessionController = (() => {
             return this.commands.rename(request);
         }
         /**
-         * 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) {
@@ -437,6 +500,47 @@ let SessionController = (() => {
         follow(request, signal) {
             return this.history.follow(request, signal);
         }
+        /**
+         * 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.
+         */
+        async projections(request, signal) {
+            const { sessionId } = request;
+            if (sessionId.length === 0) {
+                throw new RemoteError('gateway/bad-request', 'sessionId must not be empty', {});
+            }
+            try {
+                const env_2 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const observation = __addDisposableResource(env_2, await this.ctx.sessionQuery.observeSession(sessionId, { signal }), false);
+                    const projections = observation.projections;
+                    if (projections === undefined) {
+                        throw new RemoteError('session/projections-unavailable', 'Session projections are unavailable', {});
+                    }
+                    return { asOfSeq: projections.asOfSeq, values: projections.values };
+                }
+                catch (e_2) {
+                    env_2.error = e_2;
+                    env_2.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_2);
+                }
+            }
+            catch (error) {
+                if (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND')
+                    return null;
+                if (signal.aborted
+                    || (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED')) {
+                    throw new RemoteError('gateway/cancelled', 'Session projection read was cancelled', {}, { cause: error });
+                }
+                if (error instanceof RemoteError)
+                    throw error;
+                throw new RemoteError('gateway/internal', 'Session projection read failed', {}, { cause: error });
+            }
+        }
         /**
          * Stream a complete live-control baseline followed by replacement frames.
          * @param signal - cancellation owned by the Remote stream carrier.

package/lib/types/list.js

@@ -1,5 +1,4 @@
 /** Cold-safe Session list and search projection. */
-import { SessionLogOffset } from '@deepseek-ai/dsh-session';
 import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
 import { z } from 'zod';
@@ -90,6 +89,7 @@ export class ApiSessionList {
         return {
             sessionId: session.id,
             updatedAt: updatedAt(session.header, metadata),
+            agentAvailable: this.ctx.agents.get(session.id)?.session === session,
             running: this.ctx.agents.get(session.id)?.status === 'running',
             blank: metadata?.blank ?? session.seq === 0,
             ...listFields(session.header),
@@ -128,6 +128,7 @@ export class ApiSessionList {
         return {
             sessionId: header.id,
             updatedAt: updatedAt(header, metadata),
+            agentAvailable: false,
             running: false,
             // A large, metadata-less, or inaccessible cache miss remains unknown and visible.
             blank: metadata?.blank ?? false,
@@ -246,21 +247,16 @@ export class ApiSessionList {
     }
     projectionsFor(header, session) {
         try {
+            if (session !== undefined) {
+                // The live registry computed the block for this Session: its watermark
+                // shares the sequence space of the Session's baselines and frames.
+                return hintsOf('sequenced', this.ctx.sessionProjections.cachedSnapshot(session));
+            }
+            // A cold row reads the persisted cache by header alone; the cache serves
+            // seeded and unseeded lifecycles alike because a listing never seeds a
+            // fold. The watermark is the stored record's own.
             const cache = this.ctx.get('sessionProjectionCache');
-            const block = session === undefined
-                ? header.isSeeded
-                    ? undefined
-                    : cache?.cachedSnapshot(header, SessionLogOffset(0))
-                        ?? cache?.cachedPredecessorTitle(header, SessionLogOffset(0))
-                : this.ctx.sessionProjections.cachedSnapshot(session);
-            return block !== undefined && Object.keys(block.values).length > 0
-                ? {
-                    asOfSeq: block.asOfSeq,
-                    // Listing hints contain every currently cached wire value but remain
-                    // partial: missing cells and cache rows are never materialized here.
-                    values: block.values,
-                }
-                : undefined;
+            return hintsOf('cached', cache?.cachedSnapshot(header) ?? cache?.cachedPredecessorTitle(header));
         }
         catch (error) {
             this.ctx.logger.warn(`api-session.list: projection column for "${header.id}" failed; serving the row without it: ${String(error)}`);
@@ -268,6 +264,19 @@ export class ApiSessionList {
         }
     }
 }
+/**
+ * Wrap one projection block as Session-list hints of the named sequence space.
+ * @param kind - which sequence space the block's watermark belongs to.
+ * @param block - the block, or `undefined` when no source served one.
+ * @returns the hints, or `undefined` when the block is absent or carries no value.
+ */
+function hintsOf(kind, block) {
+    if (block === undefined || Object.keys(block.values).length === 0)
+        return undefined;
+    // Listing hints contain every wire value the source currently holds but
+    // remain partial: missing cells and cache rows are never materialized here.
+    return { kind, asOfSeq: block.asOfSeq, values: block.values };
+}
 function normalizeSearchQuery(query) {
     const normalized = query.trim();
     if (normalized.length === 0) {