astracode-agent 0.3.2 → 0.4.1

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 CHANGED
@@ -95,9 +95,70 @@ Commands:
95
95
  | `/memory` | what it remembers about the project |
96
96
  | `/init` | write an `AGENTS.md` |
97
97
  | `/review`, `/diff` | review this branch, or see uncommitted changes |
98
- | `/tasks`, `/mcp` | background commands and MCP servers |
98
+ | `/tasks` | background agents, commands and monitors: `/tasks <id>` shows one's output or report, `/tasks stop <id>`, `/tasks stop-all` |
99
+ | `/agents` | the agents it can start: built-in, the project's, yours and `--agents`, with each file and what it shadows |
100
+ | `/mcp` | MCP servers and their tools |
99
101
  | `/export`, `/status`, `/help` | save the conversation, account and model details, all keys |
100
102
 
103
+ ### Subagents and background tasks
104
+
105
+ The agent can hand a piece of work to a subagent: a separate agent with its
106
+ own context that reports back. The built-in ones are `general-purpose`,
107
+ `explore` (fast, read-only search), `plan` and `verify`. Your own are Markdown
108
+ files with a YAML header, in Claude Code's format, read from
109
+ `.astracode/agents/` and `.claude/agents/` in the project and
110
+ `~/.astracode/agents/` and `~/.claude/agents/` in your home folder (nearest
111
+ first; `/agents` shows which file won).
112
+
113
+ Subagents run in the background by default, several at once:
114
+
115
+ - While one works, it is drawn as a block with its type, state, step count
116
+ and its last few tool calls. When it ends, its first lines of report go into
117
+ the conversation; `/tasks <id>` has the whole of it.
118
+ - A background agent, monitor or command that ends while nothing is running
119
+ wakes the agent with its report, in a turn labelled `(background)`. After
120
+ three such turns in a row without a message from you, it waits for your next
121
+ one.
122
+ - **Ctrl-B** moves the foreground agent or command to the background, and the
123
+ turn carries on.
124
+ - **Esc** stops the turn and its foreground agents. Background ones keep
125
+ going.
126
+ - Leaving (Ctrl-D, `/exit`) stops whatever is still running and prints one
127
+ line naming what it stopped.
128
+
129
+ **`--agents <json|file>`** defines agents for one session, in Claude Code's
130
+ JSON shape. They take precedence over the project's and your own files of the
131
+ same name.
132
+
133
+ ```bash
134
+ astracode-agent --agents '{"reviewer": {"description": "Reviews a diff for bugs",
135
+ "prompt": "You review code...", "tools": ["Read", "Grep", "Glob"], "model": "fast"}}'
136
+ ```
137
+
138
+ Fields: `description` and `prompt` (required), `tools`, `disallowedTools`
139
+ (Claude Code's tool names or ours), `model` (`inherit`, `fast`, `strong`, or
140
+ `haiku`/`sonnet`/`opus`), `permissionMode`, `maxTurns`, `skills`,
141
+ `mcpServers` (names of configured servers), `hooks`, `background`,
142
+ `isolation: "worktree"`, `effort`, `color`, `memory`.
143
+
144
+ An agent file can declare its own MCP servers (`mcpServers:` with a
145
+ `command` or a `url`), started with the agent and stopped when it ends. Those
146
+ in your own files (`~/.astracode/agents`, `~/.claude/agents`) start. A
147
+ project's file is the repository's to write, so in a conversation its server
148
+ starts only in a folder you said you trust, after you have been shown exactly
149
+ what runs and said yes (remembered on this machine, and asked again if the
150
+ definition changes). With `-p` and `acp` nobody can be asked: they start only
151
+ with `--allow-agent-mcp`, for that run. Servers get exactly the environment
152
+ the file gives them.
153
+
154
+ The shared task list the agents work from is kept with the conversation, so
155
+ `--continue` and `/resume` bring it back.
156
+
157
+ **`--agent <name>`** runs the whole session as one agent: its prompt, its
158
+ tools and its model tier. It works with or without `-p`. If its tools say
159
+ `Agent(explore, plan)`, those are the only agents the session can start; any
160
+ other is refused by name.
161
+
101
162
  Your own commands and skills from `.astracode/commands` and
102
163
  `.astracode/skills` appear in the `/` menu too. The skills that come with the
103
164
  editor (infrastructure as code, web and mobile interface design) come with the
@@ -118,6 +179,10 @@ astracode-agent -p "<prompt>" [options]
118
179
  | `--permissions read-only\|auto\|full` | What the agent may do. See below. |
119
180
  | `--max-steps <n>` | Step limit for the run. The default is 150. |
120
181
  | `--cwd <dir>` | The workspace. The default is the current directory. |
182
+ | `--agents <json\|file>` | Agent definitions for this run. See [Subagents](#subagents-and-background-tasks). |
183
+ | `--agent <name>` | Run as that agent: its prompt, tools and model. |
184
+ | `--allow-agent-mcp` | Start the MCP servers the project's agent files declare. See [Subagents](#subagents-and-background-tasks). |
185
+ | `--report-to <url>` | Post the run's progress to `<url>/events` as it goes. See [Reporting progress](#reporting-progress). |
121
186
  | `-v, --verbose` | Prints the agent's log on stderr. |
122
187
 
123
188
  ### Permissions
@@ -139,9 +204,19 @@ changed.
139
204
 
140
205
  - **`text`**: stdout is the agent's final answer, and nothing else.
141
206
  - **`json`**: stdout is one object, with `ok`, `end`, `summary`,
142
- `filesChanged`, `denied`, `steps` and `durationMs`.
207
+ `filesChanged`, `denied`, `steps`, `durationMs` and `tasks`.
143
208
  - **`stream-json`**: one JSON object per line, one for each agent event
144
209
  (tool calls, tool results, text, todos), then the same result object.
210
+ Subagents' events carry `agentId` and `parentAgentId`: their tool calls,
211
+ and `agentStarted`, `agentProgress` and `agentEnded`.
212
+
213
+ Background agents are waited for before the process exits. A report the
214
+ agent never read (it had finished its turn by then) is printed after its
215
+ answer in `text`, as `[background agent ag1 (explore) "..." completed]` and
216
+ the report. `json` lists every task the run started under `tasks`, each with
217
+ its `id`, `kind`, `state`, `agentType`, `parentTaskId` and, for an agent, its
218
+ `report`. Monitors and commands still running at the end are stopped, and
219
+ stderr says so.
145
220
 
146
221
  ### Exit status
147
222
 
@@ -170,12 +245,52 @@ apology in the summary.
170
245
  Let the agent make the edits, and let the workflow's own steps commit, push and
171
246
  comment. The agent refuses `git push` under `auto` for that reason.
172
247
 
248
+ ### Reporting progress
249
+
250
+ `--report-to <url>` posts the run's progress, one small JSON event per request,
251
+ to `<url>/events`, with the run's credential (`ASTRACODE_API_KEY`, or your
252
+ session) as the bearer token:
253
+
254
+ ```json
255
+ { "seq": 3, "type": "tool", "data": { "name": "edit_file", "step": 2 } }
256
+ ```
257
+
258
+ `type` is `started`, `step`, `tool`, `report` (the final answer, at most
259
+ 20,000 characters) or `ended` (`completed`, `failed` or `stopped`, with the
260
+ exit code). `seq` counts up from 1, so a receiver can drop a retried event it
261
+ already has. Only tool names, counts, the report and the outcome are sent:
262
+ never a tool's input or output, a file's contents, a path or a command.
263
+
264
+ Delivery never slows or fails the run. Events are sent in order, behind the
265
+ agent; a failed one is retried three times with backoff and then dropped; once
266
+ several in a row have failed the endpoint is taken to be down and only the
267
+ report and the end are still tried; at exit the CLI waits at most ten seconds
268
+ for what is left. The exit status is always the agent's. The URL must be
269
+ `https` (plain `http` only to this machine).
270
+
271
+ The AstraCode gateway takes these events at `/v1/runs/<id>/events` for an API
272
+ key with the "Run agents" scope and keeps them for seven days; that is what
273
+ remote agents use.
274
+
275
+ ### Remote agents
276
+
277
+ In the AstraCode editor, an agent can run in your repository's GitHub Actions
278
+ instead of on your machine (`isolation: remote`) and come back as a pull
279
+ request. "AstraCode: Enable remote agents for this repository" writes
280
+ `.github/workflows/astracode-agent.yml` for you to review and commit; it runs
281
+ this CLI, at a pinned version, with `--report-to` the gateway, so the agent's
282
+ card in the editor follows each step. It needs Actions allowed to open pull
283
+ requests, and no secret: each run signs in with the identity token GitHub gives
284
+ the job. A repository secret `ASTRACODE_TOKEN` (an API key with the "Run agents"
285
+ scope), if set, is used instead. See [Remote agents](https://astracode.io/docs/agent/remote-agents/).
286
+
173
287
  ## In Zed or a JetBrains IDE
174
288
 
175
289
  `astracode-agent acp` speaks the [Agent Client Protocol](https://agentclientprotocol.com),
176
290
  so editors that run external agents can use AstraCode as their agent. You sign
177
291
  in the same way as on the command line, and usage is billed to your AstraCode
178
- account.
292
+ account. A prompt that starts background agents waits for them before it
293
+ ends, and the agent answers with their reports in the same prompt.
179
294
 
180
295
  **Zed**: add this to `settings.json`, then pick AstraCode in the agent panel:
181
296
 
@@ -213,12 +328,26 @@ or runs a command. **Always allow** applies to that tool for the rest of the
213
328
  session. Risky commands and requests to other machines are asked about every
214
329
  time.
215
330
 
331
+ **Running as one of your agents.** Each session has an **Agent** option
332
+ (an ACP session config option, id `agent`): AstraCode itself, or any agent
333
+ from `.astracode/agents`, `.claude/agents`, your home folder's or `--agents`.
334
+ Pick one and, from the next prompt, the session runs as that agent, as
335
+ `--agent` does on the command line: its prompt, its tools, its model tier and
336
+ the agents it may start. An editor that does not show config options can set a
337
+ starting agent for every session in its `args`:
338
+
339
+ ```json
340
+ "args": ["acp", "--agents", "/Users/you/agents.json", "--agent", "reviewer"]
341
+ ```
342
+
343
+ `--allow-agent-mcp` in the same `args` lets the project's agent files start
344
+ the MCP servers they declare; without it, only your own agent files' do.
216
345
 
217
346
 
218
347
  These are not available without an editor:
219
348
 
220
349
  - diagnostics and language-server lookups
221
- - MCP servers
350
+ - the MCP servers in your settings (an agent file's own servers do start, as above)
222
351
  - the code index
223
352
  - memories and checkpoints
224
353