AgentUse v0.17.0: model aliases, agentuse test, and learnings that graduate

AgentUse v0.17.0 is on npm. It closes three gaps that show up once you run agents for real: model ids that rot, agents you can't safely test, and corrections that pile up without ever sticking. It also makes agentuse serve survive restarts without killing the work in flight.

npm install -g agentuse@latest

Name a model line, not a version

Leave the version off a model id and the agent follows the newest release in that line:

model: anthropic:claude-sonnet

A new model release no longer means editing every .agentuse file. Aliases resolve at parse time, so session logs and cost accounting always record the concrete model that ran, and a suspended run resumes on the model it started with, never a different one mid-conversation. A real model id always wins over an alias, so nothing you pin can be reinterpreted.

You can also name your own models in ~/.agentuse/config.json and repoint a whole fleet with one edit:

{
  "models": {
    "aliases": { "fast": "anthropic:claude-haiku" },
    "default": "anthropic:claude-sonnet"
  }
}

Reference them as model: "@fast", or set models.default and skip model: entirely. An alias can even define ordered fallback candidates with a cooldown, so a provider outage or missing login fails over to the next model instead of failing the run.

For files you already have, agentuse models unpin swaps pinned versions for aliases, and agentuse models bump moves stale pins forward. Both take a directory and support --dry-run. Full details in the model configuration guide.

agentuse test: validate an agent without real side effects

agentuse test <file> runs an agent end-to-end with side effects fabricated, approval gates auto-resolved, and stores isolated, so a test loop can run unattended with zero irreversible actions.

How much gets fabricated is controlled by --scope, and the default is picked from the agent itself. An agent that declares tools.bash.gated patterns gets gated scope: only those fenced-off commands are fabricated, and everything else, file reads, non-gated bash, MCP tools, skills, runs for real. That's the useful middle ground: the test grounds itself in your real project state, but the commands you marked as consequential never actually fire. An agent with no gated patterns gets full mock, where every side effect is fabricated. Force either mode with --scope gated or --scope all (or AGENTUSE_MOCK_SCOPE for a whole environment).

Approvals are testable the same way: --approval reject and --approval comment:<text> exercise the other branches of a gate, and the session log records the full gate flow, so every branch is reviewable afterwards. Gate enforcement stays real too: a gated command issued without an approved gate is still denied, even in a test. Mock runs are marked everywhere, excluded from dashboards by default, and never touch real agent memory.

Two things to know before trying it: tests need a mock model (--mock-model or AGENTUSE_MOCK_MODEL), and there's a version-matched tester builtin skill (agentuse skills get tester) so coding agents working on .agentuse files can discover this workflow straight from the CLI.

Learnings that earn their place

Corrections you give an agent used to accumulate in a staging file, where most never reached the model again. Now they graduate: a learning that survives 3 clean human approvals (or 10 runs in force) is promoted into the agent file itself, inside a marked block, where it applies on every run and lives in git like the rest of the file.

agentuse learnings tidy merges duplicates, shortens the verbose, retires the superseded, and promotes the proven, one pass, one undo, with a diff of everything it changed. It's available in the serve UI right where you review runs.

Breaking: learnings staging files move out of your repo. Every run used to rewrite *.learnings.md next to your agent files, in one real repo that meant 49 commits of pure churn. They now live with session logs under the AgentUse state directory. Run this once after upgrading:

agentuse learnings migrate --all

It copies first and asks before deleting anything. Graduated rules inside your .agentuse files are unaffected. Two small config removals ride along: learning.file is gone, and the pre-0.15 learning.evaluate shape is gone (use capture: true).

Restarting serve no longer kills your agents

If you run serve under a process manager, a pm2 restart, systemctl restart, or badly timed Ctrl-C used to destroy whatever was mid-run. Workers holding live runs are now released instead of killed: they finish the run out of process, write results to storage as normal, and exit on their own. The replacement daemon sees those runs as alive and leaves them alone.

In the same vein: idle workers that have banked a big run's memory are recycled instead of holding 400MB forever, and agentuse sessions reconcile settles runs stuck at running from before the daemon's normal sweep window.

Also in this release

• agentuse doctor now prices the whole per-request prompt, including preloaded skills and the visible skill catalog, which could silently cost ~11k tokens per request.
• store_list gained since, countOnly, and a deduplicated key listing, recent-items queries cost a third of what they did.
• allowed-tools parsing in skills is paren-aware, so multi-word patterns like Bash(git commit *) finally work.
• A blip refreshing an Anthropic OAuth token retries instead of failing the run with a misleading "no authentication found".
• Bash commands that read stdin see EOF immediately instead of hanging until timeout.
• Model registry refreshed: adds Claude Opus 5, so anthropic:claude-opus now points there.