lazyclaw 6.0.0 → 6.0.1

package/daemon/routes/conversation.mjs

@@ -0,0 +1,371 @@
+// Daemon route handlers (conversation), extracted verbatim from makeHandler (D5).
+// Each handler takes the per-request dispatch context `c` and returns the
+// HTTP response. Bodies are unchanged; only the dispatch wrapper is new.
+import { fs, nodePath, PROVIDERS, PROVIDER_INFO, maskApiKey, costFromUsage, RATE_CARD_SHAPE, composeSystemPrompt, listSkills, loadSkill, skillPath, installSkill, removeSkill, parseFrontmatter, skillsDefaultConfigDir, indexDb, skillSynth, sandboxListBackends, summarizeState, listWorkflowSessions, loadWorkflowState, aggregateNodeStats, validateConfig, validateRates, fileExists, readJson, readTextBody, writeJson, writeSseHead, writeSse, statusForProviderError, checkCostCap, accumulateMetricsFromCost, resolveProvider, openThreads, handoffWithRollback } from './_deps.mjs';
+import { randomBytes } from 'node:crypto';
+
+// F5 — mint a fresh session id for a newly-seen channel:externalId binding.
+// Kept filename-local (threads.mjs's newThreadId isn't exported); the `ib_`
+// hex form satisfies sessions.mjs sessionPath validation (no / \ . ..).
+function newInboundSessionId() {
+  return 'ib_' + randomBytes(8).toString('hex');
+}
+
+export async function execRequest(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          // Remote exec-approval bridge. This route is AUTH-TOKEN-GATED
+          // (above), so only the trusted local operator/CLI can REQUEST an
+          // approval; a paired mobile device RESOLVES it over the gateway
+          // (POST /gateway/exec/resolve). The route long-polls: it awaits
+          // the device's decision (or the approval's timeout) and returns
+          // { approved, by, reason }.
+          let body;
+          try { body = await readJson(req); }
+          catch (e) { return writeJson(res, 400, { error: `invalid JSON body: ${e.message}` }); }
+          if (!body || typeof body.tool !== 'string' || !body.tool) {
+            return writeJson(res, 400, { error: 'tool is required' });
+          }
+          const { promise } = gateway.requestApproval(
+            { tool: body.tool, args: body.args, agentId: body.agentId, summary: body.summary },
+            { timeoutMs: Number.isFinite(+body.timeoutMs) ? +body.timeoutMs : undefined },
+          );
+          const result = await promise;
+          return writeJson(res, 200, result);
+}
+
+export async function chat(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          // Cost-cap gate: short-circuit before parsing the body so the
+          // 402 fires fast and we don't pay for body buffering on a
+          // request we're refusing.
+          const breach = checkCostCap(metrics, costCap);
+          if (breach) {
+            return writeJson(res, 402, {
+              error: 'cost cap exceeded',
+              currency: breach.currency,
+              spent: breach.spent,
+              cap: breach.cap,
+            });
+          }
+          // Full message-array input, single response (or stream). Useful when
+          // the caller already has a message history and doesn't want to use
+          // the disk-persisted session model.
+          const body = await readJson(req);
+          const cfg = ctx.readConfig();
+          const provName = body.provider || cfg.provider || 'mock';
+          const resolved = resolveProvider(body, provName, cachedByName, logger);
+          if (resolved.error) return writeJson(res, 400, { error: resolved.error });
+          const prov = resolved.provider;
+          const messages = Array.isArray(body.messages) ? body.messages.filter(m => m && typeof m.role === 'string' && typeof m.content === 'string') : null;
+          if (!messages || messages.length === 0) return writeJson(res, 400, { error: 'messages array required' });
+          const thinkingBudget = Number(body.thinkingBudget) || 0;
+          // Usage capture: opt-in via body.usage. The provider only does
+          // the extra work (and pays the wire cost on OpenAI) when the
+          // caller asks for it.
+          let captured = null;
+          const sendOpts = {
+            apiKey: cfg['api-key'],
+            model: body.model || cfg.model,
+            thinking: thinkingBudget > 0 ? { enabled: true, budgetTokens: thinkingBudget } : undefined,
+            onUsage: body.usage ? (u) => { captured = u; } : undefined,
+          };
+          // Cost lookup: body.cost:true asks the daemon to attach a cost
+          // block when usage was captured AND cfg.rates has a card for
+          // the active provider/model. Pure arithmetic — no extra wire
+          // calls. Inline rather than helper-extract because the two
+          // response paths (stream / non-stream) need to bind it
+          // differently (SSE event vs JSON field).
+          const computeCost = () => {
+            if (!body.cost || !captured || !cfg.rates) return null;
+            try {
+              const c = costFromUsage(
+                { provider: provName, model: body.model || cfg.model, usage: captured },
+                cfg.rates,
+              );
+              if (c) accumulateMetricsFromCost(metrics, captured, c);
+              return c;
+            } catch { return null; }
+          };
+          if (body.stream === true) {
+            writeSseHead(res);
+            // Abort the provider when the SSE client disconnects — otherwise it
+            // keeps generating (burning tokens/cost) for a caller that's gone.
+            // Mirrors the /agent stream path.
+            const ac = new AbortController();
+            req.on('aborted', () => ac.abort());
+            res.on('close', () => { if (!res.writableEnded) ac.abort(); });
+            try {
+              for await (const chunk of prov.sendMessage(messages, { ...sendOpts, signal: ac.signal })) {
+                if (ac.signal.aborted) break;
+                writeSse(res, 'token', { text: chunk });
+                await new Promise(r => setImmediate(r));
+              }
+              if (!ac.signal.aborted) {
+                if (captured) writeSse(res, 'usage', captured);
+                const cost = computeCost();
+                if (cost) writeSse(res, 'cost', cost);
+                writeSse(res, 'done', { ok: true });
+              }
+              return res.end();
+            } catch (err) {
+              if (err?.code === 'ABORT' || ac.signal.aborted) return res.end();
+              writeSse(res, 'error', { message: err?.message || String(err) });
+              return res.end();
+            }
+          }
+          let acc = '';
+          try {
+            for await (const chunk of prov.sendMessage(messages, sendOpts)) acc += chunk;
+            const cost = computeCost();
+            const out = { reply: acc };
+            if (captured) out.usage = captured;
+            if (cost) out.cost = cost;
+            return writeJson(res, 200, out);
+          } catch (err) {
+            const m = statusForProviderError(err);
+            return writeJson(res, m.status, {
+              error: err?.message || String(err),
+              code: err?.code || null,
+              ...(err?.retryAfterMs ? { retryAfterMs: err.retryAfterMs } : {}),
+            }, m.headers || {});
+          }
+}
+
+export async function inbound(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          // Generic inbound bridge — a stable, channel-agnostic relay
+          // target so ANY platform (a Discord/WhatsApp/etc. bot the user
+          // runs elsewhere) can forward a message in and get one reply,
+          // without lazyclaw shipping that platform's SDK. Auth-token
+          // gated like every non-gateway route; additionally pairing-gated
+          // on senderId when a pairing allowlist is configured.
+          const breach = checkCostCap(metrics, costCap);
+          if (breach) return writeJson(res, 402, { error: 'cost cap exceeded', currency: breach.currency, spent: breach.spent, cap: breach.cap });
+          let body;
+          try { body = await readJson(req); }
+          catch (e) { return writeJson(res, 400, { error: `invalid JSON body: ${e.message}` }); }
+          const text = typeof body.text === 'string' ? body.text.trim() : '';
+          if (!text) return writeJson(res, 400, { error: 'text is required' });
+          const cfg = ctx.readConfig();
+          // Pairing gate: when the operator has paired any senders, the
+          // relay must identify an allowlisted senderId.
+          const allow = Array.isArray(cfg.pairing) ? cfg.pairing.map((p) => String(p && p.id)) : [];
+          if (allow.length > 0) {
+            const sender = String(body.senderId || '');
+            if (!sender || !allow.includes(sender)) return writeJson(res, 403, { error: 'sender not paired' });
+          }
+          const provName = body.provider || cfg.provider || 'mock';
+          const resolved = resolveProvider(body, provName, cachedByName, logger);
+          if (resolved.error) return writeJson(res, 400, { error: resolved.error });
+          // F5 — when the relaying bot identifies its channel + external
+          // conversation id, bind {channel, externalId} -> a persistent
+          // session so context follows across channels (and across a
+          // /handoff). Without those fields we keep the original stateless
+          // one-shot behavior, byte-compatible with existing callers.
+          const cfgDir = ctx.sessionsDirGetter();
+          const channel = (typeof body.channel === 'string' && body.channel) ? body.channel : null;
+          const externalId = (body.externalId != null && String(body.externalId)) ? String(body.externalId) : null;
+          let threads = null;
+          let bound = null;
+          let sessionId = null;
+          if (channel && externalId) {
+            threads = openThreads(cfgDir);
+            bound = threads.findByExternal(channel, externalId);
+            if (bound) {
+              sessionId = bound.sessionId;
+            } else {
+              sessionId = newInboundSessionId();
+              threads.upsert({ channel, externalId, sessionId });
+              bound = threads.findByExternal(channel, externalId);
+            }
+          }
+          // Hydrate prior turns for a bound session (mirrors POST /agent).
+          const messages = sessionId
+            ? ctx.sessionsMod.loadTurns(sessionId, cfgDir).map((t) => ({ role: t.role, content: t.content }))
+            : [];
+          messages.push({ role: 'user', content: text });
+          if (sessionId) ctx.sessionsMod.appendTurn(sessionId, 'user', text, cfgDir);
+          let acc = '';
+          let inboundUsage = null;
+          try {
+            for await (const chunk of resolved.provider.sendMessage(
+              messages,
+              { apiKey: cfg['api-key'], model: body.model || cfg.model, onUsage: (u) => { inboundUsage = u; } },
+            )) acc += chunk;
+          } catch (err) {
+            const m = statusForProviderError(err);
+            return writeJson(res, m.status, { error: err?.message || String(err), code: err?.code || null }, m.headers || {});
+          }
+          if (sessionId) {
+            ctx.sessionsMod.appendTurn(sessionId, 'assistant', acc, cfgDir);
+            // Refresh lastTurnAt on the binding.
+            threads.upsert({ channel, externalId, sessionId, threadId: bound.threadId });
+          }
+          // Feed the running spend total so the cost cap can actually trip
+          // on /inbound traffic (mirrors POST /agent / POST /chat).
+          if (inboundUsage && cfg.rates) {
+            try {
+              const c = costFromUsage({ provider: provName, model: body.model || cfg.model, usage: inboundUsage }, cfg.rates);
+              if (c) accumulateMetricsFromCost(metrics, inboundUsage, c);
+            } catch { /* cost is best-effort; never block a reply on it */ }
+          }
+          const out = { reply: acc, threadId: bound ? bound.threadId : (body.threadId || null) };
+          if (sessionId) out.sessionId = sessionId;
+          return writeJson(res, 200, out);
+}
+
+export async function handoff(c) {
+  const { ctx, res, req } = c;
+          // F6 — re-point a thread to a new channel/externalId so a later
+          // inbound on the target resumes the SAME session (context follows).
+          // The daemon has no live per-channel send map, so it migrates the
+          // binding directly with no notifier; once a send adapter is injected,
+          // a failed target notify rolls the binding back (channels/handoff.mjs).
+          let body;
+          try { body = await readJson(req); }
+          catch (e) { return writeJson(res, 400, { error: `invalid JSON body: ${e.message}` }); }
+          const threadId = typeof body.threadId === 'string' ? body.threadId.trim() : '';
+          const target = typeof body.target === 'string' ? body.target.trim() : '';
+          const externalId = body.externalId != null ? String(body.externalId).trim() : '';
+          if (!threadId || !target || !externalId) {
+            return writeJson(res, 400, { error: 'threadId, target, and externalId are required' });
+          }
+          const cfgDir = ctx.sessionsDirGetter();
+          const threads = openThreads(cfgDir);
+          try {
+            const next = await handoffWithRollback({
+              threads, threadId, target, externalId,
+              note: typeof body.note === 'string' ? body.note : '',
+            });
+            return writeJson(res, 200, {
+              threadId: next.threadId, channel: next.channel,
+              externalId: next.externalId, sessionId: next.sessionId,
+            });
+          } catch (err) {
+            if (err?.code === 'THREAD_NOT_FOUND') return writeJson(res, 404, { error: err.message, code: 'THREAD_NOT_FOUND' });
+            if (err?.code === 'HANDOFF_SEND_FAILED') return writeJson(res, 502, { error: err.message, code: 'HANDOFF_SEND_FAILED' });
+            return writeJson(res, 400, { error: err?.message || String(err) });
+          }
+}
+
+export async function agent(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          const breach = checkCostCap(metrics, costCap);
+          if (breach) {
+            return writeJson(res, 402, {
+              error: 'cost cap exceeded',
+              currency: breach.currency,
+              spent: breach.spent,
+              cap: breach.cap,
+            });
+          }
+          const body = await readJson(req);
+          const cfg = ctx.readConfig();
+          const provName = body.provider || cfg.provider || 'mock';
+          const resolved = resolveProvider(body, provName, cachedByName, logger);
+          if (resolved.error) return writeJson(res, 400, { error: resolved.error });
+          const prov = resolved.provider;
+          const prompt = String(body.prompt ?? '').trim();
+          if (!prompt) return writeJson(res, 400, { error: 'prompt required' });
+          const model = body.model || cfg.model;
+          const thinkingBudget = Number(body.thinkingBudget) || 0;
+
+          // Session hydration if sessionId provided.
+          const sid = body.sessionId || null;
+          const cfgDir = ctx.sessionsDirGetter();
+          let messages = sid ? ctx.sessionsMod.loadTurns(sid, cfgDir).map(t => ({ role: t.role, content: t.content })) : [];
+          // Skill composition: body.skills can be a comma-separated string
+          // ("a,b") or an array (["a","b"]). Compose only when no system
+          // message already exists in the message array (so re-runs of
+          // the same session don't double-prepend).
+          const skillNames = Array.isArray(body.skills)
+            ? body.skills
+            : (typeof body.skills === 'string' ? body.skills.split(',').map(s => s.trim()).filter(Boolean) : []);
+          if (skillNames.length > 0 && !messages.some(m => m.role === 'system')) {
+            try {
+              const sys = composeSystemPrompt(skillNames, cfgDir);
+              if (sys) messages.unshift({ role: 'system', content: sys });
+            } catch (err) {
+              return writeJson(res, 400, { error: `skill error: ${err?.message || String(err)}` });
+            }
+          }
+          messages.push({ role: 'user', content: prompt });
+          if (sid) ctx.sessionsMod.appendTurn(sid, 'user', prompt, cfgDir);
+
+          // body.usage opt-in mirrors POST /chat — provider only does the
+          // extra work when the caller asks for it.
+          let agentCaptured = null;
+          const agentSendOpts = {
+            apiKey: cfg['api-key'],
+            model,
+            thinking: thinkingBudget > 0 ? { enabled: true, budgetTokens: thinkingBudget } : undefined,
+            onUsage: body.usage ? (u) => { agentCaptured = u; } : undefined,
+          };
+          const computeAgentCost = () => {
+            if (!body.cost || !agentCaptured || !cfg.rates) return null;
+            try {
+              const c = costFromUsage(
+                { provider: provName, model, usage: agentCaptured },
+                cfg.rates,
+              );
+              if (c) accumulateMetricsFromCost(metrics, agentCaptured, c);
+              return c;
+            } catch { return null; }
+          };
+
+          if (body.stream === true) {
+            writeSseHead(res);
+            // Forward client disconnect to the provider so we don't keep
+            // burning tokens after the consumer has gone away.
+            const ac = new AbortController();
+            req.on('aborted', () => ac.abort());
+            res.on('close', () => { if (!res.writableEnded) ac.abort(); });
+            let acc = '';
+            try {
+              for await (const chunk of prov.sendMessage(messages, { ...agentSendOpts, signal: ac.signal })) {
+                if (ac.signal.aborted) break;
+                acc += chunk;
+                writeSse(res, 'token', { text: chunk });
+                // Backpressure: yield so the caller can read each frame.
+                await new Promise(r => setImmediate(r));
+              }
+              if (sid && !ac.signal.aborted) ctx.sessionsMod.appendTurn(sid, 'assistant', acc, cfgDir);
+              if (!ac.signal.aborted) {
+                if (agentCaptured) writeSse(res, 'usage', agentCaptured);
+                const cost = computeAgentCost();
+                if (cost) writeSse(res, 'cost', cost);
+                writeSse(res, 'done', { ok: true });
+              }
+              return res.end();
+            } catch (err) {
+              if (err?.code === 'ABORT' || ac.signal.aborted) {
+                // Client gave up — partial assistant turn is discarded.
+                return res.end();
+              }
+              writeSse(res, 'error', { message: err?.message || String(err) });
+              return res.end();
+            }
+          }
+
+          // Non-streaming: collect then return once. Reuse agentSendOpts
+          // (carrying the optional onUsage capture) so usage lands in the
+          // response when body.usage was set.
+          let acc = '';
+          try {
+            for await (const chunk of prov.sendMessage(messages, agentSendOpts)) acc += chunk;
+            if (sid) ctx.sessionsMod.appendTurn(sid, 'assistant', acc, cfgDir);
+            const cost = computeAgentCost();
+            const out = { reply: acc };
+            if (agentCaptured) out.usage = agentCaptured;
+            if (cost) out.cost = cost;
+            return writeJson(res, 200, out);
+          } catch (err) {
+            const m = statusForProviderError(err);
+            return writeJson(res, m.status, {
+              error: err?.message || String(err),
+              code: err?.code || null,
+              ...(err?.retryAfterMs ? { retryAfterMs: err.retryAfterMs } : {}),
+            }, m.headers || {});
+          }
+}
+

package/daemon/routes/meta.mjs

@@ -0,0 +1,239 @@
+// Daemon route handlers (meta), extracted verbatim from makeHandler (D5).
+// Each handler takes the per-request dispatch context `c` and returns the
+// HTTP response. Bodies are unchanged; only the dispatch wrapper is new.
+import { fs, nodePath, PROVIDERS, PROVIDER_INFO, maskApiKey, costFromUsage, RATE_CARD_SHAPE, composeSystemPrompt, listSkills, loadSkill, skillPath, installSkill, removeSkill, parseFrontmatter, skillsDefaultConfigDir, indexDb, skillSynth, sandboxListBackends, summarizeState, listWorkflowSessions, loadWorkflowState, aggregateNodeStats, validateConfig, validateRates, fileExists, readJson, readTextBody, writeJson, writeSseHead, writeSse, statusForProviderError, checkCostCap, accumulateMetricsFromCost, resolveProvider } from './_deps.mjs';
+import { fileURLToPath } from 'node:url';
+
+// Serve a static asset that lives alongside the dashboard HTML in web/.
+// Used for the split-out dashboard.css / dashboard.js (CLAUDE.md §7: one
+// file = one responsibility). Same loopback origin as the JSON API, so no
+// CORS handling is needed. Returns 404 (not the dashboard's 503 install
+// hint) since a missing asset is a narrower failure.
+function serveWebFile(c, filename, contentType) {
+  const { res } = c;
+  try {
+    const here = nodePath.dirname(fileURLToPath(import.meta.url));
+    const filePath = nodePath.join(here, '..', '..', 'web', filename);
+    const body = fs.readFileSync(filePath);
+    res.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-cache' });
+    return res.end(body);
+  } catch (e) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    return res.end(`not found: ${filename} (${e?.message || e})\n`);
+  }
+}
+
+export async function dashboardCss(c) {
+  return serveWebFile(c, 'dashboard.css', 'text/css; charset=utf-8');
+}
+
+export async function dashboardJs(c) {
+  return serveWebFile(c, 'dashboard.js', 'text/javascript; charset=utf-8');
+}
+
+export async function dashboard(c) {
+  const { res } = c;
+          // Serve the lazyclaw-only web dashboard (a single static
+          // HTML in src/lazyclaw/web/). Co-resident with the JSON
+          // API so a single port handles both — no CORS song and
+          // dance, no separate static server. Falls back to a
+          // helpful text response when the file is missing (someone
+          // ran the daemon out of a partial install).
+          try {
+            const fs = await import('node:fs');
+            const path = await import('node:path');
+            const url = await import('node:url');
+            const here = path.dirname(url.fileURLToPath(import.meta.url));
+            const htmlPath = path.join(here, '..', '..', 'web', 'dashboard.html');
+            const body = fs.readFileSync(htmlPath, 'utf8');
+            res.writeHead(200, {
+              'content-type': 'text/html; charset=utf-8',
+              'cache-control': 'no-cache',
+            });
+            return res.end(body);
+          } catch (e) {
+            res.writeHead(503, { 'content-type': 'text/plain; charset=utf-8' });
+            return res.end(
+              `lazyclaw daemon is up but the dashboard HTML wasn't found.\n` +
+              `Try \`lazyclaw version\` to confirm install integrity, or hit any /api endpoint directly.\n\n` +
+              `error: ${e?.message || e}\n`,
+            );
+          }
+}
+
+export async function version(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          return writeJson(res, 200, { version: ctx.version(), nodeVersion: process.version, platform: `${process.platform}-${process.arch}` });
+}
+
+export async function health(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          // Conventional liveness check — always 200 if the process
+          // is alive enough to hit the route. No config inspection
+          // (use /doctor for readiness), no provider probing — this
+          // is the "is the daemon up?" probe that load balancers
+          // and watchdog scripts expect at this path. m15: K8s
+          // readiness probes default to /healthz so we alias.
+          return writeJson(res, 200, {
+            ok: true,
+            status: 'alive',
+            uptimeMs: Date.now() - metrics.startedAtMs,
+            timestamp: new Date().toISOString(),
+          });
+}
+
+export async function metrics(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          // Aggregate per-handler counters. cacheStats are pulled per
+          // wrapped provider — we report a sum across all populated
+          // entries so the figure reflects total cache activity.
+          let cacheHits = 0, cacheMisses = 0, cacheSize = 0;
+          if (cachedByName) {
+            for (const wrapped of cachedByName.values()) {
+              const s = typeof wrapped.cacheStats === 'function' ? wrapped.cacheStats() : null;
+              if (s) {
+                cacheHits += s.hits || 0;
+                cacheMisses += s.misses || 0;
+                cacheSize += s.size || 0;
+              }
+            }
+          }
+          // Cumulative tokens / cost — meaningful only when callers used
+          // body.usage / body.cost. The fields are always present (zero
+          // by default) so monitoring tooling sees a stable schema.
+          const tokensTotal = { ...metrics.tokensTotal };
+          const costs = {};
+          for (const [cur, n] of Object.entries(metrics.costsByCurrency)) {
+            // Round to six decimals here too, matching costFromUsage's
+            // precision so monitoring deltas line up with per-request
+            // breakdowns.
+            costs[cur] = Math.round(n * 1_000_000) / 1_000_000;
+          }
+          // Workflow snapshot — opportunistic. We scan the state dir
+          // once per /metrics call and count per bucket. This is
+          // cheap unless the user has thousands of state files; for
+          // truly large fleets the operator can disable by passing
+          // ctx.workflowMetrics === false.
+          let workflows = null;
+          if (ctx.workflowMetrics !== false) {
+            try {
+              const stateDir = ctx.workflowStateDir();
+              if (fs.existsSync(stateDir)) {
+                const sessions = listWorkflowSessions(stateDir);
+                workflows = { total: sessions.length, done: 0, resumable: 0, failed: 0, running: 0 };
+                for (const s of sessions) {
+                  if (s.summary.done)        workflows.done++;
+                  if (s.summary.resumable)   workflows.resumable++;
+                  if (s.summary.failed > 0)  workflows.failed++;
+                  if (s.summary.running > 0) workflows.running++;
+                }
+              } else {
+                workflows = { total: 0, done: 0, resumable: 0, failed: 0, running: 0 };
+              }
+            } catch {
+              // Don't fail /metrics because the state dir is unreadable —
+              // expose the gap as null and keep monitoring alive.
+              workflows = null;
+            }
+          }
+          return writeJson(res, 200, {
+            uptimeMs: Date.now() - metrics.startedAtMs,
+            requestsTotal: metrics.requestsTotal,
+            requestsByStatus: metrics.requestsByStatus,
+            rateLimitDenied: metrics.rateLimitDenied,
+            cache: cachedByName ? { hits: cacheHits, misses: cacheMisses, size: cacheSize } : null,
+            tokensTotal,
+            costsByCurrency: costs,
+            workflows,
+            timestamp: new Date().toISOString(),
+          });
+}
+
+export async function status(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          const cfg = ctx.readConfig();
+          // v5: surface a one-line summary of trainer / index / sandbox so
+          // the dashboard banner doesn't need three more round-trips.
+          const trainerCfg = (cfg.trainer && typeof cfg.trainer === 'object') ? cfg.trainer : {};
+          const sandboxBackend = (cfg.sandbox && typeof cfg.sandbox === 'object' && cfg.sandbox.default) || 'local';
+          let indexRows = null;
+          try {
+            const db = indexDb.openIndex(gwConfigDir, { runIntegrityCheck: false });
+            const r = db.prepare(
+              "SELECT (SELECT COUNT(*) FROM fts_sessions) + (SELECT COUNT(*) FROM fts_skills) " +
+              " + (SELECT COUNT(*) FROM fts_trajectories) + (SELECT COUNT(*) FROM fts_memories) AS n"
+            ).get();
+            indexRows = r && typeof r.n === 'number' ? r.n : null;
+          } catch { /* index may not exist yet */ }
+          // Migration backup path is conventionally <configDir>/backup-v4/.
+          let migrateBackup = null;
+          try {
+            const p = nodePath.join(gwConfigDir || skillsDefaultConfigDir(), 'backup-v4');
+            if (fs.existsSync(p)) migrateBackup = p;
+          } catch { /* ignore */ }
+          return writeJson(res, 200, {
+            provider: cfg.provider || null,
+            model: cfg.model || null,
+            keyMasked: maskApiKey(cfg['api-key']),
+            v5: {
+              trainer: {
+                provider: trainerCfg.provider || null,
+                model: trainerCfg.model || null,
+              },
+              sandboxBackend,
+              indexRows,
+              migrateBackup,
+            },
+          });
+}
+
+export async function doctor(c) {
+  const { ctx, logger, metrics, gateway, costCap, cachedByName, gwConfigDir, nudgeSuggestionsRing, workflowStateDir, req, res, method, path, route, url, sessionMatch, providerMatch, providerTestMatch, sessionExportMatch, skillMatch, workflowMatch, configKeyMatch, ratesKeyMatch } = c;
+          // Mirror the CLI doctor output — same field set so any tool that
+          // already knows how to read CLI doctor JSON can hit this endpoint.
+          const cfg = ctx.readConfig();
+          const issues = [];
+          if (!cfg.provider) issues.push('config.provider is missing');
+          if (cfg.provider && cfg.provider !== 'mock' && !cfg['api-key']) {
+            issues.push(`config['api-key'] is missing for provider "${cfg.provider}"`);
+          }
+          if (cfg.provider && !Object.prototype.hasOwnProperty.call(PROVIDERS, cfg.provider)) {
+            issues.push(`unknown provider "${cfg.provider}"`);
+          }
+          // v5: FTS5 index integrity. Failure here is degraded-not-fatal —
+          // surfaced as an issue but doesn't take the daemon down.
+          let indexBlock = null;
+          try {
+            const integ = indexDb.integrityCheck(gwConfigDir);
+            const db = indexDb.openIndex(gwConfigDir, { runIntegrityCheck: false });
+            const rowCounts = {};
+            for (const t of ['fts_sessions', 'fts_skills', 'fts_trajectories', 'fts_memories']) {
+              try { rowCounts[t] = db.prepare(`SELECT COUNT(*) AS n FROM ${t}`).get().n; }
+              catch { rowCounts[t] = null; }
+            }
+            indexBlock = {
+              ok: !!integ.ok,
+              result: integ.result || null,
+              rowCounts,
+              lastRebuiltAt: ctx.indexLastRebuiltAt || null,
+            };
+            if (!integ.ok) issues.push(`FTS5 index integrity_check returned ${integ.result}`);
+          } catch (e) {
+            indexBlock = { ok: false, error: e?.message || String(e), rowCounts: {}, lastRebuiltAt: null };
+            issues.push(`FTS5 index unavailable: ${e?.message || e}`);
+          }
+          const ok = issues.length === 0;
+          return writeJson(res, ok ? 200 : 503, {
+            ok,
+            provider: cfg.provider || null,
+            model: cfg.model || null,
+            hasApiKey: !!cfg['api-key'],
+            nodeVersion: process.version,
+            platform: `${process.platform}-${process.arch}`,
+            issues,
+            knownProviders: Object.keys(PROVIDERS),
+            index: indexBlock,
+            timestamp: new Date().toISOString(),
+          });
+}
+