@prur/dsh-chat-service 0.1.14

package/lib/index.js

@@ -0,0 +1,379 @@
+/**
+ * chat Typert Remote namespace: a plain streaming model chat domain
+ * (conversations stored under `$DSH_HOME/chat/`) that never enters the
+ * session/agent loop — no tools, no approvals, no workspace. Directly wired
+ * to `ctx.llm.stream`; progress is pushed through the plugin's own WebSocket
+ * downlink (`/chat/events`, see {@link ChatEventsGateway}) as
+ * `host/remote-event`-shaped frames, so no host code change is needed.
+ * @module @prur/dsh-chat-service
+ */
+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 { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { ChatStore, ChatStorageError } from './store.js';
+import { ChatTurnRunner, nextSeq } from './runner.js';
+import { ChatEventBus, ChatEventsGateway } from './events.js';
+import { deriveTitle } from './engine.js';
+/** Default page size for `chat/history`. */
+const DEFAULT_HISTORY_PAGE = 50;
+/** Upper bound on one history page. */
+const MAX_HISTORY_PAGE = 500;
+/** Maximum system prompt characters. */
+const MAX_SYSTEM_PROMPT_CHARS = 16_000;
+/** Stable Cordis plugin name. */
+export const name = 'chat-service';
+/** Business failure carrying a stable code for diagnostics. */
+export class ChatServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ChatServiceError';
+    }
+}
+/** Resolve the harness home the chat store lives under (env overrides default). */
+export function chatHomePath() {
+    const envHome = process.env['DSH_HOME'];
+    return join(envHome ?? join(homedir(), '.dsh'), 'chat');
+}
+/** Validate the composition config; defaults to an empty fence (loopback only). */
+export const Config = z.object({
+    trustedHosts: z.array(String).default([]),
+    // Optional by schemastery convention: only `.required()` fields are mandatory.
+    apiToken: z.string().min(1),
+});
+/**
+ * Host face of the chat namespace: one service per host, conversations keyed
+ * by `conversationId`, turns serialized per conversation through
+ * {@link ChatTurnRunner}, push frames via {@link ChatEventsGateway}.
+ */
+let ChatService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _list_decorators;
+    let _create_decorators;
+    let _rename_decorators;
+    let _delete_decorators;
+    let _history_decorators;
+    let _send_decorators;
+    let _cancel_decorators;
+    let _selectModel_decorators;
+    let _update_decorators;
+    return class ChatService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _list_decorators = [Remote('list')];
+            _create_decorators = [Remote('create')];
+            _rename_decorators = [Remote('rename')];
+            _delete_decorators = [Remote('delete')];
+            _history_decorators = [Remote('history')];
+            _send_decorators = [Remote('send')];
+            _cancel_decorators = [Remote('cancel')];
+            _selectModel_decorators = [Remote('selectModel')];
+            _update_decorators = [Remote('update')];
+            __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, _create_decorators, { kind: "method", name: "create", static: false, private: false, access: { has: obj => "create" in obj, get: obj => obj.create }, 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, _delete_decorators, { kind: "method", name: "delete", static: false, private: false, access: { has: obj => "delete" in obj, get: obj => obj.delete }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _history_decorators, { kind: "method", name: "history", static: false, private: false, access: { has: obj => "history" in obj, get: obj => obj.history }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _send_decorators, { kind: "method", name: "send", static: false, private: false, access: { has: obj => "send" in obj, get: obj => obj.send }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __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, _selectModel_decorators, { kind: "method", name: "selectModel", static: false, private: false, access: { has: obj => "selectModel" in obj, get: obj => obj.selectModel }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _update_decorators, { kind: "method", name: "update", static: false, private: false, access: { has: obj => "update" in obj, get: obj => obj.update }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        /** Required services: the LLM runtime and the HTTP carrier for the downlink. */
+        static inject = ['llm', 'webServer'];
+        store = (__runInitializers(this, _instanceExtraInitializers), new ChatStore(chatHomePath()));
+        runners = new Map();
+        bus = new ChatEventBus();
+        gateway;
+        constructor(ctx, config) {
+            super(ctx, 'chat');
+            this.gateway = new ChatEventsGateway(ctx, config.trustedHosts, config.apiToken);
+            this.bus.subscribe(frame => this.gateway.broadcast(frame));
+            // Recover pending queues after a host restart: a half-finished turn can
+            // never resume (its assistant message was never persisted), so running
+            // conversations settle as aborted; queued sends re-enter their runners.
+            void this.recover().catch((error) => {
+                ctx.logger.warn('chat: recovery failed');
+                ctx.logger.warn(error);
+            });
+            ctx.effect(() => () => {
+                for (const runner of this.runners.values())
+                    runner.dispose();
+                this.runners.clear();
+            }, '@prur/dsh-chat-service: dispose runners');
+        }
+        /** Re-run queued sends and settle half-finished conversations on startup. */
+        async recover() {
+            await this.store.ensure();
+            const records = await this.store.list();
+            for (const record of records) {
+                if (record.running) {
+                    await this.store.put({ ...record, running: false });
+                    this.emitStatus(record.conversationId, { running: false, turn: 0, reason: 'aborted' });
+                }
+                if (record.queue.length > 0) {
+                    for (const send of record.queue)
+                        this.runnerFor(record.conversationId).enqueue(send);
+                }
+            }
+        }
+        /** List conversations newest-first with a running flag. */
+        async list() {
+            const records = await this.store.list();
+            const items = await Promise.all(records.map(async (record) => ({
+                conversationId: record.conversationId,
+                title: record.title,
+                provider: record.provider,
+                model: record.model,
+                updatedAt: record.updatedAt,
+                messageCount: (await this.store.readMessages(record.conversationId)).length,
+                // Read-only: never create a runner just to answer a list query.
+                running: record.running || (this.runners.get(record.conversationId)?.isRunning() ?? false),
+            })));
+            return { ok: true, value: { items } };
+        }
+        /** Create a conversation; absent provider/model defaults to the host's current model. */
+        async create(provider, model, title) {
+            const defaults = this.defaultSelection();
+            const resolvedProvider = provider ?? defaults?.provider;
+            const resolvedModel = model ?? defaults?.model;
+            if (resolvedProvider === undefined || resolvedModel === undefined) {
+                throw new ChatServiceError('no-model', 'chat: no model available — provide provider and model, or configure a host default model');
+            }
+            const now = Date.now();
+            const record = {
+                conversationId: randomUUID(),
+                title: title ?? null,
+                createdAt: now,
+                updatedAt: now,
+                provider: resolvedProvider,
+                model: resolvedModel,
+                temperature: null,
+                contextMessages: null,
+                systemPrompt: null,
+                queue: [],
+                running: false,
+            };
+            await this.store.put(record);
+            return { ok: true, value: { conversationId: record.conversationId } };
+        }
+        /** Rename a conversation. */
+        async rename(conversationId, title) {
+            const record = await this.store.require(conversationId);
+            await this.store.put({ ...record, title, updatedAt: Date.now() });
+            return { ok: true, value: {} };
+        }
+        /** Delete a conversation and its message log; idempotent. */
+        async delete(conversationId) {
+            const runner = this.runners.get(conversationId);
+            runner?.cancel();
+            runner?.dispose();
+            this.runners.delete(conversationId);
+            await this.store.remove(conversationId);
+            return { ok: true, value: {} };
+        }
+        /** Page a conversation's history newest-first under the `beforeSeq` anchor. */
+        async history(conversationId, beforeSeq, maxMessages) {
+            await this.store.require(conversationId);
+            const page = await this.store.paginate(conversationId, beforeSeq, clampPage(maxMessages));
+            return { ok: true, value: page };
+        }
+        /**
+         * Send one user turn into a conversation: the user message persists and is
+         * anchored through `chat/message`, then its turn joins the FIFO queue.
+         */
+        async send(conversationId, content) {
+            const record = await this.store.require(conversationId);
+            const blocks = validateTextBlocks(content);
+            if (blocks.length === 0) {
+                throw new ChatServiceError('invalid-request', 'chat: send needs at least one text block');
+            }
+            const history = await this.store.readMessages(conversationId);
+            const message = {
+                seq: nextSeq(history),
+                role: 'user',
+                blocks,
+                createdAt: Date.now(),
+            };
+            await this.store.appendMessage(conversationId, message);
+            this.emitMessage(conversationId, message);
+            const title = record.title ?? deriveTitle(blocks.map(block => block.text).join(''));
+            // Bind the queued send to its message seq: a queued turn's context must
+            // not include LATER queued user messages (boundary in runTurn).
+            const pending = { seq: message.seq, content: blocks, createdAt: Date.now() };
+            await this.store.put({
+                ...record,
+                title,
+                updatedAt: Date.now(),
+                queue: [...record.queue, pending],
+            });
+            this.runnerFor(conversationId).enqueue(pending);
+            return { ok: true, value: { accepted: true } };
+        }
+        /** Abort the in-flight turn (frozen partial is persisted); idempotent. */
+        async cancel(conversationId) {
+            await this.store.require(conversationId);
+            this.runnerFor(conversationId).cancel();
+            return { ok: true, value: {} };
+        }
+        /** Switch the conversation's model selection. */
+        async selectModel(conversationId, provider, model) {
+            if (provider.length === 0 || model.length === 0) {
+                throw new ChatServiceError('invalid-request', 'chat: provider and model must be non-empty');
+            }
+            const record = await this.store.require(conversationId);
+            await this.store.put({ ...record, provider, model, updatedAt: Date.now() });
+            return { ok: true, value: { provider, model } };
+        }
+        /** Update conversation settings; `null` in the patch unsets a field. */
+        async update(conversationId, patch) {
+            const record = await this.store.require(conversationId);
+            const systemPrompt = patch.systemPrompt === undefined ? record.systemPrompt : patch.systemPrompt;
+            if (systemPrompt !== null && systemPrompt.length > MAX_SYSTEM_PROMPT_CHARS) {
+                throw new ChatServiceError('invalid-request', `chat: system prompt exceeds ${MAX_SYSTEM_PROMPT_CHARS} characters`);
+            }
+            const temperature = patch.temperature === undefined ? record.temperature : patch.temperature;
+            if (temperature !== null && (!Number.isFinite(temperature) || temperature < 0 || temperature > 2)) {
+                throw new ChatServiceError('invalid-request', 'chat: temperature must be within 0..2');
+            }
+            const contextMessages = patch.contextMessages === undefined ? record.contextMessages : patch.contextMessages;
+            if (contextMessages !== null && (!Number.isInteger(contextMessages) || contextMessages <= 0)) {
+                throw new ChatServiceError('invalid-request', 'chat: contextMessages must be a positive integer');
+            }
+            const updatedAt = Date.now();
+            const next = {
+                ...record,
+                systemPrompt,
+                temperature,
+                contextMessages,
+                updatedAt,
+            };
+            await this.store.put(next);
+            return { ok: true, value: settingsView(next) };
+        }
+        defaultSelection() {
+            return this.ctx.get('agentDefaultModel')?.currentSelection();
+        }
+        runnerFor(conversationId) {
+            let runner = this.runners.get(conversationId);
+            if (runner === undefined) {
+                runner = new ChatTurnRunner(conversationId, {
+                    sink: {
+                        emitMessage: (id, message) => this.emitMessage(id, message),
+                        emitChunk: (id, seq, text) => this.bus.publish('chat/chunk', [id, seq, text]),
+                        emitStatus: (id, status) => this.emitStatus(id, status),
+                    },
+                    llm: this.ctx.llm,
+                    store: this.store,
+                    record: () => this.turnRecord(conversationId),
+                    onTurnStart: () => this.turnStart(conversationId),
+                    onTurnEnd: () => this.turnEnd(conversationId),
+                });
+                this.runners.set(conversationId, runner);
+            }
+            return runner;
+        }
+        async turnRecord(conversationId) {
+            const record = await this.store.require(conversationId);
+            return {
+                provider: record.provider,
+                model: record.model,
+                temperature: record.temperature,
+                contextMessages: record.contextMessages,
+                systemPrompt: record.systemPrompt,
+            };
+        }
+        /** Persist turn-start bookkeeping: shift the queued send and mark running. */
+        async turnStart(conversationId) {
+            const record = await this.store.require(conversationId);
+            await this.store.put({
+                ...record,
+                running: true,
+                queue: record.queue.slice(1),
+                updatedAt: Date.now(),
+            });
+        }
+        /** Persist turn-end bookkeeping: release the running flag. */
+        async turnEnd(conversationId) {
+            const record = await this.store.require(conversationId);
+            await this.store.put({ ...record, running: false, updatedAt: Date.now() });
+        }
+        emitMessage(conversationId, message) {
+            this.bus.publish('chat/message', [conversationId, message.seq, message]);
+        }
+        emitStatus(conversationId, status) {
+            this.bus.publish('chat/status', [conversationId, status]);
+        }
+    };
+})();
+export { ChatService };
+function clampPage(maxMessages) {
+    if (maxMessages === undefined)
+        return DEFAULT_HISTORY_PAGE;
+    return Math.min(Math.max(Math.trunc(maxMessages), 1), MAX_HISTORY_PAGE);
+}
+/** Accept only text blocks on the v1 wire; anything else is rejected up front. */
+function validateTextBlocks(content) {
+    const blocks = [];
+    for (const block of content) {
+        if (typeof block !== 'object' || block === null || block.type !== 'text' || typeof block.text !== 'string') {
+            throw new ChatServiceError('unsupported-block', 'chat: v1 accepts text blocks only');
+        }
+        blocks.push({ type: 'text', text: block.text });
+    }
+    return blocks;
+}
+function settingsView(record) {
+    return {
+        conversationId: record.conversationId,
+        title: record.title,
+        provider: record.provider,
+        model: record.model,
+        temperature: record.temperature,
+        contextMessages: record.contextMessages,
+        systemPrompt: record.systemPrompt,
+        updatedAt: record.updatedAt,
+    };
+}
+export default ChatService;
+// Re-export the storage error so consumers can classify RPC failures.
+export { ChatStorageError };

package/lib/runner.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Streaming turn runner for one chat conversation: FIFO queue, one turn at a
+ * time, chunk event emission, cancel/abort settlement, and window-trim
+ * signaling. The llm seam is structural (`LlmLike`) so unit tests run with a
+ * fake stream in this repo; the live service wires `ctx.llm` in.
+ * @module @prur/dsh-chat-service/src/runner
+ */
+import type { ChatMessage, ChatStatus } from './types.ts';
+import type { AssembledMessage } from './engine.ts';
+import type { PendingSend } from './store.ts';
+/** Options a turn passes to the llm stream (structural, llm-compatible). */
+export interface LlmStreamOptions {
+    readonly provider: string;
+    readonly model: string;
+    readonly messages: readonly AssembledMessage[];
+    readonly system?: string;
+    readonly temperature?: number;
+    readonly signal?: AbortSignal;
+}
+/** Streaming chunk projection consumed by the runner. */
+export interface LlmChunkLike {
+    readonly type: string;
+    readonly index?: number;
+    readonly text?: string;
+    readonly block?: {
+        readonly type: string;
+        readonly text?: string;
+    };
+    readonly reason?: {
+        readonly kind: string;
+        readonly failure?: {
+            readonly message: string;
+        };
+    };
+}
+/** Structural llm service seam (matches `ctx.llm`'s used surface). */
+export interface LlmLike {
+    stream(options: LlmStreamOptions): AsyncIterable<LlmChunkLike>;
+    resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
+        readonly context?: {
+            readonly contextWindow: number;
+        };
+    }>;
+}
+/** Event sink for the forwarded chat triplet (host allowlist). */
+export interface ChatEventSink {
+    emitMessage(conversationId: string, message: ChatMessage): void;
+    emitChunk(conversationId: string, seq: number, text: string): void;
+    emitStatus(conversationId: string, status: ChatStatus): void;
+}
+/** Per-turn configuration snapshot: the conversation record at turn start. */
+export interface TurnRecord {
+    readonly provider: string;
+    readonly model: string;
+    readonly temperature: number | null;
+    readonly contextMessages: number | null;
+    readonly systemPrompt: string | null;
+}
+/** Storage interface the runner needs (subset of {@link ChatStore}). */
+export interface RunnerStore {
+    readMessages(conversationId: string): Promise<ChatMessage[]>;
+    appendMessage(conversationId: string, message: ChatMessage): Promise<{
+        trimmed: boolean;
+    }>;
+}
+/** Next monotonic message sequence for a conversation's persisted history. */
+export declare function nextSeq(messages: readonly ChatMessage[]): number;
+/**
+ * Serialized per-conversation turn machine: sends enqueue; the queue drains
+ * one turn at a time; cancel aborts only the in-flight turn.
+ */
+export declare class ChatTurnRunner {
+    private readonly conversationId;
+    private readonly deps;
+    private readonly queue;
+    private running;
+    private controller;
+    private disposed;
+    constructor(conversationId: string, deps: {
+        readonly sink: ChatEventSink;
+        readonly llm: LlmLike;
+        readonly store: RunnerStore;
+        readonly record: () => Promise<TurnRecord>;
+        /** Persist the turn-start bookkeeping (running flag, queue shift). */
+        readonly onTurnStart?: () => Promise<void>;
+        /** Persist the turn-end bookkeeping (running flag release). */
+        readonly onTurnEnd?: () => Promise<void>;
+    });
+    /** Whether a turn is currently streaming. */
+    isRunning(): boolean;
+    /** Enqueue a user send and start draining if idle. */
+    enqueue(send: PendingSend): void;
+    /** Abort the in-flight turn; returns whether one was running. */
+    cancel(): boolean;
+    /** Stop queue advances; an in-flight turn still settles before the runner is dropped. */
+    dispose(): void;
+    private drain;
+    private runTurn;
+    private emitMessage;
+    private emitStatus;
+    private resolveWindow;
+}