@mutagent/cli 0.2.330 → 0.2.332
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -71
- package/dist/agent-build-worker.js +2 -2
- package/dist/bin/cli.js +807 -3216
- package/dist/index.js +3 -5
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -65,11 +65,12 @@ mutagent providers mirror
|
|
|
65
65
|
# 3. Create an Environment: the variables and secrets a sandbox gets
|
|
66
66
|
mutagent env set staging GREETING=hello --secrets-from-file .env.secrets
|
|
67
67
|
|
|
68
|
-
# 4. Run
|
|
69
|
-
mutagent helix
|
|
68
|
+
# 4. Run an agent.md folder on a task with the local Helix binary
|
|
69
|
+
mutagent install helix
|
|
70
|
+
mutagent agent run reviewer/agent.md "check the deploy"
|
|
70
71
|
```
|
|
71
72
|
|
|
72
|
-
|
|
73
|
+
`mutagent architech` runs the Architech harness on a task in a cloud sandbox.
|
|
73
74
|
|
|
74
75
|
## Concepts
|
|
75
76
|
|
|
@@ -77,22 +78,22 @@ To run Helix on your own machine instead, install the Helix binary with `mutagen
|
|
|
77
78
|
belong to in its organization. `mutagent workspaces use <name>` selects one, and `--workspace`
|
|
78
79
|
overrides it for a single command.
|
|
79
80
|
- **LLM provider (BYOK)**: a model provider key (OpenAI, Anthropic, Google, ...) stored in the
|
|
80
|
-
workspace, encrypted.
|
|
81
|
+
workspace, encrypted. A cloud run uses it to call models. Manage them with
|
|
81
82
|
`mutagent providers`.
|
|
82
83
|
- **Environment**: a named set of variables and secrets an agent's tools need, such as a GitHub
|
|
83
84
|
token or a database URL. Load one into a run with `--env <name>`. Values are write-only:
|
|
84
85
|
`mutagent env show` prints names and fingerprints, never a value. LLM provider keys do not
|
|
85
86
|
belong here.
|
|
86
|
-
- **
|
|
87
|
-
when the run starts. `mutagent
|
|
87
|
+
- **Cloud session**: a cloud run of the Architech harness, addressed by a reference (`hs1_...`)
|
|
88
|
+
that is printed when the run starts. `mutagent architech session` lists sessions, attaches to them, sends input,
|
|
88
89
|
answers their questions, stops, checkpoints and restores them. A sandbox idle for 15 minutes is
|
|
89
90
|
stopped, and an interactive session in it is checkpointed first.
|
|
90
91
|
- **Managed agent**: a folder whose entry file is `agent.md` (YAML frontmatter, then the standing
|
|
91
92
|
prompt). `mutagent agent deploy` stores each change as a new revision. A slot is the agent in one
|
|
92
93
|
Environment (`--env`).
|
|
93
94
|
- **Sandbox provider and preset**: where a cloud run executes, and the named sandbox definition it
|
|
94
|
-
uses. Both are managed by the platform. You choose
|
|
95
|
-
`--
|
|
95
|
+
uses. Both are managed by the platform. You choose a sandbox provider per run with
|
|
96
|
+
`--sandbox-provider`.
|
|
96
97
|
- **Gateway**: connects GitHub and Slack, and runs Helix when an event or a schedule fires.
|
|
97
98
|
|
|
98
99
|
## Commands
|
|
@@ -164,15 +165,26 @@ is refused unless you pass `--allow-provider-key`. Environment names use letters
|
|
|
164
165
|
and `-` (up to 64 characters). Variable names use `A-Z`, `0-9` and `_`, and cannot start with a
|
|
165
166
|
digit. An Environment holds up to 64 KiB.
|
|
166
167
|
|
|
167
|
-
### Run
|
|
168
|
+
### Run Architech in the cloud (`architech`)
|
|
169
|
+
|
|
170
|
+
`mutagent architech` is the cloud form of the local `architech`. It always runs the Architech
|
|
171
|
+
harness in a new sandbox, so it has no `--preset` and no `--sandbox`.
|
|
168
172
|
|
|
169
173
|
```bash
|
|
170
|
-
mutagent
|
|
171
|
-
mutagent
|
|
172
|
-
mutagent
|
|
173
|
-
mutagent
|
|
174
|
-
mutagent
|
|
175
|
-
mutagent
|
|
174
|
+
mutagent architech -p "plan the refactor" # Run to completion and print the final answer
|
|
175
|
+
mutagent architech --mode json "run the tests" # Stream events as JSON lines
|
|
176
|
+
mutagent architech --mode rpc # A steerable session: JSON commands on stdin
|
|
177
|
+
mutagent architech --prime -p "plan the refactor"
|
|
178
|
+
mutagent architech agent --name reviewer -p "review the diff"
|
|
179
|
+
mutagent architech session list
|
|
180
|
+
mutagent architech session send <reference> "and now the tests"
|
|
181
|
+
mutagent architech session end <reference> --force
|
|
182
|
+
mutagent architech models # Models a cloud run can use, and the default
|
|
183
|
+
mutagent architech models default <provider/model> # Set the workspace default model
|
|
184
|
+
|
|
185
|
+
# Sandbox providers and presets
|
|
186
|
+
mutagent sandbox providers
|
|
187
|
+
mutagent sandbox presets
|
|
176
188
|
```
|
|
177
189
|
|
|
178
190
|
| Run option | What it does |
|
|
@@ -183,7 +195,6 @@ mutagent helix --repository acme/api --branch feat/login --mode rpc
|
|
|
183
195
|
| `--prime` | Run the lean Prime agent instead of the full orchestrator |
|
|
184
196
|
| `--model <provider/model>` | Model to use (default: the workspace default model) |
|
|
185
197
|
| `--env <name>` | Workspace Environment to load |
|
|
186
|
-
| `--preset <name>` | Sandbox preset (default: the server's Helix preset) |
|
|
187
198
|
| `--sandbox-provider <name>` | Run on this sandbox provider |
|
|
188
199
|
| `--cwd <path>` | Working directory in the sandbox |
|
|
189
200
|
| `--repository <owner/name>` | Run in a checkout of this GitHub repository (needs the workspace's GitHub connection) |
|
|
@@ -192,55 +203,9 @@ mutagent helix --repository acme/api --branch feat/login --mode rpc
|
|
|
192
203
|
There is no terminal chat UI: choose `-p`, `--mode json` or `--mode rpc`. Each run prints its
|
|
193
204
|
session reference (`hs1_...`) on stderr. Ctrl-C stops the session.
|
|
194
205
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
mutagent helix agent --file reviewer.md --mode json "run the suite"
|
|
199
|
-
|
|
200
|
-
# Sessions
|
|
201
|
-
mutagent helix session list
|
|
202
|
-
mutagent helix session attach <reference> # Watch it (--since <n> replays)
|
|
203
|
-
mutagent helix session send <reference> "and now the tests"
|
|
204
|
-
mutagent helix session send <reference> --type steer "stop and re-read the spec"
|
|
205
|
-
mutagent helix session approvals <reference> # What it is waiting on (a question it asked)
|
|
206
|
-
mutagent helix session answer <reference> <id> --value 'an option' # Answer it (--cancel denies)
|
|
207
|
-
mutagent helix session signal <reference> --force # Stop it; the sandbox stays up
|
|
208
|
-
mutagent helix session close-input <reference>
|
|
209
|
-
mutagent helix session checkpoint <reference>
|
|
210
|
-
mutagent helix session checkpoints <reference>
|
|
211
|
-
mutagent helix session restore <reference> # Continue in a rebuilt sandbox
|
|
212
|
-
|
|
213
|
-
# Models
|
|
214
|
-
mutagent helix models # Models Helix can use, and the default
|
|
215
|
-
mutagent helix models default <provider/model> # Set the workspace default model
|
|
216
|
-
|
|
217
|
-
# Diagnostics
|
|
218
|
-
mutagent helix version # This CLI's version and the cloud Helix version
|
|
219
|
-
mutagent helix doctor # Helix's own diagnostics in a temporary sandbox
|
|
220
|
-
mutagent helix smoke # Helix's smoke test in a temporary sandbox
|
|
221
|
-
|
|
222
|
-
# Sandbox providers and presets a run can name
|
|
223
|
-
mutagent sandbox providers
|
|
224
|
-
mutagent sandbox presets
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
### Run Architech in the cloud (`architech`)
|
|
228
|
-
|
|
229
|
-
`mutagent architech` is the cloud form of the local `architech`, as `mutagent helix` is of the
|
|
230
|
-
local `helix`. It takes the same launch flags, `agent` forms and `session`, `models` and
|
|
231
|
-
`access` verbs, and always runs the Architech harness in a new sandbox, so it has no `--preset`.
|
|
232
|
-
|
|
233
|
-
```bash
|
|
234
|
-
mutagent architech --mode rpc # A steerable Architech session
|
|
235
|
-
mutagent architech --prime -p "plan the refactor"
|
|
236
|
-
mutagent architech agent --name reviewer -p "review the diff"
|
|
237
|
-
mutagent architech session list
|
|
238
|
-
mutagent architech session send <reference> "and now the tests"
|
|
239
|
-
mutagent architech session end <reference> --force
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
`mutagent helix --preset architech` is refused: it names the `mutagent architech` command to run
|
|
243
|
-
instead.
|
|
206
|
+
`mutagent helix` and `mutagent factory` are removed. They answer `UNKNOWN_COMMAND` with what does
|
|
207
|
+
the job now: `mutagent agent run` for an agent.md, `mutagent install helix` for the Helix binary,
|
|
208
|
+
the Factory page in the web app for Agent Factory entries. See the CHANGELOG.
|
|
244
209
|
|
|
245
210
|
Only an interactive session (`--mode rpc`) accepts `session send`. A send to a session whose
|
|
246
211
|
sandbox was stopped for idling wakes it from its last checkpoint.
|
|
@@ -252,7 +217,6 @@ mutagent agent check invoice/agent.md # Compile and validate; n
|
|
|
252
217
|
mutagent agent pack invoice/agent.md --output invoice.tgz
|
|
253
218
|
mutagent agent run invoice/agent.md "Price three widget units." # Local, with the local Helix binary
|
|
254
219
|
mutagent agent deploy invoice/agent.md --env prod
|
|
255
|
-
mutagent helix agent @invoice-pricing --env prod -p "Price three widget units."
|
|
256
220
|
mutagent agent list
|
|
257
221
|
mutagent agent inspect invoice-pricing --env prod
|
|
258
222
|
mutagent agent activate invoice-pricing --revision v2 --env prod # An older revision is a rollback
|
|
@@ -262,7 +226,7 @@ mutagent agent retire invoice-pricing --env prod --force
|
|
|
262
226
|
The `agent.md` frontmatter fields `name`, `description`, `model`, `thinking`, `tools`,
|
|
263
227
|
`disallowed_tools` and `skills` are a local brief. Deployment settings live in one optional
|
|
264
228
|
`harness:` block (tools, skills, files, bindings, runtime). `name` is the slug, and `model` is
|
|
265
|
-
`provider/model` as `mutagent
|
|
229
|
+
`provider/model` as `mutagent architech models` lists it.
|
|
266
230
|
|
|
267
231
|
Each deploy of new content is the next revision (`v1`, `v2`, ...). `--no-activate` stores it
|
|
268
232
|
without moving the slot. `@slug:vN` pins a revision and `@slug:latest` runs the newest one.
|
|
@@ -364,8 +328,8 @@ paths and the context of your prompts. Use it only when you mean to share all of
|
|
|
364
328
|
| `-h, --help` | Help for any command |
|
|
365
329
|
| `-v, --version` | CLI version (only before a subcommand) |
|
|
366
330
|
|
|
367
|
-
With `mutagent
|
|
368
|
-
(`mutagent --api-key <key>
|
|
331
|
+
With `mutagent architech`, put `--api-key` and `--endpoint` before `architech`
|
|
332
|
+
(`mutagent --api-key <key> architech -p "<task>"`). After `architech` they are refused, so a model key
|
|
369
333
|
cannot be sent as your Mutagent key.
|
|
370
334
|
|
|
371
335
|
## Scripts, CI and coding agents
|
|
@@ -380,8 +344,8 @@ mutagent providers list --json
|
|
|
380
344
|
- **Coding agents:** run `mutagent skills install` first. It installs a skill that teaches the agent
|
|
381
345
|
the CLI's workflows. To help a person sign in, run `mutagent login --browser --json`, show them the
|
|
382
346
|
printed URL, and wait (the CLI polls for up to 5 minutes).
|
|
383
|
-
- **JSON:** pass `--json` to every command except a `mutagent
|
|
384
|
-
own. A response may carry `_directive` (a status card and the next step for an agent), `_links`
|
|
347
|
+
- **JSON:** pass `--json` to every command except a `mutagent architech` launch, whose output is the
|
|
348
|
+
harness's own. A response may carry `_directive` (a status card and the next step for an agent), `_links`
|
|
385
349
|
(dashboard and API URLs) and `_compat` (CLI and skill versions).
|
|
386
350
|
- **Destructive commands** (delete, retire, signal, cancel, ...) need `-f/--force` in every mode.
|
|
387
351
|
Without it they refuse with `CONFIRMATION_REQUIRED` and send nothing. They never prompt.
|