@prur/dsh-chat-service 0.1.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/engine.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure conversation logic for the chat domain: title derivation, context
+ * assembly, and window trimming. No official runtime imports — unit tests run
+ * in this repo directly against these functions.
+ * @module @prur/dsh-chat-service/src/engine
+ */
+import type { ChatMessage } from './types.ts';
+/** Truncated title derived from the first user message. */
+export declare const TITLE_MAX_CHARS = 30;
+/** Rough token estimate (4 chars per token) for context-window trimming. */
+export declare const CHARS_PER_TOKEN = 4;
+/** Context-window utilization kept under this fraction before trimming. */
+export declare const CONTEXT_WINDOW_SAFETY = 0.9;
+/** One model-facing message produced by context assembly. */
+export interface AssembledMessage {
+    readonly role: 'user' | 'assistant';
+    readonly content: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+}
+/** Derived one-line title from a prompt's text; null for empty prompts. */
+export declare function deriveTitle(text: string): string | null;
+/** The assembled model-facing message list for one turn. */
+export interface ContextAssemblyResult {
+    readonly messages: readonly AssembledMessage[];
+    readonly contextMessages: number | null;
+    /** True when the context-window estimate trimmed older messages. */
+    readonly windowTrimmed: boolean;
+}
+/**
+ * Assemble the model-facing message list for one turn. System marker rows and
+ * failed assistant messages are excluded; `contextMessages` (when set) keeps
+ * only the newest that many messages; a `contextWindow` estimate drops older
+ * messages when the rough token count would overflow the model window.
+ */
+export declare function assembleContext(history: readonly ChatMessage[], contextMessages: number | null, contextWindow: number | null): ContextAssemblyResult;
+/** Rough token estimate for one message's text blocks. */
+export declare function estimateTokens(message: ChatMessage): number;

package/lib/engine.js

@@ -0,0 +1,71 @@
+/**
+ * Pure conversation logic for the chat domain: title derivation, context
+ * assembly, and window trimming. No official runtime imports — unit tests run
+ * in this repo directly against these functions.
+ * @module @prur/dsh-chat-service/src/engine
+ */
+/** Truncated title derived from the first user message. */
+export const TITLE_MAX_CHARS = 30;
+/** Rough token estimate (4 chars per token) for context-window trimming. */
+export const CHARS_PER_TOKEN = 4;
+/** Context-window utilization kept under this fraction before trimming. */
+export const CONTEXT_WINDOW_SAFETY = 0.9;
+/** Derived one-line title from a prompt's text; null for empty prompts. */
+export function deriveTitle(text) {
+    const firstLine = text.replace(/\s+/g, ' ').trim();
+    if (firstLine.length === 0)
+        return null;
+    return firstLine.length <= TITLE_MAX_CHARS
+        ? firstLine
+        : `${firstLine.slice(0, TITLE_MAX_CHARS - 1)}…`;
+}
+function isUsable(message) {
+    return message.role !== 'system' && message.error === undefined;
+}
+/**
+ * Assemble the model-facing message list for one turn. System marker rows and
+ * failed assistant messages are excluded; `contextMessages` (when set) keeps
+ * only the newest that many messages; a `contextWindow` estimate drops older
+ * messages when the rough token count would overflow the model window.
+ */
+export function assembleContext(history, contextMessages, contextWindow) {
+    const usable = history.filter(isUsable);
+    let selected = usable;
+    let windowTrimmed = false;
+    if (contextMessages !== null && selected.length > contextMessages) {
+        selected = selected.slice(-contextMessages);
+    }
+    if (contextWindow !== null && contextWindow > 0) {
+        const budget = Math.max(1, Math.floor(contextWindow * CONTEXT_WINDOW_SAFETY));
+        // Trim from the oldest while the rough token count overflows; the newest
+        // message is always kept (it is the prompt this turn answers).
+        let tokens = 0;
+        let kept = 0;
+        for (let index = selected.length - 1; index >= 0; index -= 1) {
+            const next = estimateTokens(selected[index]);
+            if (kept > 0 && tokens + next > budget)
+                break;
+            tokens += next;
+            kept += 1;
+        }
+        if (kept < selected.length) {
+            windowTrimmed = true;
+            selected = selected.slice(selected.length - kept);
+        }
+    }
+    return {
+        messages: selected.map((message) => ({
+            role: message.role,
+            content: message.blocks.map(block => ({ type: 'text', text: block.text })),
+        })),
+        contextMessages,
+        windowTrimmed,
+    };
+}
+/** Rough token estimate for one message's text blocks. */
+export function estimateTokens(message) {
+    let chars = 0;
+    for (const block of message.blocks)
+        chars += block.text.length;
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+}

package/lib/events.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Plugin-owned chat event downlink: an in-process bus plus a WebSocket
+ * gateway at `/chat/events`, so clients stream chat frames through the
+ * plugin itself instead of the host's remote-event allowlist (which only
+ * forwards host-declared events). Frames use the SAME `server-request`
+ * envelope as `/api/events.host` (`{type: 'server-request', rpcId, method:
+ * 'host/remote-event', payload: {event, args}}`), so a client decodes them
+ * with its existing downlink frame parser unchanged.
+ * @module @prur/dsh-chat-service/src/events
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The three chat events a client may receive on the downlink. */
+export type ChatDownlinkEvent = 'chat/message' | 'chat/chunk' | 'chat/status';
+/**
+ * Downlink frame: the full `server-request` envelope the DSH downlink
+ * transport uses (exact same shape as `/api/events.host` remote-event
+ * frames), so clients reuse their existing `ServerRequest` parse path.
+ */
+export interface ChatDownlinkFrame {
+    readonly type: 'server-request';
+    readonly rpcId: string;
+    readonly method: 'host/remote-event';
+    readonly payload: {
+        readonly event: ChatDownlinkEvent;
+        readonly args: readonly unknown[];
+    };
+}
+/** Dedicated downstream WebSocket pathname (outside the /api prefix gate). */
+export declare const CHAT_EVENTS_PATH = "/chat/events";
+/**
+ * In-process event bus. The service publishes; the gateway subscribes and
+ * broadcasts to every connected client. Synchronous, listener failures are
+ * contained (one broken observer must not break a turn).
+ */
+export declare class ChatEventBus {
+    private readonly listeners;
+    publish(event: ChatDownlinkEvent, args: readonly unknown[]): void;
+    subscribe(listener: (frame: ChatDownlinkFrame) => void): () => void;
+}
+/**
+ * WebSocket gateway for {@link CHAT_EVENTS_PATH}. The handshake passes the
+ * connection-mobile trust gate (bearer token / loopback fence) — the exact
+ * check the /api gate applies — so the chat channel inherits the deployment's
+ * authentication policy without duplicating it.
+ */
+export declare class ChatEventsGateway {
+    private readonly ctx;
+    private readonly trustedHosts;
+    private readonly apiToken;
+    private readonly server;
+    private readonly clients;
+    private heartbeat;
+    constructor(ctx: Context, trustedHosts: readonly string[], apiToken: string | undefined);
+    /** Broadcast one frame to every connected client. */
+    broadcast(frame: ChatDownlinkFrame): void;
+    private handleUpgrade;
+}

package/lib/events.js

@@ -0,0 +1,114 @@
+/**
+ * Plugin-owned chat event downlink: an in-process bus plus a WebSocket
+ * gateway at `/chat/events`, so clients stream chat frames through the
+ * plugin itself instead of the host's remote-event allowlist (which only
+ * forwards host-declared events). Frames use the SAME `server-request`
+ * envelope as `/api/events.host` (`{type: 'server-request', rpcId, method:
+ * 'host/remote-event', payload: {event, args}}`), so a client decodes them
+ * with its existing downlink frame parser unchanged.
+ * @module @prur/dsh-chat-service/src/events
+ */
+import { randomUUID } from 'node:crypto';
+import { isTrustedOrAuthorizedApiRequest, rejectWebSocketUpgrade, } from '@prur/dsh-client-connection-mobile';
+import WebSocket, { WebSocketServer } from 'ws';
+/** Dedicated downstream WebSocket pathname (outside the /api prefix gate). */
+export const CHAT_EVENTS_PATH = '/chat/events';
+/** Heartbeat interval; keeps proxies from dropping an idle downlink. */
+const HEARTBEAT_INTERVAL_MS = 15_000;
+/**
+ * In-process event bus. The service publishes; the gateway subscribes and
+ * broadcasts to every connected client. Synchronous, listener failures are
+ * contained (one broken observer must not break a turn).
+ */
+export class ChatEventBus {
+    listeners = new Set();
+    publish(event, args) {
+        const frame = {
+            type: 'server-request',
+            rpcId: randomUUID(),
+            method: 'host/remote-event',
+            payload: { event, args },
+        };
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(frame);
+            }
+            catch {
+                // A failed observer is contained; the turn continues.
+            }
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}
+/**
+ * WebSocket gateway for {@link CHAT_EVENTS_PATH}. The handshake passes the
+ * connection-mobile trust gate (bearer token / loopback fence) — the exact
+ * check the /api gate applies — so the chat channel inherits the deployment's
+ * authentication policy without duplicating it.
+ */
+export class ChatEventsGateway {
+    ctx;
+    trustedHosts;
+    apiToken;
+    server = new WebSocketServer({ noServer: true });
+    clients = new Set();
+    heartbeat = null;
+    constructor(ctx, trustedHosts, apiToken) {
+        this.ctx = ctx;
+        this.trustedHosts = trustedHosts;
+        this.apiToken = apiToken;
+        this.ctx.effect(() => {
+            const dispose = this.ctx.webServer.registerUpgrade({
+                path: CHAT_EVENTS_PATH,
+                handler: (req, socket, head) => this.handleUpgrade(req, socket, head),
+            });
+            return () => {
+                dispose();
+                for (const client of this.clients)
+                    client.terminate();
+                this.clients.clear();
+                this.server.close();
+                if (this.heartbeat !== null) {
+                    clearInterval(this.heartbeat);
+                    this.heartbeat = null;
+                }
+            };
+        }, '@prur/dsh-chat-service: /chat/events WebSocket');
+    }
+    /** Broadcast one frame to every connected client. */
+    broadcast(frame) {
+        const payload = JSON.stringify(frame);
+        for (const client of this.clients) {
+            if (client.readyState === WebSocket.OPEN)
+                client.send(payload);
+        }
+    }
+    handleUpgrade(req, socket, head) {
+        if (!isTrustedOrAuthorizedApiRequest(req, this.trustedHosts, this.apiToken, req.socket.localAddress)) {
+            rejectWebSocketUpgrade(socket);
+            return;
+        }
+        this.server.handleUpgrade(req, socket, head, (websocket) => {
+            this.clients.add(websocket);
+            const close = () => { this.clients.delete(websocket); };
+            websocket.on('close', close);
+            websocket.on('error', close);
+            // Downlink only: a client message is a protocol violation.
+            websocket.on('message', () => websocket.close(1008, 'downlink only'));
+        });
+        if (this.heartbeat === null) {
+            this.heartbeat = setInterval(() => {
+                for (const client of this.clients) {
+                    if (client.readyState === WebSocket.OPEN)
+                        client.ping();
+                }
+            }, HEARTBEAT_INTERVAL_MS);
+            this.heartbeat.unref?.();
+        }
+        // 认证边界：此通道以原生客户端（Bearer 头）为准；浏览器 dsh_token cookie 的
+        // Path=/api 不覆盖 /chat/events —— 移动端 SDK 一律带 Authorization 连入。
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { ChatStorageError } from './store.ts';
+import type { ChatCreateResult, ChatEmptyResult, ChatHistoryResult, ChatListResult, ChatSelectModelResult, ChatSendResult, ChatUpdateResult, ChatTextBlock } from './types.ts';
+/** Stable Cordis plugin name. */
+export declare const name = "chat-service";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        chat: ChatService;
+        /** Optional host default-model config provided by the agent-default-model plugin. */
+        agentDefaultModel?: {
+            currentSelection(): {
+                provider: string;
+                model: string;
+            };
+        };
+    }
+}
+/** Business failure carrying a stable code for diagnostics. */
+export declare class ChatServiceError extends Error {
+    readonly code: 'no-model' | 'invalid-request' | 'unsupported-block';
+    constructor(code: 'no-model' | 'invalid-request' | 'unsupported-block', message: string);
+}
+/** Resolve the harness home the chat store lives under (env overrides default). */
+export declare function chatHomePath(): string;
+/** Composition config: the trust-gate facts mirroring connection-mobile's row. */
+export interface ChatServiceConfig {
+    /** Non-loopback serving authorities, same fence semantics as connection-mobile. */
+    trustedHosts: string[];
+    /** Optional bearer token gating every non-loopback handshake. */
+    apiToken?: string;
+}
+/** Validate the composition config; defaults to an empty fence (loopback only). */
+export declare const Config: z<ChatServiceConfig>;
+/**
+ * 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}.
+ */
+export declare class ChatService extends TypertRemoteService {
+    /** Required services: the LLM runtime and the HTTP carrier for the downlink. */
+    static inject: string[];
+    private readonly store;
+    private readonly runners;
+    private readonly bus;
+    private readonly gateway;
+    constructor(ctx: Context, config: ChatServiceConfig);
+    /** Re-run queued sends and settle half-finished conversations on startup. */
+    private recover;
+    /** List conversations newest-first with a running flag. */
+    list(): Promise<ChatListResult>;
+    /** Create a conversation; absent provider/model defaults to the host's current model. */
+    create(provider?: string, model?: string, title?: string): Promise<ChatCreateResult>;
+    /** Rename a conversation. */
+    rename(conversationId: string, title: string): Promise<ChatEmptyResult>;
+    /** Delete a conversation and its message log; idempotent. */
+    delete(conversationId: string): Promise<ChatEmptyResult>;
+    /** Page a conversation's history newest-first under the `beforeSeq` anchor. */
+    history(conversationId: string, beforeSeq?: number, maxMessages?: number): Promise<ChatHistoryResult>;
+    /**
+     * Send one user turn into a conversation: the user message persists and is
+     * anchored through `chat/message`, then its turn joins the FIFO queue.
+     */
+    send(conversationId: string, content: readonly ChatTextBlock[]): Promise<ChatSendResult>;
+    /** Abort the in-flight turn (frozen partial is persisted); idempotent. */
+    cancel(conversationId: string): Promise<ChatEmptyResult>;
+    /** Switch the conversation's model selection. */
+    selectModel(conversationId: string, provider: string, model: string): Promise<ChatSelectModelResult>;
+    /** Update conversation settings; `null` in the patch unsets a field. */
+    update(conversationId: string, patch: {
+        readonly systemPrompt?: string | null;
+        readonly temperature?: number | null;
+        readonly contextMessages?: number | null;
+    }): Promise<ChatUpdateResult>;
+    private defaultSelection;
+    private runnerFor;
+    private turnRecord;
+    /** Persist turn-start bookkeeping: shift the queued send and mark running. */
+    private turnStart;
+    /** Persist turn-end bookkeeping: release the running flag. */
+    private turnEnd;
+    private emitMessage;
+    private emitStatus;
+}
+export default ChatService;
+export { ChatStorageError };