@askalf/dario 3.25.0 → 3.27.0

package/dist/cli.js

@@ -456,6 +456,19 @@ async function help() {
     dario backend remove N   Remove an OpenAI-compat backend
     dario shim -- CMD ARGS   Run CMD inside the dario shim (experimental,
                              stealth fingerprint via in-process fetch patch)
+    dario subagent install   Register ~/.claude/agents/dario.md so Claude Code
+                             can delegate dario diagnostics / template-refresh
+                             operations to a named sub-agent (v3.26)
+    dario subagent remove    Remove the registered sub-agent file
+    dario subagent status    Show whether the sub-agent is installed
+    dario mcp                Run dario as an MCP (Model Context Protocol)
+                             server on stdio. Exposes read-only tools
+                             (doctor, status, accounts_list, backends_list,
+                             subagent_status, fingerprint_info) so MCP
+                             clients (Claude Desktop, IDEs, etc.) can
+                             inspect dario's state. No destructive ops
+                             are exposed — mutations still require the
+                             CLI. (v3.27)
     dario doctor             Print a health report: dario / Node / CC /
                              template / drift / OAuth / pool / backends
 
@@ -574,6 +587,113 @@ async function shim() {
         process.exit(1);
     }
 }
+async function subagent() {
+    const sub = args[1] ?? 'status';
+    const { installSubagent, removeSubagent, loadSubagentStatus, SUBAGENT_NAME } = await import('./subagent.js');
+    if (sub === 'install') {
+        const r = installSubagent();
+        console.log('');
+        console.log('  dario — Sub-agent install');
+        console.log('  ─────────────────────────');
+        console.log('');
+        if (r.action === 'unchanged') {
+            console.log(`  Already up to date at ${r.path} (v${r.version}).`);
+        }
+        else {
+            console.log(`  ${r.action === 'created' ? 'Installed' : 'Updated'} at ${r.path} (v${r.version}).`);
+        }
+        console.log('');
+        console.log('  Claude Code will pick up the new sub-agent on its next startup.');
+        console.log(`  Invoke it from CC with: "Use the ${SUBAGENT_NAME} sub-agent to …"`);
+        console.log('');
+        return;
+    }
+    if (sub === 'remove' || sub === 'uninstall') {
+        const r = removeSubagent();
+        console.log('');
+        console.log('  dario — Sub-agent remove');
+        console.log('  ────────────────────────');
+        console.log('');
+        if (r.removed) {
+            console.log(`  Removed ${r.path}.`);
+        }
+        else {
+            console.log(`  Nothing to remove — ${r.path} was not present.`);
+        }
+        console.log('');
+        return;
+    }
+    if (sub === 'status') {
+        const s = loadSubagentStatus();
+        console.log('');
+        console.log('  dario — Sub-agent status');
+        console.log('  ────────────────────────');
+        console.log('');
+        console.log(`  Path:             ${s.path}`);
+        console.log(`  ~/.claude/agents: ${s.agentsDirExists ? 'exists' : 'missing (Claude Code not installed?)'}`);
+        if (!s.installed) {
+            console.log('  Installed:        no');
+            console.log('');
+            console.log('  Install with: dario subagent install');
+        }
+        else {
+            console.log(`  Installed:        yes (v${s.fileVersion ?? 'unknown'})`);
+            if (!s.current) {
+                console.log('  Note:             file version does not match installed dario — run `dario subagent install` to refresh.');
+            }
+        }
+        console.log('');
+        return;
+    }
+    console.error('');
+    console.error('  Usage: dario subagent <install | remove | status>');
+    console.error('');
+    console.error('  install   Write ~/.claude/agents/dario.md so Claude Code can');
+    console.error('            delegate dario diagnostics to a named sub-agent.');
+    console.error('  remove    Remove the installed sub-agent file.');
+    console.error('  status    Report whether the sub-agent is installed (default).');
+    console.error('');
+    process.exit(1);
+}
+async function mcp() {
+    // MCP-over-stdio: protocol frames on stdout ONLY. Any stray console.log
+    // from downstream modules (doctor / oauth / accounts helpers) would
+    // corrupt the frame stream, so redirect them to stderr defensively for
+    // the lifetime of the server. Restored in the finally block for tests /
+    // embedders that re-use the process after `dario mcp`.
+    const origLog = console.log;
+    const origInfo = console.info;
+    console.log = (...a) => console.error(...a);
+    console.info = (...a) => console.error(...a);
+    try {
+        const [{ buildDefaultToolRegistry }, { runMcpServer }] = await Promise.all([
+            import('./mcp/tools.js'),
+            import('./mcp/server.js'),
+        ]);
+        const { readFile } = await import('node:fs/promises');
+        const { fileURLToPath } = await import('node:url');
+        const here = join(fileURLToPath(import.meta.url), '..', '..');
+        let pkgVersion = 'unknown';
+        try {
+            const pkg = JSON.parse(await readFile(join(here, 'package.json'), 'utf-8'));
+            if (typeof pkg.version === 'string')
+                pkgVersion = pkg.version;
+        }
+        catch {
+            // package.json missing or malformed — fall back to 'unknown' but let
+            // the server keep running so tool responses are still usable.
+        }
+        const tools = await buildDefaultToolRegistry();
+        await runMcpServer({
+            tools,
+            server: { name: 'dario', version: pkgVersion },
+        });
+    }
+    finally {
+        console.log = origLog;
+        console.info = origInfo;
+    }
+}
 async function doctor() {
     const { runChecks, formatChecks, exitCodeFor } = await import('./doctor.js');
     console.log('');
@@ -612,6 +732,8 @@ const commands = {
     accounts,
     backend,
     shim,
+    subagent,
+    mcp,
     doctor,
     help,
     version,

package/dist/doctor.js

@@ -197,6 +197,30 @@ export async function runChecks() {
     catch (err) {
         checks.push({ status: 'warn', label: 'Backends', detail: `check failed: ${err.message}` });
     }
+    // ---- CC sub-agent (v3.26, direction #2)
+    try {
+        const { loadSubagentStatus } = await import('./subagent.js');
+        const s = loadSubagentStatus();
+        if (!s.agentsDirExists) {
+            checks.push({ status: 'info', label: 'Sub-agent', detail: 'not installed (~/.claude/agents missing — Claude Code not installed?)' });
+        }
+        else if (!s.installed) {
+            checks.push({ status: 'info', label: 'Sub-agent', detail: 'not installed — run `dario subagent install` to enable CC integration' });
+        }
+        else if (!s.current) {
+            checks.push({
+                status: 'warn',
+                label: 'Sub-agent',
+                detail: `installed v${s.fileVersion ?? 'unknown'}, does not match this dario — run \`dario subagent install\` to refresh`,
+            });
+        }
+        else {
+            checks.push({ status: 'ok', label: 'Sub-agent', detail: `installed v${s.fileVersion} at ${s.path}` });
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Sub-agent', detail: `check failed: ${err.message}` });
+    }
     // ---- ~/.dario dir
     try {
         const home = join(homedir(), '.dario');

package/dist/mcp/protocol.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimal MCP (Model Context Protocol) implementation — JSON-RPC 2.0 + the
+ * subset of methods dario needs to expose as an MCP server (direction #4,
+ * v3.27). Zero-runtime-deps policy means we don't pull in
+ * `@modelcontextprotocol/sdk`; the protocol surface we need is small enough
+ * to hand-roll correctly.
+ *
+ * MCP over stdio uses newline-delimited JSON — each line on stdin is one
+ * complete JSON-RPC message; each line on stdout is one complete response
+ * or notification. That's what `parseLine` and `encodeMessage` handle.
+ *
+ * We implement three methods from the MCP spec:
+ *   initialize           — handshake, server replies with capabilities.
+ *   tools/list           — enumerate exposed tools + their JSON schemas.
+ *   tools/call           — invoke a named tool with structured arguments.
+ *
+ * Plus the standard JSON-RPC error shapes. Notifications (no-`id` messages)
+ * are accepted and, for the only one we care about (`notifications/initialized`),
+ * acknowledged silently.
+ *
+ * Kept pure on purpose so the tests can exercise every branch without any
+ * stdio — `handleMessage` takes a raw JSON-RPC payload and a tool registry
+ * and returns either a response string or null (for notifications).
+ */
+/** MCP spec revisions ship with different wire quirks; pin the one we test against. */
+export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
+/** JSON-RPC 2.0 error codes (https://www.jsonrpc.org/specification). */
+export declare const JSONRPC_ERRORS: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification;
+/** Shape of an MCP tool's content block — we only emit text content. */
+export interface McpToolContent {
+    type: 'text';
+    text: string;
+}
+export interface McpToolResult {
+    content: McpToolContent[];
+    /** If a tool ran but the operation itself failed (e.g. upstream error), set isError: true. */
+    isError?: boolean;
+}
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<McpToolResult>;
+}
+/** Server identity the client sees on `initialize`. */
+export interface ServerInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Parse one newline-delimited JSON line into a JSON-RPC message.
+ * Returns `{ ok: true, msg }` on success or `{ ok: false, error }` so the
+ * caller can emit the canonical -32700 parse-error response. Blank lines
+ * are reported as ok=false with no error — they're legal stdio framing
+ * noise, not protocol violations.
+ */
+export declare function parseLine(line: string): {
+    ok: true;
+    msg: JsonRpcMessage;
+} | {
+    ok: false;
+    error: string | null;
+};
+/**
+ * Shape a successful response. `id` is echoed from the request.
+ */
+export declare function successResponse(id: string | number, result: unknown): JsonRpcResponse;
+/**
+ * Shape an error response with a JSON-RPC error code + message. When the
+ * originating message was unparseable (no id extractable), pass `null`.
+ */
+export declare function errorResponse(id: string | number | null, code: number, message: string, data?: unknown): JsonRpcResponse;
+/** Encode a response as a newline-terminated string ready for stdout. */
+export declare function encodeMessage(msg: JsonRpcResponse): string;
+/**
+ * Core request-dispatch routine. Pure: given a parsed message + a tool
+ * registry + server identity, returns the JSON-RPC response (or null for
+ * a notification that expects no reply).
+ */
+export declare function handleMessage(msg: JsonRpcMessage, tools: McpTool[], server: ServerInfo): Promise<JsonRpcResponse | null>;

package/dist/mcp/protocol.js

@@ -0,0 +1,135 @@
+/**
+ * Minimal MCP (Model Context Protocol) implementation — JSON-RPC 2.0 + the
+ * subset of methods dario needs to expose as an MCP server (direction #4,
+ * v3.27). Zero-runtime-deps policy means we don't pull in
+ * `@modelcontextprotocol/sdk`; the protocol surface we need is small enough
+ * to hand-roll correctly.
+ *
+ * MCP over stdio uses newline-delimited JSON — each line on stdin is one
+ * complete JSON-RPC message; each line on stdout is one complete response
+ * or notification. That's what `parseLine` and `encodeMessage` handle.
+ *
+ * We implement three methods from the MCP spec:
+ *   initialize           — handshake, server replies with capabilities.
+ *   tools/list           — enumerate exposed tools + their JSON schemas.
+ *   tools/call           — invoke a named tool with structured arguments.
+ *
+ * Plus the standard JSON-RPC error shapes. Notifications (no-`id` messages)
+ * are accepted and, for the only one we care about (`notifications/initialized`),
+ * acknowledged silently.
+ *
+ * Kept pure on purpose so the tests can exercise every branch without any
+ * stdio — `handleMessage` takes a raw JSON-RPC payload and a tool registry
+ * and returns either a response string or null (for notifications).
+ */
+/** MCP spec revisions ship with different wire quirks; pin the one we test against. */
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+/** JSON-RPC 2.0 error codes (https://www.jsonrpc.org/specification). */
+export const JSONRPC_ERRORS = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};
+/**
+ * Parse one newline-delimited JSON line into a JSON-RPC message.
+ * Returns `{ ok: true, msg }` on success or `{ ok: false, error }` so the
+ * caller can emit the canonical -32700 parse-error response. Blank lines
+ * are reported as ok=false with no error — they're legal stdio framing
+ * noise, not protocol violations.
+ */
+export function parseLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+        return { ok: false, error: null };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return { ok: false, error: 'top-level not an object' };
+    const obj = parsed;
+    if (obj.jsonrpc !== '2.0')
+        return { ok: false, error: 'missing or wrong jsonrpc version' };
+    if (typeof obj.method !== 'string')
+        return { ok: false, error: 'method must be a string' };
+    return { ok: true, msg: obj };
+}
+/**
+ * Shape a successful response. `id` is echoed from the request.
+ */
+export function successResponse(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+/**
+ * Shape an error response with a JSON-RPC error code + message. When the
+ * originating message was unparseable (no id extractable), pass `null`.
+ */
+export function errorResponse(id, code, message, data) {
+    const err = { code, message };
+    if (data !== undefined)
+        err.data = data;
+    return { jsonrpc: '2.0', id, error: err };
+}
+/** Encode a response as a newline-terminated string ready for stdout. */
+export function encodeMessage(msg) {
+    return JSON.stringify(msg) + '\n';
+}
+/**
+ * Core request-dispatch routine. Pure: given a parsed message + a tool
+ * registry + server identity, returns the JSON-RPC response (or null for
+ * a notification that expects no reply).
+ */
+export async function handleMessage(msg, tools, server) {
+    const isNotification = !('id' in msg) || msg.id === undefined;
+    const id = isNotification ? null : msg.id;
+    // Notifications — no response expected. Only handle the ones we care about;
+    // silently ignore others (per JSON-RPC spec).
+    if (isNotification) {
+        return null;
+    }
+    const reqId = id;
+    switch (msg.method) {
+        case 'initialize':
+            return successResponse(reqId, {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: server,
+            });
+        case 'tools/list':
+            return successResponse(reqId, {
+                tools: tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                })),
+            });
+        case 'tools/call': {
+            const params = (msg.params ?? {});
+            if (typeof params.name !== 'string') {
+                return errorResponse(reqId, JSONRPC_ERRORS.INVALID_PARAMS, 'tools/call requires string `name`');
+            }
+            const tool = tools.find((t) => t.name === params.name);
+            if (!tool) {
+                return errorResponse(reqId, JSONRPC_ERRORS.METHOD_NOT_FOUND, `unknown tool: ${params.name}`);
+            }
+            const argsVal = params.arguments;
+            const args = (argsVal && typeof argsVal === 'object' && !Array.isArray(argsVal))
+                ? argsVal
+                : {};
+            try {
+                const result = await tool.handler(args);
+                return successResponse(reqId, result);
+            }
+            catch (err) {
+                return errorResponse(reqId, JSONRPC_ERRORS.INTERNAL_ERROR, `tool handler threw: ${err.message}`);
+            }
+        }
+        default:
+            return errorResponse(reqId, JSONRPC_ERRORS.METHOD_NOT_FOUND, `unknown method: ${msg.method}`);
+    }
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP server runtime — bridges newline-delimited JSON-RPC on stdio to the
+ * pure `handleMessage` dispatcher in `./protocol.ts`. Everything stateful
+ * (stream I/O, serialization, logging) lives here; the protocol module
+ * stays pure so its tests don't need fake streams.
+ *
+ * Why serial: for await (const line of rl) processes one line at a time
+ * and we await the handler before reading the next. MCP clients tolerate
+ * both ordered and out-of-order responses, but ordered keeps the stdio
+ * frame sequence deterministic, avoids interleaving partial writes, and
+ * — the boring reason — matches what the tests can easily assert on.
+ *
+ * Why `runMcpServer` takes injectable streams: makes the event loop
+ * testable end-to-end with a PassThrough pair, no child process needed.
+ */
+import { type McpTool, type ServerInfo } from './protocol.js';
+export interface RunServerOptions {
+    tools: McpTool[];
+    server: ServerInfo;
+    /** Stream of newline-delimited JSON-RPC messages. Defaults to `process.stdin`. */
+    stdin?: NodeJS.ReadableStream;
+    /** Sink for newline-delimited JSON-RPC responses. Defaults to `process.stdout`. */
+    stdout?: NodeJS.WritableStream;
+    /** Diagnostic channel. Defaults to `process.stderr`. */
+    stderr?: NodeJS.WritableStream;
+    /** Hook fired when a handler throws unexpectedly — primarily for tests. */
+    onError?: (err: unknown, line: string) => void;
+}
+export declare function runMcpServer(opts: RunServerOptions): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,63 @@
+/**
+ * MCP server runtime — bridges newline-delimited JSON-RPC on stdio to the
+ * pure `handleMessage` dispatcher in `./protocol.ts`. Everything stateful
+ * (stream I/O, serialization, logging) lives here; the protocol module
+ * stays pure so its tests don't need fake streams.
+ *
+ * Why serial: for await (const line of rl) processes one line at a time
+ * and we await the handler before reading the next. MCP clients tolerate
+ * both ordered and out-of-order responses, but ordered keeps the stdio
+ * frame sequence deterministic, avoids interleaving partial writes, and
+ * — the boring reason — matches what the tests can easily assert on.
+ *
+ * Why `runMcpServer` takes injectable streams: makes the event loop
+ * testable end-to-end with a PassThrough pair, no child process needed.
+ */
+import { createInterface } from 'node:readline';
+import { handleMessage, parseLine, errorResponse, encodeMessage, JSONRPC_ERRORS, } from './protocol.js';
+/**
+ * Back-pressure-aware line write. Using the callback form of
+ * `stream.write` means we wait for the chunk to drain before proceeding —
+ * on a slow stdout consumer that prevents us from buffering unboundedly.
+ */
+function writeLine(stream, chunk) {
+    return new Promise((resolve, reject) => {
+        stream.write(chunk, (err) => (err ? reject(err) : resolve()));
+    });
+}
+export async function runMcpServer(opts) {
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stdout;
+    const stderr = opts.stderr ?? process.stderr;
+    const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+    for await (const line of rl) {
+        const parsed = parseLine(line);
+        if (!parsed.ok) {
+            // Blank lines are legal framing noise, not errors — skip silently.
+            if (parsed.error === null)
+                continue;
+            await writeLine(stdout, encodeMessage(errorResponse(null, JSONRPC_ERRORS.PARSE_ERROR, `parse error: ${parsed.error}`)));
+            continue;
+        }
+        try {
+            const response = await handleMessage(parsed.msg, opts.tools, opts.server);
+            if (response !== null) {
+                await writeLine(stdout, encodeMessage(response));
+            }
+        }
+        catch (err) {
+            // `handleMessage` already wraps tool-handler errors into -32603 responses;
+            // anything reaching here is a bug in the dispatcher itself. Still, don't
+            // let it crash the server — emit a synthetic error response and log.
+            const message = err?.message ?? 'internal error';
+            const id = 'id' in parsed.msg && parsed.msg.id !== undefined
+                ? parsed.msg.id
+                : null;
+            if (opts.onError)
+                opts.onError(err, line);
+            else
+                stderr.write(`[dario mcp] unhandled: ${message}\n`);
+            await writeLine(stdout, encodeMessage(errorResponse(id, JSONRPC_ERRORS.INTERNAL_ERROR, message)));
+        }
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,69 @@
+/**
+ * MCP tool registry for the dario MCP server (v3.27, direction #4).
+ *
+ * Each tool wraps an existing dario subsystem that's already covered by
+ * its own tests, so these wrappers stay thin — fetch data, format it as
+ * text content, return. All tools are read-only. Destructive operations
+ * (login/logout, accounts add/remove, backend add/remove, proxy start)
+ * are deliberately NOT exposed: an MCP client shouldn't be able to
+ * mutate the user's dario state just by being connected, same boundary
+ * as the sub-agent prompt (v3.26).
+ *
+ * `buildToolRegistry` is a factory so tests can inject fake backends for
+ * each dario subsystem. In production, `buildDefaultToolRegistry` wires
+ * up the real dynamic imports — the imports live inside the factory so
+ * `src/mcp/protocol.ts` stays a pure module, decoupled from any of
+ * dario's heavier code paths.
+ */
+import type { McpTool } from './protocol.js';
+/**
+ * Injectable data sources for the tool handlers. Production wiring in
+ * `buildDefaultToolRegistry` fills these in with the real dario imports;
+ * tests can substitute pure synthetic data to avoid touching network /
+ * filesystem / OAuth state.
+ */
+export interface ToolDataSources {
+    doctor: () => Promise<Array<{
+        status: string;
+        label: string;
+        detail: string;
+    }>>;
+    status: () => Promise<{
+        authenticated: boolean;
+        status: string;
+        expiresIn?: string;
+        canRefresh?: boolean;
+    }>;
+    accounts: () => Promise<Array<{
+        alias: string;
+        expiresAt: number;
+    }>>;
+    backends: () => Promise<Array<{
+        name: string;
+        baseUrl: string;
+        model?: string;
+    }>>;
+    subagent: () => Promise<{
+        installed: boolean;
+        path: string;
+        fileVersion: string | null;
+        current: boolean;
+        agentsDirExists: boolean;
+    }>;
+    fingerprint: () => Promise<{
+        runtime: string;
+        runtimeVersion: string;
+        status: string;
+        detail: string;
+        templateSource: string;
+        templateSchema: number | null;
+    }>;
+    darioVersion: () => string;
+}
+export declare function buildToolRegistry(data: ToolDataSources): McpTool[];
+/**
+ * Default production wiring — imports dario's real subsystems. Kept out
+ * of `buildToolRegistry` so the registry factory stays pure over its
+ * data sources (and the unit tests don't pay for dynamic imports).
+ */
+export declare function buildDefaultToolRegistry(): Promise<McpTool[]>;

package/dist/mcp/tools.js

@@ -0,0 +1,205 @@
+/**
+ * MCP tool registry for the dario MCP server (v3.27, direction #4).
+ *
+ * Each tool wraps an existing dario subsystem that's already covered by
+ * its own tests, so these wrappers stay thin — fetch data, format it as
+ * text content, return. All tools are read-only. Destructive operations
+ * (login/logout, accounts add/remove, backend add/remove, proxy start)
+ * are deliberately NOT exposed: an MCP client shouldn't be able to
+ * mutate the user's dario state just by being connected, same boundary
+ * as the sub-agent prompt (v3.26).
+ *
+ * `buildToolRegistry` is a factory so tests can inject fake backends for
+ * each dario subsystem. In production, `buildDefaultToolRegistry` wires
+ * up the real dynamic imports — the imports live inside the factory so
+ * `src/mcp/protocol.ts` stays a pure module, decoupled from any of
+ * dario's heavier code paths.
+ */
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: 'text', text }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+export function buildToolRegistry(data) {
+    const emptyObjectSchema = { type: 'object', properties: {}, required: [] };
+    return [
+        {
+            name: 'doctor',
+            description: 'Run dario\'s health-report checks and return the formatted output. Covers: dario version, Node, platform, runtime TLS fingerprint, CC binary + compat, template source + drift, OAuth state, account pool, backends, CC sub-agent install. No side effects.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const checks = await data.doctor();
+                if (checks.length === 0)
+                    return textResult('No checks produced output.');
+                const labelWidth = checks.reduce((n, c) => Math.max(n, c.label.length), 0);
+                const prefix = {
+                    ok: '[ OK ]', warn: '[WARN]', fail: '[FAIL]', info: '[INFO]',
+                };
+                const lines = checks.map((c) => `${prefix[c.status] ?? '[????]'}  ${c.label.padEnd(labelWidth)}  ${c.detail}`);
+                const failed = checks.filter((c) => c.status === 'fail').length;
+                const warned = checks.filter((c) => c.status === 'warn').length;
+                const summary = `\n\nSummary: ${checks.length} checks — ${failed} fail, ${warned} warn`;
+                return textResult(lines.join('\n') + summary);
+            },
+        },
+        {
+            name: 'status',
+            description: 'Report the dario OAuth authentication status: whether credentials are present, valid, and when they expire. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const s = await data.status();
+                if (!s.authenticated) {
+                    const detail = s.status === 'none'
+                        ? 'No credentials — run `dario login`.'
+                        : s.status === 'expired' && s.canRefresh
+                            ? 'Credentials expired but refreshable — run `dario refresh` or `dario proxy`.'
+                            : `Not authenticated (status: ${s.status}).`;
+                    return textResult(`Authenticated: no\n${detail}`);
+                }
+                return textResult(`Authenticated: yes\nStatus: ${s.status}\nExpires in: ${s.expiresIn ?? 'unknown'}`);
+            },
+        },
+        {
+            name: 'accounts_list',
+            description: 'List the accounts configured in dario\'s multi-account pool (~/.dario/accounts/). Returns alias + token expiry per account. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const accounts = await data.accounts();
+                if (accounts.length === 0) {
+                    return textResult('No pool accounts configured. dario runs in single-account mode from ~/.dario/credentials.json.');
+                }
+                const now = Date.now();
+                const lines = accounts.map((a) => {
+                    const msLeft = Math.max(0, a.expiresAt - now);
+                    const hours = Math.floor(msLeft / 3600000);
+                    const mins = Math.floor((msLeft % 3600000) / 60000);
+                    const expiry = msLeft > 0 ? `${hours}h ${mins}m` : 'expired';
+                    return `  ${a.alias.padEnd(20)} token expires in ${expiry}`;
+                });
+                const note = accounts.length < 2
+                    ? '\n\nPool mode activates at 2+ accounts — currently single-account.'
+                    : '';
+                return textResult(`${accounts.length} account${accounts.length === 1 ? '' : 's'}:\n${lines.join('\n')}${note}`);
+            },
+        },
+        {
+            name: 'backends_list',
+            description: 'List configured OpenAI-compat backends (OpenAI, OpenRouter, Groq, LiteLLM, Ollama, etc.). Read-only — does not expose API keys.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const backends = await data.backends();
+                if (backends.length === 0) {
+                    return textResult('No OpenAI-compat backends configured. Claude subscription is the only route.');
+                }
+                const lines = backends.map((b) => `  ${b.name.padEnd(20)} ${b.baseUrl}${b.model ? `  (default model: ${b.model})` : ''}`);
+                return textResult(`${backends.length} backend${backends.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
+            },
+        },
+        {
+            name: 'subagent_status',
+            description: 'Report whether the dario CC sub-agent (~/.claude/agents/dario.md) is installed and whether it matches the running dario version. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const s = await data.subagent();
+                const lines = [];
+                lines.push(`Path: ${s.path}`);
+                lines.push(`~/.claude/agents exists: ${s.agentsDirExists ? 'yes' : 'no'}`);
+                lines.push(`Installed: ${s.installed ? `yes (v${s.fileVersion ?? 'unknown'})` : 'no'}`);
+                if (s.installed && !s.current) {
+                    lines.push('Note: file version does not match running dario — run `dario subagent install` to refresh.');
+                }
+                if (!s.installed && s.agentsDirExists) {
+                    lines.push('Install with: `dario subagent install`.');
+                }
+                return textResult(lines.join('\n'));
+            },
+        },
+        {
+            name: 'fingerprint_info',
+            description: 'Report dario\'s runtime / TLS fingerprint state: whether the proxy is running under Bun (matches CC\'s TLS stack) or Node (diverges), which template source is active (live-captured vs bundled), and the template schema version. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const f = await data.fingerprint();
+                const lines = [];
+                lines.push(`Runtime:         ${f.runtime} ${f.runtimeVersion}`);
+                lines.push(`TLS status:      ${f.status}`);
+                lines.push(`TLS detail:      ${f.detail}`);
+                lines.push(`Template source: ${f.templateSource}`);
+                lines.push(`Template schema: v${f.templateSchema ?? '?'}`);
+                lines.push(`dario version:   ${data.darioVersion()}`);
+                return textResult(lines.join('\n'));
+            },
+        },
+    ];
+}
+/**
+ * Default production wiring — imports dario's real subsystems. Kept out
+ * of `buildToolRegistry` so the registry factory stays pure over its
+ * data sources (and the unit tests don't pay for dynamic imports).
+ */
+export async function buildDefaultToolRegistry() {
+    const [doctorMod, oauthMod, accountsMod, backendMod, subagentMod, runtimeMod, templateMod, pkgVersion] = await Promise.all([
+        import('../doctor.js'),
+        import('../oauth.js'),
+        import('../accounts.js'),
+        import('../openai-backend.js'),
+        import('../subagent.js'),
+        import('../runtime-fingerprint.js'),
+        import('../cc-template.js'),
+        readDarioVersion(),
+    ]);
+    return buildToolRegistry({
+        doctor: async () => {
+            const checks = await doctorMod.runChecks();
+            return checks.map((c) => ({
+                status: c.status,
+                label: c.label,
+                detail: c.detail,
+            }));
+        },
+        status: async () => oauthMod.getStatus(),
+        accounts: async () => {
+            const loaded = await accountsMod.loadAllAccounts();
+            return loaded.map((a) => ({
+                alias: a.alias,
+                expiresAt: a.expiresAt,
+            }));
+        },
+        backends: async () => {
+            const backends = await backendMod.listBackends();
+            return backends.map((b) => ({
+                name: b.name,
+                baseUrl: b.baseUrl,
+                model: b.model,
+            }));
+        },
+        subagent: async () => subagentMod.loadSubagentStatus(),
+        fingerprint: async () => {
+            const rt = runtimeMod.detectRuntimeFingerprint();
+            const tmpl = templateMod.CC_TEMPLATE;
+            return {
+                runtime: rt.runtime,
+                runtimeVersion: rt.runtimeVersion,
+                status: rt.status,
+                detail: rt.detail,
+                templateSource: tmpl._source ?? 'unknown',
+                templateSchema: tmpl._schemaVersion ?? null,
+            };
+        },
+        darioVersion: () => pkgVersion,
+    });
+}
+async function readDarioVersion() {
+    try {
+        const { readFileSync } = await import('node:fs');
+        const { fileURLToPath } = await import('node:url');
+        const { dirname, join } = await import('node:path');
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/subagent.d.ts

@@ -0,0 +1,74 @@
+/**
+ * CC sub-agent hook (v3.26, direction #2).
+ *
+ * Claude Code reads sub-agent definitions from `~/.claude/agents/*.md` —
+ * a YAML-frontmatter markdown file that exposes a tool-scoped prompt
+ * context CC can delegate work into. Installing a "dario" sub-agent
+ * gives the user (or CC itself, via the Task tool) a named handle to
+ * delegate dario operations into: refreshing the baked template from
+ * a live capture, checking proxy health, listing pool / backend state.
+ *
+ * The sub-agent runs with Bash + Read tool access only — it can invoke
+ * the `dario` CLI to produce reports, but it cannot modify dario state
+ * (accounts add/remove, backend configuration, etc.) without the user
+ * explicitly running those commands in their own session. That boundary
+ * is baked into the prompt so the sub-agent doesn't accidentally take
+ * destructive actions on the user's behalf.
+ *
+ * The file content is versioned via an inline `dario-sub-agent-version:`
+ * marker so a later release can detect stale installations (same axis as
+ * the `_schemaVersion` check on the live-fingerprint cache). `readStatus`
+ * is pure over `(fileExists, fileBody)` so the tests exercise every
+ * branch without touching the filesystem.
+ */
+export declare const SUBAGENT_NAME = "dario";
+export declare const SUBAGENT_FILENAME = "dario.md";
+/** `~/.claude/agents/dario.md`. */
+export declare function getSubagentPath(): string;
+/**
+ * Construct the full sub-agent file body for a given dario version. Pure
+ * function — the tests pin the output so a change to the content is a
+ * deliberate, diffable update.
+ */
+export declare function buildSubagentFile(darioVersion: string): string;
+export interface SubagentStatus {
+    installed: boolean;
+    path: string;
+    /** Parsed from the inline `dario-sub-agent-version:` marker when the file is present. */
+    fileVersion: string | null;
+    /** Whether the installed file matches the version currently being built. */
+    current: boolean;
+    /** Whether `~/.claude/agents/` exists (is CC installed / agents dir created?). */
+    agentsDirExists: boolean;
+}
+/**
+ * Pure status computation over (fileExists, fileBody, currentVersion).
+ * Separated from `loadStatus` so tests can feed synthetic bodies and
+ * exercise every branch without the filesystem.
+ */
+export declare function computeSubagentStatus(path: string, fileExists: boolean, fileBody: string | null, agentsDirExists: boolean, currentVersion: string): SubagentStatus;
+/**
+ * Read the current on-disk status. Safe to call whether or not
+ * `~/.claude/` exists; a missing directory is reported via
+ * `agentsDirExists: false` so the caller can decide whether to create it
+ * (install) or just skip (status).
+ */
+export declare function loadSubagentStatus(): SubagentStatus;
+/**
+ * Install or refresh the sub-agent. Creates `~/.claude/agents/` if it
+ * doesn't exist. Returns what happened so the CLI can log accurately.
+ */
+export declare function installSubagent(): {
+    path: string;
+    action: 'created' | 'updated' | 'unchanged';
+    version: string;
+};
+/**
+ * Remove the sub-agent file. Idempotent — returns `{ removed: false }`
+ * if the file wasn't present. Does not remove the parent `~/.claude/agents/`
+ * directory even if it becomes empty (user may have other sub-agents).
+ */
+export declare function removeSubagent(): {
+    path: string;
+    removed: boolean;
+};

package/dist/subagent.js

@@ -0,0 +1,167 @@
+/**
+ * CC sub-agent hook (v3.26, direction #2).
+ *
+ * Claude Code reads sub-agent definitions from `~/.claude/agents/*.md` —
+ * a YAML-frontmatter markdown file that exposes a tool-scoped prompt
+ * context CC can delegate work into. Installing a "dario" sub-agent
+ * gives the user (or CC itself, via the Task tool) a named handle to
+ * delegate dario operations into: refreshing the baked template from
+ * a live capture, checking proxy health, listing pool / backend state.
+ *
+ * The sub-agent runs with Bash + Read tool access only — it can invoke
+ * the `dario` CLI to produce reports, but it cannot modify dario state
+ * (accounts add/remove, backend configuration, etc.) without the user
+ * explicitly running those commands in their own session. That boundary
+ * is baked into the prompt so the sub-agent doesn't accidentally take
+ * destructive actions on the user's behalf.
+ *
+ * The file content is versioned via an inline `dario-sub-agent-version:`
+ * marker so a later release can detect stale installations (same axis as
+ * the `_schemaVersion` check on the live-fingerprint cache). `readStatus`
+ * is pure over `(fileExists, fileBody)` so the tests exercise every
+ * branch without touching the filesystem.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const SUBAGENT_NAME = 'dario';
+export const SUBAGENT_FILENAME = `${SUBAGENT_NAME}.md`;
+/** `~/.claude/agents/dario.md`. */
+export function getSubagentPath() {
+    return join(homedir(), '.claude', 'agents', SUBAGENT_FILENAME);
+}
+/**
+ * Construct the full sub-agent file body for a given dario version. Pure
+ * function — the tests pin the output so a change to the content is a
+ * deliberate, diffable update.
+ */
+export function buildSubagentFile(darioVersion) {
+    return `---
+name: ${SUBAGENT_NAME}
+description: Use this sub-agent for dario-related diagnostics and template-refresh operations. It can invoke the \`dario\` CLI (via Bash) to run a health report, refresh the baked CC request template from a live capture, or check the proxy's account pool and backend configuration. It will not modify dario state (credentials, accounts, backends) without explicit user authorization.
+tools: Bash, Read
+---
+
+<!-- dario-sub-agent-version: ${darioVersion} -->
+<!-- managed by: dario subagent install / remove -->
+
+You are **dario's integration sub-agent**. You have access to the \`dario\` CLI via the Bash tool. Your job is to help the user with dario-related diagnostics and refresh operations by running read-only or user-requested commands and summarizing the output.
+
+## What you can do (read-only — no user confirmation required)
+
+- **\`dario doctor\`** — produce a health report covering Node / platform, runtime TLS fingerprint, CC binary + compatibility range, template source + drift, OAuth state, account pool, and backend configuration. Summarize any \`[WARN]\` or \`[FAIL]\` rows in plain language and suggest the fix hinted in the detail column.
+- **\`dario status\`** — quick auth status (authenticated, expires in, claim).
+- **\`dario accounts list\`** — list the configured account pool and per-account token expiry.
+- **\`dario backend list\`** — list configured OpenAI-compat backends (OpenRouter, Groq, LiteLLM, etc.).
+- **\`dario --version\`** — report the installed dario version.
+
+## What requires explicit user authorization first
+
+Before invoking any of these, ask the user to confirm:
+
+- \`dario login\` / \`dario refresh\` — mutates credentials.
+- \`dario accounts add/remove\` — mutates the account pool.
+- \`dario backend add/remove\` — mutates backend configuration.
+- \`dario logout\` — deletes stored credentials.
+
+## What you should NOT do
+
+- Do not run \`dario proxy\` — the proxy is a long-running server; invoking it from a sub-agent context would block the parent CC session indefinitely.
+- Do not modify \`~/.dario/\` files directly (credentials.json, accounts/, backends.json). Use the CLI.
+- Do not dump credentials, tokens, or bearer values in your output.
+
+## Style
+
+- Lead with the headline answer (one line).
+- For diagnostics, group findings by severity (FAIL → WARN → OK).
+- When suggesting a fix, quote the exact command the user should run.
+- Keep output concise — the user is delegating to you because they want a summary, not a transcript.
+`;
+}
+/**
+ * Pure status computation over (fileExists, fileBody, currentVersion).
+ * Separated from `loadStatus` so tests can feed synthetic bodies and
+ * exercise every branch without the filesystem.
+ */
+export function computeSubagentStatus(path, fileExists, fileBody, agentsDirExists, currentVersion) {
+    if (!fileExists || fileBody === null) {
+        return { installed: false, path, fileVersion: null, current: false, agentsDirExists };
+    }
+    const m = /<!-- dario-sub-agent-version: ([^ ]+) -->/.exec(fileBody);
+    const fileVersion = m ? m[1] : null;
+    const current = fileVersion === currentVersion;
+    return { installed: true, path, fileVersion, current, agentsDirExists };
+}
+/**
+ * Read the current on-disk status. Safe to call whether or not
+ * `~/.claude/` exists; a missing directory is reported via
+ * `agentsDirExists: false` so the caller can decide whether to create it
+ * (install) or just skip (status).
+ */
+export function loadSubagentStatus() {
+    const path = getSubagentPath();
+    const agentsDir = dirname(path);
+    const agentsDirExists = existsSync(agentsDir);
+    const fileExists = existsSync(path);
+    let fileBody = null;
+    if (fileExists) {
+        try {
+            fileBody = readFileSync(path, 'utf-8');
+        }
+        catch {
+            fileBody = null;
+        }
+    }
+    return computeSubagentStatus(path, fileExists, fileBody, agentsDirExists, currentDarioVersion());
+}
+/**
+ * Install or refresh the sub-agent. Creates `~/.claude/agents/` if it
+ * doesn't exist. Returns what happened so the CLI can log accurately.
+ */
+export function installSubagent() {
+    const path = getSubagentPath();
+    const agentsDir = dirname(path);
+    if (!existsSync(agentsDir)) {
+        mkdirSync(agentsDir, { recursive: true });
+    }
+    const version = currentDarioVersion();
+    const desired = buildSubagentFile(version);
+    let existingBody = null;
+    const exists = existsSync(path);
+    if (exists) {
+        try {
+            existingBody = readFileSync(path, 'utf-8');
+        }
+        catch {
+            existingBody = null;
+        }
+    }
+    if (existingBody === desired) {
+        return { path, action: 'unchanged', version };
+    }
+    writeFileSync(path, desired, 'utf-8');
+    return { path, action: exists ? 'updated' : 'created', version };
+}
+/**
+ * Remove the sub-agent file. Idempotent — returns `{ removed: false }`
+ * if the file wasn't present. Does not remove the parent `~/.claude/agents/`
+ * directory even if it becomes empty (user may have other sub-agents).
+ */
+export function removeSubagent() {
+    const path = getSubagentPath();
+    if (!existsSync(path))
+        return { path, removed: false };
+    unlinkSync(path);
+    return { path, removed: true };
+}
+function currentDarioVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.25.0",
+  "version": "3.27.0",
   "description": "A local LLM router. One endpoint, every provider — Claude subscriptions, OpenAI, OpenRouter, Groq, local LiteLLM, any OpenAI-compat endpoint — your tools don't need to change.",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "build": "tsc && cp src/cc-template-data.json dist/ && node -e \"require('fs').mkdirSync('dist/shim',{recursive:true})\" && cp src/shim/runtime.cjs dist/shim/",
-    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/tool-schema-contract.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/pool-sticky.mjs && node test/sealed-pool.mjs && node test/live-fingerprint.mjs && node test/shim-runtime.mjs && node test/shim-e2e.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/drift-detection.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs",
+    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/tool-schema-contract.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/pool-sticky.mjs && node test/sealed-pool.mjs && node test/live-fingerprint.mjs && node test/shim-runtime.mjs && node test/shim-e2e.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/subagent.mjs && node test/mcp-protocol.mjs && node test/mcp-tools.mjs && node test/mcp-e2e.mjs && node test/drift-detection.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs",
     "audit": "npm audit --production --audit-level=high",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",