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

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) {
@@ -403,7 +466,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.
          */
@@ -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) {

package/lib/types/skill-catalog.js

@@ -114,72 +114,82 @@ let SessionSkillCatalog = (() => {
          * @throws RemoteError when the Session cannot be inspected or no registry can serve it.
          */
         async list(request, signal) {
-            void signal;
-            const { sessionId } = request;
-            let cwd;
-            let agentPreset;
+            const env_1 = { stack: [], error: void 0, hasError: false };
             try {
-                const env_1 = { stack: [], error: void 0, hasError: false };
+                void signal;
+                const { sessionId } = request;
+                let cwd;
+                let agentPreset;
                 try {
-                    const observation = __addDisposableResource(env_1, await this.ctx.sessionQuery.observeSession(sessionId), false);
-                    if (observation.projections === undefined) {
-                        throw new Error('skill catalog requires a projected Session observation');
+                    const env_2 = { stack: [], error: void 0, hasError: false };
+                    try {
+                        const observation = __addDisposableResource(env_2, await this.ctx.sessionQuery.observeSession(sessionId), false);
+                        if (observation.projections === undefined) {
+                            throw new Error('skill catalog requires a projected Session observation');
+                        }
+                        cwd = observation.header.cwd;
+                        agentPreset = observation.projections.values.agentPreset ?? undefined;
+                    }
+                    catch (e_1) {
+                        env_2.error = e_1;
+                        env_2.hasError = true;
+                    }
+                    finally {
+                        __disposeResources(env_2);
                     }
-                    cwd = observation.header.cwd;
-                    agentPreset = observation.projections.values.agentPreset ?? undefined;
                 }
-                catch (e_1) {
-                    env_1.error = e_1;
-                    env_1.hasError = true;
+                catch (error) {
+                    if (error instanceof SessionQueryError
+                        && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
+                        throw new RemoteError('session/not-found', `session "${sessionId}" not found`, { sessionId });
+                    }
+                    throw new RemoteError('gateway/internal', `session "${sessionId}" could not be inspected: ${String(error)}`, {});
                 }
-                finally {
-                    __disposeResources(env_1);
+                if (cwd === undefined) {
+                    throw new RemoteError('gateway/internal', `session "${sessionId}" has no project cwd`, {});
                 }
-            }
-            catch (error) {
-                if (error instanceof SessionQueryError
-                    && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
-                    throw new RemoteError('session/not-found', `session "${sessionId}" not found`, { sessionId });
+                const live = this.ctx.agents.get(sessionId);
+                const presets = this.ctx.get('agentPresets');
+                const scoped = live === undefined ? undefined : presets?.serviceFor(live, 'skills');
+                const skillRegistry = scoped ?? this.ctx.get('skills');
+                if (skillRegistry === undefined) {
+                    throw new RemoteError('gateway/internal', 'skill registry is absent: neither this session\'s agent preset nor the host composition mounts @deepseek-ai/dsh-skill', {});
+                }
+                const lease = __addDisposableResource(env_1, live === undefined ? await this.scopeFor(agentPreset) : undefined, true);
+                const scope = live ?? lease?.key;
+                try {
+                    const skills = (await skillRegistry.list({ cwd, scope })).filter(isUserInvocable);
+                    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,
+                        })),
+                    };
+                }
+                catch (error) {
+                    throw new RemoteError('gateway/internal', `skill listing failed: ${String(error)}`, {});
                 }
-                throw new RemoteError('gateway/internal', `session "${sessionId}" could not be inspected: ${String(error)}`, {});
-            }
-            if (cwd === undefined) {
-                throw new RemoteError('gateway/internal', `session "${sessionId}" has no project cwd`, {});
-            }
-            const live = this.ctx.agents.get(sessionId);
-            const presets = this.ctx.get('agentPresets');
-            const scoped = live === undefined ? undefined : presets?.serviceFor(live, 'skills');
-            const skillRegistry = scoped ?? this.ctx.get('skills');
-            if (skillRegistry === undefined) {
-                throw new RemoteError('gateway/internal', 'skill registry is absent: neither this session\'s agent preset nor the host composition mounts @deepseek-ai/dsh-skill', {});
             }
-            const scope = await this.scopeFor(sessionId, agentPreset);
-            try {
-                const skills = (await skillRegistry.list({ cwd, scope })).filter(isUserInvocable);
-                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,
-                    })),
-                };
+            catch (e_2) {
+                env_1.error = e_2;
+                env_1.hasError = true;
             }
-            catch (error) {
-                throw new RemoteError('gateway/internal', `skill listing failed: ${String(error)}`, {});
+            finally {
+                const result_1 = __disposeResources(env_1);
+                if (result_1)
+                    await result_1;
             }
         }
         /** Resolve a live or standing preset scope without creating an Agent. */
-        async scopeFor(sessionId, agentPreset) {
-            const live = this.ctx.agents.get(sessionId);
-            if (live !== undefined)
-                return live;
+        async scopeFor(agentPreset) {
             const presets = this.ctx.get('agentPresets');
             if (presets === undefined)
                 return undefined;
             try {
-                return await presets.standingKeyFor(agentPreset);
+                return await presets.acquireScope(agentPreset);
             }
             catch {
                 // An unknown or unusable recorded preset falls back to the global registry.

package/lib/types/types.d.ts

@@ -1,11 +1,11 @@
 /** Browser-safe request, result, and lifecycle vocabulary for the Session Remote service. */
+import type { NativeFileApplication } from '@deepseek-ai/dsh-native-command/types';
 import type { AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
 import type { Branded } from '@deepseek-ai/dsh-brand';
 import type { LlmAttemptId, MessageId } from '@deepseek-ai/dsh-llm/brand';
-import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { TextBlock } from '@deepseek-ai/dsh-llm';
 import type { SessionId, SessionSeqCursor } from '@deepseek-ai/dsh-session/types';
 import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types';
-import type { JobId } from '@deepseek-ai/dsh-jobs/brand';
 import type { JsonValue } from '@deepseek-ai/dsh-util-values';
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
 declare module '@deepseek-ai/dsh-session-projection/types' {
@@ -42,10 +42,24 @@ export interface SessionListMetadata {
     /** Latest human-authored prompt time in the folded prefix. */
     readonly lastPromptAt: number | null;
 }
-/** Every available cached wire value used as partial, possibly stale Session-list hints. */
+/**
+ * Every available wire value a Session-list row carries as partial, possibly
+ * stale hints. `kind` and `asOfSeq` are independent facts: `kind` says which
+ * sequence space `asOfSeq` belongs to, and therefore how a client may merge
+ * the block; `asOfSeq` is the producer's watermark in that space.
+ */
 export interface SessionProjectionHints {
+    /**
+     * `sequenced`: the Host's live registry produced the block for an attached
+     * Session, so `asOfSeq` is comparable with baselines and frames of the same
+     * connection. `cached`: a header-only listing viewed the block from the
+     * persisted projection cache, so `asOfSeq` is the stored record's own
+     * watermark and must not be compared with the connected Session's values.
+     */
+    readonly kind: 'cached' | 'sequenced';
+    /** Watermark of the block in the sequence space named by `kind`. */
     readonly asOfSeq: number;
-    /** Provider-validated values present in the cache; omitted keys remain unknown. */
+    /** Provider-validated values present in the block; omitted keys remain unknown. */
     readonly values: SessionProjectionValues;
 }
 /** Complete projection values at an exact Session event cursor. */
@@ -135,7 +149,7 @@ export interface ModelCatalog {
 export type QueueAction = {
     readonly kind: 'edit';
     /** Non-empty text-only replacement content. */
-    readonly content: readonly ContentBlock[];
+    readonly content: readonly TextBlock[];
 } | {
     readonly kind: 'remove';
 } | {
@@ -143,6 +157,8 @@ export type QueueAction = {
 };
 /** One Session list entry. */
 export interface SessionSummary {
+    /** Whether this Session currently owns a live Agent. */
+    readonly agentAvailable: boolean;
     readonly sessionId: SessionId;
     readonly updatedAt: number;
     readonly running: boolean;
@@ -172,6 +188,10 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
             readonly requestedCwd: string;
             readonly existingCwd?: string;
         };
+        'session/projections-unavailable': Record<string, never>;
+        'session/writer-held': {
+            readonly sessionId: SessionId;
+        };
         'session/agent-busy': {
             readonly reason: string;
         };
@@ -284,6 +304,7 @@ export interface SessionRenameValue {
 /** Session fork request. */
 export interface SessionForkRequest {
     readonly sessionId: SessionId;
+    /** Exact inclusive source event seq; omission selects the latest completed-turn prefix. */
     readonly atSeq?: number;
 }
 /** Identity of a newly forked Session. */
@@ -336,6 +357,8 @@ export interface SessionCancelValue {
 export interface SessionOpenWorkspacePathRequest {
     /** File-manager navigation when requested; omission uses the default application. */
     readonly action?: 'reveal';
+    /** Registered application identifier; ignored for reveal. Omission preserves the operating system default. */
+    readonly application?: string;
     /** Path after best-effort Session workspace resolution, in Host filesystem syntax. */
     readonly path: string;
 }
@@ -363,8 +386,14 @@ export type SessionAddress = {
     readonly kind: 'subagent';
     readonly parentSessionId: SessionId;
     readonly childSessionId: SessionId;
-    readonly mode: 'one-shot' | 'continuable';
+    readonly mode: 'one-shot' | 'continuable' | 'unknown';
 };
+/** One non-activating Session projection read. */
+export interface SessionProjectionsRequest {
+    readonly sessionId: SessionId;
+}
+/** Complete Session projection baseline; null when the Session does not exist. */
+export type SessionProjectionsValue = SessionProjectionBaseline | null;
 /** One raw Session event in the Remote journal. */
 export interface SessionEventEntry {
     readonly type: 'event';
@@ -486,32 +515,8 @@ 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;
-    readonly kind: string;
-    readonly label: string;
-    readonly status: 'running' | 'stopping' | 'completed' | 'killed' | 'failed';
-    readonly detail?: string;
-    readonly startedAt: number;
-    readonly finishedAt?: number;
-}
 /** 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>>;
 }
 /** One finished projection value and its durable watermark. */
@@ -525,23 +530,16 @@ 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;
-    readonly jobs: readonly SessionJob[];
 } | ({
     readonly type: 'projection';
 } & SessionProjectionUpdate);
 declare module '@deepseek-ai/cordis' {
     interface Events {
         /**
-         * A Session became visible to Session list consumers.
+         * A Session became visible or its Agent was created or disposed.
+         * Consumers upsert the summary and replace its current running and availability state.
          * @mode emit
-         * @param summary - initial list row for the Session.
+         * @param summary - current list row for the Session.
          */
         'api-session/added'(summary: SessionSummary): void;
         /**
@@ -575,4 +573,6 @@ declare module '@deepseek-ai/cordis' {
 }
 /** JSON-compatible projection value accepted by list consumers. */
 export type SessionProjectionValue = JsonValue;
+/** Application metadata returned by the serving desktop for one file. */
+export type SessionWorkspacePathApplication = NativeFileApplication;
 //# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -1,4 +1,3 @@
-/** Browser-safe request, result, and lifecycle vocabulary for the Session Remote service. */
 /** Maximum number of Sessions returned by one search. */
 export const SESSION_SEARCH_RESULT_LIMIT = 20;
 /** Maximum search snippet length in Unicode code points. */