@nathapp/nax-agent-acp 0.91.7-canary.9 → 0.91.7

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 CHANGED
@@ -3,6 +3,22 @@
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.91.7] - 2026-11-01
7
+
8
+ - No changes in this package. Released in lockstep with the other nax packages.
9
+
10
+ ## [0.91.7-canary.12] - 2026-11-01
11
+
12
+ - No changes in this package. Released in lockstep with the other nax packages.
13
+
14
+ ## [0.91.7-canary.11] - 2026-10-31
15
+
16
+ - No changes in this package. Released in lockstep with the other nax packages.
17
+
18
+ ## [0.91.7-canary.10] - 2026-10-30
19
+
20
+ - No changes in this package. Released in lockstep with the other nax packages.
21
+
6
22
  ## [0.91.7-canary.9] - 2026-10-30
7
23
 
8
24
  - No changes in this package. Released in lockstep with the other nax packages.
@@ -20,7 +20,7 @@
20
20
  * is written to the transcript document after each priced turn, so a resume in a
21
21
  * new process prices its first turn from it (D6-a).
22
22
  */
23
- import { getLogger, NO_OP_INTERACTION_HANDLER, } from "@nathapp/nax-agent";
23
+ import { getLogger, NaxError, NO_OP_INTERACTION_HANDLER, } from "@nathapp/nax-agent";
24
24
  import { answerElicitation } from "#src/client/elicitation";
25
25
  import { sessionLost } from "#src/client/errors";
26
26
  import { createTurnCollector } from "#src/client/events";
@@ -32,6 +32,7 @@ import { createOwnToolLedger } from "#src/client/own-tool-calls";
32
32
  import { decidePermission } from "#src/client/permissions";
33
33
  import { race } from "#src/client/race";
34
34
  import { canRestore, storedSessionOf } from "#src/client/resume";
35
+ import { configureAcpSession } from "#src/client/session-configure";
35
36
  import { shellSandboxPlan } from "#src/client/shell-sandbox";
36
37
  import { createToolCalls } from "#src/client/tool-calls";
37
38
  import { createToolHost, newToolHostServerName, newToolHostToken } from "#src/client/tool-host";
@@ -161,6 +162,7 @@ async function openBackend(base, ctx) {
161
162
  const live = await connect(base, ctx, restore, [], serverName);
162
163
  return assemble({
163
164
  base,
165
+ configOptions: live.acp.configOptions,
164
166
  ctx,
165
167
  serverName,
166
168
  live,
@@ -198,6 +200,8 @@ function assemble(s) {
198
200
  return infoOf(s);
199
201
  },
200
202
  turnOpts: () => ({ interactionHandler: NO_OP_INTERACTION_HANDLER }),
203
+ acceptsImages: async () => s.live.acp.record.image,
204
+ configure: (change) => configure(s, change),
201
205
  close: () => {
202
206
  s.closing ??= shutdown(s);
203
207
  return s.closing;
@@ -233,6 +237,7 @@ async function reconnect(s, signal) {
233
237
  const ctx = { ...s.ctx, openSignal: AbortSignal.any([s.ctx.openSignal, signal]) };
234
238
  try {
235
239
  s.live = await connect(s.base, ctx, restore, old.tokens, s.serverName);
240
+ s.configOptions = s.live.acp.configOptions;
236
241
  return s.live;
237
242
  }
238
243
  catch (err) {
@@ -241,9 +246,30 @@ async function reconnect(s, signal) {
241
246
  throw err;
242
247
  }
243
248
  }
249
+ /** US-002: model and effort set on the live process; each accepted part is recorded for a reconnect. */
250
+ async function configure(s, change) {
251
+ const live = await liveFor(s, s.ctx.openSignal);
252
+ await configureAcpSession({
253
+ link: live.acp.link,
254
+ agentSessionId: live.acp.agentSessionId,
255
+ agentName: s.base.agentName,
256
+ secrets: live.options.secrets,
257
+ timeoutMs: s.base.initializeTimeoutMs,
258
+ signal: s.ctx.openSignal,
259
+ sessionId: s.ctx.sessionId,
260
+ configOptions: s.configOptions,
261
+ change,
262
+ }, (part, configOptions) => {
263
+ s.base = Object.freeze({ ...s.base, ...part });
264
+ s.configOptions = configOptions;
265
+ });
266
+ }
244
267
  async function sendTurn(s, prompt, opts) {
245
268
  const signal = opts.signal ?? s.ctx.turnSignal();
246
269
  const live = await liveFor(s, signal);
270
+ if (opts.images?.length && !live.acp.record.image) {
271
+ throw new NaxError("[acp] The agent does not support image input", "ACP_IMAGE_INPUT_UNSUPPORTED", { stage: "acp" });
272
+ }
247
273
  const instructions = s.instructionsSent ? undefined : s.ctx.instructions;
248
274
  const text = instructions === undefined || instructions === "" ? prompt : `${instructions}\n\n${prompt}`;
249
275
  // #2364: delivered once the agent shows it has the prompt, not when it is sent.
@@ -260,7 +286,12 @@ async function sendTurn(s, prompt, opts) {
260
286
  });
261
287
  const release = live.router.attach(live.acp.agentSessionId, collector, AbortSignal.any([signal, live.gone.signal]));
262
288
  try {
263
- return await runPromptTurn(live.state, { text, signal, collector });
289
+ return await runPromptTurn(live.state, {
290
+ text,
291
+ signal,
292
+ collector,
293
+ ...(opts.images === undefined ? {} : { images: opts.images }),
294
+ });
264
295
  }
265
296
  finally {
266
297
  await release();
@@ -17,6 +17,7 @@ export type CapabilityRecord = {
17
17
  readonly resume: boolean;
18
18
  readonly close: boolean;
19
19
  readonly mcpHttp: boolean;
20
+ readonly image: boolean;
20
21
  /** The registry can enforce profiles none/read on this agent. */
21
22
  readonly readOnlyMode: boolean;
22
23
  /** The registry knows how to pre-approve embedder tools at the adapter (R12). */
@@ -23,6 +23,7 @@ export function buildCapabilityRecord(init, entry) {
23
23
  resume: isObject(caps.sessionCapabilities?.resume),
24
24
  close: isObject(caps.sessionCapabilities?.close),
25
25
  mcpHttp: caps.mcpCapabilities?.http === true,
26
+ image: caps.promptCapabilities?.image === true,
26
27
  readOnlyMode: entry?.readOnly !== undefined,
27
28
  preApproval: entry?.preApproval !== undefined,
28
29
  ownToolCalls: entry?.mcpCallIdentity !== undefined,
@@ -11,7 +11,7 @@
11
11
  * bounded by initializeTimeoutMs (D-c) and by openSignal: close() during open
12
12
  * rejects AGENT_SESSION_CLOSED.
13
13
  */
14
- import { type ClientCapabilities } from "@agentclientprotocol/sdk";
14
+ import { type ClientCapabilities, type SessionConfigOption } from "@agentclientprotocol/sdk";
15
15
  import { type AgentSessionProfile, type BackendOpenContext } from "@nathapp/nax-agent";
16
16
  import { type CapabilityRecord } from "#src/client/capabilities";
17
17
  import { type AcpLink, type InboundHandlers } from "#src/client/connection";
@@ -33,8 +33,15 @@ export interface OpenedAcp {
33
33
  readonly startupBanner?: string;
34
34
  /** The models and efforts the agent offered once the mode and model were applied. */
35
35
  readonly offered: OfferedChoices;
36
+ /**
37
+ * The config options the agent last reported: the answer to the last config request open
38
+ * sent, else the session/new or restore answer's. `configure` resolves against them.
39
+ */
40
+ readonly configOptions: readonly SessionConfigOption[];
36
41
  }
37
42
  /** `restore`: restore that stored agent session instead of creating one (§6.9). */
38
43
  export declare function openAcpSession(options: ResolvedAcpOptions, ctx: BackendOpenContext, handlers: InboundHandlers, launch: LaunchFn, host?: ToolHost, restore?: Restore): Promise<OpenedAcp>;
39
44
  /** §6.3 step 1.1: no fs and no terminal (R11); form elicitation under ask and full (§6.8, D5-l). */
40
45
  export declare function clientCapabilitiesFor(profile: AgentSessionProfile): ClientCapabilities;
46
+ /** The model ids the config options offer, raw: category "model" values in offer order. */
47
+ export declare function configModelIds(options: readonly SessionConfigOption[]): string[];
@@ -125,7 +125,7 @@ async function establish(o) {
125
125
  const session = o.restore === undefined
126
126
  ? await newSession(o, setup)
127
127
  : await restoreSession(o.restore, record, setup, o.link, (label, request) => step(o, label, request));
128
- const finalOffers = await applyConfig(o, session.agentSessionId, session.offers);
128
+ const applied = await applyConfig(o, session.agentSessionId, session.offers);
129
129
  if (o.restore === undefined) {
130
130
  await o.ctx.transcriptStore.save(o.ctx.sessionId, initialDoc(o, record, session.agentSessionId));
131
131
  }
@@ -135,7 +135,8 @@ async function establish(o) {
135
135
  record,
136
136
  agentSessionId: session.agentSessionId,
137
137
  cwd: session.cwd,
138
- offered: offeredChoices(finalOffers, o.options.agentName, o.options.secrets),
138
+ offered: offeredChoices(applied.offers, o.options.agentName, o.options.secrets),
139
+ configOptions: applied.configOptions,
139
140
  ...(session.restoredWith === undefined ? {} : { restoredWith: session.restoredWith }),
140
141
  ...(session.startupBanner === undefined ? {} : { startupBanner: session.startupBanner }),
141
142
  };
@@ -195,8 +196,8 @@ async function sessionSetup(o, sandbox) {
195
196
  async function applyConfig(o, sessionId, offers) {
196
197
  const afterMode = await applyMode(o, sessionId, offers);
197
198
  const afterModel = await applyModel(o, sessionId, afterMode);
198
- await applyEffort(o, sessionId, afterModel);
199
- return afterModel;
199
+ const afterEffort = await applyEffort(o, sessionId, afterModel);
200
+ return { offers: afterModel, configOptions: afterEffort.configOptions };
200
201
  }
201
202
  /**
202
203
  * The profile's mode. A config option offering the value is used first (the ACP 1.x
@@ -221,12 +222,12 @@ async function applyMode(o, sessionId, offers) {
221
222
  /** At most this many offered ids, each cleaned and capped, go into a model refusal (agent-supplied text). */
222
223
  const MAX_OFFERED_MODELS = 50;
223
224
  /** The model ids the config options offer, raw: category "model" values in offer order. */
224
- function configModelIds(offers) {
225
- return offers.configOptions.filter((option) => option.category === "model").flatMap((option) => selectValues(option));
225
+ export function configModelIds(options) {
226
+ return options.filter((option) => option.category === "model").flatMap((option) => selectValues(option));
226
227
  }
227
228
  /** The model ids a refusal names: the config options' ids first, then the legacy `models` block's, capped. */
228
229
  function offeredModels(offers, secrets) {
229
- return [...configModelIds(offers), ...offers.modelIds]
230
+ return [...configModelIds(offers.configOptions), ...offers.modelIds]
230
231
  .slice(0, MAX_OFFERED_MODELS)
231
232
  .map((id) => cleanLabel(id, secrets, MODEL_ID_MAX_CHARS) ?? "")
232
233
  .filter((id) => id !== "");
@@ -243,7 +244,7 @@ async function applyModel(o, sessionId, offers) {
243
244
  const requested = o.options.model;
244
245
  if (requested === undefined)
245
246
  return offers;
246
- const fromOptions = configModelIds(offers);
247
+ const fromOptions = configModelIds(offers.configOptions);
247
248
  const model = resolveModelValue(o.options.agentName, fromOptions.length > 0 ? fromOptions : offers.modelIds, requested, o.options.secrets);
248
249
  const configId = modelOptionId(offers.configOptions, model);
249
250
  if (configId !== undefined) {
@@ -261,16 +262,17 @@ async function applyModel(o, sessionId, offers) {
261
262
  async function applyEffort(o, sessionId, offers) {
262
263
  const effort = o.options.effort;
263
264
  if (effort === undefined)
264
- return;
265
+ return offers;
265
266
  const configId = effortOptionId(offers.configOptions, o.options.agentName, effort);
266
267
  if (configId === undefined) {
267
268
  getLogger().warn("acp", "The agent offers no effort option for this value; effort skipped", {
268
269
  agent: o.options.agentName,
269
270
  effort,
270
271
  });
271
- return;
272
+ return offers;
272
273
  }
273
- await step(o, "session/set_config_option", o.link.setConfigOption({ sessionId, configId, value: effort }));
274
+ const set = await step(o, "session/set_config_option", o.link.setConfigOption({ sessionId, configId, value: effort }));
275
+ return { ...offers, configOptions: set.configOptions ?? offers.configOptions };
274
276
  }
275
277
  function initialDoc(o, record, agentSessionId) {
276
278
  return {
@@ -0,0 +1,38 @@
1
+ /**
2
+ * OpenedBackend.configure over ACP (chat-acp-switch-and-replay US-002): the model and
3
+ * the effort are set on the live agent session with session/set_config_option, the
4
+ * same request open sends (open.ts applyModel / applyEffort). The model goes first;
5
+ * the effort option is then looked up in the options the model response returned, so
6
+ * an agent whose effort choices depend on the model is handled. An unoffered model or
7
+ * effort refuses before any request (open skips an unoffered effort instead). Each
8
+ * request is bounded by `timeoutMs` and the session's open signal, as an open step is,
9
+ * and a JSON-RPC error is classified by openRequestError. `onApplied` hears each part
10
+ * the moment its request succeeds, so a later failure never hides what the live agent
11
+ * already holds. Only config options are used: the legacy session/set_model is not.
12
+ */
13
+ import type { SessionConfigOption } from "@agentclientprotocol/sdk";
14
+ import type { SessionConfigureInput } from "@nathapp/nax-agent";
15
+ import type { AcpLink } from "#src/client/connection";
16
+ /** One part of a configure that the agent has accepted. `model` is the value sent (resolved). */
17
+ export type AppliedPart = {
18
+ readonly model: string;
19
+ } | {
20
+ readonly effort: string;
21
+ };
22
+ export interface ConfigureAcpInput {
23
+ readonly link: AcpLink;
24
+ readonly agentSessionId: string;
25
+ readonly agentName: string;
26
+ readonly secrets: readonly string[];
27
+ readonly timeoutMs: number;
28
+ readonly signal: AbortSignal;
29
+ readonly sessionId: string;
30
+ /** The session's current config options. */
31
+ readonly configOptions: readonly SessionConfigOption[];
32
+ readonly change: SessionConfigureInput;
33
+ }
34
+ /**
35
+ * Applies `change`; resolves with the config options after the last request sent (the
36
+ * input's when none was). `onApplied(part, configOptions)` runs right after each request succeeds.
37
+ */
38
+ export declare function configureAcpSession(input: ConfigureAcpInput, onApplied?: (part: AppliedPart, configOptions: readonly SessionConfigOption[]) => void): Promise<readonly SessionConfigOption[]>;
@@ -0,0 +1,65 @@
1
+ import { effortOptionId, MODEL_ID_MAX_CHARS, modelOptionId, resolveModelValue } from "#src/client/capabilities";
2
+ import { agentTextExcerpt, backendUnavailable, capabilityUnsupported, closedDuringOpen, openRequestError, rpcErrorOf, } from "#src/client/errors";
3
+ import { configModelIds } from "#src/client/open";
4
+ import { race } from "#src/client/race";
5
+ import { cleanLabel } from "#src/client/text";
6
+ const STEP = "session/set_config_option";
7
+ /** At most this many offered ids go into a model refusal (agent-supplied text). */
8
+ const MAX_OFFERED_MODELS = 50;
9
+ /**
10
+ * Applies `change`; resolves with the config options after the last request sent (the
11
+ * input's when none was). `onApplied(part, configOptions)` runs right after each request succeeds.
12
+ */
13
+ export async function configureAcpSession(input, onApplied = () => { }) {
14
+ let options = input.configOptions;
15
+ const { model, effort } = input.change;
16
+ if (model !== undefined) {
17
+ const value = resolveModel(input, options, model);
18
+ const configId = modelOptionId(options, value);
19
+ if (configId === undefined)
20
+ throw modelRefusal(input, options, value);
21
+ options = await setOption(input, options, configId, value);
22
+ onApplied({ model: value }, options);
23
+ }
24
+ if (effort !== undefined) {
25
+ const configId = effortOptionId(options, input.agentName, effort);
26
+ if (configId === undefined) {
27
+ throw capabilityUnsupported("effort", `the agent offers no effort option "${effort}"`);
28
+ }
29
+ options = await setOption(input, options, configId, effort);
30
+ onApplied({ effort }, options);
31
+ }
32
+ return options;
33
+ }
34
+ function resolveModel(input, options, model) {
35
+ return resolveModelValue(input.agentName, configModelIds(options), model, input.secrets);
36
+ }
37
+ function modelRefusal(input, options, model) {
38
+ const ids = configModelIds(options)
39
+ .slice(0, MAX_OFFERED_MODELS)
40
+ .map((id) => cleanLabel(id, input.secrets, MODEL_ID_MAX_CHARS) ?? "")
41
+ .filter((id) => id !== "");
42
+ return capabilityUnsupported("model", `the agent offers no model option "${model}"; offered: ${ids.length === 0 ? "(none)" : ids.join(", ")}`, { offered: ids });
43
+ }
44
+ /** One bounded session/set_config_option; the options its answer carries, else the ones it was sent against. */
45
+ async function setOption(input, current, configId, value) {
46
+ const result = await race(input.link.setConfigOption({ sessionId: input.agentSessionId, configId, value }), {
47
+ timeoutMs: input.timeoutMs,
48
+ signal: input.signal,
49
+ });
50
+ switch (result.kind) {
51
+ case "ok":
52
+ return result.value.configOptions ?? current;
53
+ case "aborted":
54
+ throw closedDuringOpen(input.sessionId);
55
+ case "timeout":
56
+ throw backendUnavailable(`${STEP} timed out after ${input.timeoutMs} ms`, { during: STEP });
57
+ case "failed": {
58
+ const rpc = rpcErrorOf(result.error);
59
+ if (rpc !== undefined)
60
+ throw openRequestError(STEP, rpc, input.secrets);
61
+ const message = result.error instanceof Error ? result.error.message : String(result.error);
62
+ throw backendUnavailable(`${STEP} failed: ${agentTextExcerpt(message, input.secrets)}`, { step: STEP });
63
+ }
64
+ }
65
+ }
@@ -1,4 +1,4 @@
1
- import { type TurnResult } from "@nathapp/nax-agent";
1
+ import { type ImageAttachment, type TurnResult } from "@nathapp/nax-agent";
2
2
  import type { AcpLink } from "#src/client/connection";
3
3
  import type { TurnCollector } from "#src/client/events";
4
4
  import { type LaunchedAgent } from "#src/client/launch";
@@ -13,6 +13,7 @@ export interface TurnState {
13
13
  }
14
14
  export interface TurnInput {
15
15
  readonly text: string;
16
+ readonly images?: readonly ImageAttachment[];
16
17
  readonly signal: AbortSignal;
17
18
  readonly collector: TurnCollector;
18
19
  }
@@ -1,4 +1,4 @@
1
- import { attachTurnSpend, NaxError } from "@nathapp/nax-agent";
1
+ import { attachTurnSpend, NaxError, } from "@nathapp/nax-agent";
2
2
  import { emptyTurnError, promptRequestError, rpcErrorOf, stopReasonError } from "#src/client/errors";
3
3
  import { agentGoneError } from "#src/client/launch";
4
4
  import { race } from "#src/client/race";
@@ -19,7 +19,7 @@ export async function runPromptTurn(state, input) {
19
19
  let carried;
20
20
  for (let continuation = 0;; continuation += 1) {
21
21
  const denialsBefore = input.collector.denials();
22
- const response = await promptOnce(state, input, text, carried);
22
+ const response = await promptOnce(state, input, { text, carried, firstPrompt: continuation === 0 });
23
23
  const usage = sumUsage(carried, response.usage);
24
24
  const continueAfterDenial = response.stopReason === "cancelled" &&
25
25
  !input.signal.aborted &&
@@ -36,10 +36,15 @@ export async function runPromptTurn(state, input) {
36
36
  * already answered and no cost (the cost reading moves to the next turn); an abort
37
37
  * throws with the spend of every prompt this turn answered.
38
38
  */
39
- async function promptOnce(state, input, text, carried) {
39
+ async function promptOnce(state, input, prompt) {
40
+ const { text, carried, firstPrompt } = prompt;
41
+ const images = firstPrompt ? (input.images ?? []) : [];
40
42
  const pending = state.link.prompt({
41
43
  sessionId: state.agentSessionId,
42
- prompt: [{ type: "text", text }],
44
+ prompt: [
45
+ ...images.map((image) => ({ type: "image", mimeType: image.mimeType, data: image.data })),
46
+ { type: "text", text },
47
+ ],
43
48
  });
44
49
  const outcome = await race(pending, { signal: input.signal });
45
50
  switch (outcome.kind) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nathapp/nax-agent-acp",
3
- "version": "0.91.7-canary.9",
3
+ "version": "0.91.7",
4
4
  "description": "ACP (Agent Client Protocol) backend for @nathapp/nax-agent sessions: drive Claude Code and other ACP agents through the nax-agent session API.",
5
5
  "license": "MIT",
6
6
  "author": "William Khoo",
@@ -49,12 +49,12 @@
49
49
  "zod": "^4.3.6"
50
50
  },
51
51
  "peerDependencies": {
52
- "@nathapp/nax-agent": "^0.91.7-canary.9"
52
+ "@nathapp/nax-agent": "^0.91.7"
53
53
  },
54
54
  "publishConfig": {
55
55
  "access": "public",
56
56
  "registry": "https://registry.npmjs.org/",
57
57
  "provenance": true,
58
- "tag": "canary"
58
+ "tag": "latest"
59
59
  }
60
60
  }