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

package/lib/types/control.js

@@ -0,0 +1,192 @@
+/** Live Session queue, jobs, and 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. */
+    constructor(ctx) {
+        this.ctx = ctx;
+        ctx.on('session/event', (session, event) => { this.onSessionEvent(session, event); });
+        ctx.sessionProjections.onChanged((session, key, value, seq) => {
+            this.broadcast({
+                type: 'projection',
+                sessionId: session.id,
+                key,
+                value: value,
+                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();
+            this.streams.clear();
+        }, 'session-controller.control');
+    }
+    /**
+     * Open one generation of Host-wide live control state.
+     * @param signal - Remote stream cancellation.
+     * @returns one complete baseline followed by live replacement frames.
+     */
+    async *control(signal) {
+        signal.throwIfAborted();
+        const queue = new ControlQueue();
+        this.streams.add(queue);
+        try {
+            yield { type: 'baseline', value: this.baseline() };
+            yield* queue.iterate(signal);
+        }
+        finally {
+            this.streams.delete(queue);
+            queue.end();
+        }
+    }
+    baseline() {
+        const sessions = this.ctx.sessions.list();
+        const queues = Object.create(null);
+        const jobs = Object.create(null);
+        for (const session of sessions) {
+            const agent = this.ctx.agents.get(session.id);
+            queues[session.id] = agent?.session === session ? queueItems(agent) : [];
+            jobs[session.id] = this.jobsFor(agent);
+        }
+        return {
+            queues,
+            jobs,
+            projections: this.projectionBaseline(sessions),
+        };
+    }
+    projectionBaseline(sessions) {
+        const blocks = Object.create(null);
+        for (const session of sessions) {
+            const snapshot = this.ctx.sessionProjections.snapshot(session);
+            blocks[session.id] = {
+                asOfSeq: snapshot.asOfSeq,
+                // Every projection definition validates its value before snapshot publication.
+                values: snapshot.values,
+            };
+        }
+        return blocks;
+    }
+    onSessionEvent(session, event) {
+        if (event.type !== 'agent/inbox/spliced')
+            return;
+        const agent = this.ctx.agents.get(session.id);
+        if (agent?.session !== session)
+            return;
+        this.broadcast({
+            type: 'queue',
+            sessionId: session.id,
+            items: queueItems(agent, event.data),
+        });
+    }
+    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);
+    }
+}
+class ControlQueue {
+    buffer = new Deque();
+    wake;
+    done = false;
+    push(frame) {
+        if (this.done)
+            return;
+        this.buffer.pushBack(frame);
+        const wake = this.wake;
+        this.wake = undefined;
+        wake?.();
+    }
+    end() {
+        if (this.done)
+            return;
+        this.done = true;
+        const wake = this.wake;
+        this.wake = undefined;
+        wake?.();
+    }
+    async *iterate(signal) {
+        const onAbort = () => { this.end(); };
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            while (!this.done && !signal.aborted) {
+                const frame = this.buffer.popFront();
+                if (frame !== undefined) {
+                    yield frame;
+                    continue;
+                }
+                await new Promise((resolve) => { this.wake = resolve; });
+            }
+            while (this.buffer.size > 0 && !signal.aborted)
+                yield this.buffer.popFront();
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+            this.end();
+        }
+    }
+}
+function queueItems(agent, splice) {
+    const project = (target) => {
+        const messages = target === 'next-turn' ? agent.inbox.nextTurn : agent.inbox.nextStep;
+        return splice?.target === target
+            ? messages.toSpliced(splice.start, splice.removedCount ?? 0, ...splice.inserted)
+            : messages;
+    };
+    return [
+        ...project('next-turn').map(message => ({
+            id: message.id,
+            placement: 'queued',
+            ...promptRpcId(message),
+            message: { id: message.id, content: message.content },
+        })),
+        ...project('next-step').map(message => ({
+            id: message.id,
+            placement: message.source.kind === 'user' ? 'steering' : 'context',
+            ...promptRpcId(message),
+            message: { id: message.id, content: message.content },
+        })),
+    ];
+}
+/** Prompt-RPC identity carried by a browser-submitted message's user source. */
+function promptRpcId(message) {
+    const source = message.source;
+    return source.kind === 'user' && 'rpcId' in source ? { rpcId: source.rpcId } : {};
+}
+function jobView(job) {
+    return {
+        id: job.id,
+        kind: job.kind,
+        label: job.label,
+        status: job.status,
+        ...(job.detail === undefined ? {} : { detail: job.detail }),
+        startedAt: job.startedAt,
+        ...(job.finishedAt === undefined ? {} : { finishedAt: job.finishedAt }),
+    };
+}
+//# sourceMappingURL=control.js.map

package/lib/types/file-references.d.ts

@@ -0,0 +1,27 @@
+/** Session Controller adapter for Agent-scoped file-reference discovery. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { FileReferenceCandidate } from '@deepseek-ai/dsh-file-reference/types';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Host owner of the `fileReferences` Remote namespace. */
+        sessionFileReferences: SessionFileReferences;
+    }
+}
+/** Host Remote adapter over the composed file-reference provider. */
+export declare class SessionFileReferences extends TypertRemoteService {
+    static inject: string[];
+    /** @param ctx - Host context carrying the selected file-reference provider. */
+    constructor(ctx: Context);
+    /**
+     * List file and directory candidates for one Agent's working directory.
+     * @param agent - target Agent resolved from the Session identity on the wire.
+     * @param query - path text following `@` or `@"`.
+     * @param signal - caller cancellation.
+     * @returns deterministic path-only candidates from the composed provider.
+     */
+    list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
+}
+export default SessionFileReferences;
+//# sourceMappingURL=file-references.d.ts.map

package/lib/types/file-references.js

@@ -0,0 +1,69 @@
+/** Session Controller adapter for Agent-scoped file-reference discovery. */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+/** Host Remote adapter over the composed file-reference provider. */
+let SessionFileReferences = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _list_decorators;
+    return class SessionFileReferences extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _list_decorators = [Remote];
+            __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);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static inject = ['fileReferences', 'typert'];
+        /** @param ctx - Host context carrying the selected file-reference provider. */
+        constructor(ctx) {
+            super(ctx, 'sessionFileReferences', { namespace: 'fileReferences' });
+            __runInitializers(this, _instanceExtraInitializers);
+        }
+        /**
+         * List file and directory candidates for one Agent's working directory.
+         * @param agent - target Agent resolved from the Session identity on the wire.
+         * @param query - path text following `@` or `@"`.
+         * @param signal - caller cancellation.
+         * @returns deterministic path-only candidates from the composed provider.
+         */
+        list(agent, query, signal) {
+            return this.ctx.fileReferences.list(agent, query, signal);
+        }
+    };
+})();
+export { SessionFileReferences };
+export default SessionFileReferences;
+//# sourceMappingURL=file-references.js.map

package/lib/types/history.d.ts

@@ -0,0 +1,31 @@
+/** Cold Session history pagination and live-event source. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SessionObservation } from '@deepseek-ai/dsh-session-query';
+import type { SessionFollowRequest, SessionFollowFrame, SessionPage, SessionPageRequest } from './types.ts';
+/** Implements cold-safe history operations delegated by the Session Controller. */
+export declare class SessionHistoryController {
+    private readonly ctx;
+    private readonly promote;
+    private readonly closeFollowers;
+    /**
+     * @param ctx - Host context carrying Session query and projection services.
+     * @param promote - starts ordinary Session activation after snapshot delivery.
+     */
+    constructor(ctx: Context, promote: (observation: SessionObservation) => void);
+    /**
+     * 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.
+     */
+    page(request: SessionPageRequest, signal: AbortSignal): Promise<SessionPage>;
+    /**
+     * 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.
+     */
+    follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>;
+    private sourceFor;
+}
+//# sourceMappingURL=history.d.ts.map