lazyclaw 6.4.0 → 6.6.0

package/commands/config.mjs

@@ -102,11 +102,45 @@ export async function cmdConfigEdit() {
   }
 }
 
+// Coerce a CLI string value into the type it most likely represents so a
+// boolean/number setting isn't stored as a string the rest of the code then
+// mis-compares (`if (cfg.chat.recall)` is truthy for the string "false").
+//   'true' / 'false'        → boolean
+//   integer / float strings → number
+//   everything else         → the original string (provider/model/api-key/…)
+function coerceConfigValue(value) {
+  if (typeof value !== 'string') return value;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  // Only treat as a number when the WHOLE string is a clean numeric literal —
+  // Number('') is 0 and Number('1.2.3') is NaN, both of which we reject so
+  // ids like "gpt-4.1" or empty values stay strings.
+  if (value.trim() !== '' && /^-?(?:\d+|\d*\.\d+|\d+\.\d*)$/.test(value.trim()) && Number.isFinite(Number(value))) {
+    return Number(value);
+  }
+  return value;
+}
+
 export function cmdConfigSet(key, value) {
   const cfg = readConfig();
-  cfg[key] = value;
+  const coerced = coerceConfigValue(value);
+  if (typeof key === 'string' && key.includes('.')) {
+    // Dotted key → nested path. Walk/create each intermediate object so
+    // `chat.recall` lands as cfg.chat.recall (not a flat "chat.recall" key).
+    // A non-object value blocking the path is replaced rather than crashing.
+    const segs = key.split('.');
+    let node = cfg;
+    for (let i = 0; i < segs.length - 1; i++) {
+      const seg = segs[i];
+      if (!node[seg] || typeof node[seg] !== 'object' || Array.isArray(node[seg])) node[seg] = {};
+      node = node[seg];
+    }
+    node[segs[segs.length - 1]] = coerced;
+  } else {
+    cfg[key] = coerced;
+  }
   writeConfig(cfg);
-  console.log(JSON.stringify({ ok: true, key, value }));
+  console.log(JSON.stringify({ ok: true, key, value: coerced }));
 }
 export async function cmdDoctor() {
   await ensureRegistry();

package/commands/help_text.mjs

@@ -0,0 +1,78 @@
+// commands/help_text.mjs — pure-data help tables for `lazyclaw help`,
+// extracted verbatim from commands/setup.mjs (file-size gate, no behavior
+// change). HELP_SUMMARIES (one-liners for `help`) and HELP_DETAILS (per-
+// subcommand usage for `help <name>`) are read only by cmdHelp. They import
+// nothing and reference nothing else — pure data, lowest-risk extraction.
+
+// One-line summaries used by `lazyclaw help`. Format keeps it scan-friendly
+// in a 80-column terminal: subcommand padded to 12 chars, then the summary.
+export const HELP_SUMMARIES = {
+  run:        'Execute a workflow file (run <session-id> <workflow.mjs>)',
+  resume:     'Resume a workflow from its last persisted checkpoint',
+  config:     'Manage local config (get|set|list|delete <key>)',
+  chat:       'Interactive REPL with the configured provider',
+  agent:      'One-shot prompt: streams a single response, exits',
+  doctor:     'Print diagnostic JSON; exits non-zero on issues',
+  status:     'Print current provider/model/masked key as JSON',
+  onboard:    'Guided setup (use --non-interactive for scripts)',
+  sessions:   'Persistent chat sessions (list|show|clear|export)',
+  skills:     'Markdown skill bundles (list|show|install|remove)',
+  providers:  'Inspect / register providers (list|info|test|add|remove|models)',
+  daemon:     'Run the local HTTP gateway (--port, --auth-token, --allow-origin)',
+  version:    'Print VERSION + node + platform as JSON',
+  completion: 'Emit shell completion script (completion <bash|zsh>)',
+  export:     'Dump config + skills (+ optional sessions) as a JSON bundle',
+  import:     'Apply a JSON bundle from stdin or --from <path>',
+  rates:      'Manage cost rate-cards in config (rates list|set <provider/model>|delete|shape)',
+  auth:       'Multiple keys per provider (auth list|add|remove|use|rotate <provider>)',
+  pairing:    'Sender allowlist for the messaging surface (pairing list|add|remove <id>)',
+  nodes:      'Companion device registration (nodes list|register|remove <id>)',
+  message:    'Outbound webhook messaging (message list|add|remove|send <name>)',
+  workspace:  'AGENTS.md / SOUL.md / TOOLS.md system-prompt convention (workspace list|init|show|remove|path)',
+  browse:     'Fetch a URL and emit Markdown on stdout (browse <url> [--max-bytes <N>])',
+  cron:       'Schedule recurring agent runs via launchd / crontab (cron list|add|remove|show|sync|run)',
+  setup:      'Hermes-style phased first-run wizard (provider + verify chat + channel + workspace + skill + webhook)',
+  dashboard:  'Launch the lazyclaw-only web UI (lighter than the full lazyclaude dashboard)',
+  inspect:    'Print persisted workflow state without executing',
+  clear:      'Delete a persisted workflow state file (idempotent)',
+  validate:   'Static-check a workflow file: shape, deps, cycles, parallelism',
+  graph:      'Emit workflow DAG as Mermaid syntax (paste-ready for docs)',
+  orchestrator: 'Multi-agent dispatch — planner decomposes, workers run, planner synthesises',
+};
+
+// Detailed usage per subcommand for `lazyclaw help <name>`. Kept as flat
+// strings so the help output is identical in every terminal.
+export const HELP_DETAILS = {
+  run: 'Usage: lazyclaw run <session-id> <workflow.mjs> [--parallel | --parallel-persistent] [--concurrency <N>]\n  Default: runPersistent — sequential, persists state, resumable via `lazyclaw resume`.\n  --parallel: runParallel — topological-level DAG, in-memory only, NOT resumable.\n  --parallel-persistent: runPersistentDag — DAG + checkpoint + resume.\n  --concurrency <N>: cap in-flight nodes within a level (DAG modes only). 0/missing → unbounded.\n  Workflow file exports `nodes`; deps: string[] declares dependencies for both DAG modes.',
+  resume: 'Usage: lazyclaw resume <session-id> <workflow.mjs> [--parallel-persistent] [--concurrency <N>]\n  Re-enters a previously persisted run; succeeds nodes are skipped.\n  Pass --parallel-persistent to resume a DAG run (must match the original run\'s mode).\n  --concurrency <N>: cap in-flight nodes per level (DAG mode only).',
+  inspect: 'Usage: lazyclaw inspect [<session-id>] [--dir <state-dir>] [--status done|resumable|failed|running] [--summary] [--filter <substr>] [--limit <N>] [--node <node-id>] [--slowest <N>] [--critical-path <workflow.mjs>] [--aggregate]\n  With no session-id: list every persisted session in the state dir, sorted by recency.\n  --aggregate (list mode): per-node stats across all sessions (count, success/failed/pending/running, min/max/avg/total duration).\n  --status filters the listing to a single lifecycle bucket.\n  --filter / --limit refine list-mode further (case-insensitive sessionId substring + post-filter cap).\n  --summary trims per-node detail in single-session mode (matches list-mode shape).\n  --node <id>: print just that node\'s state. Exit 0 success/pending/running, 1 failed, 2 no such node.\n  --slowest <N>: top N nodes by durationMs (descending, ties broken by id).\n  --critical-path <workflow.mjs>: longest-weighted-path analysis using each node\'s recorded durationMs (bottleneck finder).\n  With a session-id (no per-node flag): print full state. Exit code: 0=resumable, 1=fully done, 2=no state, 3=terminal failure.',
+  clear: 'Usage: lazyclaw clear <session-id> [--dir <state-dir>]\n  Delete the state file for <session-id>. Idempotent — exits 0 whether the file existed or not.\n  Refuses sessionIds that resolve outside <state-dir>. Mirrors DELETE /workflows/<id> on the daemon.',
+  validate: 'Usage: lazyclaw validate <workflow.mjs>\n  Static check: load + shape + dep + cycle + parallelism estimate.\n  Exit 0 valid · 1 hard failure (issues populated) · 2 file/import error.',
+  graph: 'Usage: lazyclaw graph <workflow.mjs> [--lr] [--state <session-id>] [--dir <state-dir>]\n  Emit the workflow DAG as Mermaid syntax (graph TD by default; --lr for left-right).\n  --state overlays a persisted run\'s status (success ✓ / running ⏳ / failed ✗ / pending) with classDef styling.\n  Output is paste-ready for GitHub markdown / Notion / Obsidian.',
+  config: 'Usage: lazyclaw config <get|set|list|delete|path|edit|validate> [key] [value]\n  Local key-value config at $LAZYCLAW_CONFIG_DIR/config.json (default ~/.lazyclaw).\n  `path` prints the file location; `edit` opens it in $EDITOR (or $LAZYCLAW_EDITOR / $VISUAL / vi) and validates JSON on save.\n  `validate` checks the structural integrity of the whole config file (typed values, known providers, rate-card shape).',
+  chat: 'Usage: lazyclaw chat [--session <id>] [--skill name1,name2] [--workspace <name>] [--pick] [--sandbox docker:<image>] [--sandbox-network <net>] [--sandbox-mount <m>] [--sandbox-env <e>]\n  --session persists turns to <configDir>/sessions/<id>.jsonl across invocations.\n  --skill composes named skills into a system message at the head of the conversation.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md from <configDir>/workspaces/<name>/ into the system prompt.\n  --pick opens an interactive provider/model picker before the prompt (also auto-fires on first run).\n  --sandbox routes the underlying claude CLI through `docker run --rm -i --network <net> -v cwd:cwd ...` (default --network=none).',
+  agent: 'Usage: lazyclaw agent <prompt|-> [--provider X] [--model Y] [--skill list] [--workspace <name>] [--thinking N] [--show-thinking] [--usage] [--cost] [--sandbox docker:<image>]\n  One-shot non-interactive call. Pass "-" as the prompt to read from stdin.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md into the system prompt (combines with --skill).\n  --usage prints normalized {inputTokens, outputTokens, ...} to stderr after the response.\n  --cost adds a cost line on stderr when config.rates has a card for the active provider/model.\n  --sandbox docker:<image> wraps the subprocess provider (claude-cli) in a Docker container; --sandbox-network defaults to none.',
+  doctor: 'Usage: lazyclaw doctor\n  Validates configuration and registered providers. Exits 0 only when no issues.',
+  status: 'Usage: lazyclaw status\n  Provider, model, and masked API key. Never prints the raw key.',
+  onboard: 'Usage: lazyclaw onboard [--non-interactive] [--provider X] [--model Y] [--api-key Z]\n  --model accepts the unified "provider/model" string (e.g. anthropic/claude-opus-4-7).',
+  sessions: 'Usage: lazyclaw sessions <list [--filter <substr>] [--limit <N>]|show <id>|clear <id>|export <id> [--format md|json|text]|search <query> [--regex]>\n  list — recent sessions by mtime; --filter caps to ids containing substring (case-insensitive); --limit caps result count.\n  export — render in chosen format (md default for human sharing, json for tooling, text for paste).\n  search — case-insensitive substring (or --regex pattern) match across all session content; returns first excerpt + match count per matching session.',
+  skills: 'Usage: lazyclaw skills <list [--filter <substr>] [--limit <N>]|show <name>|install <user/repo[@ref][:path]> [--prefix <p>] [--force] | install <name> [--from <path> | --from-url <https://...>]|remove <name>|search <query> [--regex]>\n  list — installed skills; --filter caps to names containing substring (case-insensitive); --limit caps result count.\n  install <user>/<repo>[@<ref>][:<subpath>] — fetch a GitHub tarball, install every .md under skills/ (or the explicit subpath, or repo root). Default ref is `main`.\n    --prefix prepends a name prefix so a multi-skill repo doesn\'t collide with locally-managed skills. --force overwrites existing names.\n  install <name> --from <path> | --from-url <https://...> — single-file install. --from-url is HTTPS-only with a 1 MiB cap.\n  search — case-insensitive substring (or --regex) match across all skill markdown bodies; returns first excerpt + match count per skill.',
+  providers: 'Usage: lazyclaw providers <list [--filter <substr>] [--limit <N>] | info <name> | test <name> [--model X] [--prompt T] | test [--all] [--prompt T] | add <name> --base-url <url> [--api-key <k>] [--default-model <id>] [--no-probe] | remove <name> | models <name> [--filter <substr>]>\n  list   — registered providers (--filter case-insensitive name substring; --limit caps post-filter count).\n  info   — static metadata: requiresApiKey, defaultModel, suggestedModels, endpoint.\n  test   — send a 1-token "ping" through the provider and report ok/error + duration.\n           Useful after configuring an API key to verify it works before relying on it.\n           No name OR --all: tests every registered provider in parallel; exits 0 only when ALL pass.\n  add    — register a custom OpenAI-compatible endpoint (NIM / OpenRouter / Together / Groq / vLLM / LM Studio / …).\n           Probes /v1/models on success unless --no-probe is set; persists to cfg.customProviders[].\n  remove — drop a custom provider entry from cfg.customProviders[].\n  models — fetch + print the live model catalogue from <provider>/v1/models (works for openai / ollama / custom).',
+  daemon: 'Usage: lazyclaw daemon [--port <N>] [--once] [--auth-token <token>] [--allow-origin <origin>] [--rate-limit <N>] [--response-cache] [--log <level>] [--shutdown-timeout-ms <N>] [--cost-cap-<currency> <N> ...] [--workflow-state-dir <dir>]\n  Always binds 127.0.0.1. --port 0 picks a random port and prints the URL.\n  --auth-token also reads $LAZYCLAW_AUTH_TOKEN; --allow-origin also reads $LAZYCLAW_ALLOW_ORIGINS.\n  --rate-limit <N> caps each remote IP at N requests / 60 s.\n  --response-cache enables process-scoped memoization; per-request opt-in via body.cache.\n  --log <debug|info|warn|error> emits JSON-line access logs on stderr (also reads $LAZYCLAW_LOG_LEVEL).\n  --shutdown-timeout-ms <N> caps graceful drain on SIGINT/SIGTERM (default 10000). Second signal forces immediate exit.\n  --cost-cap-usd 100 (or any currency code in lowercase) rejects POST /agent + /chat with 402 once cumulative cost reaches the cap.\n  --workflow-state-dir <dir> backs GET /workflows + GET /workflows/<id> (default .workflow-state, also reads $LAZYCLAW_WORKFLOW_STATE_DIR).',
+  version: 'Usage: lazyclaw version\n  Aliases: --version, -v.',
+  completion: 'Usage: lazyclaw completion <bash|zsh>\n  bash:   eval "$(lazyclaw completion bash)"\n  zsh:    lazyclaw completion zsh > "${fpath[1]}/_lazyclaw"',
+  export: 'Usage: lazyclaw export [--include-secrets] [--include-sessions] > bundle.json\n  --include-secrets keeps the raw api-key in the bundle (default redacts it).\n  --include-sessions adds full turn content (default keeps metadata only).',
+  import: 'Usage: lazyclaw import [--from <path>] [--overwrite-skills] [--no-overwrite-config] [--import-sessions]\n  Reads JSON from stdin (or --from <path>). Sessions are NEVER overwritten.\n  Redacted api-keys (***REDACTED***) are dropped, never written.',
+  rates: 'Usage: lazyclaw rates <list [--filter <substr>] [--limit <N>] | set <provider/model> --input <N> --output <N> [--cache-read <N>] [--cache-create <N>] [--currency USD] | delete <key> | shape | validate | copy <src> <dst> [--force]>\n  Rates are per million tokens. costFromUsage uses cfg.rates to compute the cost block in /usage and body.cost.\n  `list` accepts --filter (case-insensitive key substring) and --limit (post-filter cap), same shape sessions/skills/workflows lists use.\n  `shape` prints the reference template (zero-filled) you can copy into config.\n  `validate` checks the cfg.rates shape: required fields, non-negative numbers, known providers (warn-only).\n  `copy` clones an existing card to a new key (use when a new model launches at the same price as an old one).',
+  sandbox: 'Usage: lazyclaw sandbox <list|test|add|use> [args]\n  list             show 6 backends (local, docker, ssh, singularity, modal, daytona)\n  test <kind>      run echo through the backend (or argv-shape check for remote)\n  add <name> --kind <kind> [--image|--host|--user|--workspace|--app|--confiner ...]\n  use <profile>    set the profile as cfg.sandbox.default',
+  auth: 'Usage: lazyclaw auth <list <provider> | add <provider> <key> [--label <name>] | remove <provider> <label> | use <provider> <label> | rotate <provider>>\n  Multiple keys per provider for rate-limit rotation. The active label is sent on every chat / agent call.\n  `rotate` advances the cursor to the next label; pair with a 429 hook for auto-failover.',
+  pairing: 'Usage: lazyclaw pairing <list | add <id> [--label <name>] | remove <id>>\n  Sender allowlist for the messaging surface. Inbound senders not on this list are rejected.\n  Sender ids are opaque per-channel: Slack member id, Discord user id, phone number for SMS, etc.',
+  nodes: 'Usage: lazyclaw nodes <list | register <id> [--platform macos|ios|android|web|cli] [--label <name>] | remove <id>>\n  Companion device registration table. CLI only — the actual mobile / menu-bar apps are out of scope here.\n  Platform is free-form lower-case; future surfaces (iOS / Android nodes) authenticate against the daemon using these ids.',
+  message: 'Usage: lazyclaw message <list | add <name> <webhook-url> [--kind slack|discord|generic] | remove <name> | send <name> <text>>\n  Outbound webhook messaging — Slack / Discord Incoming Webhooks. Auto-detects kind from the URL pattern.\n  send accepts a literal string, or `-` to read the body from stdin.',
+  workspace: 'Usage: lazyclaw workspace <list | init <name> | show <name> [<file>] | remove <name> | path <name>>\n  Workspace = a directory under <configDir>/workspaces/<name>/ containing AGENTS.md, SOUL.md, TOOLS.md.\n  When `chat` or `agent` is invoked with --workspace <name>, the three files are stitched into a single system prompt at the head of the conversation. Missing files are skipped silently.\n  init scaffolds the three files with short stubs you replace.\n  show prints the composed prompt; show <name> AGENTS.md (etc) prints just one file.',
+  browse: 'Usage: lazyclaw browse <url> [--max-bytes <N>] [--timeout-ms <N>] [--user-agent <ua>] [--meta]\n  Fetches the URL and emits Markdown on stdout. Pipes cleanly into `agent`:\n      lazyclaw browse https://example.com/docs | lazyclaw agent -\n  Strips <script>/<style>/<svg>/comments, prefers <main>/<article>, falls back to <body>.\n  --max-bytes caps the body read (default 2 MB) so a misconfigured upstream can\'t OOM the process.\n  --meta prints { url, title, bytes, truncated } as JSON to stderr alongside the markdown on stdout.',
+  cron: 'Usage: lazyclaw cron <list | add <name> "<cron-spec>" -- <cmd> ... | remove <name> | show <name> | sync | run <name>>\n  Schedule recurring agent runs. macOS uses launchd (~/Library/LaunchAgents/com.lazyclaw.<name>.plist); Linux / WSL uses the user crontab.\n  Cron spec is the standard 5-field form (minute hour dom month dow). Supports *, range a-b, list a,b,c, step */N.\n  add: pass the command after `--`. Typical use:\n      lazyclaw cron add daily-summary "0 9 * * 1-5" -- lazyclaw agent "Summarise today\'s TODOs"\n  list / show: read from cfg.cron[name] (config is the source of truth).\n  sync: re-installs every job in cfg.cron into the system scheduler — handy after a reinstall.\n  run: one-shot in-process execution of the named job; the OS scheduler does the same thing on its trigger.\n  Logs: ~/.lazyclaw/logs/cron-<name>.{out,err}.log (macOS launchd path).',
+  setup: 'Usage: lazyclaw setup [--skip-test] [--only <steps>] [--skip <steps>]\n  --only/--skip take a comma list of: provider verify channel workspace skill webhook orchestrator (e.g. --only channel re-runs just that step).\n  Hermes-style phased first-run wizard — get one clean chat working first,\n  then optionally add the rest. Walks through:\n    1. Provider + model + api-key (delegates to onboard --pick; ≥64k-context tip)\n    2. Verify the provider responds (1-token ping; --skip-test bypasses)\n    3. Optional channel / gateway (Slack / Telegram / Matrix / HTTP built in;\n       Discord / Email / Signal / Voice / WhatsApp via plugin packages)\n    4. Optional workspace init  (AGENTS.md / SOUL.md / TOOLS.md)\n    5. Optional skill bundle install from GitHub\n    6. Optional outbound webhook (Slack / Discord)\n    7. Optional multi-agent orchestration (planner + workers)\n  Each optional step takes Enter or "skip" to bypass. Re-runnable safely.\n  Also fires automatically on first run when `lazyclaw` is invoked with no config.',
+  dashboard: 'Usage: lazyclaw dashboard [--port <N>] [--no-open]\n  Launches the lazyclaw-only web UI on http://127.0.0.1:<port> (default 19600) and opens it in the default browser.\n  Wraps `lazyclaw daemon` + a static HTML; no Python / lazyclaude dashboard required.\n  See web/dashboard.html for the current tab set (v5: Chat / Sessions / Workflows / Skills / Providers / Rates / Metrics / Doctor / Config / Status / Agents / Teams / Tasks / Trainer / Recall / Sandbox / Channels).\n  --no-open keeps the browser closed (handy for SSH / headless / dev). The bound URL is always printed to stdout.',
+  orchestrator: 'Usage: lazyclaw orchestrator <status | set-planner <provider[:model]> | workers add <spec> | workers remove <spec> | workers set <spec,spec,...> | workers clear | set-max-subtasks <N> | clear>\n  Read/write cfg.orchestrator without editing config.json by hand.\n  status               — print {planner, workers, maxSubtasks} as JSON; lists registered providers for reference.\n  set-planner          — replace the planner spec ("provider" or "provider:model"). "orchestrator" itself is rejected (self-recursion).\n  workers add          — append a worker (idempotent — duplicates skipped).\n  workers remove       — drop a worker by exact match. Idempotent.\n  workers set          — replace the whole list (comma-separated specs).\n  workers clear        — empty the workers list.\n  set-max-subtasks <N> — cap subtasks per request, clamped 1..10 (default 5).\n  clear                — delete the cfg.orchestrator block entirely.\n  Pair with: `lazyclaw config set provider orchestrator` to route chats through it.',
+};

package/commands/setup.mjs

@@ -25,6 +25,7 @@ import { dispatchSlash as _dispatchSlash, parseSlashLine as _parseSlashLine } fr
 import { SLASH_COMMANDS } from '../tui/slash_commands.mjs';
 import { runChannelStep, runWebhookStep, runOrchestratorStep, runContextStep } from './setup_channels.mjs';
 import { splashPropsForSetup, renderSplashToString } from '../tui/splash_props.mjs';
+import { HELP_SUMMARIES, HELP_DETAILS } from './help_text.mjs';
 
 function applyOnboardConfig(currentCfg, flags) {
   // Honors the OpenClaw-style unified provider/model string ("anthropic/claude-opus-4-7")
@@ -97,79 +98,6 @@ export async function cmdOnboard(flags) {
 
 
 
-// One-line summaries used by `lazyclaw help`. Format keeps it scan-friendly
-// in a 80-column terminal: subcommand padded to 12 chars, then the summary.
-const HELP_SUMMARIES = {
-  run:        'Execute a workflow file (run <session-id> <workflow.mjs>)',
-  resume:     'Resume a workflow from its last persisted checkpoint',
-  config:     'Manage local config (get|set|list|delete <key>)',
-  chat:       'Interactive REPL with the configured provider',
-  agent:      'One-shot prompt: streams a single response, exits',
-  doctor:     'Print diagnostic JSON; exits non-zero on issues',
-  status:     'Print current provider/model/masked key as JSON',
-  onboard:    'Guided setup (use --non-interactive for scripts)',
-  sessions:   'Persistent chat sessions (list|show|clear|export)',
-  skills:     'Markdown skill bundles (list|show|install|remove)',
-  providers:  'Inspect / register providers (list|info|test|add|remove|models)',
-  daemon:     'Run the local HTTP gateway (--port, --auth-token, --allow-origin)',
-  version:    'Print VERSION + node + platform as JSON',
-  completion: 'Emit shell completion script (completion <bash|zsh>)',
-  export:     'Dump config + skills (+ optional sessions) as a JSON bundle',
-  import:     'Apply a JSON bundle from stdin or --from <path>',
-  rates:      'Manage cost rate-cards in config (rates list|set <provider/model>|delete|shape)',
-  auth:       'Multiple keys per provider (auth list|add|remove|use|rotate <provider>)',
-  pairing:    'Sender allowlist for the messaging surface (pairing list|add|remove <id>)',
-  nodes:      'Companion device registration (nodes list|register|remove <id>)',
-  message:    'Outbound webhook messaging (message list|add|remove|send <name>)',
-  workspace:  'AGENTS.md / SOUL.md / TOOLS.md system-prompt convention (workspace list|init|show|remove|path)',
-  browse:     'Fetch a URL and emit Markdown on stdout (browse <url> [--max-bytes <N>])',
-  cron:       'Schedule recurring agent runs via launchd / crontab (cron list|add|remove|show|sync|run)',
-  setup:      'Hermes-style phased first-run wizard (provider + verify chat + channel + workspace + skill + webhook)',
-  dashboard:  'Launch the lazyclaw-only web UI (lighter than the full lazyclaude dashboard)',
-  inspect:    'Print persisted workflow state without executing',
-  clear:      'Delete a persisted workflow state file (idempotent)',
-  validate:   'Static-check a workflow file: shape, deps, cycles, parallelism',
-  graph:      'Emit workflow DAG as Mermaid syntax (paste-ready for docs)',
-  orchestrator: 'Multi-agent dispatch — planner decomposes, workers run, planner synthesises',
-};
-
-// Detailed usage per subcommand for `lazyclaw help <name>`. Kept as flat
-// strings so the help output is identical in every terminal.
-const HELP_DETAILS = {
-  run: 'Usage: lazyclaw run <session-id> <workflow.mjs> [--parallel | --parallel-persistent] [--concurrency <N>]\n  Default: runPersistent — sequential, persists state, resumable via `lazyclaw resume`.\n  --parallel: runParallel — topological-level DAG, in-memory only, NOT resumable.\n  --parallel-persistent: runPersistentDag — DAG + checkpoint + resume.\n  --concurrency <N>: cap in-flight nodes within a level (DAG modes only). 0/missing → unbounded.\n  Workflow file exports `nodes`; deps: string[] declares dependencies for both DAG modes.',
-  resume: 'Usage: lazyclaw resume <session-id> <workflow.mjs> [--parallel-persistent] [--concurrency <N>]\n  Re-enters a previously persisted run; succeeds nodes are skipped.\n  Pass --parallel-persistent to resume a DAG run (must match the original run\'s mode).\n  --concurrency <N>: cap in-flight nodes per level (DAG mode only).',
-  inspect: 'Usage: lazyclaw inspect [<session-id>] [--dir <state-dir>] [--status done|resumable|failed|running] [--summary] [--filter <substr>] [--limit <N>] [--node <node-id>] [--slowest <N>] [--critical-path <workflow.mjs>] [--aggregate]\n  With no session-id: list every persisted session in the state dir, sorted by recency.\n  --aggregate (list mode): per-node stats across all sessions (count, success/failed/pending/running, min/max/avg/total duration).\n  --status filters the listing to a single lifecycle bucket.\n  --filter / --limit refine list-mode further (case-insensitive sessionId substring + post-filter cap).\n  --summary trims per-node detail in single-session mode (matches list-mode shape).\n  --node <id>: print just that node\'s state. Exit 0 success/pending/running, 1 failed, 2 no such node.\n  --slowest <N>: top N nodes by durationMs (descending, ties broken by id).\n  --critical-path <workflow.mjs>: longest-weighted-path analysis using each node\'s recorded durationMs (bottleneck finder).\n  With a session-id (no per-node flag): print full state. Exit code: 0=resumable, 1=fully done, 2=no state, 3=terminal failure.',
-  clear: 'Usage: lazyclaw clear <session-id> [--dir <state-dir>]\n  Delete the state file for <session-id>. Idempotent — exits 0 whether the file existed or not.\n  Refuses sessionIds that resolve outside <state-dir>. Mirrors DELETE /workflows/<id> on the daemon.',
-  validate: 'Usage: lazyclaw validate <workflow.mjs>\n  Static check: load + shape + dep + cycle + parallelism estimate.\n  Exit 0 valid · 1 hard failure (issues populated) · 2 file/import error.',
-  graph: 'Usage: lazyclaw graph <workflow.mjs> [--lr] [--state <session-id>] [--dir <state-dir>]\n  Emit the workflow DAG as Mermaid syntax (graph TD by default; --lr for left-right).\n  --state overlays a persisted run\'s status (success ✓ / running ⏳ / failed ✗ / pending) with classDef styling.\n  Output is paste-ready for GitHub markdown / Notion / Obsidian.',
-  config: 'Usage: lazyclaw config <get|set|list|delete|path|edit|validate> [key] [value]\n  Local key-value config at $LAZYCLAW_CONFIG_DIR/config.json (default ~/.lazyclaw).\n  `path` prints the file location; `edit` opens it in $EDITOR (or $LAZYCLAW_EDITOR / $VISUAL / vi) and validates JSON on save.\n  `validate` checks the structural integrity of the whole config file (typed values, known providers, rate-card shape).',
-  chat: 'Usage: lazyclaw chat [--session <id>] [--skill name1,name2] [--workspace <name>] [--pick] [--sandbox docker:<image>] [--sandbox-network <net>] [--sandbox-mount <m>] [--sandbox-env <e>]\n  --session persists turns to <configDir>/sessions/<id>.jsonl across invocations.\n  --skill composes named skills into a system message at the head of the conversation.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md from <configDir>/workspaces/<name>/ into the system prompt.\n  --pick opens an interactive provider/model picker before the prompt (also auto-fires on first run).\n  --sandbox routes the underlying claude CLI through `docker run --rm -i --network <net> -v cwd:cwd ...` (default --network=none).',
-  agent: 'Usage: lazyclaw agent <prompt|-> [--provider X] [--model Y] [--skill list] [--workspace <name>] [--thinking N] [--show-thinking] [--usage] [--cost] [--sandbox docker:<image>]\n  One-shot non-interactive call. Pass "-" as the prompt to read from stdin.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md into the system prompt (combines with --skill).\n  --usage prints normalized {inputTokens, outputTokens, ...} to stderr after the response.\n  --cost adds a cost line on stderr when config.rates has a card for the active provider/model.\n  --sandbox docker:<image> wraps the subprocess provider (claude-cli) in a Docker container; --sandbox-network defaults to none.',
-  doctor: 'Usage: lazyclaw doctor\n  Validates configuration and registered providers. Exits 0 only when no issues.',
-  status: 'Usage: lazyclaw status\n  Provider, model, and masked API key. Never prints the raw key.',
-  onboard: 'Usage: lazyclaw onboard [--non-interactive] [--provider X] [--model Y] [--api-key Z]\n  --model accepts the unified "provider/model" string (e.g. anthropic/claude-opus-4-7).',
-  sessions: 'Usage: lazyclaw sessions <list [--filter <substr>] [--limit <N>]|show <id>|clear <id>|export <id> [--format md|json|text]|search <query> [--regex]>\n  list — recent sessions by mtime; --filter caps to ids containing substring (case-insensitive); --limit caps result count.\n  export — render in chosen format (md default for human sharing, json for tooling, text for paste).\n  search — case-insensitive substring (or --regex pattern) match across all session content; returns first excerpt + match count per matching session.',
-  skills: 'Usage: lazyclaw skills <list [--filter <substr>] [--limit <N>]|show <name>|install <user/repo[@ref][:path]> [--prefix <p>] [--force] | install <name> [--from <path> | --from-url <https://...>]|remove <name>|search <query> [--regex]>\n  list — installed skills; --filter caps to names containing substring (case-insensitive); --limit caps result count.\n  install <user>/<repo>[@<ref>][:<subpath>] — fetch a GitHub tarball, install every .md under skills/ (or the explicit subpath, or repo root). Default ref is `main`.\n    --prefix prepends a name prefix so a multi-skill repo doesn\'t collide with locally-managed skills. --force overwrites existing names.\n  install <name> --from <path> | --from-url <https://...> — single-file install. --from-url is HTTPS-only with a 1 MiB cap.\n  search — case-insensitive substring (or --regex) match across all skill markdown bodies; returns first excerpt + match count per skill.',
-  providers: 'Usage: lazyclaw providers <list [--filter <substr>] [--limit <N>] | info <name> | test <name> [--model X] [--prompt T] | test [--all] [--prompt T] | add <name> --base-url <url> [--api-key <k>] [--default-model <id>] [--no-probe] | remove <name> | models <name> [--filter <substr>]>\n  list   — registered providers (--filter case-insensitive name substring; --limit caps post-filter count).\n  info   — static metadata: requiresApiKey, defaultModel, suggestedModels, endpoint.\n  test   — send a 1-token "ping" through the provider and report ok/error + duration.\n           Useful after configuring an API key to verify it works before relying on it.\n           No name OR --all: tests every registered provider in parallel; exits 0 only when ALL pass.\n  add    — register a custom OpenAI-compatible endpoint (NIM / OpenRouter / Together / Groq / vLLM / LM Studio / …).\n           Probes /v1/models on success unless --no-probe is set; persists to cfg.customProviders[].\n  remove — drop a custom provider entry from cfg.customProviders[].\n  models — fetch + print the live model catalogue from <provider>/v1/models (works for openai / ollama / custom).',
-  daemon: 'Usage: lazyclaw daemon [--port <N>] [--once] [--auth-token <token>] [--allow-origin <origin>] [--rate-limit <N>] [--response-cache] [--log <level>] [--shutdown-timeout-ms <N>] [--cost-cap-<currency> <N> ...] [--workflow-state-dir <dir>]\n  Always binds 127.0.0.1. --port 0 picks a random port and prints the URL.\n  --auth-token also reads $LAZYCLAW_AUTH_TOKEN; --allow-origin also reads $LAZYCLAW_ALLOW_ORIGINS.\n  --rate-limit <N> caps each remote IP at N requests / 60 s.\n  --response-cache enables process-scoped memoization; per-request opt-in via body.cache.\n  --log <debug|info|warn|error> emits JSON-line access logs on stderr (also reads $LAZYCLAW_LOG_LEVEL).\n  --shutdown-timeout-ms <N> caps graceful drain on SIGINT/SIGTERM (default 10000). Second signal forces immediate exit.\n  --cost-cap-usd 100 (or any currency code in lowercase) rejects POST /agent + /chat with 402 once cumulative cost reaches the cap.\n  --workflow-state-dir <dir> backs GET /workflows + GET /workflows/<id> (default .workflow-state, also reads $LAZYCLAW_WORKFLOW_STATE_DIR).',
-  version: 'Usage: lazyclaw version\n  Aliases: --version, -v.',
-  completion: 'Usage: lazyclaw completion <bash|zsh>\n  bash:   eval "$(lazyclaw completion bash)"\n  zsh:    lazyclaw completion zsh > "${fpath[1]}/_lazyclaw"',
-  export: 'Usage: lazyclaw export [--include-secrets] [--include-sessions] > bundle.json\n  --include-secrets keeps the raw api-key in the bundle (default redacts it).\n  --include-sessions adds full turn content (default keeps metadata only).',
-  import: 'Usage: lazyclaw import [--from <path>] [--overwrite-skills] [--no-overwrite-config] [--import-sessions]\n  Reads JSON from stdin (or --from <path>). Sessions are NEVER overwritten.\n  Redacted api-keys (***REDACTED***) are dropped, never written.',
-  rates: 'Usage: lazyclaw rates <list [--filter <substr>] [--limit <N>] | set <provider/model> --input <N> --output <N> [--cache-read <N>] [--cache-create <N>] [--currency USD] | delete <key> | shape | validate | copy <src> <dst> [--force]>\n  Rates are per million tokens. costFromUsage uses cfg.rates to compute the cost block in /usage and body.cost.\n  `list` accepts --filter (case-insensitive key substring) and --limit (post-filter cap), same shape sessions/skills/workflows lists use.\n  `shape` prints the reference template (zero-filled) you can copy into config.\n  `validate` checks the cfg.rates shape: required fields, non-negative numbers, known providers (warn-only).\n  `copy` clones an existing card to a new key (use when a new model launches at the same price as an old one).',
-  sandbox: 'Usage: lazyclaw sandbox <list|test|add|use> [args]\n  list             show 6 backends (local, docker, ssh, singularity, modal, daytona)\n  test <kind>      run echo through the backend (or argv-shape check for remote)\n  add <name> --kind <kind> [--image|--host|--user|--workspace|--app|--confiner ...]\n  use <profile>    set the profile as cfg.sandbox.default',
-  auth: 'Usage: lazyclaw auth <list <provider> | add <provider> <key> [--label <name>] | remove <provider> <label> | use <provider> <label> | rotate <provider>>\n  Multiple keys per provider for rate-limit rotation. The active label is sent on every chat / agent call.\n  `rotate` advances the cursor to the next label; pair with a 429 hook for auto-failover.',
-  pairing: 'Usage: lazyclaw pairing <list | add <id> [--label <name>] | remove <id>>\n  Sender allowlist for the messaging surface. Inbound senders not on this list are rejected.\n  Sender ids are opaque per-channel: Slack member id, Discord user id, phone number for SMS, etc.',
-  nodes: 'Usage: lazyclaw nodes <list | register <id> [--platform macos|ios|android|web|cli] [--label <name>] | remove <id>>\n  Companion device registration table. CLI only — the actual mobile / menu-bar apps are out of scope here.\n  Platform is free-form lower-case; future surfaces (iOS / Android nodes) authenticate against the daemon using these ids.',
-  message: 'Usage: lazyclaw message <list | add <name> <webhook-url> [--kind slack|discord|generic] | remove <name> | send <name> <text>>\n  Outbound webhook messaging — Slack / Discord Incoming Webhooks. Auto-detects kind from the URL pattern.\n  send accepts a literal string, or `-` to read the body from stdin.',
-  workspace: 'Usage: lazyclaw workspace <list | init <name> | show <name> [<file>] | remove <name> | path <name>>\n  Workspace = a directory under <configDir>/workspaces/<name>/ containing AGENTS.md, SOUL.md, TOOLS.md.\n  When `chat` or `agent` is invoked with --workspace <name>, the three files are stitched into a single system prompt at the head of the conversation. Missing files are skipped silently.\n  init scaffolds the three files with short stubs you replace.\n  show prints the composed prompt; show <name> AGENTS.md (etc) prints just one file.',
-  browse: 'Usage: lazyclaw browse <url> [--max-bytes <N>] [--timeout-ms <N>] [--user-agent <ua>] [--meta]\n  Fetches the URL and emits Markdown on stdout. Pipes cleanly into `agent`:\n      lazyclaw browse https://example.com/docs | lazyclaw agent -\n  Strips <script>/<style>/<svg>/comments, prefers <main>/<article>, falls back to <body>.\n  --max-bytes caps the body read (default 2 MB) so a misconfigured upstream can\'t OOM the process.\n  --meta prints { url, title, bytes, truncated } as JSON to stderr alongside the markdown on stdout.',
-  cron: 'Usage: lazyclaw cron <list | add <name> "<cron-spec>" -- <cmd> ... | remove <name> | show <name> | sync | run <name>>\n  Schedule recurring agent runs. macOS uses launchd (~/Library/LaunchAgents/com.lazyclaw.<name>.plist); Linux / WSL uses the user crontab.\n  Cron spec is the standard 5-field form (minute hour dom month dow). Supports *, range a-b, list a,b,c, step */N.\n  add: pass the command after `--`. Typical use:\n      lazyclaw cron add daily-summary "0 9 * * 1-5" -- lazyclaw agent "Summarise today\'s TODOs"\n  list / show: read from cfg.cron[name] (config is the source of truth).\n  sync: re-installs every job in cfg.cron into the system scheduler — handy after a reinstall.\n  run: one-shot in-process execution of the named job; the OS scheduler does the same thing on its trigger.\n  Logs: ~/.lazyclaw/logs/cron-<name>.{out,err}.log (macOS launchd path).',
-  setup: 'Usage: lazyclaw setup [--skip-test] [--only <steps>] [--skip <steps>]\n  --only/--skip take a comma list of: provider verify channel workspace skill webhook orchestrator (e.g. --only channel re-runs just that step).\n  Hermes-style phased first-run wizard — get one clean chat working first,\n  then optionally add the rest. Walks through:\n    1. Provider + model + api-key (delegates to onboard --pick; ≥64k-context tip)\n    2. Verify the provider responds (1-token ping; --skip-test bypasses)\n    3. Optional channel / gateway (Slack / Telegram / Matrix / HTTP built in;\n       Discord / Email / Signal / Voice / WhatsApp via plugin packages)\n    4. Optional workspace init  (AGENTS.md / SOUL.md / TOOLS.md)\n    5. Optional skill bundle install from GitHub\n    6. Optional outbound webhook (Slack / Discord)\n    7. Optional multi-agent orchestration (planner + workers)\n  Each optional step takes Enter or "skip" to bypass. Re-runnable safely.\n  Also fires automatically on first run when `lazyclaw` is invoked with no config.',
-  dashboard: 'Usage: lazyclaw dashboard [--port <N>] [--no-open]\n  Launches the lazyclaw-only web UI on http://127.0.0.1:<port> (default 19600) and opens it in the default browser.\n  Wraps `lazyclaw daemon` + a static HTML; no Python / lazyclaude dashboard required.\n  See web/dashboard.html for the current tab set (v5: Chat / Sessions / Workflows / Skills / Providers / Rates / Metrics / Doctor / Config / Status / Agents / Teams / Tasks / Trainer / Recall / Sandbox / Channels).\n  --no-open keeps the browser closed (handy for SSH / headless / dev). The bound URL is always printed to stdout.',
-  orchestrator: 'Usage: lazyclaw orchestrator <status | set-planner <provider[:model]> | workers add <spec> | workers remove <spec> | workers set <spec,spec,...> | workers clear | set-max-subtasks <N> | clear>\n  Read/write cfg.orchestrator without editing config.json by hand.\n  status               — print {planner, workers, maxSubtasks} as JSON; lists registered providers for reference.\n  set-planner          — replace the planner spec ("provider" or "provider:model"). "orchestrator" itself is rejected (self-recursion).\n  workers add          — append a worker (idempotent — duplicates skipped).\n  workers remove       — drop a worker by exact match. Idempotent.\n  workers set          — replace the whole list (comma-separated specs).\n  workers clear        — empty the workers list.\n  set-max-subtasks <N> — cap subtasks per request, clamped 1..10 (default 5).\n  clear                — delete the cfg.orchestrator block entirely.\n  Pair with: `lazyclaw config set provider orchestrator` to route chats through it.',
-};
-
 export function cmdHelp(name) {
   if (!name) {
     process.stdout.write('lazyclaw — terminal AI assistant + workflow engine\n\n');

package/daemon/lib/cost.mjs

@@ -26,6 +26,11 @@ export function accumulateMetricsFromCost(metrics, usage, cost) {
   if (usage) {
     if (Number.isFinite(usage.inputTokens)) metrics.tokensTotal.inputTokens += usage.inputTokens;
     if (Number.isFinite(usage.outputTokens)) metrics.tokensTotal.outputTokens += usage.outputTokens;
+    // inputTokens is reported NET of cache by the providers, so the cache
+    // buckets would otherwise go uncounted. Track them separately to keep the
+    // token totals complete (this is metrics-only — cost math is unchanged).
+    if (Number.isFinite(usage.cacheReadInputTokens)) metrics.tokensTotal.cacheReadInputTokens += usage.cacheReadInputTokens;
+    if (Number.isFinite(usage.cacheCreationInputTokens)) metrics.tokensTotal.cacheCreationInputTokens += usage.cacheCreationInputTokens;
   }
 }
 

package/daemon/route_table.mjs

@@ -28,6 +28,7 @@ export const ROUTES = [
   { m: (c) => c.route === 'GET /dashboard.css', h: meta.dashboardCss },
   { m: (c) => c.route === 'GET /dashboard.js', h: meta.dashboardJs },
   { m: (c) => c.req.method === 'GET' && /^\/avatars\/\d{2}\.png$/.test(c.path || ''), h: meta.avatar },
+  { m: (c) => c.req.method === 'GET' && /^\/agent-avatars\/[A-Za-z0-9_-]+\.[a-z]+$/.test(c.path || ''), h: meta.agentAvatar },
   { m: (c) => c.route === 'GET /version', h: meta.version },
   { m: (c) => c.route === 'POST /exec/request', h: conversation.execRequest },
   { m: (c) => c.route === 'GET /health' || c.route === 'GET /healthz', h: meta.health },

package/daemon/routes/meta.mjs

@@ -65,6 +65,35 @@ export async function dashboardJs(c) {
   return serveWebFile(c, 'dashboard.js', 'text/javascript; charset=utf-8');
 }
 
+// Serve a custom agent character image (web app: <img src="/agent-avatars/NN">).
+// These are user-supplied photos copied under <configDir>/agent-avatars/ by
+// `lazyclaw agent set-avatar`. Served from the config dir (NOT the package web/
+// dir) since they're per-install user data. The filename is constrained to
+// `<word>.<ext>` so no path traversal escapes the agent-avatars directory.
+const _AGENT_AVATAR_CT = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp',
+};
+export async function agentAvatar(c) {
+  const { res } = c;
+  const m = /^\/agent-avatars\/([A-Za-z0-9_-]+\.[a-z]+)$/.exec(c.path || '');
+  const file = m && m[1];
+  const ct = file && _AGENT_AVATAR_CT[nodePath.extname(file).toLowerCase()];
+  const base = c.gwConfigDir;
+  if (!file || file.includes('..') || !ct || !base) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    return res.end('not found\n');
+  }
+  try {
+    const body = _readAssetCached(nodePath.join(base, 'agent-avatars', file));
+    res.writeHead(200, { 'content-type': ct, '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: ${file} (${e?.message || e})\n`);
+  }
+}
+
 export async function dashboard(c) {
   const { res } = c;
           // Serve the lazyclaw-only web dashboard (a single static

package/daemon.mjs

@@ -102,7 +102,7 @@ export function makeHandler(ctx) {
     // EUR-priced regional contract) doesn't silently sum mismatched
     // numbers. Tokens are unit-free so we keep them in a single counter.
     costsByCurrency: /** @type {Record<string, number>} */({}),
-    tokensTotal: { inputTokens: 0, outputTokens: 0 },
+    tokensTotal: { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, cacheCreationInputTokens: 0 },
   };
   // Device gateway (Phase 27). The ChallengeRegistry is a per-process
   // singleton: a challenge minted by one request is consumed by a later

package/lib/args.mjs

@@ -277,6 +277,6 @@ _lazyclaw "$@"
 // AGENT_REG_SUBS to decide whether a bare `agent <sub>` routes to the agent
 // registry vs a one-shot agent run. TEAM_SUBS/TASK_SUBS mirror their command's
 // subcommands for the same disambiguation pattern.
-export const AGENT_REG_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete', 'memory', 'reflect', 'skill-synth']);
+export const AGENT_REG_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete', 'memory', 'reflect', 'skill-synth', 'set-avatar']);
 export const TEAM_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete']);
 export const TASK_SUBS = new Set(['start', 'tick', 'list', 'show', 'abandon', 'done', 'transcript', 'remove', 'rm', 'delete']);

package/mas/agent_turn.mjs

@@ -204,6 +204,13 @@ export async function runAgentTurn({
     iterations++;
     const resp = await adapter.callOnce({
       messages, tools, model: agent.model, apiKey, system: systemPrompt,
+      // Forward-compat: thread an explicit per-agent output cap when the agent
+      // record carries one. No current config/setup path populates
+      // agent.maxTokens / agent.maxOutputTokens, so this is `undefined` today —
+      // each adapter then falls back to its own DEFAULT (anthropic/openai) or
+      // leaves the cap unset (gemini), keeping existing turns byte-stable. When
+      // a future config does set it, the cap reaches gemini (FIX D) too.
+      maxTokens: agent.maxTokens ?? agent.maxOutputTokens,
       fetchImpl, baseUrl, signal, cache,
     });
     if (resp.text) lastText = resp.text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "6.4.0",
+  "version": "6.6.0",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama, orchestrating multi-step LLM workflows, and running multi-agent Slack teams with cross-task memory. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",

package/providers/claude_cli.mjs

@@ -179,7 +179,7 @@ export const claudeCliProvider = {
         });
         let yielded = false;
         try {
-          for await (const chunk of session.send(String(last.content), { signal: opts.signal, onUsage: opts.onUsage })) {
+          for await (const chunk of session.send(String(last.content), { signal: opts.signal, onUsage: opts.onUsage, onTruncated: opts.onTruncated })) {
             yielded = true;
             yield chunk;
           }

package/providers/claude_cli_session.mjs

@@ -78,12 +78,15 @@ class ClaudeSession {
   }
 
   // Stream one turn. Yields text deltas until the matching `result` event.
-  async *send(userText, { signal, onUsage } = {}) {
+  async *send(userText, { signal, onUsage, onTruncated } = {}) {
     if (this.busy) throw new Error('claude session busy — sends must be serialised per session');
     if (!this.alive) throw new Error('claude session is not alive');
     this.busy = true;
     this._touch();
 
+    // Per-turn usage accumulated from `assistant` events (incl. cache fields);
+    // falls back to the result event's usage if no assistant event was seen.
+    const u = { input: 0, output: 0, cacheCreate: 0, cacheRead: 0, saw: false };
     const queue = [];
     let done = false;
     let error = null;
@@ -100,16 +103,30 @@ class ClaudeSession {
         try { obj = JSON.parse(line); } catch { continue; }
         const t = extractTextDelta(obj);
         if (t) { queue.push(t); if (wake) wake(); }
+        if (obj.type === 'assistant' && obj.message && obj.message.usage) {
+          const mu = obj.message.usage;
+          u.input += mu.input_tokens || 0;
+          u.output += mu.output_tokens || 0;
+          u.cacheCreate += mu.cache_creation_input_tokens || 0;
+          u.cacheRead += mu.cache_read_input_tokens || 0;
+          u.saw = true;
+        }
         if (obj.type === 'result') {
-          if (typeof onUsage === 'function' && obj.usage) {
+          if (typeof onUsage === 'function') {
+            const ru = obj.usage || {};
             try {
               onUsage({
-                inputTokens: obj.usage.input_tokens || 0,
-                outputTokens: obj.usage.output_tokens || 0,
+                inputTokens: u.saw ? u.input : (ru.input_tokens || 0),
+                outputTokens: u.saw ? u.output : (ru.output_tokens || 0),
+                cacheCreationInputTokens: u.saw ? u.cacheCreate : (ru.cache_creation_input_tokens || 0),
+                cacheReadInputTokens: u.saw ? u.cacheRead : (ru.cache_read_input_tokens || 0),
                 totalCostUsd: obj.total_cost_usd || 0,
               });
             } catch { /* never fail a turn on a usage callback */ }
           }
+          if (typeof onTruncated === 'function' && obj.is_error && /max_turns/.test(String(obj.subtype || ''))) {
+            try { onTruncated('max_turns'); } catch { /* ditto */ }
+          }
           done = true; if (wake) wake();
         }
       }

package/providers/codex_cli.mjs

@@ -140,15 +140,18 @@ function extractUsage(obj) {
   // OpenAI Responses-API convention (codex follows it): input_tokens already
   // INCLUDES cached_input_tokens, and output_tokens already INCLUDES
   // reasoning_output_tokens — they are subset breakdowns, not additive. Summing
-  // them double-counts and trips the cost cap early. Report the totals and
-  // surface cached input separately so it can bill at the cache-read rate.
-  const input = u.input_tokens ?? 0;
+  // them double-counts and trips the cost cap early. Report NET (non-cached)
+  // input — total minus the cached subset — to match Anthropic's convention so
+  // rates.mjs's single cost formula doesn't bill the cached tokens at BOTH the
+  // input rate and the cache-read rate. Surface the cached subset separately.
+  const cacheRead = u.cached_input_tokens ?? 0;
+  const input = (u.input_tokens ?? 0) - cacheRead;
   const output = u.output_tokens ?? 0;
-  if (!input && !output) return null;
+  if (!input && !output && !cacheRead) return null;
   return {
     inputTokens: input,
     outputTokens: output,
-    cacheReadInputTokens: u.cached_input_tokens ?? 0,
+    cacheReadInputTokens: cacheRead,
     totalCostUsd: 0,
   };
 }

package/providers/gemini.mjs

@@ -268,7 +268,10 @@ export const geminiProvider = {
     if (lastUsage && typeof opts.onUsage === 'function') {
       try {
         opts.onUsage({
-          inputTokens: lastUsage.promptTokenCount ?? null,
+          // promptTokenCount is cache-INCLUSIVE; report NET (minus cached) to
+          // match Anthropic's convention so rates.mjs doesn't bill the cached
+          // tokens at BOTH the input rate and the cache-read rate.
+          inputTokens: (lastUsage.promptTokenCount ?? 0) - (lastUsage.cachedContentTokenCount ?? 0),
           outputTokens: lastUsage.candidatesTokenCount ?? null,
           cacheReadInputTokens: lastUsage.cachedContentTokenCount ?? 0,
           totalCostUsd: 0,

package/providers/gemini_cli.mjs

@@ -103,13 +103,17 @@ function extractUsage(stats) {
   let input = 0, output = 0, cached = 0;
   for (const m of Object.values(models)) {
     const t = m?.tokens || {};
-    input  += (t.prompt ?? t.input ?? 0);
+    // cached is a subset of prompt → report NET (prompt minus cached) so it
+    // matches Anthropic's convention and rates.mjs doesn't bill the cached
+    // tokens at BOTH the input rate and the cache-read rate. Surface cached
+    // separately so it can still bill at the cache-read rate.
+    input  += (t.prompt ?? t.input ?? 0) - (t.cached ?? 0);
     // thoughts = reasoning tokens, billed as output and reported separately from
-    // candidates (additive). cached is a subset of prompt → surface, don't sum.
+    // candidates (additive).
     output += (t.candidates ?? t.output ?? 0) + (t.thoughts ?? 0);
     cached += (t.cached ?? 0);
   }
-  if (!input && !output) return null;
+  if (!input && !output && !cached) return null;
   return { inputTokens: input, outputTokens: output, cacheReadInputTokens: cached, totalCostUsd: 0 };
 }
 
@@ -217,6 +221,16 @@ export const geminiCliProvider = {
       // so surface it instead of silently yielding nothing.
       const text = typeof parsed.response === 'string' ? parsed.response : '';
       if (!text && parsed.error) {
+        // A failed turn is still METERED: gemini-cli puts the partial token
+        // usage in the SAME JSON's `stats` even when the turn errored out. Bill
+        // it BEFORE throwing so a failed-but-metered turn still reaches the cost
+        // cap (the error path used to throw before extractUsage ever ran, so a
+        // failed turn leaked its tokens past accounting). Guarded so a usage
+        // callback can never mask the real error.
+        const failedUsage = extractUsage(parsed.stats);
+        if (failedUsage && typeof opts.onUsage === 'function') {
+          try { opts.onUsage(failedUsage); } catch (_) { /* never let usage hide the error */ }
+        }
         const em = parsed.error?.message
           || (typeof parsed.error === 'string' ? parsed.error : JSON.stringify(parsed.error));
         throw new CliExitError(exitInfo.code, exitInfo.signal, em);

package/providers/tool_use/gemini.mjs

@@ -78,6 +78,7 @@ export async function callOnce({
   model,
   apiKey,
   system,
+  maxTokens,
   baseUrl,
   fetchImpl,
   signal,
@@ -97,6 +98,13 @@ export async function callOnce({
   if (system && String(system).trim()) {
     body.system_instruction = { parts: [{ text: String(system) }] };
   }
+  // Cap the output like the anthropic/openai adapters do. Gemini carries the
+  // ceiling on generationConfig.maxOutputTokens; merge so a caller that already
+  // populated generationConfig keeps their other fields. Only a finite,
+  // positive maxTokens applies — omitting it leaves generationConfig untouched.
+  if (Number.isFinite(maxTokens) && maxTokens > 0) {
+    body.generationConfig = { ...(body.generationConfig || {}), maxOutputTokens: maxTokens };
+  }
 
   const res = await fetchFn(url, {
     method: 'POST',
@@ -146,7 +154,10 @@ export function parseResponse(json) {
   const um = json?.usageMetadata;
   const usage = um
     ? {
-        inputTokens: um.promptTokenCount || 0,
+        // promptTokenCount is cache-INCLUSIVE; report NET (minus cached) to
+        // match Anthropic's convention so the cost cap doesn't bill the cached
+        // tokens at BOTH the input rate and the cache-read rate.
+        inputTokens: (um.promptTokenCount || 0) - (um.cachedContentTokenCount || 0),
         outputTokens: um.candidatesTokenCount || 0,
         cacheReadInputTokens: um.cachedContentTokenCount || 0,
       }

package/providers/tool_use/openai.mjs

@@ -131,6 +131,13 @@ export function parseResponse(json) {
       else { try { input = JSON.parse(a); } catch (e) { input = {}; parseError = `malformed tool arguments: ${e.message}`; } }
     } else if (a && typeof a === 'object') {
       input = a;
+    } else if (a !== undefined && a !== null) {
+      // arguments is present but neither a string nor an object (e.g. a number
+      // or boolean) — an unexpected wire shape. Surface it as a tool failure
+      // instead of silently running the tool with {} (mirrors the malformed
+      // JSON-string branch above).
+      input = {};
+      parseError = `unexpected tool arguments type: ${typeof a}`;
     }
     return { id: tc.id, name: tc?.function?.name, input, ...(parseError ? { parseError } : {}) };
   });