@dsh-cc/mcp-client 0.5.0

package/lib/stdio-stderr.js

@@ -0,0 +1,187 @@
+/**
+ * Capture stdio MCP server stderr so it cannot inherit the parent TTY.
+ * SDK default is `stderr: 'inherit'`; piping is mandatory for a TUI host.
+ *
+ * @module
+ */
+import { createWriteStream, mkdirSync, openSync, renameSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Ring capacity for the in-memory tail used in connection-failure warns. */
+export const STDERR_TAIL_CAPACITY = 4 * 1024;
+/** Max characters of that tail embedded in a single-line `ctx.logger.warn`. */
+export const STDERR_WARN_CAPACITY = 1024;
+/** Default size cap for the stdio stderr log; ONE backup generation is kept. */
+export const STDIO_LOG_MAX_BYTES = 4 * 1024 * 1024;
+const tails = new WeakMap();
+/**
+ * Append-only ring of the newest `capacity` characters. Used so a noisy
+ * server cannot grow memory without bound while still leaving a crash banner
+ * for the supervisor's warn line.
+ */
+export class BoundedTail {
+    capacity;
+    buffer = '';
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    push(chunk) {
+        this.buffer += chunk;
+        if (this.buffer.length > this.capacity) {
+            this.buffer = this.buffer.slice(this.buffer.length - this.capacity);
+        }
+    }
+    snapshot() {
+        return this.buffer;
+    }
+}
+/**
+ * Default directory for captured stdio stderr.
+ * `$DSH_HOME/mcp-logs`, falling back to `~/.dsh/mcp-logs`.
+ */
+function defaultStdioLogDir() {
+    return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'mcp-logs');
+}
+/**
+ * Last ≤1 KB of a captured tail, newlines collapsed, for a one-line logger.
+ * @returns `undefined` when the tail is empty so callers can omit the suffix.
+ */
+export function formatStdioStderrForWarn(tail) {
+    const collapsed = tail.trim().replace(/\r?\n/g, '⏎');
+    if (collapsed.length === 0)
+        return undefined;
+    return collapsed.length > STDERR_WARN_CAPACITY
+        ? collapsed.slice(collapsed.length - STDERR_WARN_CAPACITY)
+        : collapsed;
+}
+/** Snapshot of the ring attached to `transport`, or `''` when none. */
+export function stdioStderrTail(transport) {
+    return tails.get(transport)?.snapshot() ?? '';
+}
+/**
+ * Pipe `transport.stderr`, drain into a 4 KB ring, and append raw bytes to
+ * `$DSH_HOME/mcp-logs/<serverName>.log` (or `logDir` when given), rotating at
+ * `maxBytes` (default {@link STDIO_LOG_MAX_BYTES}; `maxBytes <= 0` disables)
+ * into a single `<serverName>.log.1` backup generation, both at open time and
+ * mid-stream.
+ *
+ * Must run before `start()`: SDK 1.29 creates the PassThrough in the
+ * constructor when `stderr: 'pipe'`. An undrained pipe back-pressures the
+ * child until it blocks in `write(2)`.
+ *
+ * No-ops when `stderr` is missing so `vi.fn()` SDK mocks stay constructible.
+ *
+ * ponytail: rotation is size-based with one backup generation (the previous
+ * `.log.1` is discarded on each rotation); concurrent dsh-cc sessions sharing
+ * a serverName may interleave (session header marks each generation);
+ * WriteStream buffer grows if the disk stalls — log must never block MCP.
+ * Documented rotation edges: (a) bytes buffered in the old stream at rotation
+ * time flush into `.log.1` after the rename — a crash between rename and
+ * flush loses at most one stream buffer; (b) another session holding the
+ * renamed `.log.1` writes into an anonymous inode whose bytes vanish on
+ * close — worst-case extra disk ≈ maxBytes × live sessions. A failed
+ * rotation rename (e.g. `.log.1` is a directory) sets `rotationDisabled` so
+ * appending cannot become a rename-retry storm per chunk; appending then
+ * grows unbounded, which is exactly the pre-rotation worst case.
+ *
+ * INVARIANT: all rotation fs ops (`statSync`/`renameSync`/`createWriteStream`)
+ * are SYNCHRONOUS and run inside the `data` handler / open path. PassThrough
+ * `data` events cannot interleave, and the `end` handler cannot fire
+ * mid-rotation; async fs here would reintroduce real races.
+ */
+export function attachStdioStderrDrain(transport, serverName, logDir, maxBytes = STDIO_LOG_MAX_BYTES) {
+    const stream = transport.stderr;
+    if (stream === null || stream === undefined)
+        return;
+    const tail = new BoundedTail(STDERR_TAIL_CAPACITY);
+    tails.set(transport, tail);
+    const dir = logDir ?? defaultStdioLogDir();
+    const path = join(dir, `${serverName}.log`);
+    let rotationDisabled = maxBytes <= 0;
+    let file;
+    // Byte tally for the currently open generation, reset to the just-opened
+    // file's size on every open (0 after a rotation, pre-existing size
+    // otherwise). The `--- dsh-cc pid … ---` session header bytes are
+    // deliberately NOT counted: the cap governs captured server output, not
+    // our bookkeeping lines.
+    let tally = 0;
+    const rotationActive = () => !rotationDisabled;
+    const open = () => {
+        file = openLogFile(path, rotationActive() ? maxBytes : 0, (seed) => { tally = seed; });
+    };
+    stream.on('data', (chunk) => {
+        const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+        tail.push(bytes.toString('utf8'));
+        if (file === undefined)
+            open(); // lazy: a silent server leaves no file
+        if (file === undefined)
+            return;
+        file.write(bytes);
+        tally += bytes.length;
+        if (!rotationDisabled && tally >= maxBytes) {
+            let renamed = false;
+            try {
+                // Rename WHILE the old stream is open: POSIX keeps the open fd on the
+                // inode, so buffered bytes flush into `.log.1` — no loss. The chunk
+                // that crossed the boundary stays in the old file; never split it.
+                renameSync(path, `${path}.1`);
+                renamed = true;
+            }
+            catch {
+                // Unrenamable backup path (EISDIR/EPERM/…): stop trying, or every
+                // subsequent chunk retriggers the same doomed rename.
+                rotationDisabled = true;
+            }
+            if (renamed) {
+                file.end();
+                open();
+            }
+        }
+    });
+    // SDK close() does not destroy the PassThrough; the child's stderr `end`
+    // does. Keep the data listener through SIGTERM grace so the last crash
+    // line lands in both the ring and the file.
+    stream.on('end', () => { file?.end(); file = undefined; });
+}
+/**
+ * Open (lazily) the generation log file: rotate an oversized existing file to
+ * `<path>.1` first, seed the caller's byte tally from the file's size, then
+ * append a fresh session header. Never throws.
+ */
+function openLogFile(path, maxBytes, seedTally) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        if (maxBytes > 0 && fileSizeOrZero(path) >= maxBytes) {
+            try {
+                renameSync(path, `${path}.1`);
+            }
+            catch {
+                // Leave the oversized file in place and keep appending; the mid-stream
+                // path disables rotation on the same condition via its own flag.
+            }
+        }
+        seedTally(maxBytes > 0 ? fileSizeOrZero(path) : 0);
+        // openSync binds the fd to the inode NOW: a mid-stream renameSync then
+        // keeps this fd on the renamed `.1`, so bytes queued before the rename
+        // still flush into the old generation. A lazily-opened WriteStream would
+        // resolve its open AFTER the rename and recreate `path` — splitting one
+        // chunk batch across generations.
+        const file = createWriteStream(path, { fd: openSync(path, 'a') });
+        file.on('error', () => { });
+        file.write(`--- dsh-cc pid ${process.pid} ${new Date().toISOString()} ---\n`);
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** File size, or 0 when missing (ENOENT is the common first-run path). */
+function fileSizeOrZero(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=stdio-stderr.js.map

package/lib/stdio-stderr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-stderr.js","sourceRoot":"","sources":["../src/stdio-stderr.ts"],"names":[],"mappings":"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"}

package/lib/tools.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Tool bridge: discovers MCP tools, registers them on the harness ToolRuntime
+ * under deterministic server-qualified public names, and handles re-sync when
+ * the server's tool list changes.
+ *
+ * Naming contract (see the mcp-client Agent Note "Naming invariants"): every MCP tool
+ * has the stable identity `(serverName, rawName)`; the model-facing public name
+ * is `mcp__<serverName>__<rawName>`, normalized to the DeepSeek function-name
+ * constraints. The raw name is only ever sent on the wire (`tools/call`); the
+ * public name is never parsed to recover it.
+ *
+ * @module
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Context } from '@deepseek-ai/cordis';
+import type { JsonValue } from '@dsh-cc/tools';
+export { DEFAULT_DEFER_TOOL_THRESHOLD } from './defer.ts';
+/** Resolved options relevant to tool bridging. */
+export interface ToolBridgeOptions {
+    /** Whether a registry conflict is contained or rejects this synchronization. */
+    registrationFailure: 'contain' | 'throw';
+    serverName: string;
+    toolCallTimeoutMs: number;
+    /**
+     * Listed-tool count above which this server's deferrable tools register
+     * through `ctx.toolSearch` instead of eagerly. Counts the server's
+     * `tools/list` length including alwaysLoad tools; a tool flagged
+     * `_meta['anthropic/alwaysLoad']` is still eager even on a deferred server.
+     * `0` defers whenever `toolSearch` is present. Default
+     * {@link DEFAULT_DEFER_TOOL_THRESHOLD}.
+     */
+    deferToolThreshold?: number;
+    /**
+     * Called before a single mid-session 401 retry. The SDK auto-refreshes an
+     * expired token before a request; a mid-session `UnauthorizedError` means the
+     * token was revoked, so the provider drops the stored state and re-runs the
+     * token flow before the bridge retries the request once.
+     */
+    onUnauthorized?: () => Promise<void> | void;
+}
+/** State for one sync generation: the current set of disposers keyed by public name. */
+export type ToolDisposers = Map<string, () => void>;
+/**
+ * One registered tool generation plus the identity data used to skip no-op
+ * swaps. `fingerprintTools` fingerprints the raw server payload; when a
+ * re-sync produces the same fingerprint on the same client generation, the
+ * live registrations are kept as-is so request prefixes stay stable.
+ */
+export interface ToolGeneration {
+    /** Live registrations owned by this generation, keyed by public name. */
+    disposers: ToolDisposers;
+    /**
+     * Fingerprint of the raw server payload that produced this generation.
+     * `undefined` when nothing is registered (initial state or rolled-back
+     * registration), which forces the next sync to attempt a real swap.
+     */
+    fingerprint: string | undefined;
+    /** The client generation the payload was fetched from; a new client forces a swap. */
+    client: Client | undefined;
+    /** Listed tools registered eagerly (visible in the model-facing schema). */
+    eagerCount: number;
+    /** Listed tools registered deferred (searchable, hidden until activated). */
+    deferredCount: number;
+}
+/** The generation representing "nothing registered yet" (or a rolled-back swap). */
+export declare function emptyToolGeneration(): ToolGeneration;
+/**
+ * Fingerprint the raw tools/list payload for swap short-circuiting.
+ *
+ * Entries are ordered by public name, then stable-stringified (recursive key
+ * sort, array order preserved) and hashed. The fingerprint covers every field
+ * of the raw entries — including `execution.taskSupport`, which
+ * `createExecutor` bakes into the executor's semantics, and `outputSchema`,
+ * which shapes the registered output schema — so any server-side semantic
+ * change forces a swap. Executor closures are not compared (functions are not
+ * serializable); identical fingerprints on one client generation imply the
+ * rebuilt executors would be behaviorally identical.
+ *
+ * @param serverName - Namespace used to derive each entry's public name for ordering.
+ * @param tools - Raw entries exactly as returned by the server's `tools/list`.
+ * @returns A hex digest that is equal precisely when the payload is semantically unchanged.
+ */
+export declare function fingerprintTools(serverName: string, tools: readonly unknown[]): string;
+/** Canonical MCP result exposed to Code Mode without discarding protocol blocks. */
+export type McpResult<Structured extends JsonValue = JsonValue> = {
+    content: JsonValue[];
+    structuredContent?: Structured;
+};
+/**
+ * Derive the model-facing public name for one MCP tool.
+ *
+ * Deterministic pure function of `(serverName, rawName)`: the clean case is
+ * `mcp__<serverName>__<rawName>` verbatim. When character replacement or
+ * truncation to the DeepSeek function-name contract (64 chars,
+ * `[A-Za-z0-9_-]`) changes the name, a 12-hex-char SHA-256 hash of the
+ * identity is appended so distinct MCP identities never collapse into the
+ * same public name.
+ *
+ * @param serverName - Stable local namespace from plugin config.
+ * @param rawName - The MCP server's own tool name.
+ * @returns The globally unique, model-facing ToolRuntime name.
+ */
+export declare function publicToolName(serverName: string, rawName: string): string;
+/**
+ * Sync the MCP server's tool list into the harness ToolRuntime.
+ *
+ * Two phases keep the swap safe:
+ *
+ * 1. Fetch: drain uncached `tools/list` pagination and build the full next
+ *    generation of `ToolDefinition`s under public names. Any failure here
+ *    (network error, duplicate raw name in the server's list) rejects and
+ *    leaves the previous generation registered untouched.
+ * 2. Swap: dispose the previous generation, publish the new one. A registry
+ *    conflict here can only mean a foreign registration squats on this
+ *    server's `mcp__<serverName>__` namespace — the partial generation is
+ *    rolled back (zero tools from this server) and logged. Initial strict
+ *    synchronization may propagate the conflict so its parent transaction
+ *    rejects; ordinary clients and later re-syncs return an empty generation.
+ *    Deferred publishing detects the same squat up front (`ctx.tools.get`)
+ *    because `registerDeferred` only reserves the name.
+ *
+ * When the `ctx.toolSearch` seam is mounted and the server lists at least
+ * `deferToolThreshold` tools (default {@link DEFAULT_DEFER_TOOL_THRESHOLD}),
+ * each deferrable tool registers through `registerDeferred` instead: its
+ * definition stays out of the model-visible schema until a ToolSearch hit
+ * activates it. Tools flagged `_meta['anthropic/alwaysLoad']` register eagerly
+ * even on a deferred server. Without the seam the swap is eager at any
+ * threshold.
+ *
+ * Between the phases, a fingerprint of the raw payload decides whether the
+ * swap is needed at all: when the payload is semantically unchanged (key
+ * order may drift; content may not) AND `previous` was produced by the same
+ * client generation, the live registrations are kept and `previous` is
+ * returned unchanged — dispose+register churn (and the request-prefix churn
+ * it risks) is skipped. A new client generation always forces a real swap,
+ * so reconnects never reuse the previous generation's registrations.
+ *
+ * @param client - Connected MCP Client instance used to list and call tools.
+ * @param ctx - Cordis context providing the `tools` service for registration.
+ * @param opts - Bridge options: server namespace and per-call timeout.
+ * @param previous - The prior sync generation; its registrations are disposed
+ *   during the swap phase (only after the fetch phase succeeded and the
+ *   fingerprint check found a real change).
+ * @returns The live generation — `previous` itself on a fingerprint hit,
+ *   otherwise the newly registered one.
+ */
+export declare function syncTools(client: Client, ctx: Context, opts: ToolBridgeOptions, previous: ToolGeneration): Promise<ToolGeneration>;
+/**
+ * Run an MCP request, retrying once on a mid-session `UnauthorizedError`.
+ * Between the original attempt and the retry, `onUnauthorized` runs to drop
+ * stale OAuth state and re-establish a token. Only a single retry is attempted
+ * (the spec's "401 自动重试一次"); a second failure propagates to the caller.
+ *
+ * @param request - the MCP request to attempt.
+ * @param onUnauthorized - re-auth hook run before the single retry.
+ * @returns the request result.
+ */
+export declare function retryUnauthorizedOnce<T>(request: () => Promise<T>, onUnauthorized?: () => Promise<void> | void): Promise<T>;
+/** Whether a thrown error signals an expired/revoked OAuth session. */
+export declare function isUnauthorized(error: unknown): boolean;
+//# sourceMappingURL=tools.d.ts.map

package/lib/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAIvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,KAAK,EAAkB,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAA;AAEzD,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,mBAAmB,EAAE,SAAS,GAAG,OAAO,CAAA;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC5C;AAED,wFAAwF;AACxF,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,SAAS,EAAE,aAAa,CAAA;IACxB;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,sFAAsF;IACtF,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAWtF;AAED,oFAAoF;AACpF,MAAM,MAAM,SAAS,CAAC,UAAU,SAAS,SAAS,GAAG,SAAS,IAAI;IAChE,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,iBAAiB,CAAC,EAAE,UAAU,CAAA;CAC/B,CAAA;AA2CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAM1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC,CAuEzB;AA4CD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAQjI;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGtD"}