astracode-agent 0.3.2 → 0.4.0

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,55 @@ 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
+ **`--agent <name>`** runs the whole session as one agent: its prompt, its
145
+ tools and its model tier. It works with or without `-p`.
146
+
101
147
  Your own commands and skills from `.astracode/commands` and
102
148
  `.astracode/skills` appear in the `/` menu too. The skills that come with the
103
149
  editor (infrastructure as code, web and mobile interface design) come with the
@@ -118,6 +164,9 @@ astracode-agent -p "<prompt>" [options]
118
164
  | `--permissions read-only\|auto\|full` | What the agent may do. See below. |
119
165
  | `--max-steps <n>` | Step limit for the run. The default is 150. |
120
166
  | `--cwd <dir>` | The workspace. The default is the current directory. |
167
+ | `--agents <json\|file>` | Agent definitions for this run. See [Subagents](#subagents-and-background-tasks). |
168
+ | `--agent <name>` | Run as that agent: its prompt, tools and model. |
169
+ | `--report-to <url>` | Post the run's progress to `<url>/events` as it goes. See [Reporting progress](#reporting-progress). |
121
170
  | `-v, --verbose` | Prints the agent's log on stderr. |
122
171
 
123
172
  ### Permissions
@@ -139,9 +188,19 @@ changed.
139
188
 
140
189
  - **`text`**: stdout is the agent's final answer, and nothing else.
141
190
  - **`json`**: stdout is one object, with `ok`, `end`, `summary`,
142
- `filesChanged`, `denied`, `steps` and `durationMs`.
191
+ `filesChanged`, `denied`, `steps`, `durationMs` and `tasks`.
143
192
  - **`stream-json`**: one JSON object per line, one for each agent event
144
193
  (tool calls, tool results, text, todos), then the same result object.
194
+ Subagents' events carry `agentId` and `parentAgentId`: their tool calls,
195
+ and `agentStarted`, `agentProgress` and `agentEnded`.
196
+
197
+ Background agents are waited for before the process exits. A report the
198
+ agent never read (it had finished its turn by then) is printed after its
199
+ answer in `text`, as `[background agent ag1 (explore) "..." completed]` and
200
+ the report. `json` lists every task the run started under `tasks`, each with
201
+ its `id`, `kind`, `state`, `agentType`, `parentTaskId` and, for an agent, its
202
+ `report`. Monitors and commands still running at the end are stopped, and
203
+ stderr says so.
145
204
 
146
205
  ### Exit status
147
206
 
@@ -170,12 +229,51 @@ apology in the summary.
170
229
  Let the agent make the edits, and let the workflow's own steps commit, push and
171
230
  comment. The agent refuses `git push` under `auto` for that reason.
172
231
 
232
+ ### Reporting progress
233
+
234
+ `--report-to <url>` posts the run's progress, one small JSON event per request,
235
+ to `<url>/events`, with the run's credential (`ASTRACODE_API_KEY`, or your
236
+ session) as the bearer token:
237
+
238
+ ```json
239
+ { "seq": 3, "type": "tool", "data": { "name": "edit_file", "step": 2 } }
240
+ ```
241
+
242
+ `type` is `started`, `step`, `tool`, `report` (the final answer, at most
243
+ 20,000 characters) or `ended` (`completed`, `failed` or `stopped`, with the
244
+ exit code). `seq` counts up from 1, so a receiver can drop a retried event it
245
+ already has. Only tool names, counts, the report and the outcome are sent:
246
+ never a tool's input or output, a file's contents, a path or a command.
247
+
248
+ Delivery never slows or fails the run. Events are sent in order, behind the
249
+ agent; a failed one is retried three times with backoff and then dropped; once
250
+ several in a row have failed the endpoint is taken to be down and only the
251
+ report and the end are still tried; at exit the CLI waits at most ten seconds
252
+ for what is left. The exit status is always the agent's. The URL must be
253
+ `https` (plain `http` only to this machine).
254
+
255
+ The AstraCode gateway takes these events at `/v1/runs/<id>/events` for an API
256
+ key with the "Run agents" scope and keeps them for seven days; that is what
257
+ remote agents use.
258
+
259
+ ### Remote agents
260
+
261
+ In the AstraCode editor, an agent can run in your repository's GitHub Actions
262
+ instead of on your machine (`isolation: remote`) and come back as a pull
263
+ request. "AstraCode: Enable remote agents for this repository" writes
264
+ `.github/workflows/astracode-agent.yml` for you to review and commit; it runs
265
+ this CLI, at a pinned version, with `--report-to` the gateway, so the agent's
266
+ card in the editor follows each step. It needs a repository secret
267
+ `ASTRACODE_TOKEN` (an API key with the "Run agents" scope) and Actions allowed
268
+ to open pull requests. See [Remote agents](https://astracode.io/docs/agent/remote-agents/).
269
+
173
270
  ## In Zed or a JetBrains IDE
174
271
 
175
272
  `astracode-agent acp` speaks the [Agent Client Protocol](https://agentclientprotocol.com),
176
273
  so editors that run external agents can use AstraCode as their agent. You sign
177
274
  in the same way as on the command line, and usage is billed to your AstraCode
178
- account.
275
+ account. A prompt that starts background agents waits for them before it
276
+ ends, and the agent answers with their reports in the same prompt.
179
277
 
180
278
  **Zed**: add this to `settings.json`, then pick AstraCode in the agent panel:
181
279