astracode-agent 0.3.1 → 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 +102 -4
- package/dist/astracode-agent.cjs +15374 -6306
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ checksum, and on a Mac also checks that AstraCode signed it. To update, run
|
|
|
18
18
|
With Homebrew, on macOS or Linux:
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
|
-
brew install
|
|
21
|
+
brew install astracode-io/tap/astracode-agent
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
With Node 20 or later you can also install it from npm:
|
|
@@ -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
|
|
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 `
|
|
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
|
|