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

package/lib/types/history.js

@@ -0,0 +1,376 @@
+/** Cold Session history pagination and live-event source. */
+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 { Deque } from '@deepseek-ai/dsh-deque';
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session';
+import { isChunkRow, packChunkRuns } from '@deepseek-ai/dsh-session/chunk-rows';
+import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+const DEFAULT_MAX_MESSAGES = 50;
+const MESSAGE_TYPES = new Set(['user/message', 'assistant/message']);
+/** Implements cold-safe history operations delegated by the Session Controller. */
+export class SessionHistoryController {
+    ctx;
+    promote;
+    closeFollowers = new Set();
+    /**
+     * @param ctx - Host context carrying Session query and projection services.
+     * @param promote - starts ordinary Session activation after snapshot delivery.
+     */
+    constructor(ctx, promote) {
+        this.ctx = ctx;
+        this.promote = promote;
+        ctx.effect(() => () => {
+            for (const close of this.closeFollowers)
+                close();
+            this.closeFollowers.clear();
+        }, 'session-controller.history');
+    }
+    /**
+     * Read one message-aligned history page without activating an Agent.
+     * @param request - durable address and backwards-page cursor.
+     * @param signal - caller cancellation for persistence reads.
+     * @returns a contiguous event page.
+     */
+    async page(request, signal) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            validatePageRequest(request);
+            const source = __addDisposableResource(env_1, await this.sourceFor(request.address, signal, false), false);
+            signal.throwIfAborted();
+            const sourceLog = source.events;
+            const sourceCursor = sourceLog.at(-1)?.seq ?? -1;
+            if (request.throughSeq > sourceCursor) {
+                throw new RemoteError('gateway/bad-request', `session page through seq ${String(request.throughSeq)} is past cursor ${String(sourceCursor)}`, {});
+            }
+            /* v8 ignore next -- Session and persistence validation guarantee a dense zero-based event prefix. */
+            if (request.throughSeq >= 0 && sourceLog[request.throughSeq]?.seq !== request.throughSeq) {
+                throw new RemoteError('gateway/internal', `session log does not contain through seq ${String(request.throughSeq)}`, {});
+            }
+            const page = paginate(sourceLog, request.beforeSeq, request.maxMessages ?? DEFAULT_MAX_MESSAGES, request.throughSeq);
+            const records = pageRecords(page.events);
+            return {
+                records,
+                hasMore: page.hasMore,
+            };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    /**
+     * Follow events appended after an initial cursor on one durable address.
+     * @param request - durable address and last committed sequence already held by the caller.
+     * @param signal - stream cancellation owned by the Remote carrier.
+     * @returns a complete opening snapshot followed by gap-free event frames.
+     */
+    async *follow(request, signal) {
+        validateFollowRequest(request);
+        const { address } = request;
+        const target = addressId(address);
+        const buffered = new Deque();
+        let snapshotCursor;
+        let wake;
+        const notify = () => {
+            const resume = wake;
+            wake = undefined;
+            resume?.();
+        };
+        const follower = { closed: false };
+        const close = () => {
+            follower.closed = true;
+            notify();
+        };
+        this.closeFollowers.add(close);
+        const disposeEvent = this.ctx.on('session/event', (session, event) => {
+            if (session.id !== target)
+                return;
+            buffered.pushBack(event);
+            notify();
+        }, { global: true });
+        const disposeCreated = this.ctx.on('session/created', (session) => {
+            if (session.id !== target)
+                return;
+            // Constructor seed events have no session/event notification. Normally
+            // only the end-seed suffix is new; if persistence advanced after the
+            // opening observation, replay everything beyond that snapshot cursor.
+            const suffix = session.events.slice(snapshotCursor === undefined
+                ? session.firstLiveSeq
+                : snapshotCursor + 1);
+            for (let index = suffix.length - 1; index >= 0; index -= 1) {
+                buffered.pushFront(suffix[index]);
+            }
+            notify();
+        }, { global: true });
+        const onAbort = () => { notify(); };
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const source = __addDisposableResource(env_2, await this.sourceFor(address, signal, true), false);
+                const events = source.events;
+                signal.throwIfAborted();
+                const cursor = source.cursor;
+                snapshotCursor = cursor;
+                const page = paginate(events, undefined, request.maxMessages ?? DEFAULT_MAX_MESSAGES);
+                yield {
+                    type: 'snapshot',
+                    header: source.header,
+                    cursor,
+                    records: pageRecords(page.events),
+                    hasMore: page.hasMore,
+                    projections: source.projections === undefined
+                        ? { asOfSeq: cursor, values: {} }
+                        : projectionBlock(source.projections),
+                };
+                if (address.kind === 'session' && source.source === 'prepared') {
+                    const promotion = source.retain();
+                    try {
+                        this.promote(promotion);
+                    }
+                    catch (error) {
+                        promotion[Symbol.dispose]();
+                        throw error;
+                    }
+                }
+                let nextSeq = cursor + 1;
+                while (!follower.closed && !signal.aborted) {
+                    const item = buffered.popFront();
+                    if (item === undefined) {
+                        await new Promise((resolve) => { wake = resolve; });
+                        continue;
+                    }
+                    if (item.seq < nextSeq)
+                        continue;
+                    if (item.seq !== nextSeq) {
+                        throw new RemoteError('gateway/internal', `session event stream skipped seq ${String(nextSeq)}`, {});
+                    }
+                    nextSeq++;
+                    yield entryFor(item);
+                }
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
+            }
+        }
+        finally {
+            this.closeFollowers.delete(close);
+            signal.removeEventListener('abort', onAbort);
+            disposeCreated();
+            disposeEvent();
+        }
+    }
+    async sourceFor(address, signal, withProjections) {
+        const sessionId = addressId(address);
+        try {
+            const observation = await this.ctx.sessionQuery.observeSession(sessionId, {
+                signal,
+                projectionMode: withProjections || address.kind === 'subagent' ? 'all' : 'none',
+            });
+            if (observation.header.cwd === undefined) {
+                observation[Symbol.dispose]();
+                rejectNotFound(address);
+            }
+            try {
+                validateAddress(address, observation.header, observation.projections);
+            }
+            catch (error) {
+                observation[Symbol.dispose]();
+                throw error;
+            }
+            return observation;
+        }
+        catch (error) {
+            if (error instanceof SessionQueryError
+                && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND')
+                rejectNotFound(address);
+            throw error;
+        }
+    }
+}
+function projectionBlock(snapshot) {
+    return {
+        asOfSeq: snapshot.asOfSeq,
+        // Projection definitions validate whole JSON values before snapshot publication.
+        values: snapshot.values,
+    };
+}
+function validatePageRequest(request) {
+    if (!Number.isSafeInteger(request.throughSeq) || request.throughSeq < -1) {
+        throw new RemoteError('gateway/bad-request', 'throughSeq must be an integer greater than or equal to -1', {});
+    }
+    if (request.beforeSeq !== undefined
+        && (!Number.isSafeInteger(request.beforeSeq) || 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', {});
+    }
+}
+function validateFollowRequest(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', {});
+    }
+}
+function addressId(address) {
+    return address.kind === 'session' ? address.sessionId : address.childSessionId;
+}
+function validateAddress(address, header, projections) {
+    if (address.kind === 'session') {
+        if (header.origin === 'subagent') {
+            throw new RemoteError('session/agent-busy', 'subagent Sessions require their durable parent address', {
+                reason: 'use subagent delivery for this child session',
+            });
+        }
+        return;
+    }
+    if (header.origin !== 'subagent' || header.parentSession !== address.parentSessionId) {
+        throw new RemoteError('subagent/unauthorized', 'subagent does not belong to the supplied parent', {
+            childSessionId: address.childSessionId,
+        });
+    }
+    const identity = projections?.values.subagent;
+    if (identity === null) {
+        throw new RemoteError('subagent/catalog-diagnostic', 'subagent descriptor is corrupt', {
+            parentSessionId: address.parentSessionId,
+            childSessionId: address.childSessionId,
+            reason: 'corrupt',
+        });
+    }
+    if (identity === undefined || identity.seq < (header.seedLength ?? 0)) {
+        throw new RemoteError('subagent/catalog-diagnostic', 'subagent descriptor is unavailable', {
+            parentSessionId: address.parentSessionId,
+            childSessionId: address.childSessionId,
+            reason: 'unsupported',
+        });
+    }
+    if (identity.mode !== address.mode) {
+        throw new RemoteError('subagent/unauthorized', 'subagent mode does not match the supplied address', {
+            childSessionId: address.childSessionId,
+        });
+    }
+}
+function rejectNotFound(address) {
+    if (address.kind === 'session') {
+        throw new RemoteError('session/not-found', `session "${address.sessionId}" not found`, { sessionId: address.sessionId });
+    }
+    throw new RemoteError('subagent/not-found', 'subagent is unavailable', {
+        parentSessionId: address.parentSessionId,
+        childSessionId: address.childSessionId,
+    });
+}
+function paginate(events, beforeSeq, maxMessages, throughSeq = events.at(-1)?.seq ?? -1) {
+    const end = Math.min(throughSeq + 1, beforeSeq ?? throughSeq + 1);
+    let count = 0;
+    let cut = 0;
+    for (let index = end - 1; index >= 0; index--) {
+        const event = events[index];
+        if (!MESSAGE_TYPES.has(event.type) || !isAppendSurfaceEvent(event))
+            continue;
+        count++;
+        const sources = event.sourceEventSeqs;
+        let groupStart = event.seq;
+        if (sources !== undefined) {
+            for (const source of sources)
+                groupStart = Math.min(groupStart, source);
+        }
+        if (count >= maxMessages) {
+            cut = groupStart;
+            break;
+        }
+    }
+    return { events: events.slice(cut, end), hasMore: cut > 0 };
+}
+function entryFor(event) {
+    return {
+        type: 'event',
+        // Session.append validates and freezes event data as JSON before publication.
+        event: event,
+    };
+}
+function chunkEntryFor(row) {
+    switch (row.type) {
+        case 'text-chunks':
+            return {
+                type: 'chunks',
+                event: { type: 'chunkrow/text-chunks', seq: row.seq0, time: row.time0, data: row.data },
+            };
+        case 'reasoning-chunks':
+            return {
+                type: 'chunks',
+                event: { type: 'chunkrow/reasoning-chunks', seq: row.seq0, time: row.time0, data: row.data },
+            };
+        case 'tool-call-chunks':
+            return {
+                type: 'chunks',
+                event: { type: 'chunkrow/tool-call-chunks', seq: row.seq0, time: row.time0, data: row.data },
+            };
+    }
+}
+/** Encode one bounded logical page without changing its pagination cut. */
+function pageRecords(events) {
+    return packChunkRuns(events).map(record => isChunkRow(record)
+        ? chunkEntryFor(record)
+        : entryFor(record));
+}
+//# sourceMappingURL=history.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,171 @@
+/** 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 type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session';
+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';
+export type * from './types.ts';
+export { ApiSessionNotFound } from './agent.ts';
+export { SessionFileReferences } from './file-references.ts';
+export { SessionSkillCatalog } from './skill-catalog.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Host Session business API and Remote namespace owner. */
+        sessionController: SessionController;
+    }
+}
+/** Session Controller deployment policy. */
+export interface Config {
+    /** Maximum cold Session artifact size eligible for one full projection observation. */
+    readonly coldBlankProbeMaxBytes?: number;
+    /** Override platform desktop-opener detection. */
+    readonly nativeOpen?: boolean;
+}
+/** Host integrations replaceable by direct unit tests. */
+export interface SessionControllerInternals {
+    /** Native default-application handoff. */
+    readonly openPath?: (path: string, signal: AbortSignal) => Promise<void>;
+    /** Native handoff availability probe. */
+    readonly canOpenPath?: () => boolean;
+}
+/** Host service backing the generated `ctx.remote.session` namespace. */
+export declare class SessionController extends TypertRemoteService {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly agents;
+    private readonly commands;
+    private readonly controlState;
+    private readonly history;
+    private readonly listState;
+    private readonly openPath;
+    private readonly canOpenPath;
+    private readonly promotions;
+    /**
+     * @param ctx - Host context containing the Session capability assembly.
+     * @param config - cold-list observation policy.
+     */
+    constructor(ctx: Context, config: Config, internals?: SessionControllerInternals);
+    private promote;
+    /**
+     * Resolve or resume one ordinary Session for another Host API domain.
+     * @param sessionId - Session identity whose Agent owns the operation.
+     * @returns the live Agent or the stable Session-domain failure.
+     */
+    resolveAgent(sessionId: SessionId): Promise<ApiSessionAgentResult>;
+    /**
+     * Inspect one attached or persisted Session without activating its Agent.
+     * @param sessionId - durable Session identity.
+     * @param signal - optional caller cancellation for persistence reads.
+     * @returns the current attached state or persisted header and event prefix.
+     */
+    inspect(sessionId: SessionId, signal?: AbortSignal): Promise<{
+        meta: SessionHeader;
+        events: SessionEvent[];
+    }>;
+    /**
+     * Read all visible Session rows without resuming an Agent.
+     * @param _request - reserved empty list request.
+     * @param signal - cancellation for persistence reads.
+     * @returns visible Session summaries ordered by activity.
+     */
+    list(_request: SessionListRequest, signal: AbortSignal): Promise<SessionListValue>;
+    /**
+     * Search visible Session content without resuming an Agent.
+     * @param request - literal message-content query.
+     * @param signal - cancellation for list and search reads.
+     * @returns authorized bounded Session search results.
+     */
+    search(request: SessionSearchRequest, signal: AbortSignal): Promise<SessionSearchValue>;
+    /**
+     * Create or idempotently adopt one ordinary Session.
+     * @param request - requested identity, location, and Agent preset.
+     * @returns the Session identity and resolved preset when configured.
+     */
+    create(request: SessionCreateRequest): Promise<SessionCreateValue>;
+    /**
+     * Select one Session-local model after explicitly resuming the Session.
+     * @param request - Session identity and requested model selection.
+     * @returns the normalized selection installed for the Session.
+     */
+    selectModel(request: SessionSelectModelRequest): Promise<SessionSelectModelValue>;
+    /**
+     * Describe every currently routable model for Host-generation selectors.
+     * @returns provider-grouped models, the deployment default, and isolated provider failures.
+     */
+    modelCatalog(): Promise<ModelCatalog>;
+    /**
+     * Report whether this deployment can hand a Session workspace path to a native desktop.
+     * @returns true when the matching open operation is available.
+     */
+    canOpenWorkspacePath(): boolean;
+    /**
+     * Open one path prepared by a Session-aware caller 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.
+     */
+    openWorkspacePath(request: SessionOpenWorkspacePathRequest, signal: AbortSignal): Promise<SessionOpenWorkspacePathValue>;
+    /**
+     * Rename one Session after explicitly resuming it.
+     * @param request - Session identity and proposed title.
+     * @returns the accepted title and durable event sequence.
+     */
+    rename(request: SessionRenameRequest): Promise<SessionRenameValue>;
+    /**
+     * Fork one cold-readable completed-turn prefix into a new Session.
+     * @param request - source Session and optional event anchor.
+     * @returns the new Session identity.
+     */
+    fork(request: SessionForkRequest): Promise<SessionForkValue>;
+    /**
+     * Admit one prompt after explicitly resuming its Session.
+     * @param request - Session identity, prompt content, source metadata, and delivery mode.
+     * @param signal - caller cancellation before prompt admission begins.
+     * @returns acknowledgement that the Agent accepted the prompt.
+     */
+    prompt(request: SessionPromptRequest, signal: AbortSignal): Promise<SessionPromptValue>;
+    /**
+     * Read one image proven reachable from the addressed Session log.
+     * @param request - Session and attachment identities used for authorization.
+     * @returns the durable attachment reference and base64-encoded bytes.
+     */
+    attachment(request: SessionAttachmentRequest): Promise<SessionAttachmentValue>;
+    /**
+     * Mutate one still-pending queue occurrence on a live Agent.
+     * @param request - Session, queue item, and requested mutation.
+     * @returns acknowledgement that the queue mutation was applied.
+     */
+    updateQueue(request: SessionUpdateQueueRequest): SessionUpdateQueueValue;
+    /**
+     * Cancel one active Agent turn without dropping its pending inbox.
+     * @param request - Session whose active Agent turn is cancelled.
+     * @returns acknowledgement that cancellation was requested.
+     */
+    cancel(request: SessionCancelRequest): SessionCancelValue;
+    /**
+     * Read one cold-safe, message-aligned Session history page.
+     * @param request - durable address, backward cursor, and page budget.
+     * @param signal - cancellation for persistence reads.
+     * @returns one chronological page.
+     */
+    page(request: SessionPageRequest, signal: AbortSignal): Promise<SessionPage>;
+    /**
+     * Follow one Session log from its opening or resume cursor.
+     * @param request - durable address and last committed sequence already held by the caller.
+     * @param signal - cancellation owned by the Remote stream carrier.
+     * @returns a complete opening snapshot followed by gap-free event frames.
+     */
+    follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>;
+    /**
+     * Stream a complete live-control baseline followed by replacement frames.
+     * @param signal - cancellation owned by the Remote stream carrier.
+     * @returns one complete baseline followed by live replacement frames.
+     */
+    control(signal: AbortSignal): AsyncIterable<SessionControlFrame>;
+}
+export { buildModelCatalog };
+export default SessionController;
+//# sourceMappingURL=index.d.ts.map