@prur/dsh-chat-service 0.1.14

package/lib/runner.js

@@ -0,0 +1,222 @@
+/**
+ * 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 { assembleContext } from './engine.js';
+function isAbortError(error) {
+    if (error instanceof Error && error.name === 'AbortError')
+        return true;
+    const cause = error?.cause;
+    return cause instanceof Error && cause.name === 'AbortError';
+}
+function mapFinishKind(kind) {
+    switch (kind) {
+        case 'aborted': return 'aborted';
+        case 'error': return 'error';
+        case 'max-tokens': return 'max-tokens';
+        default: return 'completed';
+    }
+}
+/** Next monotonic message sequence for a conversation's persisted history. */
+export function nextSeq(messages) {
+    let last = 0;
+    for (const message of messages) {
+        if (message.seq > last)
+            last = message.seq;
+    }
+    return last + 1;
+}
+/**
+ * Serialized per-conversation turn machine: sends enqueue; the queue drains
+ * one turn at a time; cancel aborts only the in-flight turn.
+ */
+export class ChatTurnRunner {
+    conversationId;
+    deps;
+    queue = [];
+    running = false;
+    controller = null;
+    disposed = false;
+    constructor(conversationId, deps) {
+        this.conversationId = conversationId;
+        this.deps = deps;
+    }
+    /** Whether a turn is currently streaming. */
+    isRunning() {
+        return this.running;
+    }
+    /** Enqueue a user send and start draining if idle. */
+    enqueue(send) {
+        this.queue.push(send);
+        void this.drain().catch((error) => {
+            // A turn-level failure is contained inside runTurn; reaching here only
+            // means the runner itself broke — settle the conversation visibly.
+            this.emitStatus({ running: false, turn: -1, reason: 'error' });
+            this.emitMessage({
+                seq: -1,
+                role: 'assistant',
+                blocks: [],
+                error: `chat: turn runner failed: ${error.message}`,
+                createdAt: Date.now(),
+            });
+        });
+    }
+    /** Abort the in-flight turn; returns whether one was running. */
+    cancel() {
+        if (!this.running || this.controller === null)
+            return false;
+        this.controller.abort();
+        return true;
+    }
+    /** Stop queue advances; an in-flight turn still settles before the runner is dropped. */
+    dispose() {
+        this.disposed = true;
+    }
+    async drain() {
+        if (this.running || this.disposed)
+            return;
+        this.running = true;
+        try {
+            while (this.queue.length > 0 && !this.disposed) {
+                const send = this.queue.shift();
+                try {
+                    await this.deps.onTurnStart?.();
+                }
+                catch {
+                    // The conversation vanished mid-queue (deleted while drained): stop.
+                    break;
+                }
+                try {
+                    await this.runTurn(send);
+                }
+                finally {
+                    await this.deps.onTurnEnd?.().catch(() => { });
+                }
+            }
+        }
+        finally {
+            this.running = false;
+            this.controller = null;
+        }
+    }
+    async runTurn(send) {
+        const record = await this.deps.record();
+        const all = await this.deps.store.readMessages(this.conversationId);
+        // Context boundary: this turn answers only its own user message. Later
+        // (queued) user messages stay out of the prompt until their own turn.
+        const history = typeof send.seq === 'number'
+            ? all.filter(message => message.seq <= send.seq)
+            : all;
+        const window = await this.resolveWindow(record);
+        const assembled = assembleContext(history, record.contextMessages, window);
+        const seq = nextSeq(history);
+        const controller = new AbortController();
+        this.controller = controller;
+        this.emitStatus({ running: true, turn: seq });
+        const parts = new Map();
+        const emitDelta = (index, text) => {
+            if (text.length === 0)
+                return;
+            parts.set(index, (parts.get(index) ?? '') + text);
+            this.deps.sink.emitChunk(this.conversationId, seq, text);
+        };
+        let finishReason = 'completed';
+        let failure;
+        try {
+            const stream = this.deps.llm.stream({
+                provider: record.provider,
+                model: record.model,
+                messages: assembled.messages,
+                ...record.systemPrompt === null ? {} : { system: record.systemPrompt },
+                ...record.temperature === null ? {} : { temperature: record.temperature },
+                signal: controller.signal,
+            });
+            for await (const chunk of stream) {
+                if (this.disposed)
+                    break;
+                if (chunk.type === 'text-delta' && typeof chunk.index === 'number' && typeof chunk.text === 'string') {
+                    emitDelta(chunk.index, chunk.text);
+                }
+                else if (chunk.type === 'block-end' && chunk.index !== undefined && chunk.block?.type === 'text') {
+                    // Some adapters deliver only the assembled block; backfill when no
+                    // delta streamed for this index.
+                    if (!parts.has(chunk.index) && typeof chunk.block.text === 'string' && chunk.block.text.length > 0) {
+                        emitDelta(chunk.index, chunk.block.text);
+                    }
+                }
+                else if (chunk.type === 'finish') {
+                    if (chunk.reason?.kind === 'aborted')
+                        finishReason = 'aborted';
+                    else if (chunk.reason?.kind === 'error') {
+                        finishReason = 'error';
+                        failure = chunk.reason.failure?.message ?? '模型调用失败';
+                    }
+                    else {
+                        finishReason = mapFinishKind(chunk.reason?.kind);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (isAbortError(error)) {
+                finishReason = 'aborted';
+            }
+            else {
+                finishReason = 'error';
+                failure = error instanceof Error ? error.message : String(error);
+            }
+        }
+        const text = [...parts.entries()].sort((a, b) => a[0] - b[0]).map(entry => entry[1]).join('');
+        // The conversation was deleted while the turn streamed: settle without
+        // persisting (the log file is gone and must not be recreated).
+        if (this.disposed) {
+            this.emitStatus({ running: false, turn: seq, reason: 'aborted' });
+            return;
+        }
+        const blocks = text.length > 0
+            ? [{ type: 'text', text }]
+            : [];
+        // An empty abort persists nothing (nothing was frozen to settle).
+        if (this.disposed || (finishReason === 'aborted' && text.length === 0)) {
+            this.emitStatus({ running: false, turn: seq, reason: 'aborted' });
+            return;
+        }
+        const message = {
+            seq,
+            role: 'assistant',
+            blocks,
+            model: record.model,
+            provider: record.provider,
+            ...failure === undefined ? {} : { error: failure },
+            createdAt: Date.now(),
+        };
+        await this.deps.store.appendMessage(this.conversationId, message);
+        this.deps.sink.emitMessage(this.conversationId, message);
+        if (assembled.windowTrimmed && (finishReason === 'completed' || finishReason === 'max-tokens')) {
+            finishReason = 'context-trimmed';
+        }
+        this.emitStatus({ running: false, turn: seq, reason: finishReason });
+    }
+    emitMessage(message) {
+        if (this.disposed)
+            return;
+        this.deps.sink.emitMessage(this.conversationId, message);
+    }
+    emitStatus(status) {
+        if (this.disposed)
+            return;
+        this.deps.sink.emitStatus(this.conversationId, status);
+    }
+    async resolveWindow(record) {
+        try {
+            const info = await this.deps.llm.resolveModelInfo(record.provider, record.model);
+            return info.context?.contextWindow ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/lib/store.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Durable storage for the chat domain: `$DSH_HOME/chat/index.json` plus one
+ * JSONL file per conversation (`$DSH_HOME/chat/<conversationId>.jsonl`).
+ * Kept free of official runtime imports so unit tests run in this repo; the
+ * live behavior is covered by the isolated-instance smoke matrix.
+ *
+ * Consistency model: every mutation serializes through one store-wide write
+ * lock (`withWriteLock`) and persists via a unique temp file + rename, so
+ * concurrent conversations cannot lose each other's index updates and a torn
+ * append cannot corrupt a log.
+ * @module @prur/dsh-chat-service/src/store
+ */
+import type { ChatMessage, ChatTextBlock } from './types.ts';
+/** One still-queued user send (content persisted before the turn runs). */
+export interface PendingSend {
+    /** Persisted user message seq this send belongs to — the turn's context boundary. */
+    readonly seq: number;
+    readonly content: readonly ChatTextBlock[];
+    readonly createdAt: number;
+}
+/** Durable per-conversation record, held in `index.json`. */
+export interface ChatIndexRecord {
+    readonly conversationId: string;
+    readonly title: string | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly temperature: number | null;
+    readonly contextMessages: number | null;
+    readonly systemPrompt: string | null;
+    readonly queue: readonly PendingSend[];
+    /** Mirror of the live run state, persisted so restart recovery can resume the queue. */
+    readonly running: boolean;
+}
+/** Storage failure raised by a missing conversation; mapped to an RPC error. */
+export declare class ChatStorageError extends Error {
+    readonly code: 'conversation-not-found' | 'io' | 'corrupt';
+    constructor(code: 'conversation-not-found' | 'io' | 'corrupt', message: string);
+}
+/** Hard cap on persisted messages per conversation (design §4.1). */
+export declare const CHAT_MESSAGE_CAP = 500;
+/** Marker row inserted after trimming: keeps the timeline readable for clients. */
+export declare const CHAT_TRIM_MARKER_TEXT = "\u4E0A\u4E0B\u6587\u5DF2\u88C1\u526A";
+/** Whether a candidate conversation id is safe to use as a filename stem. */
+export declare function isSafeConversationId(conversationId: string): boolean;
+/**
+ * JSONL-backed chat store rooted at `chatHome/chat`. All mutations go through
+ * {@link withWriteLock}; readers stay lock-free (writes are atomic renames).
+ */
+export declare class ChatStore {
+    private readonly chatHome;
+    private writeTail;
+    constructor(chatHome: string);
+    private indexPath;
+    private logPath;
+    /** Serialize every mutation: one store-wide chain, errors contained per op. */
+    private withWriteLock;
+    ensure(): Promise<void>;
+    list(): Promise<ChatIndexRecord[]>;
+    get(conversationId: string): Promise<ChatIndexRecord | undefined>;
+    /** @throws {@link ChatStorageError} when the conversation does not exist. */
+    require(conversationId: string): Promise<ChatIndexRecord>;
+    put(record: ChatIndexRecord): Promise<void>;
+    /** Delete a conversation and its log; idempotent. */
+    remove(conversationId: string): Promise<void>;
+    readMessages(conversationId: string): Promise<ChatMessage[]>;
+    /**
+     * Append one message under the write lock and maintain the per-conversation
+     * cap: when the cap would be exceeded, the oldest messages are dropped and
+     * a system marker row is appended in their place (client renders a notice).
+     * @returns whether trimming occurred.
+     */
+    appendMessage(conversationId: string, message: ChatMessage): Promise<{
+        trimmed: boolean;
+    }>;
+    /**
+     * Page history newest-first paging semantics like `session.history`: the
+     * tail page (no `beforeSeq`) returns the newest `maxMessages` messages in
+     * ascending seq; `beforeSeq` returns the `maxMessages` messages strictly
+     * older than it, still ascending, with `hasMore` telling whether an older
+     * page remains.
+     */
+    paginate(conversationId: string, beforeSeq: number | undefined, maxMessages: number): Promise<{
+        items: ChatMessage[];
+        hasMore: boolean;
+    }>;
+}

package/lib/store.js

@@ -0,0 +1,185 @@
+/**
+ * Durable storage for the chat domain: `$DSH_HOME/chat/index.json` plus one
+ * JSONL file per conversation (`$DSH_HOME/chat/<conversationId>.jsonl`).
+ * Kept free of official runtime imports so unit tests run in this repo; the
+ * live behavior is covered by the isolated-instance smoke matrix.
+ *
+ * Consistency model: every mutation serializes through one store-wide write
+ * lock (`withWriteLock`) and persists via a unique temp file + rename, so
+ * concurrent conversations cannot lose each other's index updates and a torn
+ * append cannot corrupt a log.
+ * @module @prur/dsh-chat-service/src/store
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Storage failure raised by a missing conversation; mapped to an RPC error. */
+export class ChatStorageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ChatStorageError';
+    }
+}
+/** Hard cap on persisted messages per conversation (design §4.1). */
+export const CHAT_MESSAGE_CAP = 500;
+/** Marker row inserted after trimming: keeps the timeline readable for clients. */
+export const CHAT_TRIM_MARKER_TEXT = '上下文已裁剪';
+/** conversationId charset guard: ids are opaque tokens, never path syntax. */
+const CONVERSATION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** Whether a candidate conversation id is safe to use as a filename stem. */
+export function isSafeConversationId(conversationId) {
+    return CONVERSATION_ID_PATTERN.test(conversationId);
+}
+async function readJson(path, fallback) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return fallback;
+        throw new ChatStorageError('corrupt', `chat store: cannot read ${path}: ${error.message}`);
+    }
+}
+async function writeFileAtomic(target, body) {
+    // Unique per write: concurrent mutations never share a temp path.
+    const tmp = `${target}.${randomUUID()}.tmp`;
+    await writeFile(tmp, body, 'utf8');
+    await rename(tmp, target);
+}
+/**
+ * JSONL-backed chat store rooted at `chatHome/chat`. All mutations go through
+ * {@link withWriteLock}; readers stay lock-free (writes are atomic renames).
+ */
+export class ChatStore {
+    chatHome;
+    writeTail = Promise.resolve();
+    constructor(chatHome) {
+        this.chatHome = chatHome;
+    }
+    indexPath() {
+        return join(this.chatHome, 'index.json');
+    }
+    logPath(conversationId) {
+        return join(this.chatHome, `${conversationId}.jsonl`);
+    }
+    /** Serialize every mutation: one store-wide chain, errors contained per op. */
+    withWriteLock(operation) {
+        const next = this.writeTail.then(operation, operation);
+        this.writeTail = next.catch(() => { });
+        return next;
+    }
+    async ensure() {
+        await mkdir(this.chatHome, { recursive: true });
+    }
+    async list() {
+        const records = await readJson(this.indexPath(), []);
+        return [...records].sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    async get(conversationId) {
+        const records = await readJson(this.indexPath(), []);
+        return records.find(record => record.conversationId === conversationId);
+    }
+    /** @throws {@link ChatStorageError} when the conversation does not exist. */
+    async require(conversationId) {
+        const record = await this.get(conversationId);
+        if (record === undefined) {
+            throw new ChatStorageError('conversation-not-found', `chat: conversation "${conversationId}" does not exist`);
+        }
+        return record;
+    }
+    async put(record) {
+        return this.withWriteLock(async () => {
+            await this.ensure();
+            const records = await readJson(this.indexPath(), []);
+            const next = records.filter(candidate => candidate.conversationId !== record.conversationId);
+            next.push(record);
+            await writeFileAtomic(this.indexPath(), JSON.stringify(next, null, 2));
+        });
+    }
+    /** Delete a conversation and its log; idempotent. */
+    async remove(conversationId) {
+        return this.withWriteLock(async () => {
+            const records = await readJson(this.indexPath(), []);
+            await writeFileAtomic(this.indexPath(), JSON.stringify(records.filter(candidate => candidate.conversationId !== conversationId), null, 2));
+            await unlink(this.logPath(conversationId)).catch((error) => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            });
+        });
+    }
+    async readMessages(conversationId) {
+        try {
+            const lines = (await readFile(this.logPath(conversationId), 'utf8')).split('\n');
+            const messages = [];
+            for (const line of lines) {
+                if (line.length === 0)
+                    continue;
+                try {
+                    messages.push(JSON.parse(line));
+                }
+                catch {
+                    // A torn tail line (crash mid-append) is dropped, not fatal.
+                }
+            }
+            return messages;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw new ChatStorageError('io', `chat: cannot read log: ${error.message}`);
+        }
+    }
+    /**
+     * Append one message under the write lock and maintain the per-conversation
+     * cap: when the cap would be exceeded, the oldest messages are dropped and
+     * a system marker row is appended in their place (client renders a notice).
+     * @returns whether trimming occurred.
+     */
+    async appendMessage(conversationId, message) {
+        return this.withWriteLock(async () => {
+            await this.ensure();
+            const messages = await this.readMessages(conversationId);
+            messages.push(message);
+            const excess = messages.length - CHAT_MESSAGE_CAP;
+            let trimmed = false;
+            let next = messages;
+            if (excess > 0) {
+                trimmed = true;
+                // One marker at a time: drop every existing system row, then trim the
+                // oldest real rows to the cap minus the marker slot, then append the
+                // fresh marker (a notice at the trim boundary, not a per-append flood).
+                const real = messages.filter(message => message.role !== 'system');
+                const kept = real.slice(real.length - (CHAT_MESSAGE_CAP - 1));
+                const marker = {
+                    seq: message.seq + excess,
+                    role: 'system',
+                    blocks: [{ type: 'text', text: CHAT_TRIM_MARKER_TEXT }],
+                    createdAt: Date.now(),
+                };
+                next = [...kept, marker];
+            }
+            await writeFileAtomic(this.logPath(conversationId), `${next.map(item => JSON.stringify(item)).join('\n')}\n`);
+            return { trimmed };
+        });
+    }
+    /**
+     * Page history newest-first paging semantics like `session.history`: the
+     * tail page (no `beforeSeq`) returns the newest `maxMessages` messages in
+     * ascending seq; `beforeSeq` returns the `maxMessages` messages strictly
+     * older than it, still ascending, with `hasMore` telling whether an older
+     * page remains.
+     */
+    async paginate(conversationId, beforeSeq, maxMessages) {
+        const messages = await this.readMessages(conversationId);
+        const eligible = beforeSeq === undefined
+            ? messages
+            : messages.filter(message => message.seq < beforeSeq);
+        const tail = eligible.slice(-maxMessages);
+        return {
+            items: tail,
+            hasMore: eligible.length > tail.length,
+        };
+    }
+}

package/lib/typert.host.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hand-written TYPERT host manifest for the chat Remote namespace. The
+ * official typert generator emits this artifact from the service face during
+ * the harness repository build; this package hand-writes the same contract
+ * (wire schemas + invocation descriptors) because the bridge repo builds
+ * packages with plain tsc. The typert-loader validates every field at mount
+ * time; the isolated-instance matrix asserts acceptance on boot.
+ * @module @prur/dsh-chat-service/typert
+ */
+import { z } from 'zod';
+/** One parameter wire descriptor (strict codec). */
+interface InvocationParam {
+    readonly name: string;
+    readonly wire: string;
+    readonly source: 'json';
+    readonly acceptsUndefined?: true;
+    readonly codec: {
+        readonly mode: 'strict';
+        readonly typeSymbol: string;
+        readonly schema: z.ZodType;
+    };
+}
+/** One invocation descriptor as validated by the typert-loader at mount. */
+interface InvocationEntry {
+    readonly id: string;
+    readonly service: string;
+    readonly namespace: string;
+    readonly method: string;
+    readonly invocation: {
+        readonly kind: 'direct';
+    };
+    readonly parameters: readonly InvocationParam[];
+    readonly result: {
+        readonly mode: 'strict';
+        readonly typeSymbol: string;
+        readonly schema: z.ZodType;
+    };
+}
+export declare const TYPERT: {
+    package: string;
+    face: string;
+    schemas: never[];
+    invocations: InvocationEntry[];
+    model: {
+        services: never[];
+        events: never[];
+        objects: never[];
+    };
+};
+export default TYPERT;