@nathapp/nax-agent-acp 0.90.0 → 0.90.2
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 +29 -0
- package/README.md +3 -1
- package/dist/client/backend.js +30 -6
- package/dist/client/capabilities.d.ts +35 -2
- package/dist/client/capabilities.js +61 -4
- package/dist/client/connection.d.ts +10 -1
- package/dist/client/connection.js +4 -0
- package/dist/client/cursor-sandbox.d.ts +5 -0
- package/dist/client/cursor-sandbox.js +60 -0
- package/dist/client/errors.d.ts +6 -0
- package/dist/client/errors.js +9 -0
- package/dist/client/events.d.ts +13 -0
- package/dist/client/events.js +34 -3
- package/dist/client/inbound.d.ts +2 -1
- package/dist/client/inbound.js +11 -2
- package/dist/client/index.d.ts +1 -0
- package/dist/client/open.d.ts +2 -0
- package/dist/client/open.js +82 -34
- package/dist/client/opencode-sandbox.d.ts +15 -0
- package/dist/client/opencode-sandbox.js +94 -0
- package/dist/client/options.d.ts +38 -0
- package/dist/client/options.js +54 -2
- package/dist/client/permissions.d.ts +25 -1
- package/dist/client/permissions.js +79 -12
- package/dist/client/pi-sandbox.d.ts +2 -0
- package/dist/client/pi-sandbox.js +22 -0
- package/dist/client/policy-files.d.ts +21 -0
- package/dist/client/policy-files.js +73 -0
- package/dist/client/registry.d.ts +33 -9
- package/dist/client/registry.js +130 -9
- package/dist/client/resume.d.ts +5 -3
- package/dist/client/resume.js +3 -2
- package/dist/client/rule-policy.d.ts +55 -0
- package/dist/client/rule-policy.js +181 -0
- package/dist/client/session-offers.d.ts +18 -0
- package/dist/client/session-offers.js +32 -0
- package/dist/client/shell-rules.d.ts +22 -0
- package/dist/client/shell-rules.js +134 -0
- package/dist/client/shell-sandbox.d.ts +38 -0
- package/dist/client/shell-sandbox.js +107 -0
- package/dist/client/startup-banner.d.ts +1 -0
- package/dist/client/startup-banner.js +16 -0
- package/dist/client/turn.d.ts +3 -0
- package/dist/client/turn.js +40 -9
- package/dist/client/usage.d.ts +3 -1
- package/dist/client/usage.js +23 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,35 @@
|
|
|
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.90.2] - 2026-10-18
|
|
7
|
+
|
|
8
|
+
- Shell sandbox for opencode, Cursor and pi under `review` (nax#2589). With the new
|
|
9
|
+
`shellSandbox` option and a session sandbox policy, every shell command those agents run
|
|
10
|
+
is rewritten into `<runtime> <runner> -- <policy file> <command>` and allowed with
|
|
11
|
+
`REVIEW_EXECUTE_REASON`, as for Claude. The rewrite happens through a nax-written pi
|
|
12
|
+
extension that wraps `bash` at spawn, an opencode V2 plugin (opencode runs with
|
|
13
|
+
`OPENCODE_DISABLE_PROJECT_CONFIG=1`, and nax carries the repo's `AGENTS.md` into its config
|
|
14
|
+
dir), and a Cursor `preToolUse` hook under a nax-owned `HOME`, where nax also verifies the
|
|
15
|
+
exact wrapper. `Bash` deny and ask rules still reject a matching command. An unavailable
|
|
16
|
+
sandbox keeps the previous behaviour. Known limitations (documented in the permissions
|
|
17
|
+
guide): extensions, plugins or hooks that run after nax's can rewrite a command, and only
|
|
18
|
+
shell commands are sandboxed.
|
|
19
|
+
- Cursor under `review` runs in its `agent` mode when the caller has a `Bash` allow rule,
|
|
20
|
+
instead of `ask`, whose prompt made the model refuse to try any shell command, so the
|
|
21
|
+
operator's allowed commands never reached nax. Writes stay denied by the isolated
|
|
22
|
+
`cli-config.json`, and nax still decides every shell request (nax#2592). In `agent` mode the
|
|
23
|
+
model does try to write, so a repository `.cursor/cli.json` that allows writes (already a known,
|
|
24
|
+
documented override) now lets them land.
|
|
25
|
+
- A turn that ends `end_turn` with no reply text, thought or tool call and no tokens now
|
|
26
|
+
ends `errored` with `ACP_EMPTY_TURN`, instead of `completed` with an empty answer. pi-acp
|
|
27
|
+
ends a turn this way when pi's model call fails at the provider (nax#2591).
|
|
28
|
+
- pi-acp's startup banner (`_meta.piAcp.startupInfo` on `session/new`) is no longer part of
|
|
29
|
+
the first turn's output or text deltas (nax#2591).
|
|
30
|
+
|
|
31
|
+
## [0.90.1] - 2026-10-17
|
|
32
|
+
|
|
33
|
+
- No changes in this package. Released in lockstep with the other nax packages.
|
|
34
|
+
|
|
6
35
|
## [0.90.0] - 2026-10-17
|
|
7
36
|
|
|
8
37
|
- No changes in this package. Released in lockstep with the other nax packages.
|
package/README.md
CHANGED
|
@@ -31,7 +31,9 @@ What to know:
|
|
|
31
31
|
`inheritEnv: true` hands it your whole environment instead, credentials included.
|
|
32
32
|
- **Instructions** are prepended to the first prompt only; ACP has no system prompt.
|
|
33
33
|
- **Stop reasons.** A turn that stops for anything but `end_turn` ends `errored` with
|
|
34
|
-
an `ACP_STOP_*` code (`ACP_STOP_CODES`).
|
|
34
|
+
an `ACP_STOP_*` code (`ACP_STOP_CODES`). An `end_turn` with no reply text, thought or
|
|
35
|
+
tool call and no tokens ends `errored` with `ACP_EMPTY_TURN`: an agent that swallows
|
|
36
|
+
its model call's failure ends a turn this way (pi-acp on a provider error).
|
|
35
37
|
- **Model and effort.** `model` and `effort` are set through `session/set_config_option`,
|
|
36
38
|
after the profile's mode: the model only when the agent offers it (else
|
|
37
39
|
`AGENT_SESSION_CAPABILITY_UNSUPPORTED`), the effort through the agent's `thought_level`
|
package/dist/client/backend.js
CHANGED
|
@@ -31,6 +31,7 @@ import { resolveAcpOptions } from "#src/client/options";
|
|
|
31
31
|
import { decidePermission } from "#src/client/permissions";
|
|
32
32
|
import { race } from "#src/client/race";
|
|
33
33
|
import { canRestore, storedSessionOf } from "#src/client/resume";
|
|
34
|
+
import { shellSandboxPlan } from "#src/client/shell-sandbox";
|
|
34
35
|
import { createToolCalls } from "#src/client/tool-calls";
|
|
35
36
|
import { createToolHost, newToolHostToken } from "#src/client/tool-host";
|
|
36
37
|
import { runPromptTurn } from "#src/client/turn";
|
|
@@ -73,14 +74,34 @@ export function toolHostFor(ctx, router, secrets, token) {
|
|
|
73
74
|
});
|
|
74
75
|
return _acpBackendDeps.createToolHost(calls, token, toolHostOptions(ctx));
|
|
75
76
|
}
|
|
76
|
-
/**
|
|
77
|
-
|
|
77
|
+
/**
|
|
78
|
+
* Permission requests and elicitations, decided by profile with the session's
|
|
79
|
+
* redaction set. nax#2372: the embedder sandbox joins the permission context only
|
|
80
|
+
* for an agent that actually receives it (one with a pre-approval channel); for any
|
|
81
|
+
* other, a policy there would approve an escalation the agent never sandboxed.
|
|
82
|
+
* US-003: the agent's name (which raw field carries a shell command) and the
|
|
83
|
+
* session's rules join it too, so review with no sandbox can adjudicate a command.
|
|
84
|
+
*/
|
|
85
|
+
function routerFor(ctx, options) {
|
|
86
|
+
const entry = options.entry;
|
|
87
|
+
const sandbox = entry?.preApproval !== undefined && ctx.sandbox?.kind === "policy" ? ctx.sandbox.policy : undefined;
|
|
78
88
|
const base = {
|
|
79
89
|
profile: ctx.profile,
|
|
80
90
|
asks: ctx.asks,
|
|
81
|
-
secrets,
|
|
91
|
+
secrets: options.secrets,
|
|
82
92
|
cwd: ctx.workdir,
|
|
83
|
-
|
|
93
|
+
agentName: options.agentName,
|
|
94
|
+
rules: options.rules,
|
|
95
|
+
...(sandbox === undefined ? {} : { sandbox }),
|
|
96
|
+
...(options.shellSandboxPlan === undefined
|
|
97
|
+
? {}
|
|
98
|
+
: {
|
|
99
|
+
shellSandbox: {
|
|
100
|
+
prefix: options.shellSandboxPlan.prefix,
|
|
101
|
+
verify: options.shellSandboxPlan.verify,
|
|
102
|
+
onUnwrapped: options.shellSandboxPlan.onUnwrapped,
|
|
103
|
+
},
|
|
104
|
+
}),
|
|
84
105
|
};
|
|
85
106
|
return createInboundRouter((request, signal) => decidePermission(request, { ...base, signal }), (request, signal) => answerElicitation(request, { ...base, signal }));
|
|
86
107
|
}
|
|
@@ -88,9 +109,11 @@ function routerFor(ctx, secrets) {
|
|
|
88
109
|
async function connect(base, ctx, restore, retiredTokens) {
|
|
89
110
|
const token = ctx.tools.length > 0 ? newToolHostToken() : undefined;
|
|
90
111
|
const tokens = token === undefined ? retiredTokens : [...retiredTokens, token];
|
|
91
|
-
const
|
|
112
|
+
const tokenOptions = withTokens(base, tokens);
|
|
113
|
+
const plan = await shellSandboxPlan(ctx.profile, tokenOptions, ctx.sandbox, ctx.workdir);
|
|
114
|
+
const options = Object.freeze({ ...tokenOptions, ...(plan === undefined ? {} : { shellSandboxPlan: plan }) });
|
|
92
115
|
const gone = new AbortController();
|
|
93
|
-
const router = routerFor(ctx, options
|
|
116
|
+
const router = routerFor(ctx, options);
|
|
94
117
|
const host = toolHostFor(ctx, router, options.secrets, token);
|
|
95
118
|
const acp = await openAcpSession(options, ctx, router.handlers, _acpBackendDeps.launch, host, restore).catch(async (err) => {
|
|
96
119
|
await host?.stop();
|
|
@@ -209,6 +232,7 @@ async function sendTurn(s, prompt, opts) {
|
|
|
209
232
|
secrets: live.options.secrets,
|
|
210
233
|
meter: live.meter,
|
|
211
234
|
...(onReceipt === undefined ? {} : { onReceipt }),
|
|
235
|
+
...(live.acp.startupBanner === undefined ? {} : { startupBanner: live.acp.startupBanner }),
|
|
212
236
|
});
|
|
213
237
|
const release = live.router.attach(live.acp.agentSessionId, collector, AbortSignal.any([signal, live.gone.signal]));
|
|
214
238
|
try {
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
import type { InitializeResponse, SessionConfigOption } from "@agentclientprotocol/sdk";
|
|
9
9
|
import type { AgentSessionProfile } from "@nathapp/nax-agent";
|
|
10
10
|
import type { AgentRegistryEntry, ModeSetting, ReadOnlyEnforcement } from "#src/client/registry";
|
|
11
|
+
import type { AcpPermissionRules } from "#src/client/rule-policy";
|
|
11
12
|
export type CapabilityRecord = {
|
|
12
13
|
readonly protocolVersion: number;
|
|
13
14
|
readonly agentName?: string;
|
|
@@ -31,6 +32,8 @@ export interface UnmetRequirement {
|
|
|
31
32
|
readonly reason: string;
|
|
32
33
|
}
|
|
33
34
|
export declare function buildCapabilityRecord(init: InitializeResponse, entry: AgentRegistryEntry | undefined): CapabilityRecord;
|
|
35
|
+
/** none, read and review (nax#2500) run with the agent's own write tools removed. */
|
|
36
|
+
export declare const isReadOnlyProfile: (profile: AgentSessionProfile) => profile is "none" | "read" | "review";
|
|
34
37
|
/** The first requirement this agent cannot meet, or undefined. The model is checked after session/new. */
|
|
35
38
|
export declare function unmetRequirement(record: CapabilityRecord, req: Requirements): UnmetRequirement | undefined;
|
|
36
39
|
/** The value ids a select option offers, groups flattened; none for a boolean option. */
|
|
@@ -38,11 +41,41 @@ export declare function selectValues(option: SessionConfigOption): readonly stri
|
|
|
38
41
|
export declare function offersValue(options: readonly SessionConfigOption[], configId: string, value: string): boolean;
|
|
39
42
|
/** The id of the agent's model option (category "model") that offers `model`. */
|
|
40
43
|
export declare function modelOptionId(options: readonly SessionConfigOption[], model: string): string | undefined;
|
|
44
|
+
/** At most this many characters of an agent-supplied model id go into a refusal (agent text). */
|
|
45
|
+
export declare const MODEL_ID_MAX_CHARS = 100;
|
|
46
|
+
/**
|
|
47
|
+
* The model value to set (SPEC-cursor-pi-acp-read-only US-001). Cursor's model ids carry
|
|
48
|
+
* their settings (`gpt-5.5[context=272k,reasoning=medium]`, Auto is `default[]`), so a
|
|
49
|
+
* configured bare name matches no offered id exactly: the one offered id that starts with
|
|
50
|
+
* `requested + "["` is used instead. Two or more are ambiguous and refuse the open, naming
|
|
51
|
+
* each; none, another agent's name and an exact offer all keep `requested`, so the caller's
|
|
52
|
+
* existing "not offered" refusal follows.
|
|
53
|
+
*/
|
|
54
|
+
export declare function resolveModelValue(agentName: string, offered: readonly string[], requested: string, secrets: readonly string[]): string;
|
|
41
55
|
/** Per-agent effort option ids, tried when no option has category "thought_level" (nax's EFFORT_OPTION_BY_AGENT). */
|
|
42
56
|
export declare const EFFORT_FALLBACK_IDS: Readonly<Record<string, string>>;
|
|
43
57
|
/** The option that sets `effort`: a "thought_level" option offering it, else the agent's fallback id offering it. */
|
|
44
58
|
export declare function effortOptionId(options: readonly SessionConfigOption[], agentName: string, effort: string): string | undefined;
|
|
45
59
|
/** The read-only enforcement a profile uses: the entry's for none/read, none otherwise. */
|
|
46
60
|
export declare function readOnlyFor(profile: AgentSessionProfile, entry: AgentRegistryEntry | undefined): ReadOnlyEnforcement | undefined;
|
|
47
|
-
/**
|
|
48
|
-
|
|
61
|
+
/**
|
|
62
|
+
* Whether nax decides this profile's shell requests by the operator's Bash rules:
|
|
63
|
+
* only `review` has a shell tool to police, and only when a Bash allow rule could
|
|
64
|
+
* ever allow a command (an unconditional allow is not needed: each command is asked
|
|
65
|
+
* of nax, shell-rules.ts). `read` keeps no shell tool, `none` no tool. It gates pi's
|
|
66
|
+
* shell gate (rule-policy.ts) and Cursor's review mode (nax#2372, nax#2592).
|
|
67
|
+
*/
|
|
68
|
+
export declare function reviewDecidesShell(profile: AgentSessionProfile, rules: AcpPermissionRules | undefined): boolean;
|
|
69
|
+
/**
|
|
70
|
+
* The mode a profile selects (§6.4 layer 1): the read-only entry's for none/read/review,
|
|
71
|
+
* the default mode otherwise. Under `review` with a Bash allow rule, an entry's
|
|
72
|
+
* `reviewShellMode` wins (nax#2592).
|
|
73
|
+
*/
|
|
74
|
+
export declare function modeFor(profile: AgentSessionProfile, entry: AgentRegistryEntry | undefined, rules?: AcpPermissionRules, shellSandboxed?: boolean): ModeSetting | undefined;
|
|
75
|
+
/**
|
|
76
|
+
* The environment a profile adds to the agent process (nax#2372): opencode's
|
|
77
|
+
* permission policy for none/read/review, `{}` for every other profile and for any
|
|
78
|
+
* agent that enforces read-only another way. The caller spreads this over its own
|
|
79
|
+
* env, so the enforcement value cannot be weakened by a caller-supplied variable.
|
|
80
|
+
*/
|
|
81
|
+
export declare function launchEnvFor(profile: AgentSessionProfile, entry: AgentRegistryEntry | undefined): Readonly<Record<string, string>>;
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { capabilityUnsupported } from "#src/client/errors";
|
|
2
|
+
import { cleanLabel } from "#src/client/text";
|
|
1
3
|
const LABEL_MAX_CHARS = 200;
|
|
2
4
|
function isObject(value) {
|
|
3
5
|
return typeof value === "object" && value !== null;
|
|
@@ -26,7 +28,9 @@ export function buildCapabilityRecord(init, entry) {
|
|
|
26
28
|
});
|
|
27
29
|
}
|
|
28
30
|
/** none, read and review (nax#2500) run with the agent's own write tools removed. */
|
|
29
|
-
const isReadOnlyProfile = (profile) => profile === "none" || profile === "read" || profile === "review";
|
|
31
|
+
export const isReadOnlyProfile = (profile) => profile === "none" || profile === "read" || profile === "review";
|
|
32
|
+
/** No injected environment: the common answer for full, ask and every mode-only agent. */
|
|
33
|
+
const NO_LAUNCH_ENV = Object.freeze({});
|
|
30
34
|
/** The first requirement this agent cannot meet, or undefined. The model is checked after session/new. */
|
|
31
35
|
export function unmetRequirement(record, req) {
|
|
32
36
|
if (isReadOnlyProfile(req.profile) && !record.readOnlyMode) {
|
|
@@ -56,6 +60,29 @@ export function offersValue(options, configId, value) {
|
|
|
56
60
|
export function modelOptionId(options, model) {
|
|
57
61
|
return options.find((option) => option.category === "model" && selectValues(option).includes(model))?.id;
|
|
58
62
|
}
|
|
63
|
+
/** At most this many characters of an agent-supplied model id go into a refusal (agent text). */
|
|
64
|
+
export const MODEL_ID_MAX_CHARS = 100;
|
|
65
|
+
/**
|
|
66
|
+
* The model value to set (SPEC-cursor-pi-acp-read-only US-001). Cursor's model ids carry
|
|
67
|
+
* their settings (`gpt-5.5[context=272k,reasoning=medium]`, Auto is `default[]`), so a
|
|
68
|
+
* configured bare name matches no offered id exactly: the one offered id that starts with
|
|
69
|
+
* `requested + "["` is used instead. Two or more are ambiguous and refuse the open, naming
|
|
70
|
+
* each; none, another agent's name and an exact offer all keep `requested`, so the caller's
|
|
71
|
+
* existing "not offered" refusal follows.
|
|
72
|
+
*/
|
|
73
|
+
export function resolveModelValue(agentName, offered, requested, secrets) {
|
|
74
|
+
if (agentName !== "cursor" || offered.includes(requested))
|
|
75
|
+
return requested;
|
|
76
|
+
const matches = offered.filter((id) => id.startsWith(`${requested}[`));
|
|
77
|
+
if (matches.length <= 1) {
|
|
78
|
+
const [only] = matches;
|
|
79
|
+
return only ?? requested;
|
|
80
|
+
}
|
|
81
|
+
const named = matches.map((id) => cleanLabel(id, secrets, MODEL_ID_MAX_CHARS) ?? "").filter((id) => id !== "");
|
|
82
|
+
throw capabilityUnsupported("model", `"${requested}" matches several offered models: ${named.join(", ")}`, {
|
|
83
|
+
offered: named,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
59
86
|
/** Per-agent effort option ids, tried when no option has category "thought_level" (nax's EFFORT_OPTION_BY_AGENT). */
|
|
60
87
|
export const EFFORT_FALLBACK_IDS = Object.freeze({
|
|
61
88
|
claude: "effort",
|
|
@@ -76,7 +103,37 @@ export function effortOptionId(options, agentName, effort) {
|
|
|
76
103
|
export function readOnlyFor(profile, entry) {
|
|
77
104
|
return isReadOnlyProfile(profile) ? entry?.readOnly : undefined;
|
|
78
105
|
}
|
|
79
|
-
/**
|
|
80
|
-
|
|
81
|
-
|
|
106
|
+
/**
|
|
107
|
+
* Whether nax decides this profile's shell requests by the operator's Bash rules:
|
|
108
|
+
* only `review` has a shell tool to police, and only when a Bash allow rule could
|
|
109
|
+
* ever allow a command (an unconditional allow is not needed: each command is asked
|
|
110
|
+
* of nax, shell-rules.ts). `read` keeps no shell tool, `none` no tool. It gates pi's
|
|
111
|
+
* shell gate (rule-policy.ts) and Cursor's review mode (nax#2372, nax#2592).
|
|
112
|
+
*/
|
|
113
|
+
export function reviewDecidesShell(profile, rules) {
|
|
114
|
+
return profile === "review" && (rules?.allow.some((rule) => rule.tool === "Bash") ?? false);
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* The mode a profile selects (§6.4 layer 1): the read-only entry's for none/read/review,
|
|
118
|
+
* the default mode otherwise. Under `review` with a Bash allow rule, an entry's
|
|
119
|
+
* `reviewShellMode` wins (nax#2592).
|
|
120
|
+
*/
|
|
121
|
+
export function modeFor(profile, entry, rules, shellSandboxed) {
|
|
122
|
+
if (!isReadOnlyProfile(profile))
|
|
123
|
+
return entry?.defaultMode;
|
|
124
|
+
const shellMode = reviewDecidesShell(profile, rules) || (profile === "review" && shellSandboxed === true)
|
|
125
|
+
? entry?.readOnly?.reviewShellMode
|
|
126
|
+
: undefined;
|
|
127
|
+
return shellMode ?? entry?.readOnly?.mode;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* The environment a profile adds to the agent process (nax#2372): opencode's
|
|
131
|
+
* permission policy for none/read/review, `{}` for every other profile and for any
|
|
132
|
+
* agent that enforces read-only another way. The caller spreads this over its own
|
|
133
|
+
* env, so the enforcement value cannot be weakened by a caller-supplied variable.
|
|
134
|
+
*/
|
|
135
|
+
export function launchEnvFor(profile, entry) {
|
|
136
|
+
if (!isReadOnlyProfile(profile))
|
|
137
|
+
return NO_LAUNCH_ENV;
|
|
138
|
+
return entry?.readOnly?.launchEnv[profile] ?? NO_LAUNCH_ENV;
|
|
82
139
|
}
|
|
@@ -7,8 +7,10 @@
|
|
|
7
7
|
* backend's handlers. Requests are not bounded here: callers race them (race.ts),
|
|
8
8
|
* because the SDK's cancellation is cooperative and still waits for the agent's answer.
|
|
9
9
|
*/
|
|
10
|
-
import { type CreateElicitationRequest, type CreateElicitationResponse, type InitializeRequest, type InitializeResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type RequestPermissionRequest, type RequestPermissionResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SessionNotification, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse } from "@agentclientprotocol/sdk";
|
|
10
|
+
import { type CreateElicitationRequest, type CreateElicitationResponse, type InitializeRequest, type InitializeResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type RequestPermissionRequest, type RequestPermissionResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SessionNotification, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
|
|
11
11
|
import type { LaunchTarget } from "#src/client/launch";
|
|
12
|
+
/** The legacy model method (Gemini); ACP 1.x's method table does not carry it. */
|
|
13
|
+
export declare const SET_MODEL_METHOD = "session/set_model";
|
|
12
14
|
export interface InboundHandlers {
|
|
13
15
|
onUpdate(notification: SessionNotification): void;
|
|
14
16
|
onPermission(request: RequestPermissionRequest): Promise<RequestPermissionResponse>;
|
|
@@ -20,6 +22,13 @@ export interface AcpLink {
|
|
|
20
22
|
resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse>;
|
|
21
23
|
loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse>;
|
|
22
24
|
setConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
|
|
25
|
+
/** The legacy mode method an agent offering only a `modes` block understands (Gemini). */
|
|
26
|
+
setMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse>;
|
|
27
|
+
/** The legacy model method (`SET_MODEL_METHOD`), whose answer carries nothing nax reads. */
|
|
28
|
+
setModel(params: {
|
|
29
|
+
readonly sessionId: string;
|
|
30
|
+
readonly modelId: string;
|
|
31
|
+
}): Promise<unknown>;
|
|
23
32
|
prompt(params: PromptRequest): Promise<PromptResponse>;
|
|
24
33
|
cancel(sessionId: string): Promise<void>;
|
|
25
34
|
closeSession(sessionId: string): Promise<void>;
|
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
* because the SDK's cancellation is cooperative and still waits for the agent's answer.
|
|
9
9
|
*/
|
|
10
10
|
import { client, methods, } from "@agentclientprotocol/sdk";
|
|
11
|
+
/** The legacy model method (Gemini); ACP 1.x's method table does not carry it. */
|
|
12
|
+
export const SET_MODEL_METHOD = "session/set_model";
|
|
11
13
|
export function openConnection(target, handlers) {
|
|
12
14
|
const app = client({ name: "nax-agent-acp" })
|
|
13
15
|
.onNotification(methods.client.session.update, (ctx) => handlers.onUpdate(ctx.params))
|
|
@@ -21,6 +23,8 @@ export function openConnection(target, handlers) {
|
|
|
21
23
|
resumeSession: (params) => agent.request(methods.agent.session.resume, params),
|
|
22
24
|
loadSession: (params) => agent.request(methods.agent.session.load, params),
|
|
23
25
|
setConfigOption: (params) => agent.request(methods.agent.session.setConfigOption, params),
|
|
26
|
+
setMode: (params) => agent.request(methods.agent.session.setMode, params),
|
|
27
|
+
setModel: (params) => agent.request(SET_MODEL_METHOD, params),
|
|
24
28
|
prompt: (params) => agent.request(methods.agent.session.prompt, params),
|
|
25
29
|
cancel: (sessionId) => agent.notify(methods.agent.session.cancel, { sessionId }),
|
|
26
30
|
closeSession: async (sessionId) => {
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { type ShellSandboxPlan } from "#src/client/shell-sandbox";
|
|
2
|
+
/** A malformed hook event fails closed; non-command tools need no rewrite. */
|
|
3
|
+
export declare function cursorSandboxHookSource(prefix: string): string;
|
|
4
|
+
/** Every open rewrites both private files through the shared atomic writer. */
|
|
5
|
+
export declare function cursorSandboxEnv(plan: ShellSandboxPlan, cursorConfigDir: string): Promise<Readonly<Record<string, string>>>;
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/** Cursor reads hooks only beneath HOME; isolate that HOME, not the command's home. */
|
|
2
|
+
import { dirname, join } from "node:path";
|
|
3
|
+
import { backendUnavailable } from "#src/client/errors";
|
|
4
|
+
import { digest, writeStateFile } from "#src/client/policy-files";
|
|
5
|
+
import { _shellSandboxDeps, sandboxWrapSnippet, shellQuote } from "#src/client/shell-sandbox";
|
|
6
|
+
/** A malformed hook event fails closed; non-command tools need no rewrite. */
|
|
7
|
+
export function cursorSandboxHookSource(prefix) {
|
|
8
|
+
return `${sandboxWrapSnippet(prefix)}
|
|
9
|
+
try {
|
|
10
|
+
let input = "";
|
|
11
|
+
process.stdin.setEncoding("utf8");
|
|
12
|
+
for await (const chunk of process.stdin) input += chunk;
|
|
13
|
+
const event = JSON.parse(input);
|
|
14
|
+
const toolInput = event?.tool_input;
|
|
15
|
+
const result = typeof toolInput?.command === "string"
|
|
16
|
+
? { updated_input: { ...toolInput, command: naxSandboxWrap(toolInput.command) } }
|
|
17
|
+
: {};
|
|
18
|
+
process.stdout.write(JSON.stringify(result));
|
|
19
|
+
} catch {
|
|
20
|
+
process.exitCode = 1;
|
|
21
|
+
}
|
|
22
|
+
`;
|
|
23
|
+
}
|
|
24
|
+
async function linkKeychains(home, realHome) {
|
|
25
|
+
const path = join(home, "Library", "Keychains");
|
|
26
|
+
const target = join(realHome, "Library", "Keychains");
|
|
27
|
+
try {
|
|
28
|
+
await _shellSandboxDeps.mkdir(dirname(path), { recursive: true, mode: 0o700 });
|
|
29
|
+
try {
|
|
30
|
+
await _shellSandboxDeps.symlink(target, path);
|
|
31
|
+
}
|
|
32
|
+
catch (cause) {
|
|
33
|
+
// Reuse and concurrent opens are safe only for this exact link target.
|
|
34
|
+
if (!(cause instanceof Error && "code" in cause && cause.code === "EEXIST"))
|
|
35
|
+
throw cause;
|
|
36
|
+
if ((await _shellSandboxDeps.readlink(path)) !== target)
|
|
37
|
+
throw cause;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
catch (cause) {
|
|
41
|
+
throw backendUnavailable(`the Cursor keychain link "${path}" could not be created`, { path, cause });
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
/** Every open rewrites both private files through the shared atomic writer. */
|
|
45
|
+
export async function cursorSandboxEnv(plan, cursorConfigDir) {
|
|
46
|
+
// Planning owns the invariant <stateDir>/sandbox/policy-<digest>.json.
|
|
47
|
+
const stateDir = dirname(dirname(plan.policyFile));
|
|
48
|
+
const source = cursorSandboxHookSource(plan.prefix);
|
|
49
|
+
const hookFile = await writeStateFile(stateDir, join("cursor", `sandbox-hook-${digest(source)}.mjs`), source, 0o600);
|
|
50
|
+
const content = JSON.stringify({
|
|
51
|
+
version: 1,
|
|
52
|
+
hooks: { preToolUse: [{ command: `${shellQuote(plan.runtime)} ${shellQuote(hookFile)}`, failClosed: true }] },
|
|
53
|
+
});
|
|
54
|
+
const relativeHome = join("cursor-home", digest(content));
|
|
55
|
+
await writeStateFile(stateDir, join(relativeHome, ".cursor", "hooks.json"), content, 0o600);
|
|
56
|
+
const home = join(stateDir, relativeHome);
|
|
57
|
+
if (_shellSandboxDeps.platform() === "darwin")
|
|
58
|
+
await linkKeychains(home, plan.home);
|
|
59
|
+
return Object.freeze({ CURSOR_CONFIG_DIR: cursorConfigDir, HOME: home });
|
|
60
|
+
}
|
package/dist/client/errors.d.ts
CHANGED
|
@@ -42,3 +42,9 @@ export declare function rateLimitOf(data: unknown): {
|
|
|
42
42
|
export declare function promptRequestError(err: RequestError, secrets: readonly string[]): NaxError;
|
|
43
43
|
/** A stop reason other than end_turn. Own keys only: "__proto__" or "toString" is unknown, not a code. */
|
|
44
44
|
export declare function stopReasonError(stopReason: string): NaxError;
|
|
45
|
+
/**
|
|
46
|
+
* nax#2591: an end_turn that showed no work (no reply text, thought or tool call)
|
|
47
|
+
* and reported no tokens. An agent that swallows its model call's failure ends the
|
|
48
|
+
* turn this way (pi-acp on a provider 402), so it is a failure, not an empty answer.
|
|
49
|
+
*/
|
|
50
|
+
export declare function emptyTurnError(): NaxError;
|
package/dist/client/errors.js
CHANGED
|
@@ -107,3 +107,12 @@ export function stopReasonError(stopReason) {
|
|
|
107
107
|
const shown = agentTextExcerpt(stopReason, []).slice(0, 64);
|
|
108
108
|
return new NaxError(`The ACP agent ended the turn with an unknown stop reason "${shown}"`, "AGENT_SESSION_TURN_FAILED", { stage: "acp", stopReason: shown });
|
|
109
109
|
}
|
|
110
|
+
/**
|
|
111
|
+
* nax#2591: an end_turn that showed no work (no reply text, thought or tool call)
|
|
112
|
+
* and reported no tokens. An agent that swallows its model call's failure ends the
|
|
113
|
+
* turn this way (pi-acp on a provider 402), so it is a failure, not an empty answer.
|
|
114
|
+
*/
|
|
115
|
+
export function emptyTurnError() {
|
|
116
|
+
return new NaxError("The ACP agent ended the turn without a reply, a tool call or any tokens; its model call likely failed " +
|
|
117
|
+
"(check the agent's provider, credit and model)", "ACP_EMPTY_TURN", { stage: "acp", stopReason: "end_turn" });
|
|
118
|
+
}
|
package/dist/client/events.d.ts
CHANGED
|
@@ -11,6 +11,11 @@
|
|
|
11
11
|
* turn-content update or the settle, so the backend knows its instructions arrived
|
|
12
12
|
* (#2364). Nothing is emitted after finish(). The
|
|
13
13
|
* sink is the facade's; a throw from it is contained.
|
|
14
|
+
*
|
|
15
|
+
* nax#2591: the agent's startup banner (pi-acp's `startupInfo`, sent as one message
|
|
16
|
+
* chunk that lands in the first turn) is dropped whole: it is not the agent's reply
|
|
17
|
+
* and does not show the agent read the prompt. worked() tells whether the turn showed
|
|
18
|
+
* any work: a non-empty reply or thought chunk (any non-text content counts), or a tool call.
|
|
14
19
|
*/
|
|
15
20
|
import type { PromptResponse, SessionUpdate } from "@agentclientprotocol/sdk";
|
|
16
21
|
import type { TurnEventSink } from "@nathapp/nax-agent";
|
|
@@ -22,6 +27,8 @@ export interface CollectorOptions {
|
|
|
22
27
|
readonly meter?: CostMeter;
|
|
23
28
|
/** Called once, when the turn first shows the agent has the prompt: a turn-content update or the prompt's response (#2364). */
|
|
24
29
|
readonly onReceipt?: () => void;
|
|
30
|
+
/** The session's startup banner, from session/new (nax#2591): a message chunk of exactly this text is dropped. */
|
|
31
|
+
readonly startupBanner?: string;
|
|
25
32
|
}
|
|
26
33
|
export interface TurnCollector {
|
|
27
34
|
onUpdate(update: SessionUpdate): void;
|
|
@@ -33,5 +40,11 @@ export interface TurnCollector {
|
|
|
33
40
|
settle(response: PromptResponse): TurnSpend;
|
|
34
41
|
/** The turn's agent message text, scrubbed (turn_end.output). */
|
|
35
42
|
output(): string;
|
|
43
|
+
/** A permission request of this turn was answered with a deny (nax#2582). */
|
|
44
|
+
noteDenial(): void;
|
|
45
|
+
/** Denials answered so far in this turn. */
|
|
46
|
+
denials(): number;
|
|
47
|
+
/** The turn showed work: reply text, a thought or a tool call (nax#2591). */
|
|
48
|
+
worked(): boolean;
|
|
36
49
|
}
|
|
37
50
|
export declare function createTurnCollector(emit: TurnEventSink | undefined, options?: CollectorOptions): TurnCollector;
|
package/dist/client/events.js
CHANGED
|
@@ -30,6 +30,26 @@ function containedSink(emit) {
|
|
|
30
30
|
}
|
|
31
31
|
};
|
|
32
32
|
}
|
|
33
|
+
/** Update kinds that show the agent worked on the prompt (nax#2591); usage and plans alone do not. */
|
|
34
|
+
const WORK_KINDS = new Set([
|
|
35
|
+
"agent_message_chunk",
|
|
36
|
+
"agent_thought_chunk",
|
|
37
|
+
"tool_call",
|
|
38
|
+
"tool_call_update",
|
|
39
|
+
]);
|
|
40
|
+
function isBanner(update, banner) {
|
|
41
|
+
return (banner !== undefined &&
|
|
42
|
+
update.sessionUpdate === "agent_message_chunk" &&
|
|
43
|
+
update.content.type === "text" &&
|
|
44
|
+
update.content.text === banner);
|
|
45
|
+
}
|
|
46
|
+
function showsWork(update) {
|
|
47
|
+
if (!WORK_KINDS.has(update.sessionUpdate))
|
|
48
|
+
return false;
|
|
49
|
+
if (update.sessionUpdate !== "agent_message_chunk" && update.sessionUpdate !== "agent_thought_chunk")
|
|
50
|
+
return true;
|
|
51
|
+
return update.content.type !== "text" || update.content.text !== "";
|
|
52
|
+
}
|
|
33
53
|
/**
|
|
34
54
|
* Update kinds that prove the agent is working on the prompt (#2364). An allowlist:
|
|
35
55
|
* session-level updates (commands, mode, config, session info) and replayed history
|
|
@@ -57,6 +77,8 @@ export function createTurnCollector(emit, options = {}) {
|
|
|
57
77
|
let done = false;
|
|
58
78
|
let spend;
|
|
59
79
|
let received = false;
|
|
80
|
+
let denials = 0;
|
|
81
|
+
let worked = false;
|
|
60
82
|
const receipt = () => {
|
|
61
83
|
if (received)
|
|
62
84
|
return;
|
|
@@ -100,15 +122,19 @@ export function createTurnCollector(emit, options = {}) {
|
|
|
100
122
|
};
|
|
101
123
|
return {
|
|
102
124
|
onUpdate(update) {
|
|
103
|
-
if (done)
|
|
125
|
+
if (done || isBanner(update, options.startupBanner))
|
|
104
126
|
return;
|
|
105
127
|
if (RECEIPT_KINDS.has(update.sessionUpdate))
|
|
106
128
|
receipt();
|
|
129
|
+
if (showsWork(update))
|
|
130
|
+
worked = true;
|
|
107
131
|
route(update);
|
|
108
132
|
},
|
|
109
133
|
announce(toolCall) {
|
|
110
|
-
if (
|
|
111
|
-
|
|
134
|
+
if (done)
|
|
135
|
+
return;
|
|
136
|
+
worked = true;
|
|
137
|
+
tools.announce(toolCall);
|
|
112
138
|
},
|
|
113
139
|
finish,
|
|
114
140
|
settle(response) {
|
|
@@ -121,5 +147,10 @@ export function createTurnCollector(emit, options = {}) {
|
|
|
121
147
|
return spend;
|
|
122
148
|
},
|
|
123
149
|
output: () => scrubSecrets(parts.join(""), secrets),
|
|
150
|
+
noteDenial() {
|
|
151
|
+
denials += 1;
|
|
152
|
+
},
|
|
153
|
+
denials: () => denials,
|
|
154
|
+
worked: () => worked,
|
|
124
155
|
};
|
|
125
156
|
}
|
package/dist/client/inbound.d.ts
CHANGED
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
* elicitation handler with the binding's signal, which aborts when the turn is
|
|
8
8
|
* cancelled, times out or loses its process, and when the binding is released
|
|
9
9
|
* (D3-d, D5-k). A permission request first announces its tool call on the turn's
|
|
10
|
-
* events (D5-c)
|
|
10
|
+
* events (D5-c); a deny answered while the turn is live is counted on its
|
|
11
|
+
* collector (nax#2582). Any other request (no turn, another session, a request-scoped
|
|
11
12
|
* elicitation, more than MAX_PENDING_DECISIONS pending at once) is answered locally,
|
|
12
13
|
* a permission rejected and an elicitation cancelled, and raises no event; each
|
|
13
14
|
* reason is logged once per session and kind (D3-c). Releasing a binding aborts its
|
package/dist/client/inbound.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { getLogger } from "@nathapp/nax-agent";
|
|
2
|
-
import { rejectLocally } from "#src/client/permissions";
|
|
2
|
+
import { isDenial, rejectLocally } from "#src/client/permissions";
|
|
3
3
|
import { isRecord } from "#src/client/text";
|
|
4
4
|
/** Concurrent permission requests and elicitations one turn may hold; further ones are answered locally. */
|
|
5
5
|
export const MAX_PENDING_DECISIONS = 16;
|
|
@@ -66,7 +66,16 @@ export function createInboundRouter(decide, elicit = cancelElicitation) {
|
|
|
66
66
|
}
|
|
67
67
|
if (!admitted.signal.aborted)
|
|
68
68
|
admitted.collector.announce(request.toolCall);
|
|
69
|
-
|
|
69
|
+
let decided = true;
|
|
70
|
+
const answer = await track(admitted, decide(request, admitted.signal).catch(() => {
|
|
71
|
+
decided = false;
|
|
72
|
+
return cancelled();
|
|
73
|
+
}));
|
|
74
|
+
// nax#2582: the turn learns of its policy denials, so a cancel they cause can be
|
|
75
|
+
// continued; a decider fault is not a policy denial.
|
|
76
|
+
if (decided && !admitted.signal.aborted && isDenial(request, answer))
|
|
77
|
+
admitted.collector.noteDenial();
|
|
78
|
+
return answer;
|
|
70
79
|
},
|
|
71
80
|
onElicitation: async (request) => {
|
|
72
81
|
const admitted = admit(sessionOf(request));
|
package/dist/client/index.d.ts
CHANGED
|
@@ -15,3 +15,4 @@ export type { AcpAgentSpec, AcpBackendOptions, AcpProcessHooks } from "#src/clie
|
|
|
15
15
|
export { TOOL_HOST_SERVER_NAME } from "#src/client/pre-approval";
|
|
16
16
|
export type { AcpAgentName, AgentRegistryEntry } from "#src/client/registry";
|
|
17
17
|
export { registryEntry } from "#src/client/registry";
|
|
18
|
+
export type { AcpPermissionRules, AcpRule } from "#src/client/rule-policy";
|
package/dist/client/open.d.ts
CHANGED
|
@@ -28,6 +28,8 @@ export interface OpenedAcp {
|
|
|
28
28
|
readonly cwd: string;
|
|
29
29
|
/** How a stored session was restored (§6.9); undefined for a new session. */
|
|
30
30
|
readonly restoredWith?: RestoredWith;
|
|
31
|
+
/** The startup banner session/new announced (nax#2591); turns drop it from their output. */
|
|
32
|
+
readonly startupBanner?: string;
|
|
31
33
|
}
|
|
32
34
|
/** `restore`: restore that stored agent session instead of creating one (§6.9). */
|
|
33
35
|
export declare function openAcpSession(options: ResolvedAcpOptions, ctx: BackendOpenContext, handlers: InboundHandlers, launch: LaunchFn, host?: ToolHost, restore?: Restore): Promise<OpenedAcp>;
|