@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.
Files changed (87) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +117 -22
  3. package/bin/nax-agent.js +4 -0
  4. package/dist/client/backend.js +11 -2
  5. package/dist/client/capabilities.d.ts +9 -3
  6. package/dist/client/capabilities.js +26 -5
  7. package/dist/client/elicitation.d.ts +4 -2
  8. package/dist/client/elicitation.js +14 -1
  9. package/dist/client/errors.d.ts +9 -1
  10. package/dist/client/errors.js +19 -2
  11. package/dist/client/events.d.ts +5 -1
  12. package/dist/client/events.js +31 -2
  13. package/dist/client/index.d.ts +2 -1
  14. package/dist/client/index.js +1 -0
  15. package/dist/client/launchable.d.ts +4 -0
  16. package/dist/client/launchable.js +17 -0
  17. package/dist/client/open.js +75 -13
  18. package/dist/client/options.d.ts +11 -0
  19. package/dist/client/options.js +17 -3
  20. package/dist/client/permissions.d.ts +2 -2
  21. package/dist/client/pre-approval.d.ts +5 -13
  22. package/dist/client/pre-approval.js +3 -10
  23. package/dist/client/registry.d.ts +15 -2
  24. package/dist/client/registry.js +22 -2
  25. package/dist/client/tool-calls.js +0 -4
  26. package/dist/client/tool-events.d.ts +8 -1
  27. package/dist/client/tool-events.js +39 -6
  28. package/dist/client/turn.js +28 -8
  29. package/dist/server/auth.d.ts +45 -0
  30. package/dist/server/auth.js +87 -0
  31. package/dist/server/capabilities.d.ts +7 -0
  32. package/dist/server/capabilities.js +19 -0
  33. package/dist/server/cli.d.ts +26 -0
  34. package/dist/server/cli.js +87 -0
  35. package/dist/server/client-port.d.ts +39 -0
  36. package/dist/server/client-port.js +49 -0
  37. package/dist/server/connection.d.ts +22 -0
  38. package/dist/server/connection.js +56 -0
  39. package/dist/server/errors.d.ts +21 -0
  40. package/dist/server/errors.js +70 -0
  41. package/dist/server/index.d.ts +4 -3
  42. package/dist/server/index.js +6 -1
  43. package/dist/server/logger.d.ts +7 -0
  44. package/dist/server/logger.js +25 -0
  45. package/dist/server/login.d.ts +18 -0
  46. package/dist/server/login.js +29 -0
  47. package/dist/server/main.d.ts +19 -0
  48. package/dist/server/main.js +120 -0
  49. package/dist/server/nax-config.d.ts +30 -0
  50. package/dist/server/nax-config.js +138 -0
  51. package/dist/server/open-session.d.ts +37 -0
  52. package/dist/server/open-session.js +55 -0
  53. package/dist/server/options.d.ts +27 -0
  54. package/dist/server/options.js +55 -0
  55. package/dist/server/permissions.d.ts +44 -0
  56. package/dist/server/permissions.js +157 -0
  57. package/dist/server/process-entry.d.ts +15 -0
  58. package/dist/server/process-entry.js +28 -0
  59. package/dist/server/prompt.d.ts +8 -0
  60. package/dist/server/prompt.js +29 -0
  61. package/dist/server/questions.d.ts +33 -0
  62. package/dist/server/questions.js +79 -0
  63. package/dist/server/registry-open.d.ts +33 -0
  64. package/dist/server/registry-open.js +62 -0
  65. package/dist/server/registry.d.ts +64 -0
  66. package/dist/server/registry.js +262 -0
  67. package/dist/server/server-session.d.ts +43 -0
  68. package/dist/server/server-session.js +221 -0
  69. package/dist/server/session-config.d.ts +27 -0
  70. package/dist/server/session-config.js +93 -0
  71. package/dist/server/storage.d.ts +49 -0
  72. package/dist/server/storage.js +191 -0
  73. package/dist/server/translate/diff.d.ts +30 -0
  74. package/dist/server/translate/diff.js +81 -0
  75. package/dist/server/translate/events.d.ts +37 -0
  76. package/dist/server/translate/events.js +126 -0
  77. package/dist/server/translate/notice.d.ts +10 -0
  78. package/dist/server/translate/notice.js +14 -0
  79. package/dist/server/translate/replay.d.ts +11 -0
  80. package/dist/server/translate/replay.js +53 -0
  81. package/dist/server/translate/stop.d.ts +22 -0
  82. package/dist/server/translate/stop.js +48 -0
  83. package/dist/server/translate/tool-kind.d.ts +9 -0
  84. package/dist/server/translate/tool-kind.js +67 -0
  85. package/dist/server/version.d.ts +1 -0
  86. package/dist/server/version.js +17 -0
  87. 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: pre-release (0.3.0, not yet published).** `acpBackend()` serves sessions
8
- under all four profiles, with thinking, tool and usage events, questions from the
9
- agent, embedder tools on Claude, resume across processes and reconnect after a
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 mode, and this client's
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 | Agent mode (Claude) | Permission requests |
109
+ | Profile | Claude's setup | Permission requests |
94
110
  |---|---|---|
95
- | `none` | `plan` | rejected, recorded as `decidedBy: "profile"` |
96
- | `read` | `plan` | rejected, recorded as `decidedBy: "profile"` |
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 mode,
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 cannot call `ExitPlanMode`. Left available, its
107
- refused plan would end the turn as cancelled. The `_meta` that blocks it is part
108
- of what Claude's adapter compares on resume, so resuming under another profile
109
- may rebuild the agent's session.
110
- - Plan mode lets Claude write its own plan file under `~/.claude/plans/` without
111
- asking, so `none` and `read` do not stop that write.
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`.
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { runCli } from "../dist/server/index.js";
3
+
4
+ process.exitCode = await runCli(process);
@@ -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
- const collector = createTurnCollector(opts.onTurnEvent, { secrets: live.options.secrets, meter: live.meter });
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 has a read-only mode for profiles none/read. */
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
- /** The mode a profile selects (§6.4 layer 1): read-only for none/read, the default mode otherwise. */
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?.readOnlyMode !== undefined,
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 === "none" || req.profile === "read") && !record.readOnlyMode) {
31
+ if (isReadOnlyProfile(req.profile) && !record.readOnlyMode) {
31
32
  return {
32
33
  capability: "profile",
33
- reason: `profile "${req.profile}" needs a read-only agent mode; this agent has none`,
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
- /** The mode a profile selects (§6.4 layer 1): read-only for none/read, the default mode otherwise. */
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 === "none" || profile === "read" ? entry?.readOnlyMode : entry?.defaultMode;
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, or an empty reply to a required
16
- * field, declines after asking. Each decline is noted with noteQuestion. No reply
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.companion === undefined ? "" : ", or type your own answer";
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}`;
@@ -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. */
@@ -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,
@@ -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). Nothing is emitted after finish(). The
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;
@@ -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 (!done)
79
- route(update);
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));
@@ -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 type { AcpAgentSpec, AcpBackendOptions } from "#src/client/options";
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";
@@ -10,3 +10,4 @@
10
10
  */
11
11
  export { acpBackend } from "#src/client/backend";
12
12
  export { ACP_STOP_CODES } from "#src/client/errors";
13
+ export { isAgentLaunchable, launchCandidateKind } from "#src/client/launchable";
@@ -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
+ }