@crazx/dsh-api-session-controller 0.1.2-alpha.3.zw.1

package/lib/types/commands.js

@@ -0,0 +1,544 @@
+/** Session commands whose activation policy is explicit at each Remote method. */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { randomUUID } from 'node:crypto';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { AttachmentError, admitPromptContent } from '@deepseek-ai/dsh-attachment';
+import { ReasoningEffortId, createUserMessage, freezeMessage, } from '@deepseek-ai/dsh-llm';
+import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
+import { SessionTitleInvalidError } from '@deepseek-ai/dsh-session-title';
+import { canonicalClientTimeZone } from '@deepseek-ai/dsh-util-time';
+import { RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol';
+import { ApiSessionCwdConflict, ApiSessionNotFound, ApiSessionPresetConflict, ApiSessionSubagentOwnership, apiSessionSubagentOwnershipError, hasApiSessionSubagentOwner, inspectApiSession, } from "./agent.js";
+/** Implements Session business commands delegated by the Session Controller Remote service. */
+export class SessionCommandController {
+    ctx;
+    agents;
+    defaultCwd;
+    /**
+     * @param ctx - Host context carrying Agent, model, attachment, title, and Workspace services.
+     * @param agents - sole owner of create, resume, and Session-local model selection.
+     * @param defaultCwd - project directory used when create names neither a Workspace nor a cwd.
+     */
+    constructor(ctx, agents, defaultCwd) {
+        this.ctx = ctx;
+        this.agents = agents;
+        this.defaultCwd = defaultCwd;
+    }
+    /**
+     * Create or idempotently adopt one ordinary Session.
+     * @param request - requested identity, location, and Agent preset.
+     * @returns the Session identity and resolved preset when configured.
+     */
+    async create(request) {
+        if (request.workspaceId !== undefined && request.cwd !== undefined) {
+            throw new RemoteError('gateway/bad-request', 'session.create accepts workspaceId or cwd, not both', {});
+        }
+        const sessionId = request.sessionId ?? brandString(`session-${randomUUID()}`);
+        let workspace;
+        if (request.workspaceId !== undefined) {
+            workspace = this.ctx.workspaceRegistry.get(request.workspaceId);
+            if (workspace === undefined) {
+                throw new RemoteError('workspace/not-found', `workspace "${request.workspaceId}" not found`, {
+                    workspaceId: request.workspaceId,
+                });
+            }
+        }
+        const cwd = workspace?.path ?? request.cwd ?? this.defaultCwd;
+        let adopted;
+        try {
+            adopted = await this.agents.ensureSession(sessionId, cwd, request.sessionId !== undefined, request.agentPreset);
+        }
+        catch (error) {
+            this.rejectCreation(sessionId, error);
+        }
+        if (workspace !== undefined) {
+            try {
+                await workspace.attachSession(sessionId);
+            }
+            catch (error) {
+                throw new RemoteError('session/workspace-attach-failed', `session "${sessionId}" was created but could not attach to workspace "${workspace.id}": ${String(error)}`, { sessionId, workspaceId: workspace.id });
+            }
+        }
+        const agentPreset = this.agents.presetForSession(adopted.session);
+        return { sessionId, ...(agentPreset === undefined ? {} : { agentPreset }) };
+    }
+    /**
+     * Validate and install one Session-local model selection.
+     * @param request - Session identity and requested model selection.
+     * @returns the normalized selection installed for the Session.
+     */
+    async selectModel(request) {
+        const agent = await this.resolveAgent(request.sessionId);
+        return this.agents.serializeImageAdmission(agent, async () => {
+            const persistEffortMemory = async (effort) => {
+                try {
+                    await this.ctx.agentDefaultModel.rememberEffort(request.provider, request.model, effort === undefined ? undefined : ReasoningEffortId(effort));
+                }
+                catch (error) {
+                    this.ctx.logger.warn(`session-controller: the model switch applies to this Session but its effort memory was not updated: ${String(error)}`);
+                }
+            };
+            try {
+                // An absent effort on a DIFFERENT route is a bare model pick: restore
+                // the effort the user last explicitly chose there before the adapter
+                // default materializes. On the SAME route an absent effort is the
+                // explicit provider-default gesture; the post-success write clears it.
+                const current = this.agents.selectionFor(agent).current;
+                const sameRoute = current.provider === request.provider && current.model === request.model;
+                let requested = request.reasoningEffort;
+                if (requested === undefined && !sameRoute) {
+                    const remembered = this.ctx.agentDefaultModel.recallEffort(request.provider, request.model);
+                    if (remembered !== undefined) {
+                        const info = await this.ctx.llm.resolveModelInfo(request.provider, request.model);
+                        if (info.reasoning?.efforts.some(effort => effort.id === remembered)) {
+                            requested = remembered;
+                        }
+                        else {
+                            await persistEffortMemory(undefined);
+                        }
+                    }
+                }
+                const resolved = await this.ctx.llm.resolveCallConfig({
+                    provider: request.provider,
+                    model: request.model,
+                    ...(requested === undefined
+                        ? {}
+                        : { reasoningEffort: ReasoningEffortId(requested) }),
+                });
+                const selected = {
+                    provider: resolved.provider,
+                    model: resolved.model,
+                    ...(resolved.reasoningEffort === undefined
+                        ? {}
+                        : { reasoningEffort: resolved.reasoningEffort }),
+                };
+                this.agents.selectForNextRequest(agent, selected);
+                try {
+                    await this.ctx.agentDefaultModel.saveSelection(selected);
+                }
+                catch (error) {
+                    this.ctx.logger.warn(`session-controller: model selection changed for the Session but the default was not saved: ${String(error)}`);
+                }
+                // Memory records only explicit effort statements: a wire-stated effort
+                // is remembered, and a same-route pick without one clears the route.
+                // A consulted bare pick never writes.
+                if (request.reasoningEffort !== undefined) {
+                    await persistEffortMemory(resolved.reasoningEffort);
+                }
+                else if (sameRoute) {
+                    await persistEffortMemory(undefined);
+                }
+                return { selected: { ...selected } };
+            }
+            catch (error) {
+                if (remoteErrorOf(error) !== undefined)
+                    throw error;
+                throw new RemoteError('session/model-unavailable', error instanceof Error ? error.message : String(error), { provider: request.provider, model: request.model });
+            }
+        });
+    }
+    /**
+     * Normalize and append a user-owned Session title.
+     * @param request - Session identity and proposed title.
+     * @returns the accepted title and durable event sequence.
+     */
+    async rename(request) {
+        const agent = await this.resolveAgent(request.sessionId);
+        const titles = this.ctx.get('sessionTitle');
+        if (titles === undefined) {
+            throw new RemoteError('gateway/internal', 'renaming is unavailable: this deployment mounts no session-title service', {});
+        }
+        try {
+            const accepted = titles.rename(agent.session, request.title);
+            return { title: accepted.title, seq: accepted.eventSeq };
+        }
+        catch (error) {
+            if (error instanceof SessionTitleInvalidError) {
+                throw new RemoteError('session/title-invalid', error.message, { sessionId: request.sessionId });
+            }
+            throw new RemoteError('gateway/internal', `failed to rename session "${request.sessionId}": ${String(error)}`, {});
+        }
+    }
+    /**
+     * Create a new ordinary Session from one completed-turn prefix.
+     * @param request - source Session and optional event anchor.
+     * @returns the new Session identity.
+     */
+    async fork(request) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (request.atSeq !== undefined
+                && (!Number.isInteger(request.atSeq) || request.atSeq < 0)) {
+                throw new RemoteError('gateway/bad-request', 'atSeq must be a non-negative integer', {});
+            }
+            let observed;
+            try {
+                observed = await this.ctx.sessionQuery.observeSession(request.sessionId);
+            }
+            catch (error) {
+                if (error instanceof SessionQueryError
+                    && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
+                    throw new RemoteError('session/not-found', `session "${request.sessionId}" not found`, {
+                        sessionId: request.sessionId,
+                    });
+                }
+                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 atSeq = request.atSeq;
+            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 });
+            }
+            let cut = boundary.seq + 1;
+            while (cut < source.events.length && source.events[cut]?.type !== 'turn/start')
+                cut++;
+            let workspace;
+            try {
+                workspace = await this.forkWorkspace(source.header);
+            }
+            catch (error) {
+                throw new RemoteError('gateway/internal', `failed to resolve fork workspace for session "${request.sessionId}": ${String(error)}`, {});
+            }
+            const childId = brandString(`session-${randomUUID()}`);
+            const composition = await this.agents.composeAgent(this.agents.presetForObservation(source));
+            try {
+                const { provider, model } = this.ctx.agentDefaultModel.currentSelection();
+                await this.ctx.agents.create({
+                    sessionId: childId,
+                    seed: source.events.slice(0, cut),
+                    meta: {
+                        ...(source.header.cwd === undefined ? {} : { cwd: source.header.cwd }),
+                        parentSession: source.header.id,
+                        seedLength: cut,
+                        ...(composition.agentPreset === undefined
+                            ? {}
+                            : { agentPreset: composition.agentPreset }),
+                    },
+                    agentOptions: { provider, model },
+                    setup: composition.setup,
+                });
+            }
+            catch (error) {
+                throw new RemoteError('gateway/internal', `failed to fork session "${request.sessionId}": ${String(error)}`, {});
+            }
+            if (workspace !== undefined) {
+                try {
+                    await workspace.attachSession(childId);
+                }
+                catch (error) {
+                    throw new RemoteError('session/workspace-attach-failed', `session "${childId}" was forked but could not attach to workspace "${workspace.id}": ${String(error)}`, { sessionId: childId, workspaceId: workspace.id });
+                }
+            }
+            return { sessionId: childId };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    /**
+     * Admit one browser prompt after explicit Agent resume and image validation.
+     * @param request - Session identity, prompt content, source metadata, and delivery mode.
+     * @returns acknowledgement that the Agent accepted the prompt.
+     */
+    async prompt(request) {
+        const clientTimeZone = request.clientTimeZone === undefined
+            ? undefined
+            : canonicalClientTimeZone(request.clientTimeZone);
+        if (request.clientTimeZone !== undefined && clientTimeZone === undefined) {
+            throw new RemoteError('session/invalid-time-zone', 'clientTimeZone must be UTC or a valid IANA Area/Location name', { value: request.clientTimeZone });
+        }
+        const agent = await this.resolveAgent(request.sessionId);
+        const selection = this.agents.selectionFor(agent).current;
+        if (!routeServed(this.ctx, selection.provider)) {
+            throw new RemoteError('session/model-unavailable', `no adapter serves provider "${selection.provider}"; select a model for this session`, { provider: selection.provider, model: selection.model });
+        }
+        const source = {
+            kind: 'user',
+            rpcId: request.requestId,
+            ...(clientTimeZone === undefined ? {} : { clientTimeZone }),
+        };
+        const hasImage = request.content.some(part => part.type === 'image');
+        const admit = async () => {
+            try {
+                if (hasImage) {
+                    const current = this.agents.selectionFor(agent).current;
+                    const model = await this.ctx.llm.resolveModelInfo(current.provider, current.model);
+                    if (model.inputModalities !== undefined && !model.inputModalities.includes('image')) {
+                        throw new RemoteError('session/attachment-invalid', `Model "${current.model}" does not support image input.`, { reason: 'MODEL_DOES_NOT_SUPPORT_IMAGES' });
+                    }
+                }
+                const content = await admitPromptContent(this.ctx.attachments, request.content);
+                const message = createUserMessage({ content, source });
+                if (request.mode === 'steer')
+                    agent.steer(message);
+                else
+                    agent.followup(message);
+            }
+            catch (error) {
+                if (remoteErrorOf(error) !== undefined)
+                    throw error;
+                if (error instanceof AttachmentError) {
+                    throw new RemoteError('session/attachment-invalid', error.message, { reason: error.code });
+                }
+                throw new RemoteError('session/agent-busy', 'prompt rejected', { reason: String(error) });
+            }
+            return { accepted: true };
+        };
+        return hasImage ? this.agents.serializeImageAdmission(agent, admit) : admit();
+    }
+    /**
+     * Read one durable image after proving the Session log references it.
+     * @param request - Session and attachment identities used for authorization.
+     * @returns the durable attachment reference and base64-encoded bytes.
+     */
+    async attachment(request) {
+        let source;
+        try {
+            source = await this.readSessionState(request.sessionId);
+        }
+        catch (error) {
+            if (error instanceof ApiSessionNotFound) {
+                throw new RemoteError('session/not-found', error.message, { sessionId: request.sessionId });
+            }
+            throw new RemoteError('gateway/internal', `attachment authorization unavailable for session "${request.sessionId}": ${String(error)}`, {});
+        }
+        const ref = referencedImage(source.events, String(request.attachmentId));
+        if (ref === undefined) {
+            throw new RemoteError('session/attachment-invalid', 'Image is not referenced by this session.', { reason: 'ATTACHMENT_NOT_REFERENCED' });
+        }
+        try {
+            const stored = await this.ctx.attachments.readImage(ref);
+            return {
+                attachment: stored.ref,
+                data: Buffer.from(stored.data).toString('base64'),
+            };
+        }
+        catch (error) {
+            if (error instanceof AttachmentError) {
+                throw new RemoteError('session/attachment-invalid', error.message, { reason: error.code });
+            }
+            throw new RemoteError('gateway/internal', 'Unable to read image attachment.', {});
+        }
+    }
+    /**
+     * Mutate one still-pending queue occurrence without resuming a cold Agent.
+     * @param request - Session, queue item, and requested mutation.
+     * @returns acknowledgement that the queue mutation was applied.
+     */
+    updateQueue(request) {
+        if (request.action.kind === 'edit'
+            && 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' });
+        }
+        const agent = this.ctx.agents.get(request.sessionId);
+        if (agent !== undefined && hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) {
+            throw apiSessionSubagentOwnershipError(request.sessionId);
+        }
+        if (agent === undefined) {
+            throw new RemoteError('session/queue-item-not-found', 'queued item is no longer pending', { itemId: request.itemId });
+        }
+        const nextTurn = agent.inbox.nextTurn.find(message => message.id === request.itemId);
+        const nextStep = agent.inbox.nextStep.find(message => message.id === request.itemId);
+        const located = nextTurn === undefined
+            ? nextStep === undefined ? undefined : { target: 'next-step', message: nextStep }
+            : { target: 'next-turn', message: nextTurn };
+        if (located === undefined) {
+            throw new RemoteError('session/queue-item-not-found', 'queued item is no longer pending', { itemId: request.itemId });
+        }
+        const { target, message } = located;
+        if (request.action.kind === 'steer' && (target !== 'next-turn' || agent.status !== 'running')) {
+            throw new RemoteError('session/steer-unavailable', 'current turn no longer accepts steering', { itemId: request.itemId });
+        }
+        if (request.action.kind === 'edit') {
+            agent.inbox.replace(request.itemId, freezeMessage({
+                ...message,
+                content: [...request.action.content],
+            }));
+        }
+        else {
+            agent.inbox.remove(request.itemId);
+            if (request.action.kind === 'steer')
+                agent.steer(message);
+        }
+        return { accepted: true };
+    }
+    /**
+     * Cancel one live ordinary Agent while retaining pending inbox work.
+     * @param request - Session whose active Agent turn is cancelled.
+     * @returns acknowledgement that cancellation was requested.
+     */
+    cancel(request) {
+        const agent = this.ctx.agents.get(request.sessionId);
+        if (agent === undefined) {
+            throw new RemoteError('session/not-found', `session "${request.sessionId}" not found (not attached)`, { sessionId: request.sessionId });
+        }
+        if (hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) {
+            throw apiSessionSubagentOwnershipError(request.sessionId);
+        }
+        agent.cancel({ kind: 'user' }, { keepInbox: true });
+        return { accepted: true };
+    }
+    async resolveAgent(sessionId) {
+        const found = await this.agents.resolveAgent(sessionId);
+        if ('error' in found)
+            throw found.error;
+        return found.agent;
+    }
+    rejectCreation(sessionId, error) {
+        if (remoteErrorOf(error) !== undefined)
+            throw error;
+        if (error instanceof ApiSessionPresetConflict) {
+            throw new RemoteError('agent-preset/conflict', error.message, {
+                sessionId: error.sessionId,
+                requestedPreset: error.requestedPreset,
+                ...(error.existingPreset === undefined ? {} : { existingPreset: error.existingPreset }),
+            });
+        }
+        if (error instanceof ApiSessionCwdConflict) {
+            throw new RemoteError('session/conflict', error.message, {
+                sessionId: error.sessionId,
+                requestedCwd: error.requestedCwd,
+                ...(error.existingCwd === undefined ? {} : { existingCwd: error.existingCwd }),
+            });
+        }
+        if (error instanceof ApiSessionSubagentOwnership) {
+            throw apiSessionSubagentOwnershipError(error.sessionId);
+        }
+        throw new RemoteError('gateway/internal', `failed to create session "${sessionId}": ${String(error)}`, {});
+    }
+    async readSessionState(sessionId) {
+        const attached = this.ctx.sessions.get(sessionId);
+        if (attached !== undefined) {
+            return { id: attached.id, header: attached.header, events: [...attached.events] };
+        }
+        const inspected = await inspectApiSession(this.ctx, sessionId);
+        return { id: inspected.meta.id, header: inspected.meta, events: inspected.events };
+    }
+    async forkWorkspace(source) {
+        const workspaces = this.ctx.workspaceRegistry.list();
+        const direct = workspaces.find(workspace => workspace.sessionIds.includes(source.id));
+        if (direct !== undefined || source.origin !== 'subagent')
+            return direct;
+        const lineage = await this.ctx.sessionQuery.traceSession(source.id);
+        for (const ancestor of lineage.ancestors) {
+            const workspace = workspaces.find(candidate => candidate.sessionIds.includes(ancestor.header.id));
+            if (workspace !== undefined)
+                return workspace;
+        }
+        return undefined;
+    }
+}
+function imageBlockIn(content, match) {
+    if (!Array.isArray(content))
+        return undefined;
+    for (const value of content) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            continue;
+        const block = value;
+        if (block.type === 'image' && typeof block.attachment === 'object' && block.attachment !== null) {
+            const ref = block.attachment;
+            if (match(ref))
+                return ref;
+        }
+        if (block.type === 'tool-result') {
+            const nested = imageBlockIn(block.content, match);
+            if (nested !== undefined)
+                return nested;
+        }
+    }
+    return undefined;
+}
+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;
+    }
+    return event.type === 'assistant/chunk' && data.chunk?.type === 'block-end'
+        ? imageBlockIn([data.chunk.block], match)
+        : undefined;
+}
+function referencedImage(events, attachmentId) {
+    for (const event of events) {
+        const found = imageInEvent(event, ref => String(ref.attachmentId) === attachmentId);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function routeServed(ctx, provider) {
+    return ctx.llm.listProviders().some(entry => entry.id === provider);
+}
+//# sourceMappingURL=commands.js.map

package/lib/types/control.d.ts

@@ -0,0 +1,23 @@
+/** Live Session queue, jobs, and projection state with reconnect baselines. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionControlFrame } from './types.ts';
+/** Owns the Host-wide Session control stream. */
+export declare class SessionControlController {
+    private readonly ctx;
+    private readonly streams;
+    /** @param ctx - Host context carrying live Agent, projection, and jobs services. */
+    constructor(ctx: Context);
+    /**
+     * Open one generation of Host-wide live control state.
+     * @param signal - Remote stream cancellation.
+     * @returns one complete baseline followed by live replacement frames.
+     */
+    control(signal: AbortSignal): AsyncIterable<SessionControlFrame>;
+    private baseline;
+    private projectionBaseline;
+    private onSessionEvent;
+    private onJobsChanged;
+    private jobsFor;
+    private broadcast;
+}
+//# sourceMappingURL=control.d.ts.map