mixdog 0.9.4 → 0.9.6

package/README.md

@@ -1,84 +1,158 @@
 # mixdog
 
-Mixdog is a standalone coding-agent CLI/TUI workspace for developers who want
-one terminal experience across multiple LLM providers.
+Standalone coding-agent CLI/TUI for running a multi-provider AI workspace from
+one terminal.
 
-It combines an Ink-based terminal UI, a multi-provider runtime, workflow agents,
-MCP/plugin/skill loading, memory, web search, channel integrations, and focused
-repo tools for reading, editing, testing, and reviewing code.
+Mixdog combines an Ink-based terminal UI, model/provider routing, workflow
+agents, MCP/plugin/skill loading, memory, web search, channel integrations, and
+repo-focused tools for reading, editing, testing, and reviewing code.
 
 ## Highlights
 
-- Multi-provider model routing for Anthropic, OpenAI-compatible APIs, Google,
-  XAI/Grok, OAuth-backed providers, and local endpoints.
-- Full-screen TUI with slash commands, model/workflow pickers, provider setup,
-  usage dashboards, tool cards, statusline integration, and resumable sessions.
-- Agent task delegation through the `agent` tool and `/agent` command.
-- Focused repo tools for `read`, `grep`, `glob`, `list`, `code_graph`,
+- **Multi-provider model picker** for Anthropic, OpenAI, Google/Gemini, xAI/Grok,
+  DeepSeek, OpenCode Go, OAuth-backed providers, OpenAI-compatible APIs, Ollama,
+  and LM Studio/local endpoints.
+- **Live model catalog** from provider `/models` endpoints, enriched with
+  LiteLLM/models.dev metadata for context windows, output limits, pricing, tool
+  support, reasoning, web search, and recency.
+- **Full-screen TUI** with slash commands, provider setup, model/workflow
+  pickers, usage dashboards, statusline integration, resumable sessions, and
+  detailed tool cards.
+- **Workflow delegation** through `/agent` and the `agent` tool, including
+  worker, heavy-worker, reviewer, debugger, maintainer, and explorer roles.
+- **Repo-native tools** for `read`, `grep`, `glob`, `list`, `code_graph`,
   `apply_patch`, `shell`, `cwd`, `explore`, web search, and memory recall.
-- Workflow agents for implementation, review, debugging, maintenance, web
-  research, and heavier model routes.
-- Optional Discord/channel/webhook/schedule integrations for remote or event
-  driven workflows.
+- **Remote/event workflows** via optional Discord channel, webhook, schedule,
+  and channel-management integrations.
 
 ## Requirements
 
 - Node.js >= 22
 
-## Setup
+## Install
 
 ```bash
 npm install
 ```
 
-To install the CLI globally from this checkout:
+To install the `mixdog` command globally from this checkout:
 
 ```bash
 npm install -g .
 mixdog --help
 ```
 
-## Usage
+## Run
 
 ```bash
-# Run the TUI from any project directory
+# Start the TUI in the current project
 mixdog
 
-# Run the basic smoke test
-npm run smoke
+# Start with an explicit route
+mixdog --provider anthropic-oauth --model claude-haiku-4-5-20251001
 
-# Run the core smoke suite
-npm run smoke:all
+# Read-only tool surface
+mixdog --readonly
+
+# Enable remote/channel mode for this session
+mixdog --remote
+
+# Re-run first-run setup
+mixdog --onboarding
+```
+
+Headless role mode is also supported:
+
+```bash
+mixdog worker "fix the failing test"
+mixdog reviewer "review the current diff"
 ```
 
-Inside the TUI, use `/providers` to configure model access, `/model` to switch
-models, `/workflow` to select a workflow, `/agents` to inspect available
-workflow agents, and `/agent` to manage active agent tasks.
+## TUI basics
 
-## Project Layout
+Common slash commands:
+
+```text
+/help              show help
+/providers         configure provider auth and local endpoints
+/model             choose provider/model, effort, and fast mode
+/workflow          choose the active workflow
+/agents            show available workflow agents
+/agent             manage active agent tasks
+/mode              switch tool surface: full | readonly
+/compact           compact older conversation context
+/clear             reset the conversation and screen
+/OutputStyle       show or switch Lead output style
+```
+
+Use `/providers` first if no model is configured, then `/model` to pick the
+route. The model picker warms the provider catalog in the background and keeps
+Claude families such as Opus, Sonnet, Haiku, and Fable separate when filtering
+current Anthropic models.
+
+## Scripts
+
+```bash
+npm run smoke          # basic smoke check
+npm run smoke:all      # core smoke suite
+npm run smoke:tui      # TUI render smoke
+npm run smoke:tools    # tool smoke suite
+npm run build:tui      # build the bundled Ink TUI
+npm run audit:models   # inspect model catalog metadata
+```
+
+Additional diagnostics and benchmarks live under `scripts/`.
+
+## Data and configuration
+
+Mixdog uses `~/.mixdog` as its home root. Runtime data lives in
+`~/.mixdog/data` by default.
+
+```bash
+MIXDOG_HOME=/path/to/home mixdog
+MIXDOG_DATA_DIR=/path/to/data mixdog
+```
+
+Useful environment toggles:
+
+- `MIXDOG_TUI_MOUSE=0` — use terminal-native mouse behavior instead of the TUI
+  mouse/selection layer.
+- `MIXDOG_DISABLE_MODEL_PREFETCH=1` — disable background provider model prefetch.
+- `MIXDOG_PROVIDER_MODEL_WARMUP_DELAY_MS=<ms>` — tune model-catalog warmup delay.
+- `MIXDOG_MODEL_STALE_MONTHS=<months>` — tune catalog staleness filtering.
+
+## Project layout
 
 ```text
 src/
   cli.mjs        # CLI entry point (bin: mixdog)
-  app.mjs        # app wiring
-  repl.mjs       # plain REPL loop
-  runtime/       # provider runtime, tools, memory, channels
-  tui/           # canonical Ink TUI (bundled to dist/)
+  app.mjs        # CLI/TUI/headless mode wiring
+  help.mjs       # command help text
+  runtime/       # providers, tools, memory, channels, session runtime
+  session-runtime/
+                 # model routing, catalog rows, workflow/session helpers
+  tui/           # canonical Ink TUI
   agents/        # workflow agent definitions
+  workflows/     # workflow definitions
   rules/         # Lead and agent instructions
 scripts/
   smoke*.mjs     # smoke checks
+  *test.mjs      # focused node:test checks
   build-tui.mjs  # esbuild bundle for the React TUI
 vendor/
   ink/           # Mixdog Ink renderer
 ```
 
-## Data And Configuration
+## Published package contents
+
+The npm package is limited by `package.json#files` to:
 
-Standalone Mixdog uses `~/.mixdog` as its home root. Runtime data lives in
-`~/.mixdog/data` by default. Set `MIXDOG_HOME` to move the root, or
-`MIXDOG_DATA_DIR` to override only the data directory.
+```text
+README.md
+scripts/
+src/
+vendor/
+```
 
-The TUI uses alt-screen mode and app-owned mouse wheel scrolling / drag
-selection by default. Set `MIXDOG_TUI_MOUSE=0` to opt into terminal-native mouse
-behavior.
+`docs/` is not included in the published package unless `package.json#files` is
+changed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -26,6 +26,7 @@
   "files": [
     "README.md",
     "scripts/",
+    "!scripts/bench/cache-hit-*.json",
     "src/",
     "vendor/"
   ],
@@ -54,6 +55,7 @@
     "bench:corpus": "node scripts/routing-corpus.mjs",
     "bench:run": "node scripts/bench-run.mjs",
     "bench:recall": "node scripts/recall-bench.mjs",
+    "audit:models": "node scripts/model-catalog-audit.mjs",
     "patch:replay": "node scripts/patch-replay.mjs",
     "build:tui": "node scripts/build-tui.mjs"
   },
@@ -72,6 +74,7 @@
     "discord.js": "^14.26.4",
     "ink": "^7.1.0",
     "jsdom": "^26.1.0",
+    "kiwi-nlp": "^0.21.0",
     "marked": "^14.1.4",
     "node-cron": "^4.5.0",
     "openai": "^6.44.0",

package/scripts/bench/r5-orchestrated-task.json

@@ -0,0 +1,7 @@
+[
+  {
+    "id": "r5-orchestrated-audit",
+    "agent": "lead",
+    "prompt": "You are coordinating work in this repo. Task: audit and improve the provider retry story in two independent scopes, then verify. Scope A: analyze src/runtime/agent/orchestrator/providers/retry-classifier.mjs and how openai-oauth-ws.mjs consumes its classifiers - list every classifier bucket, which are actually reachable, and any bucket that no code path can produce. Scope B: analyze the handshake retry loop in openai-oauth-ws.mjs (_acquireWithRetry) and the midstream retry loop (sendViaWebSocket) - document their budgets, backoff, and whether any error class can double-retry across both layers. These scopes are independent: delegate them to separate workers in parallel, then have the results cross-checked, and produce a single merged report with file:line evidence. Do NOT edit any files - analysis only. The final report is the deliverable."
+  }
+]