@askalf/dario 3.25.0 → 3.26.0

package/dist/cli.js

@@ -456,6 +456,11 @@ 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 doctor             Print a health report: dario / Node / CC /
                              template / drift / OAuth / pool / backends
 
@@ -574,6 +579,74 @@ 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 doctor() {
     const { runChecks, formatChecks, exitCodeFor } = await import('./doctor.js');
     console.log('');
@@ -612,6 +685,7 @@ const commands = {
     accounts,
     backend,
     shim,
+    subagent,
     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/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.26.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/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",