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 +133 -4
- package/dist/astracode-agent.cjs +15071 -7207
- package/package.json +1 -1
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
|
|
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 `
|
|
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
|
|