dsh-bots 0.0.1 → 0.2.11

package/lib/sse.js

@@ -0,0 +1,249 @@
+/**
+ * SSE plumbing for the host half — pure ring + parser (unit-tested) and a
+ * native `fetch` listener that keeps the ring fed from the sdk-bots gateway
+ * `/events` endpoint. The web client has no network, so this is the only live
+ * event path; it replays through `bots.eventsSince(seq)`.
+ *
+ * The wire uses `Accept-Encoding: identity` to sidestep gzip/deflate handling
+ * in the host fetch layer (the gateway also supports `?token=` for the old
+ * browser path, but we always send the `authorization` header).
+ * @module dsh-bots/sse
+ */
+/** Incremental SSE wire parser: feed string chunks, receive frames. */
+export class SseParser {
+    onEvent;
+    buffer = '';
+    event = '';
+    dataLines = [];
+    constructor(onEvent) {
+        this.onEvent = onEvent;
+    }
+    push(chunk) {
+        this.buffer += chunk;
+        let idx;
+        while ((idx = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, idx);
+            this.buffer = this.buffer.slice(idx + 1);
+            this.feedLine(line);
+        }
+    }
+    feedLine(line) {
+        if (line.endsWith('\r'))
+            line = line.slice(0, -1);
+        if (line === '') {
+            const data = this.dataLines.join('\n');
+            const event = this.event !== '' ? this.event : 'message';
+            if (data !== '' || (event !== 'message' && this.dataLines.length > 0)) {
+                this.onEvent(event, data);
+            }
+            this.event = '';
+            this.dataLines = [];
+            return;
+        }
+        // Comment / heartbeat line (`: ping`); ignore.
+        if (line.startsWith(':'))
+            return;
+        const colon = line.indexOf(':');
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'event')
+            this.event = value;
+        else if (field === 'data')
+            this.dataLines.push(value);
+        // `id` / `retry` are intentionally ignored: seq is assigned locally.
+    }
+}
+/** Bounded, monotonic ring of normalized events with O(log n) `eventsSince`. */
+export class SseRingBuffer {
+    onPush;
+    capacity;
+    entries = [];
+    nextSeq = 0;
+    constructor(capacity = 3000, 
+    /** Optional side-channel observer (unread tracking); must never throw. */
+    onPush) {
+        this.onPush = onPush;
+        this.capacity = Math.max(1, Math.floor(capacity));
+    }
+    /** Append one event; returns its assigned seq. */
+    push(channel, data) {
+        const seq = this.nextSeq;
+        this.nextSeq += 1;
+        if (this.entries.length >= this.capacity)
+            this.entries.shift();
+        this.entries.push({ seq, channel, data });
+        if (this.onPush !== undefined) {
+            try {
+                this.onPush(channel, data);
+            }
+            catch { /* observer must not break the ring */ }
+        }
+        return seq;
+    }
+    /** Replay events strictly after `seq`, or everything when the seq fell off. */
+    eventsSince(seq) {
+        if (this.entries.length === 0)
+            return [];
+        const oldest = this.entries[0].seq;
+        if (seq < oldest - 1 || Number.isNaN(seq))
+            return this.entries.slice();
+        let lo = 0;
+        let hi = this.entries.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (this.entries[mid].seq <= seq)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return this.entries.slice(lo);
+    }
+    get size() { return this.entries.length; }
+    get total() { return this.nextSeq; }
+}
+function toState(ring, live) {
+    return {
+        running: live.running,
+        ok: live.ok,
+        lastError: live.lastError,
+        connectedAt: live.connectedAt,
+        droppedAt: live.droppedAt,
+        buffered: ring.size,
+        total: ring.total,
+    };
+}
+/**
+ * Long-lived `/events` listener. Re-resolves discovery on every connect so a
+ * restarted sdk-bots host is picked up automatically; reconnects are silent
+ * and bounded. Deliberately never throws — errors surface via `state()`.
+ */
+export class GatewaySseClient {
+    ring;
+    resolveBase;
+    reconnectBaseMs;
+    channels;
+    onConnected;
+    ac = null;
+    timer = null;
+    stopped = true;
+    ok = false;
+    lastError = null;
+    connectedAt = null;
+    droppedAt = null;
+    attempt = 0;
+    constructor(opts) {
+        this.ring = opts.ring ?? new SseRingBuffer();
+        this.resolveBase = opts.resolveBase;
+        this.reconnectBaseMs = opts.reconnectBaseMs ?? 2000;
+        this.channels = opts.channels;
+        this.onConnected = opts.onConnected;
+    }
+    get buffer() { return this.ring; }
+    start() {
+        if (!this.stopped)
+            return;
+        this.stopped = false;
+        this.attempt = 0;
+        void this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.ac?.abort();
+        this.ac = null;
+        this.ok = false;
+        this.droppedAt = this.connectedAt !== null ? new Date().toISOString() : null;
+    }
+    state() {
+        return toState(this.ring, {
+            running: !this.stopped,
+            ok: this.ok,
+            lastError: this.lastError,
+            connectedAt: this.connectedAt,
+            droppedAt: this.droppedAt,
+        });
+    }
+    eventsSince(seq) {
+        return { events: this.ring.eventsSince(seq), nextSeq: this.ring.total, state: this.state() };
+    }
+    async connect() {
+        if (this.stopped)
+            return;
+        const base = this.resolveBase();
+        if (base === null) {
+            this.lastError = 'no-gateway-json';
+            this.schedule();
+            return;
+        }
+        this.ac = new AbortController();
+        let endpoint = `${base.url}/events`;
+        if (this.channels !== undefined && this.channels.length > 0) {
+            endpoint += `?channels=${encodeURIComponent(this.channels.join(','))}`;
+        }
+        const headers = { accept: 'text/event-stream', 'accept-encoding': 'identity' };
+        if (base.token !== null)
+            headers['authorization'] = `Bearer ${base.token}`;
+        const parser = new SseParser((event, data) => {
+            let parsed = data;
+            try {
+                parsed = JSON.parse(data);
+            }
+            catch { /* keep raw string */ }
+            this.ring.push(event, parsed);
+        });
+        try {
+            const res = await fetch(endpoint, { headers, signal: this.ac.signal });
+            if (this.stopped)
+                return;
+            if (!res.ok || res.body === null) {
+                // Non-2xx or no body → not an SSE stream; treat as a hard connection error.
+                this.ok = false;
+                this.lastError = `health-http-${res.status}`;
+                this.droppedAt = new Date().toISOString();
+                this.schedule();
+                return;
+            }
+            this.ok = true;
+            this.lastError = null;
+            this.connectedAt = new Date().toISOString();
+            this.droppedAt = null;
+            this.attempt = 0;
+            if (this.onConnected !== undefined) {
+                try {
+                    this.onConnected();
+                }
+                catch { /* observer must not break the loop */ }
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                parser.push(decoder.decode(value, { stream: true }));
+            }
+            this.ok = false;
+            this.droppedAt = new Date().toISOString();
+        }
+        catch (err) {
+            if (this.stopped)
+                return;
+            this.ok = false;
+            this.lastError = String(err?.message ?? err);
+            this.droppedAt = new Date().toISOString();
+        }
+        this.schedule();
+    }
+    schedule() {
+        if (this.stopped)
+            return;
+        this.attempt += 1;
+        const delay = Math.min(this.reconnectBaseMs * this.attempt, 15000);
+        this.timer = setTimeout(() => { this.timer = null; void this.connect(); }, delay);
+    }
+}

package/lib/types/client.d.ts

@@ -0,0 +1,35 @@
+/**
+ * dsh-bots — client half (web), formal-plugin runtime.
+ *
+ * Rendered by the dsh web shell through the standard slot system with full
+ * browser DOM access. Two rules keep the surface native rather than
+ * native-looking:
+ *
+ *  1. Components come from `@deepseek-ai/dsh-client-ui-primitives`, which the
+ *     shell publishes in its static module map alongside `react`. Buttons,
+ *     inputs, icons, state dots and the markdown renderer are therefore the
+ *     shipped ones, not reimplementations. Every lookup degrades to a local
+ *     fallback so a primitives reshuffle can never blank the plugin.
+ *  2. Our own CSS uses stable `dbs-` class names carrying the *values* read
+ *     out of the shipped stylesheets (row heights, radii, the composer var
+ *     family), expressed through dsh theme variables. No hashed class name is
+ *     borrowed, so a dsh rebuild cannot break the visuals.
+ *
+ * Sidebar integration: the left-nav workspace region (`sidebar.workspaces` is
+ * a single slot) is shadowed at a low priority — an officially supported move,
+ * the shell's own error text reads "register at a different priority to shadow
+ * it (lowest renders)" — and re-rendered as a two-group collapsible nav:
+ *   - 「工作区」 — delegates the ORIGINAL shipped workspace browser, with its
+ *                 child slots and its rail branch intact (see DelegatedBrowser).
+ *   - 「Bots」   — our bot/group tree; clicking opens the chat.
+ *
+ * Chat lives in the `shell.overlay` layer but is inset to the frame's centre
+ * column, so the sidebar stays visible and usable while a bot conversation is
+ * open — matching how a native session behaves.
+ *
+ * Live data: the host keeps an SSE ring fed from the sdk-bots `/events`
+ * channel. ONE bus drains it here and fans channels out to subscribers; no
+ * component owns the cursor and no component polls the gateway directly.
+ * @module dsh-bots/client
+ */
+export {};

package/lib/types/gateway.d.ts

@@ -0,0 +1,32 @@
+/**
+ * sdk-bots gateway client for the host half.
+ *
+ * The formal plugin runs inside the real host process, so this uses native
+ * `fetch` and `node:fs` — the curl-over-shell bridge from the dynamic-plugin
+ * prototype is gone. Discovery follows `gateway.json` in the sdk-bots data
+ * directory; `SAND_GATEWAY_TOKEN` (or the file's optional `token` field) pins
+ * auth when present.
+ * @module dsh-plugin-bots/gateway
+ */
+import type { AgentInfo, GatewayInfo, TranscriptEntry } from './shared.js';
+export interface Discovery {
+    port: number;
+    pid: number | null;
+    token: string | null;
+    host: string;
+}
+export declare function expandHome(p: string): string;
+/** Read loopback discovery from `<dataDir>/gateway.json`; null when absent/stale. */
+export declare function readDiscovery(dataDir: string): Discovery | null;
+/** Discovery + `/health` probe with pid match validation. */
+export declare function discover(dataDir: string): Promise<GatewayInfo>;
+/** POST one `/api/<method>` command; unwraps `{result}` and throws on errors. */
+export declare function callGateway<T>(dataDir: string, method: string, args?: Record<string, unknown>): Promise<T>;
+/** Project a raw gateway agent onto the wire type. */
+export declare function trimAgent(a: any): AgentInfo | null;
+/** Normalize one transcript entry for the UI's closed render switch. */
+export declare function trimEntry(en: any): TranscriptEntry;
+/** `listAgents` returns a bare array (also tolerates `{agents:[...]}`). */
+export declare function normalizeAgents(raw: any): AgentInfo[];
+/** Client nonce for idempotent create/send calls. */
+export declare function nextNonce(): string;

package/lib/types/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * dsh-bots — host half.
+ *
+ * Bridges the sdk-bots orchestration gateway (single bots, group chats,
+ * transcripts, live SSE) into dsh as a formal plugin. Publishes the `bots`
+ * Remote namespace through the Typert gateway: every method takes a single
+ * `request` JSON value and returns plain JSON (source-mode descriptors,
+ * matching how the web client calls `bots/<method>` over the connection
+ * RPC carrier).
+ *
+ * Typert identity: dsh's host identifies a `TypertRemoteService` by the module
+ * instance it was loaded from — not by name. When this plugin is installed by
+ * pnpm it can resolve a *separate* copy of `@deepseek-ai/dsh-typert-protocol`
+ * from its own node_modules, producing a class that is unequal to the host's
+ * and silently dropping every method. We therefore anchor at load time to the
+ * running dsh CLI / global layout (the same technique used by dsh-freeroute)
+ * and only fall back to plain resolution when anchoring fails. The `Remote`
+ * markers are applied with a decorator-context shim for the same reason.
+ * @module dsh-bots
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentInfo, Config, EventsSinceResult, GatewayInfo, McpServerInfo, McpToolInfo, SessionInfo, SseState, TranscriptEntry, WorkspaceInfo } from './shared.js';
+export declare const name = "dsh-bots";
+/** No hard Cordis service requirements: host reads optional services via
+ * guarded `ctx.get` so a partially-provisioned kernel never blocks activation. */
+export declare const inject: string[];
+/** Cordis range this plugin is tested against; only surfaces a warning. */
+export declare const TESTED_CORDIS_RANGE = "^4.0.1";
+/**
+ * Peer-compatibility probe — non-fatal. An unresolvable version or a caret
+ * skew inside the tested range must not brick the whole plugin tree (the
+ * guard existed to surface silent mismatches loudly).
+ */
+export declare function assertPeerCompatible(): void;
+declare const TypertRemoteService: any;
+/**
+ * The `bots` Remote namespace. One method per gateway capability, plus
+ * host-backed lists (workspaces/sessions) and live SSE replay so the web
+ * workbench renders natively without polling the transcript API.
+ */
+/** Exported for diagnostics/tests: marker assertions need the prototype. */
+export declare class BotsRemote extends TypertRemoteService {
+    private readonly cfg;
+    private readonly sse;
+    private readonly unread;
+    private rebasing;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Ring observer: feed the unread model from live transcript traffic.
+     * `appended` is the single-arrival shape; the gateway also replays a
+     * `snapshot` payload on (re)connect — both are timestamp-guarded, so
+     * replays never double-count.
+     */
+    private observeTranscript;
+    /**
+     * Reconstruct counts from transcript tails (SSE has no replay, so events
+     * that fire while the stream is down would otherwise be lost forever).
+     * Runs once per (re)connect; never throws; skips while one is in flight.
+     */
+    private rebaseUnread;
+    gatewayInfo(request: {
+        dataDir?: string;
+    } | null): Promise<GatewayInfo>;
+    /**
+     * Descriptor contract: every remote method declares exactly one plain
+     * `request` formal parameter (no defaults/destructuring/rest) — the
+     * source-mode descriptor derives its wire field from the parameter name,
+     * and the client always sends `{ args: { request } }`. A zero-param method
+     * would make the gateway reject the envelope with "unexpected request".
+     */
+    list(request: unknown): Promise<AgentInfo[]>;
+    workspaces(request: unknown): Promise<{
+        workspaces: WorkspaceInfo[];
+    }>;
+    sessions(request: unknown): Promise<{
+        sessions: SessionInfo[];
+    }>;
+    create(request: {
+        name?: string;
+        description?: string;
+    } | null): Promise<AgentInfo | null>;
+    createGroup(request: {
+        name?: string;
+        memberIds?: string[];
+    } | null): Promise<AgentInfo | null>;
+    /**
+     * Replace a group's member list (add + remove in one call — the gateway
+     * command is a full-set put, not a delta). Wire field is `memberAgentIds`,
+     * same as `createGroup` (§7.2).
+     */
+    setGroupMembers(request: {
+        id?: string;
+        memberIds?: string[];
+    } | null): Promise<AgentInfo | null>;
+    update(request: {
+        id?: string;
+        profile?: Record<string, unknown>;
+    } | null): Promise<AgentInfo | null>;
+    remove(request: {
+        id?: string;
+    } | null): Promise<unknown>;
+    send(request: {
+        agentId?: string;
+        prompt?: string;
+    } | null): Promise<unknown>;
+    /**
+     * Interrupt an agent's active run (the composer's stop button). Returns the
+     * gateway's honest `{hadActiveRun}` so the UI can tell "stopped it" from
+     * "there was nothing to stop" — never a fake success.
+     */
+    interrupt(request: {
+        id?: string;
+    } | null): Promise<{
+        hadActiveRun: boolean;
+    }>;
+    transcriptTail(request: {
+        id?: string;
+        limit?: number;
+    } | null): Promise<{
+        entries: TranscriptEntry[];
+    }>;
+    /**
+     * Clear an agent's unread badge. The plugin owns the unread model (see
+     * `unread.ts`): the marker "上次读到哪" advances to now and the count
+     * zeroes. The gateway call is kept best-effort so desktop-app surfaces
+     * (spend guard's lastViewedAt) stay consistent with what the user saw.
+     */
+    markRead(request: {
+        id?: string;
+        atMs?: number;
+    } | null): Promise<unknown>;
+    /** Trim a gateway MCP server row to the settings-page projection. */
+    private trimMcpServer;
+    /** Trim a routed MCP tool row (schema passed through verbatim). */
+    private trimMcpTool;
+    /** Installed MCP servers (engine `management.listInstalled`). */
+    mcpServers(request: unknown): Promise<{
+        servers: McpServerInfo[];
+    }>;
+    /** All routed MCP tools across servers (engine `mcp.listTools`). */
+    mcpTools(request: unknown): Promise<{
+        tools: McpToolInfo[];
+    }>;
+    /**
+     * Register one MCP server. `configJson` must decode to a JSON object —
+     * either a stdio config (`{"command": "…", "args": […]}`) or a remote URL
+     * config; the gateway JSON.parses and re-validates it.
+     */
+    mcpAdd(request: {
+        name?: string;
+        configJson?: string;
+    } | null): Promise<{
+        servers: McpServerInfo[];
+    }>;
+    mcpRemove(request: {
+        serverId?: string;
+    } | null): Promise<unknown>;
+    /** Restart / reconnect all MCP servers (engine `management.restart`). */
+    mcpRefresh(request: unknown): Promise<unknown>;
+    /**
+     * Execute one routed MCP tool outside a bot turn (tool try-run panel).
+     * Passthrough of the gateway wire shape — note the engine swaps `name`/
+     * `toolName` on the way into the executor (DEVELOPMENT.md §13.5), so the
+     * caller maps `{name: row.toolName, toolName: row.name}` until实测 confirmed.
+     */
+    mcpExecute(request: {
+        agentId?: string;
+        name?: string;
+        toolName?: string;
+        providerIdentifier?: string;
+        args?: unknown;
+        toolCallId?: string;
+    } | null): Promise<unknown>;
+    workspaceList(request: unknown): Promise<{
+        workspaces: import("./workspace.js").AgentWorkspaceConfig[];
+    }>;
+    workspaceGet(request: {
+        agentId?: string;
+    } | null): Promise<import("./workspace.js").AgentWorkspaceConfig>;
+    workspaceSet(request: {
+        agentId?: string;
+        workspaceRoot?: string | null;
+        allowPaths?: string[];
+    } | null): Promise<import("./workspace.js").AgentWorkspaceConfig>;
+    /**
+     * Append one diagnostic record to `<dataDir>/dsh-bots-diag.jsonl`.
+     *
+     * The shadow takeover of `sidebar.workspaces` is the one part of this plugin
+     * whose failure mode is invisible — a missing shipped entry or a throwing
+     * prop synthesis just renders a small notice. Recording those transitions is
+     * the only way to tell, after the fact, whether delegation actually worked
+     * on a user's machine. Best-effort by construction: diagnostics must never
+     * be able to fail a render.
+     */
+    diag(request: {
+        stage?: string;
+        detail?: unknown;
+    } | null): Promise<{
+        written: boolean;
+    }>;
+    eventsSince(request: {
+        seq?: number;
+    } | null): EventsSinceResult;
+    sseState(request: unknown): SseState;
+    /** Stop the live event loop on plugin teardown. */
+    stopSse(): void;
+}
+/** Plugin entry: guard peers, publish the `bots` Remote namespace. */
+export declare function apply(ctx: Context, config: Config): void;
+export {};