@nathapp/nax-agent-acp 0.3.0 → 0.84.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/CHANGELOG.md +33 -0
- package/README.md +117 -22
- package/bin/nax-agent.js +4 -0
- package/dist/client/backend.js +11 -2
- package/dist/client/capabilities.d.ts +9 -3
- package/dist/client/capabilities.js +26 -5
- package/dist/client/elicitation.d.ts +4 -2
- package/dist/client/elicitation.js +14 -1
- package/dist/client/errors.d.ts +9 -1
- package/dist/client/errors.js +19 -2
- package/dist/client/events.d.ts +5 -1
- package/dist/client/events.js +31 -2
- package/dist/client/index.d.ts +2 -1
- package/dist/client/index.js +1 -0
- package/dist/client/launchable.d.ts +4 -0
- package/dist/client/launchable.js +17 -0
- package/dist/client/open.js +75 -13
- package/dist/client/options.d.ts +11 -0
- package/dist/client/options.js +17 -3
- package/dist/client/permissions.d.ts +2 -2
- package/dist/client/pre-approval.d.ts +5 -13
- package/dist/client/pre-approval.js +3 -10
- package/dist/client/registry.d.ts +15 -2
- package/dist/client/registry.js +22 -2
- package/dist/client/tool-calls.js +0 -4
- package/dist/client/tool-events.d.ts +8 -1
- package/dist/client/tool-events.js +39 -6
- package/dist/client/turn.js +28 -8
- package/dist/server/auth.d.ts +45 -0
- package/dist/server/auth.js +87 -0
- package/dist/server/capabilities.d.ts +7 -0
- package/dist/server/capabilities.js +19 -0
- package/dist/server/cli.d.ts +26 -0
- package/dist/server/cli.js +87 -0
- package/dist/server/client-port.d.ts +39 -0
- package/dist/server/client-port.js +49 -0
- package/dist/server/connection.d.ts +22 -0
- package/dist/server/connection.js +56 -0
- package/dist/server/errors.d.ts +21 -0
- package/dist/server/errors.js +70 -0
- package/dist/server/index.d.ts +4 -3
- package/dist/server/index.js +6 -1
- package/dist/server/logger.d.ts +7 -0
- package/dist/server/logger.js +25 -0
- package/dist/server/login.d.ts +18 -0
- package/dist/server/login.js +29 -0
- package/dist/server/main.d.ts +19 -0
- package/dist/server/main.js +120 -0
- package/dist/server/nax-config.d.ts +30 -0
- package/dist/server/nax-config.js +138 -0
- package/dist/server/open-session.d.ts +37 -0
- package/dist/server/open-session.js +55 -0
- package/dist/server/options.d.ts +27 -0
- package/dist/server/options.js +55 -0
- package/dist/server/permissions.d.ts +44 -0
- package/dist/server/permissions.js +157 -0
- package/dist/server/process-entry.d.ts +15 -0
- package/dist/server/process-entry.js +28 -0
- package/dist/server/prompt.d.ts +8 -0
- package/dist/server/prompt.js +29 -0
- package/dist/server/questions.d.ts +33 -0
- package/dist/server/questions.js +79 -0
- package/dist/server/registry-open.d.ts +33 -0
- package/dist/server/registry-open.js +62 -0
- package/dist/server/registry.d.ts +64 -0
- package/dist/server/registry.js +262 -0
- package/dist/server/server-session.d.ts +43 -0
- package/dist/server/server-session.js +221 -0
- package/dist/server/session-config.d.ts +27 -0
- package/dist/server/session-config.js +93 -0
- package/dist/server/storage.d.ts +49 -0
- package/dist/server/storage.js +191 -0
- package/dist/server/translate/diff.d.ts +30 -0
- package/dist/server/translate/diff.js +81 -0
- package/dist/server/translate/events.d.ts +37 -0
- package/dist/server/translate/events.js +126 -0
- package/dist/server/translate/notice.d.ts +10 -0
- package/dist/server/translate/notice.js +14 -0
- package/dist/server/translate/replay.d.ts +11 -0
- package/dist/server/translate/replay.js +53 -0
- package/dist/server/translate/stop.d.ts +22 -0
- package/dist/server/translate/stop.js +48 -0
- package/dist/server/translate/tool-kind.d.ts +9 -0
- package/dist/server/translate/tool-kind.js +67 -0
- package/dist/server/version.d.ts +1 -0
- package/dist/server/version.js +17 -0
- package/package.json +6 -3
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,39 @@
|
|
|
3
3
|
All notable changes to `@nathapp/nax-agent-acp` are recorded here. Versions move in
|
|
4
4
|
step with `@nathapp/nax-agent`.
|
|
5
5
|
|
|
6
|
+
## [0.84.0] - 2026-10-09
|
|
7
|
+
|
|
8
|
+
- Versioning: released in lockstep with `@nathapp/nax`, `@nathapp/nax-ai` and the other agent package at one shared version, starting at 0.84.0 (previously 0.3.x).
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- `nax-agent` binary and the `./server` entry (`main`, `runCli`): an ACP server on stdio over nax-agent's native agent. It reads `~/.nax` (models, auth, optional `agentServer` block) and logs to stderr only (S5-0).
|
|
13
|
+
- Streamed text, thinking, tool calls with diffs, usage and compaction updates; transcript replay (S5-1).
|
|
14
|
+
- `session/new`, `session/prompt`, `session/cancel`; permission requests with per-session always-allow (keyed on command and subcommand); questions via form elicitation, or a canned answer for clients without it (S5-2).
|
|
15
|
+
- File-backed sessions: `session/load` (with replay), `resume`, `list`, `close`, `delete`, `set_mode`, `set_config_option` (model, bash approval). A model switch keeps the conversation (S5-3).
|
|
16
|
+
- `nax-agent login <provider>`, terminal `authMethods` for clients that declare `auth.terminal`, `authenticate`, and `auth_required` for missing or rejected credentials, checked before a session opens (S5-4).
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
|
|
20
|
+
- A model the agent does not offer verbatim still fails the open with `AGENT_SESSION_CAPABILITY_UNSUPPORTED`; the error now lists the model ids the agent does offer (message and `context.offered`, at most 50, cleaned like other agent text).
|
|
21
|
+
|
|
22
|
+
## [0.3.1] - 2026-10-07
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
|
|
26
|
+
- A rate-limited prompt (structured `data.errorKind: "rate_limit"`, as Claude's adapter sends) is `AGENT_SESSION_RATE_LIMITED`, classified from structured error data only. Needs `@nathapp/nax-agent` 0.3.1.
|
|
27
|
+
- `effort` option: sets the agent's reasoning effort after the model; skipped with a warning when not offered.
|
|
28
|
+
- `onProcess` option (`AcpProcessHooks`): `spawned(pid)` and `exited(pid)` for every agent process, including after a reconnect.
|
|
29
|
+
- `tool_result` events carry `resultBytes`: the UTF-8 byte length of the full result before the preview cap (0 for a call the turn never answered).
|
|
30
|
+
- `isAgentLaunchable` and `launchCandidateKind`: whether a registered agent's launcher resolves on PATH, and whether only the npx fallback does.
|
|
31
|
+
- The agent's heartbeats on a running tool surface as `tool_progress` turn events, at most one per call per 30 s; they are not session events.
|
|
32
|
+
|
|
33
|
+
### Fixed
|
|
34
|
+
|
|
35
|
+
- An errored or cancelled turn's `turn_end` carries the usage, cost and `costSource` the turn had already reported, instead of zero (#2367). A cancelled turn whose agent answers within the grace period emits its `usage` event before `turn_end`. A turn that ends with no prompt response (killed after the grace, agent gone, or a JSON-RPC error) reports cost 0 with `costSource: "unpriced"`; any reading it saw is billed to the next priced turn. Needs `@nathapp/nax-agent` 0.3.1.
|
|
36
|
+
- Session instructions are no longer lost when the agent dies before it has the prompt. They count as delivered on the first turn-content update or the prompt's response; otherwise the next prompt, after the reconnect, carries them again (#2364).
|
|
37
|
+
- Profiles `none` and `read` on Claude no longer use plan mode, which wrote its plan file under `~/.claude/plans/` without a permission request. They run in `default` mode with `Write`, `Edit`, `MultiEdit`, `NotebookEdit` and `EnterPlanMode` removed, and load no Claude settings files, so settings allow rules, hooks and MCP servers cannot act outside the profile. Embedder tools no longer carry `readOnlyHint`. Resuming a 0.3.0 `none`/`read` session may rebuild Claude's agent session (#2366).
|
|
38
|
+
|
|
6
39
|
## [0.3.0] - 2026-10-06
|
|
7
40
|
|
|
8
41
|
- Package scaffold: `./client` and `./server` entries, build, gates and release wiring.
|
package/README.md
CHANGED
|
@@ -4,10 +4,9 @@ ACP (Agent Client Protocol) backend for `@nathapp/nax-agent` sessions. It lets t
|
|
|
4
4
|
nax-agent session API (`createAgentSession`, `send()`, `answer()`, `cancel()`, `close()`)
|
|
5
5
|
drive external coding agents such as Claude Code over ACP.
|
|
6
6
|
|
|
7
|
-
**Status:
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
crash. `./server` is reserved for a later ACP server.
|
|
7
|
+
**Status: 0.4.0.** `./client`: `acpBackend()` drives external ACP agents (Claude Code and others) as
|
|
8
|
+
nax-agent sessions. `./server` and the `nax-agent` binary: nax-agent's own native coding agent as an
|
|
9
|
+
ACP server for editors (Zed) and headless clients (acpx). See "The nax-agent ACP server" below.
|
|
11
10
|
|
|
12
11
|
```ts
|
|
13
12
|
import { createAgentSession, createMemoryTranscriptStore } from "@nathapp/nax-agent";
|
|
@@ -33,6 +32,15 @@ What to know:
|
|
|
33
32
|
- **Instructions** are prepended to the first prompt only; ACP has no system prompt.
|
|
34
33
|
- **Stop reasons.** A turn that stops for anything but `end_turn` ends `errored` with
|
|
35
34
|
an `ACP_STOP_*` code (`ACP_STOP_CODES`).
|
|
35
|
+
- **Model and effort.** `model` and `effort` are set through `session/set_config_option`,
|
|
36
|
+
after the profile's mode: the model only when the agent offers it (else
|
|
37
|
+
`AGENT_SESSION_CAPABILITY_UNSUPPORTED`), the effort through the agent's `thought_level`
|
|
38
|
+
option (or its known effort option) and skipped with a warning when the value is not offered.
|
|
39
|
+
- **Agent processes.** `onProcess: { spawned(pid), exited(pid) }` is called for every agent
|
|
40
|
+
process, including a reconnect's; not when the spawn fails. A throwing hook is logged and ignored.
|
|
41
|
+
- **Rate limits.** A prompt the agent rejects with structured `data.errorKind: "rate_limit"`
|
|
42
|
+
(as Claude's adapter does) ends `AGENT_SESSION_RATE_LIMITED`. It is read from structured error
|
|
43
|
+
data only, never from message text; Claude's adapter sends no retry-after.
|
|
36
44
|
- **Usage.** Each turn ends with one `usage` event: the tokens the agent reports for
|
|
37
45
|
the turn, and the cost it reports (`costSource: "reported"`). An agent that reports
|
|
38
46
|
no cost gives `costUsd: 0` with `costSource: "unpriced"`. Never sum `unpriced`
|
|
@@ -43,6 +51,14 @@ What to know:
|
|
|
43
51
|
- **A crash between `session/new` and the first save** loses the agent's session
|
|
44
52
|
id. The next `createAgentSession` with the same id starts fresh.
|
|
45
53
|
|
|
54
|
+
## Is the agent installed?
|
|
55
|
+
|
|
56
|
+
`isAgentLaunchable(agent, env?)` is true when one of the agent's registry launch
|
|
57
|
+
candidates resolves on `PATH`, using the same resolution the backend uses at spawn.
|
|
58
|
+
`launchCandidateKind(agent, env?)` says which: `"local"` for the agent's own launcher,
|
|
59
|
+
`"npx"` when only the npx fallback resolves (the first open then downloads the
|
|
60
|
+
launcher), or `undefined`.
|
|
61
|
+
|
|
46
62
|
## Resume and reconnect
|
|
47
63
|
|
|
48
64
|
```ts
|
|
@@ -87,28 +103,29 @@ const session = await resumeAgentSession(sessionId, {
|
|
|
87
103
|
|
|
88
104
|
## Profiles on ACP
|
|
89
105
|
|
|
90
|
-
ACP enforces a profile in two layers: the agent's own
|
|
106
|
+
ACP enforces a profile in two layers: the agent's own setup, and this client's
|
|
91
107
|
answer to each permission request the agent sends.
|
|
92
108
|
|
|
93
|
-
| Profile |
|
|
109
|
+
| Profile | Claude's setup | Permission requests |
|
|
94
110
|
|---|---|---|
|
|
95
|
-
| `none` | `
|
|
96
|
-
| `read` | `
|
|
97
|
-
| `ask` | `default` | `approval_requested`; you decide with `answer()` |
|
|
98
|
-
| `full` | `default` | allowed, recorded as `decidedBy: "profile"` |
|
|
111
|
+
| `none` | `default` mode, write tools removed, no settings files | rejected, recorded as `decidedBy: "profile"` |
|
|
112
|
+
| `read` | `default` mode, write tools removed, no settings files | rejected, recorded as `decidedBy: "profile"` |
|
|
113
|
+
| `ask` | `default` mode | `approval_requested`; you decide with `answer()` |
|
|
114
|
+
| `full` | `default` mode | allowed, recorded as `decidedBy: "profile"` |
|
|
99
115
|
|
|
100
|
-
- **Only Claude supports `none` and `read`.** Other agents have no read-only
|
|
116
|
+
- **Only Claude supports `none` and `read`.** Other agents have no read-only enforcement here yet,
|
|
101
117
|
so those profiles fail with `AGENT_SESSION_CAPABILITY_UNSUPPORTED` before any prompt.
|
|
102
118
|
- **The guarantees are narrower than the native backend's.** Only actions the agent
|
|
103
119
|
routes through a permission request are decided here.
|
|
104
120
|
- Under `none` and `read`, Claude may still run tools it does not ask about, such
|
|
105
121
|
as reads and search. `none` means no permitted side effects, not no reads.
|
|
106
|
-
- Under `none` and `read`, Claude
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
122
|
+
- Under `none` and `read`, Claude has no `Write`, `Edit`, `MultiEdit`,
|
|
123
|
+
`NotebookEdit` or `EnterPlanMode` tool, and loads no user, project or local Claude
|
|
124
|
+
settings: their allow rules, hooks and MCP servers would act without asking. The
|
|
125
|
+
project's `CLAUDE.md` is not loaded either; pass what Claude needs as
|
|
126
|
+
`instructions`. A Bash command Claude does not treat as read-only asks first and
|
|
127
|
+
is refused. Changing these options changes what Claude's adapter compares on
|
|
128
|
+
resume, so resuming under another profile may rebuild the agent's session.
|
|
112
129
|
- Under `ask`, actions Claude's `default` mode allows without asking (reads and
|
|
113
130
|
other non-mutating tools) are not shown to you.
|
|
114
131
|
- **Only one-time options are chosen.** "Always allow" is never chosen, because it
|
|
@@ -152,11 +169,6 @@ MCP server this client runs for the session.
|
|
|
152
169
|
for each of your tools, so it never asks permission for them. Your tool's own
|
|
153
170
|
`approval` is the only gate: `"always"` asks you through `approval_requested` and
|
|
154
171
|
`answer()` under every profile; `"never"` runs under every profile.
|
|
155
|
-
- **Listed as read-only.** Every tool carries the MCP annotation
|
|
156
|
-
`readOnlyHint: true`. The `none` and `read` profiles put Claude in plan mode, which
|
|
157
|
-
asks before any MCP tool not marked read-only, ahead of the pre-approval. The hint
|
|
158
|
-
loosens nothing: your tool's `approval` stays the gate, and Claude's own write
|
|
159
|
-
tools are still refused under `none` and `read`.
|
|
160
172
|
- **Calls run inside a turn.** A call outside a running turn gets an error and the
|
|
161
173
|
tool does not run. When the turn is cancelled, times out, ends or loses the agent
|
|
162
174
|
process, the call's signal aborts and the agent is told the call was abandoned.
|
|
@@ -225,3 +237,86 @@ and `read` forms are not offered, and one that arrives anyway is declined.
|
|
|
225
237
|
and later fields are not asked. `answer()` on that question returns `"cancelled"`.
|
|
226
238
|
- **Question text comes from the agent.** Control characters are stripped, your
|
|
227
239
|
secrets scrubbed, and it is capped at 4 KiB.
|
|
240
|
+
|
|
241
|
+
## The nax-agent ACP server
|
|
242
|
+
|
|
243
|
+
`nax-agent` is an ACP server on stdio. It runs nax-agent's native coding agent: tools run locally
|
|
244
|
+
under nax-agent's profiles and sandbox, and edits reach the editor as diffs.
|
|
245
|
+
|
|
246
|
+
```sh
|
|
247
|
+
npm install -g @nathapp/nax-agent @nathapp/nax-agent-acp
|
|
248
|
+
nax-agent --version
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
It reads `~/.nax/config.json`, the same file nax uses:
|
|
252
|
+
- `models.native.balanced` is the default model. `fast`, `balanced` and `powerful` are the models offered in the editor.
|
|
253
|
+
- `auth` controls where credentials come from.
|
|
254
|
+
- An optional `agentServer` block sets `defaultMode`, `bashApproval` and `sessionsDir`.
|
|
255
|
+
|
|
256
|
+
Flags (`--model`, `--mode`, `--bash-approval`, `--config-dir`, `--sessions-dir`) and `NAX_AGENT_<OPTION>`
|
|
257
|
+
environment variables override the file. Sessions are stored under `~/.nax/.agent-server/sessions/`.
|
|
258
|
+
|
|
259
|
+
### Credentials
|
|
260
|
+
|
|
261
|
+
Log in once on a terminal. The credential lands in `~/.nax`, shared with `nax auth login`:
|
|
262
|
+
|
|
263
|
+
```sh
|
|
264
|
+
nax-agent login anthropic # asks for a method; --method api-key|oauth to choose
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
A provider's environment variable (for example `ANTHROPIC_API_KEY`) also works when nothing is stored.
|
|
268
|
+
|
|
269
|
+
Before opening a session, the server checks for a credential for the session model's provider. A missing
|
|
270
|
+
one fails the request with `auth_required` before anything is billed, and so does a rejected one during a
|
|
271
|
+
turn. Editors that support terminal auth then offer "Log in to <provider>", which runs
|
|
272
|
+
`nax-agent login <provider>` in a terminal.
|
|
273
|
+
|
|
274
|
+
### Zed
|
|
275
|
+
|
|
276
|
+
In Zed's `settings.json`:
|
|
277
|
+
|
|
278
|
+
```json
|
|
279
|
+
{
|
|
280
|
+
"agent_servers": {
|
|
281
|
+
"nax-agent": {
|
|
282
|
+
"type": "custom",
|
|
283
|
+
"command": "nax-agent",
|
|
284
|
+
"args": ["acp"],
|
|
285
|
+
"env": {}
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Open the agent panel and start a "nax-agent" thread.
|
|
292
|
+
- **Modes:** `ask` (default) asks before each edit or command, `full` runs without asking, `read` is read-only, and `none` has no tools.
|
|
293
|
+
- **Model:** switch it from the thread's model picker; the conversation is kept.
|
|
294
|
+
- **Persistence:** threads are saved and can be reopened after a restart.
|
|
295
|
+
|
|
296
|
+
### acpx (headless)
|
|
297
|
+
|
|
298
|
+
Add an agent to `~/.acpx/config.json`:
|
|
299
|
+
|
|
300
|
+
```json
|
|
301
|
+
{ "agents": { "nax-agent": { "argv": ["nax-agent", "acp"] } } }
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
```sh
|
|
305
|
+
acpx nax-agent sessions new # once per directory: creates the session
|
|
306
|
+
acpx --approve-all nax-agent "add a test for parseCli" # prompts the session
|
|
307
|
+
acpx nax-agent "now run it" # continues the same session
|
|
308
|
+
acpx nax-agent sessions # list sessions
|
|
309
|
+
acpx nax-agent exec "what does this repo do" # one-shot, no saved session
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
acpx refuses a prompt until `sessions new` has created a session for the directory. A missing credential
|
|
313
|
+
shows up at `sessions new` as an authentication-required error.
|
|
314
|
+
|
|
315
|
+
Questions from the agent need a client with form elicitation. A client without it (acpx) gets a notice,
|
|
316
|
+
and the agent is told to proceed on its best judgement.
|
|
317
|
+
|
|
318
|
+
### Not supported yet
|
|
319
|
+
|
|
320
|
+
- MCP servers sent by the client are ignored, with a notice.
|
|
321
|
+
- No image or audio prompts.
|
|
322
|
+
- No logout or provider management over ACP. Use `nax auth list` / `nax auth rm`.
|
package/bin/nax-agent.js
ADDED
package/dist/client/backend.js
CHANGED
|
@@ -179,9 +179,18 @@ async function sendTurn(s, prompt, opts) {
|
|
|
179
179
|
const signal = opts.signal ?? s.ctx.turnSignal();
|
|
180
180
|
const live = await liveFor(s, signal);
|
|
181
181
|
const instructions = s.instructionsSent ? undefined : s.ctx.instructions;
|
|
182
|
-
s.instructionsSent = true;
|
|
183
182
|
const text = instructions === undefined || instructions === "" ? prompt : `${instructions}\n\n${prompt}`;
|
|
184
|
-
|
|
183
|
+
// #2364: delivered once the agent shows it has the prompt, not when it is sent.
|
|
184
|
+
const onReceipt = instructions === undefined
|
|
185
|
+
? undefined
|
|
186
|
+
: () => {
|
|
187
|
+
s.instructionsSent = true;
|
|
188
|
+
};
|
|
189
|
+
const collector = createTurnCollector(opts.onTurnEvent, {
|
|
190
|
+
secrets: live.options.secrets,
|
|
191
|
+
meter: live.meter,
|
|
192
|
+
...(onReceipt === undefined ? {} : { onReceipt }),
|
|
193
|
+
});
|
|
185
194
|
const release = live.router.attach(live.acp.agentSessionId, collector, AbortSignal.any([signal, live.gone.signal]));
|
|
186
195
|
try {
|
|
187
196
|
return await runPromptTurn(live.state, { text, signal, collector });
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import type { InitializeResponse, SessionConfigOption } from "@agentclientprotocol/sdk";
|
|
9
9
|
import type { AgentSessionProfile } from "@nathapp/nax-agent";
|
|
10
|
-
import type { AgentRegistryEntry, ModeSetting } from "#src/client/registry";
|
|
10
|
+
import type { AgentRegistryEntry, ModeSetting, ReadOnlyEnforcement } from "#src/client/registry";
|
|
11
11
|
export type CapabilityRecord = {
|
|
12
12
|
readonly protocolVersion: number;
|
|
13
13
|
readonly agentName?: string;
|
|
@@ -16,7 +16,7 @@ export type CapabilityRecord = {
|
|
|
16
16
|
readonly resume: boolean;
|
|
17
17
|
readonly close: boolean;
|
|
18
18
|
readonly mcpHttp: boolean;
|
|
19
|
-
/** The registry
|
|
19
|
+
/** The registry can enforce profiles none/read on this agent. */
|
|
20
20
|
readonly readOnlyMode: boolean;
|
|
21
21
|
/** The registry knows how to pre-approve embedder tools at the adapter (R12). */
|
|
22
22
|
readonly preApproval: boolean;
|
|
@@ -38,5 +38,11 @@ export declare function selectValues(option: SessionConfigOption): readonly stri
|
|
|
38
38
|
export declare function offersValue(options: readonly SessionConfigOption[], configId: string, value: string): boolean;
|
|
39
39
|
/** The id of the agent's model option (category "model") that offers `model`. */
|
|
40
40
|
export declare function modelOptionId(options: readonly SessionConfigOption[], model: string): string | undefined;
|
|
41
|
-
/**
|
|
41
|
+
/** Per-agent effort option ids, tried when no option has category "thought_level" (nax's EFFORT_OPTION_BY_AGENT). */
|
|
42
|
+
export declare const EFFORT_FALLBACK_IDS: Readonly<Record<string, string>>;
|
|
43
|
+
/** The option that sets `effort`: a "thought_level" option offering it, else the agent's fallback id offering it. */
|
|
44
|
+
export declare function effortOptionId(options: readonly SessionConfigOption[], agentName: string, effort: string): string | undefined;
|
|
45
|
+
/** The read-only enforcement a profile uses: the entry's for none/read, none otherwise. */
|
|
46
|
+
export declare function readOnlyFor(profile: AgentSessionProfile, entry: AgentRegistryEntry | undefined): ReadOnlyEnforcement | undefined;
|
|
47
|
+
/** The mode a profile selects (§6.4 layer 1): the read-only entry's for none/read, the default mode otherwise. */
|
|
42
48
|
export declare function modeFor(profile: AgentSessionProfile, entry: AgentRegistryEntry | undefined): ModeSetting | undefined;
|
|
@@ -21,16 +21,17 @@ export function buildCapabilityRecord(init, entry) {
|
|
|
21
21
|
resume: isObject(caps.sessionCapabilities?.resume),
|
|
22
22
|
close: isObject(caps.sessionCapabilities?.close),
|
|
23
23
|
mcpHttp: caps.mcpCapabilities?.http === true,
|
|
24
|
-
readOnlyMode: entry?.
|
|
24
|
+
readOnlyMode: entry?.readOnly !== undefined,
|
|
25
25
|
preApproval: entry?.preApproval !== undefined,
|
|
26
26
|
});
|
|
27
27
|
}
|
|
28
|
+
const isReadOnlyProfile = (profile) => profile === "none" || profile === "read";
|
|
28
29
|
/** The first requirement this agent cannot meet, or undefined. The model is checked after session/new. */
|
|
29
30
|
export function unmetRequirement(record, req) {
|
|
30
|
-
if ((req.profile
|
|
31
|
+
if (isReadOnlyProfile(req.profile) && !record.readOnlyMode) {
|
|
31
32
|
return {
|
|
32
33
|
capability: "profile",
|
|
33
|
-
reason: `profile "${req.profile}" needs
|
|
34
|
+
reason: `profile "${req.profile}" needs read-only enforcement; this agent has none`,
|
|
34
35
|
};
|
|
35
36
|
}
|
|
36
37
|
if (req.toolCount > 0 && !(record.mcpHttp && record.preApproval)) {
|
|
@@ -54,7 +55,27 @@ export function offersValue(options, configId, value) {
|
|
|
54
55
|
export function modelOptionId(options, model) {
|
|
55
56
|
return options.find((option) => option.category === "model" && selectValues(option).includes(model))?.id;
|
|
56
57
|
}
|
|
57
|
-
/**
|
|
58
|
+
/** Per-agent effort option ids, tried when no option has category "thought_level" (nax's EFFORT_OPTION_BY_AGENT). */
|
|
59
|
+
export const EFFORT_FALLBACK_IDS = Object.freeze({
|
|
60
|
+
claude: "effort",
|
|
61
|
+
codex: "reasoning_effort",
|
|
62
|
+
opencode: "effort",
|
|
63
|
+
pi: "thought_level",
|
|
64
|
+
});
|
|
65
|
+
/** The option that sets `effort`: a "thought_level" option offering it, else the agent's fallback id offering it. */
|
|
66
|
+
export function effortOptionId(options, agentName, effort) {
|
|
67
|
+
const offering = options.filter((option) => selectValues(option).includes(effort));
|
|
68
|
+
const byCategory = offering.find((option) => option.category === "thought_level");
|
|
69
|
+
if (byCategory !== undefined)
|
|
70
|
+
return byCategory.id;
|
|
71
|
+
const fallback = Object.hasOwn(EFFORT_FALLBACK_IDS, agentName) ? EFFORT_FALLBACK_IDS[agentName] : undefined;
|
|
72
|
+
return fallback === undefined ? undefined : offering.find((option) => option.id === fallback)?.id;
|
|
73
|
+
}
|
|
74
|
+
/** The read-only enforcement a profile uses: the entry's for none/read, none otherwise. */
|
|
75
|
+
export function readOnlyFor(profile, entry) {
|
|
76
|
+
return isReadOnlyProfile(profile) ? entry?.readOnly : undefined;
|
|
77
|
+
}
|
|
78
|
+
/** The mode a profile selects (§6.4 layer 1): the read-only entry's for none/read, the default mode otherwise. */
|
|
58
79
|
export function modeFor(profile, entry) {
|
|
59
|
-
return profile
|
|
80
|
+
return isReadOnlyProfile(profile) ? entry?.readOnly?.mode : entry?.defaultMode;
|
|
60
81
|
}
|
|
@@ -12,8 +12,10 @@
|
|
|
12
12
|
* companion (Claude's AskUserQuestion "Other" box): not asked on its own; a reply
|
|
13
13
|
* naming no choice becomes its value. Any other field type, a malformed or oversized
|
|
14
14
|
* choice list, too many fields, or a non-form request declines the form unasked;
|
|
15
|
-
* a reply naming no choice without a companion,
|
|
16
|
-
*
|
|
15
|
+
* a reply naming no choice without a companion, a reply naming no choice to a
|
|
16
|
+
* REQUIRED select (its companion only adds to a choice — filling it alone would
|
|
17
|
+
* omit the required key), or an empty reply to a required field, declines after
|
|
18
|
+
* asking. Each decline is noted with noteQuestion. No reply
|
|
17
19
|
* (deadline, cancel, turn end, process exit) cancels. Question text is agent data:
|
|
18
20
|
* control and invisible characters stripped, secrets scrubbed, capped.
|
|
19
21
|
*/
|
|
@@ -90,8 +90,21 @@ function parseForm(request) {
|
|
|
90
90
|
? { ok: true, fields: withCompanions(fields) }
|
|
91
91
|
: REFUSED;
|
|
92
92
|
}
|
|
93
|
+
/**
|
|
94
|
+
* The companion offer, only where a typed answer would be accepted: a required
|
|
95
|
+
* select must name a choice (filling only `<key>_custom` would omit the required
|
|
96
|
+
* key), so a required single-select gets no offer and a required multi-select
|
|
97
|
+
* gets one only beside a choice.
|
|
98
|
+
*/
|
|
99
|
+
function ownAnswerHint(field) {
|
|
100
|
+
if (field.companion === undefined)
|
|
101
|
+
return "";
|
|
102
|
+
if (!field.required)
|
|
103
|
+
return ", or type your own answer";
|
|
104
|
+
return field.kind === "multi" ? "; you may add your own after at least one choice" : "";
|
|
105
|
+
}
|
|
93
106
|
function instruction(field) {
|
|
94
|
-
const own = field
|
|
107
|
+
const own = ownAnswerHint(field);
|
|
95
108
|
const skip = field.required ? "" : " Leave empty to skip.";
|
|
96
109
|
if (field.kind === "single")
|
|
97
110
|
return `Reply with one number or choice${own}.${skip}`;
|
package/dist/client/errors.d.ts
CHANGED
|
@@ -17,7 +17,7 @@ export declare const ACP_STOP_CODES: Readonly<{
|
|
|
17
17
|
export type AcpStopCode = (typeof ACP_STOP_CODES)[keyof typeof ACP_STOP_CODES];
|
|
18
18
|
/** Agent text made safe for an error: control characters stripped (except \n, \t), secrets redacted, capped. */
|
|
19
19
|
export declare function agentTextExcerpt(text: string, secrets: readonly string[]): string;
|
|
20
|
-
export declare function capabilityUnsupported(capability: string, reason: string): AgentSessionError;
|
|
20
|
+
export declare function capabilityUnsupported(capability: string, reason: string, details?: Readonly<Record<string, unknown>>): AgentSessionError;
|
|
21
21
|
export declare function backendUnavailable(reason: string, details?: Readonly<Record<string, unknown>>): AgentSessionError;
|
|
22
22
|
export declare function closedDuringOpen(sessionId: string): AgentSessionError;
|
|
23
23
|
/** The session cannot run another turn: closed, or its agent is gone and cannot be reconnected (§6.3 step 5). */
|
|
@@ -30,6 +30,14 @@ export declare function rpcErrorOf(err: unknown): RequestError | undefined;
|
|
|
30
30
|
* message; only the redacted excerpt escapes (§7).
|
|
31
31
|
*/
|
|
32
32
|
export declare function openRequestError(step: string, err: RequestError, secrets: readonly string[]): AgentSessionError;
|
|
33
|
+
/**
|
|
34
|
+
* A rate limit, read from structured JSON-RPC error data only (S4b spec §8); never
|
|
35
|
+
* from message text. claude-agent-acp sends `data.errorKind: "rate_limit"` and no
|
|
36
|
+
* retry-after (S4b-0 finding a).
|
|
37
|
+
*/
|
|
38
|
+
export declare function rateLimitOf(data: unknown): {
|
|
39
|
+
readonly retryAfterSeconds?: number;
|
|
40
|
+
} | undefined;
|
|
33
41
|
/** A rejected session/prompt (§7: a JSON-RPC error on prompt is AGENT_SESSION_TURN_FAILED). */
|
|
34
42
|
export declare function promptRequestError(err: RequestError, secrets: readonly string[]): NaxError;
|
|
35
43
|
/** A stop reason other than end_turn. Own keys only: "__proto__" or "toString" is unknown, not a code. */
|
package/dist/client/errors.js
CHANGED
|
@@ -30,8 +30,8 @@ export const ACP_STOP_CODES = Object.freeze({
|
|
|
30
30
|
export function agentTextExcerpt(text, secrets) {
|
|
31
31
|
return capBytes(redactSecrets(scrubSecrets(stripControl(text), secrets)), EXCERPT_BYTES);
|
|
32
32
|
}
|
|
33
|
-
export function capabilityUnsupported(capability, reason) {
|
|
34
|
-
return new AgentSessionError(`The ACP agent cannot meet the "${capability}" requirement: ${reason}`, "AGENT_SESSION_CAPABILITY_UNSUPPORTED", { capability });
|
|
33
|
+
export function capabilityUnsupported(capability, reason, details = {}) {
|
|
34
|
+
return new AgentSessionError(`The ACP agent cannot meet the "${capability}" requirement: ${reason}`, "AGENT_SESSION_CAPABILITY_UNSUPPORTED", { ...details, capability });
|
|
35
35
|
}
|
|
36
36
|
export function backendUnavailable(reason, details = {}) {
|
|
37
37
|
return new AgentSessionError(`The ACP agent is unavailable: ${reason}`, "AGENT_SESSION_BACKEND_UNAVAILABLE", {
|
|
@@ -68,6 +68,16 @@ export function openRequestError(step, err, secrets) {
|
|
|
68
68
|
}
|
|
69
69
|
return backendUnavailable(`${step} failed: ${excerpt}`, { step, rpcCode: err.code });
|
|
70
70
|
}
|
|
71
|
+
/**
|
|
72
|
+
* A rate limit, read from structured JSON-RPC error data only (S4b spec §8); never
|
|
73
|
+
* from message text. claude-agent-acp sends `data.errorKind: "rate_limit"` and no
|
|
74
|
+
* retry-after (S4b-0 finding a).
|
|
75
|
+
*/
|
|
76
|
+
export function rateLimitOf(data) {
|
|
77
|
+
if (typeof data !== "object" || data === null || Array.isArray(data))
|
|
78
|
+
return undefined;
|
|
79
|
+
return "errorKind" in data && data.errorKind === "rate_limit" ? {} : undefined;
|
|
80
|
+
}
|
|
71
81
|
/** A rejected session/prompt (§7: a JSON-RPC error on prompt is AGENT_SESSION_TURN_FAILED). */
|
|
72
82
|
export function promptRequestError(err, secrets) {
|
|
73
83
|
const excerpt = agentTextExcerpt(err.message, secrets);
|
|
@@ -76,6 +86,13 @@ export function promptRequestError(err, secrets) {
|
|
|
76
86
|
step: "session/prompt",
|
|
77
87
|
});
|
|
78
88
|
}
|
|
89
|
+
const limit = rateLimitOf(err.data);
|
|
90
|
+
if (limit !== undefined) {
|
|
91
|
+
return new AgentSessionError(`The ACP agent was rate-limited: ${excerpt}`, "AGENT_SESSION_RATE_LIMITED", {
|
|
92
|
+
step: "session/prompt",
|
|
93
|
+
...limit,
|
|
94
|
+
});
|
|
95
|
+
}
|
|
79
96
|
return new NaxError(`The ACP prompt failed: ${excerpt}`, "AGENT_SESSION_TURN_FAILED", {
|
|
80
97
|
stage: "acp",
|
|
81
98
|
rpcCode: err.code,
|
package/dist/client/events.d.ts
CHANGED
|
@@ -7,7 +7,9 @@
|
|
|
7
7
|
* usage_update costs feed the session's cost meter (D5-b). User chunks, plans, mode,
|
|
8
8
|
* config and command updates, and anything unknown are dropped. finish() flushes
|
|
9
9
|
* held text and answers unanswered tool calls; settle(response) does that and then
|
|
10
|
-
* emits the turn's one usage event (D5-h).
|
|
10
|
+
* emits the turn's one usage event (D5-h). onReceipt fires once, on the first
|
|
11
|
+
* turn-content update or the settle, so the backend knows its instructions arrived
|
|
12
|
+
* (#2364). Nothing is emitted after finish(). The
|
|
11
13
|
* sink is the facade's; a throw from it is contained.
|
|
12
14
|
*/
|
|
13
15
|
import type { PromptResponse, SessionUpdate } from "@agentclientprotocol/sdk";
|
|
@@ -18,6 +20,8 @@ export interface CollectorOptions {
|
|
|
18
20
|
readonly secrets?: readonly string[];
|
|
19
21
|
/** The session's cost meter; a fresh one when absent. */
|
|
20
22
|
readonly meter?: CostMeter;
|
|
23
|
+
/** Called once, when the turn first shows the agent has the prompt: a turn-content update or the prompt's response (#2364). */
|
|
24
|
+
readonly onReceipt?: () => void;
|
|
21
25
|
}
|
|
22
26
|
export interface TurnCollector {
|
|
23
27
|
onUpdate(update: SessionUpdate): void;
|
package/dist/client/events.js
CHANGED
|
@@ -30,6 +30,19 @@ function containedSink(emit) {
|
|
|
30
30
|
}
|
|
31
31
|
};
|
|
32
32
|
}
|
|
33
|
+
/**
|
|
34
|
+
* Update kinds that prove the agent is working on the prompt (#2364). An allowlist:
|
|
35
|
+
* session-level updates (commands, mode, config, session info) and replayed history
|
|
36
|
+
* can arrive after attach but before the agent reads the prompt.
|
|
37
|
+
*/
|
|
38
|
+
const RECEIPT_KINDS = new Set([
|
|
39
|
+
"agent_message_chunk",
|
|
40
|
+
"agent_thought_chunk",
|
|
41
|
+
"tool_call",
|
|
42
|
+
"tool_call_update",
|
|
43
|
+
"usage_update",
|
|
44
|
+
"plan",
|
|
45
|
+
]);
|
|
33
46
|
export function createTurnCollector(emit, options = {}) {
|
|
34
47
|
const secrets = options.secrets ?? [];
|
|
35
48
|
const meter = options.meter ?? createCostMeter();
|
|
@@ -43,6 +56,18 @@ export function createTurnCollector(emit, options = {}) {
|
|
|
43
56
|
const parts = [];
|
|
44
57
|
let done = false;
|
|
45
58
|
let spend;
|
|
59
|
+
let received = false;
|
|
60
|
+
const receipt = () => {
|
|
61
|
+
if (received)
|
|
62
|
+
return;
|
|
63
|
+
received = true;
|
|
64
|
+
try {
|
|
65
|
+
options.onReceipt?.();
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
// The backend's bookkeeping must not break the turn.
|
|
69
|
+
}
|
|
70
|
+
};
|
|
46
71
|
const route = (update) => {
|
|
47
72
|
switch (update.sessionUpdate) {
|
|
48
73
|
case "agent_message_chunk":
|
|
@@ -75,8 +100,11 @@ export function createTurnCollector(emit, options = {}) {
|
|
|
75
100
|
};
|
|
76
101
|
return {
|
|
77
102
|
onUpdate(update) {
|
|
78
|
-
if (
|
|
79
|
-
|
|
103
|
+
if (done)
|
|
104
|
+
return;
|
|
105
|
+
if (RECEIPT_KINDS.has(update.sessionUpdate))
|
|
106
|
+
receipt();
|
|
107
|
+
route(update);
|
|
80
108
|
},
|
|
81
109
|
announce(toolCall) {
|
|
82
110
|
if (!done)
|
|
@@ -85,6 +113,7 @@ export function createTurnCollector(emit, options = {}) {
|
|
|
85
113
|
finish,
|
|
86
114
|
settle(response) {
|
|
87
115
|
finish();
|
|
116
|
+
receipt();
|
|
88
117
|
if (spend === undefined) {
|
|
89
118
|
spend = turnSpend(response, meter);
|
|
90
119
|
send(usageEvent(spend));
|
package/dist/client/index.d.ts
CHANGED
|
@@ -10,5 +10,6 @@
|
|
|
10
10
|
*/
|
|
11
11
|
export { acpBackend } from "#src/client/backend";
|
|
12
12
|
export { ACP_STOP_CODES, type AcpStopCode } from "#src/client/errors";
|
|
13
|
-
export
|
|
13
|
+
export { isAgentLaunchable, type LaunchCandidateKind, launchCandidateKind } from "#src/client/launchable";
|
|
14
|
+
export type { AcpAgentSpec, AcpBackendOptions, AcpProcessHooks } from "#src/client/options";
|
|
14
15
|
export type { AcpAgentName } from "#src/client/registry";
|
package/dist/client/index.js
CHANGED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { type AcpAgentName } from "#src/client/registry";
|
|
2
|
+
export type LaunchCandidateKind = "local" | "npx";
|
|
3
|
+
export declare function launchCandidateKind(agent: AcpAgentName, env?: Readonly<Record<string, string | undefined>>): LaunchCandidateKind | undefined;
|
|
4
|
+
export declare function isAgentLaunchable(agent: AcpAgentName, env?: Readonly<Record<string, string | undefined>>): boolean;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether a registered agent can be launched on this machine (S4b spec §6.8):
|
|
3
|
+
* the same candidate resolution the backend uses at spawn (§6.10), exposed so an
|
|
4
|
+
* embedder's "is installed" check never duplicates the candidate list. "npx"
|
|
5
|
+
* means only the npx fallback resolves: the first open downloads the launcher.
|
|
6
|
+
*/
|
|
7
|
+
import { pickCandidate } from "#src/client/launch";
|
|
8
|
+
import { registryEntry } from "#src/client/registry";
|
|
9
|
+
export function launchCandidateKind(agent, env = process.env) {
|
|
10
|
+
const found = pickCandidate(registryEntry(agent)?.launch ?? [], env.PATH);
|
|
11
|
+
if (found === undefined)
|
|
12
|
+
return undefined;
|
|
13
|
+
return found.command === "npx" ? "npx" : "local";
|
|
14
|
+
}
|
|
15
|
+
export function isAgentLaunchable(agent, env = process.env) {
|
|
16
|
+
return launchCandidateKind(agent, env) !== undefined;
|
|
17
|
+
}
|