@nathapp/nax-agent-acp 0.88.0-canary.1 → 0.88.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -0
- package/dist/client/backend.d.ts +7 -2
- package/dist/client/backend.js +24 -5
- package/dist/client/capabilities.js +2 -1
- package/dist/client/claude-sandbox.d.ts +10 -0
- package/dist/client/claude-sandbox.js +29 -0
- package/dist/client/edit-targets.d.ts +9 -0
- package/dist/client/edit-targets.js +130 -0
- package/dist/client/launch.d.ts +6 -2
- package/dist/client/launch.js +22 -6
- package/dist/client/open.js +18 -3
- package/dist/client/permissions.d.ts +13 -2
- package/dist/client/permissions.js +62 -2
- package/dist/client/pre-approval.d.ts +8 -1
- package/dist/client/pre-approval.js +4 -1
- package/dist/client/tool-host.d.ts +14 -1
- package/dist/client/tool-host.js +18 -4
- package/dist/server/connection.js +10 -4
- package/dist/server/nax-config.d.ts +4 -2
- package/dist/server/options.d.ts +2 -3
- package/dist/server/permissions.d.ts +10 -6
- package/dist/server/permissions.js +10 -2
- package/dist/server/registry-lifecycle.d.ts +27 -0
- package/dist/server/registry-lifecycle.js +96 -0
- package/dist/server/registry-open.js +2 -0
- package/dist/server/registry.d.ts +2 -4
- package/dist/server/registry.js +29 -58
- package/dist/server/server-session.d.ts +4 -2
- package/dist/server/server-session.js +52 -7
- package/dist/server/session-config.d.ts +2 -3
- package/dist/server/session-lock-guard.d.ts +6 -0
- package/dist/server/session-lock-guard.js +85 -0
- package/dist/server/session-lock.d.ts +10 -0
- package/dist/server/session-lock.js +164 -0
- package/dist/server/storage.d.ts +5 -2
- package/dist/server/storage.js +7 -41
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,14 @@
|
|
|
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.88.0] - 2026-10-16
|
|
7
|
+
|
|
8
|
+
- No changes in this package. Released in lockstep with the other nax packages.
|
|
9
|
+
|
|
10
|
+
## [0.88.0-canary.2] - 2026-10-15
|
|
11
|
+
|
|
12
|
+
- No changes in this package. Released in lockstep with the other nax packages.
|
|
13
|
+
|
|
6
14
|
## [0.88.0-canary.1] - 2026-10-13
|
|
7
15
|
|
|
8
16
|
- No changes in this package. Released in lockstep with the other nax packages.
|
package/dist/client/backend.d.ts
CHANGED
|
@@ -20,11 +20,16 @@
|
|
|
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 { type SessionBackend } from "@nathapp/nax-agent";
|
|
23
|
+
import { type BackendOpenContext, type SessionBackend } from "@nathapp/nax-agent";
|
|
24
|
+
import { type InboundRouter } from "#src/client/inbound";
|
|
24
25
|
import { type LaunchFn } from "#src/client/launch";
|
|
25
26
|
import { type AcpBackendOptions } from "#src/client/options";
|
|
26
|
-
|
|
27
|
+
import { createToolHost, type ToolHost } from "#src/client/tool-host";
|
|
28
|
+
/** Test seam: the process launcher and the tool host factory. Production always uses launchAgent and createToolHost. */
|
|
27
29
|
export declare const _acpBackendDeps: {
|
|
28
30
|
launch: LaunchFn;
|
|
31
|
+
createToolHost: typeof createToolHost;
|
|
29
32
|
};
|
|
30
33
|
export declare function acpBackend(input: AcpBackendOptions): SessionBackend;
|
|
34
|
+
/** Exported for its unit test; `./client` does not re-export it. */
|
|
35
|
+
export declare function toolHostFor(ctx: BackendOpenContext, router: InboundRouter, secrets: readonly string[], token: string | undefined): ToolHost | undefined;
|
package/dist/client/backend.js
CHANGED
|
@@ -35,8 +35,11 @@ import { createToolCalls } from "#src/client/tool-calls";
|
|
|
35
35
|
import { createToolHost, newToolHostToken } from "#src/client/tool-host";
|
|
36
36
|
import { runPromptTurn } from "#src/client/turn";
|
|
37
37
|
import { createCostMeter } from "#src/client/usage";
|
|
38
|
-
/** Test seam: the process launcher. Production always uses launchAgent. */
|
|
39
|
-
export const _acpBackendDeps = {
|
|
38
|
+
/** Test seam: the process launcher and the tool host factory. Production always uses launchAgent and createToolHost. */
|
|
39
|
+
export const _acpBackendDeps = {
|
|
40
|
+
launch: launchAgent,
|
|
41
|
+
createToolHost,
|
|
42
|
+
};
|
|
40
43
|
export function acpBackend(input) {
|
|
41
44
|
const options = resolveAcpOptions(input);
|
|
42
45
|
return Object.freeze({ kind: options.kind, open: (ctx) => openBackend(options, ctx) });
|
|
@@ -47,7 +50,17 @@ function withTokens(options, tokens) {
|
|
|
47
50
|
return options;
|
|
48
51
|
return Object.freeze({ ...options, secrets: Object.freeze([...options.secrets, ...tokens]) });
|
|
49
52
|
}
|
|
50
|
-
|
|
53
|
+
/**
|
|
54
|
+
* The host's options: nax#2517's rendered `## MCP servers` text, which the
|
|
55
|
+
* agent's MCP client reads from `initialize`. Absent — an empty one counts as
|
|
56
|
+
* absent, as in the native path — leaves the option off entirely.
|
|
57
|
+
*/
|
|
58
|
+
function toolHostOptions(ctx) {
|
|
59
|
+
const instructions = ctx.providerInstructions;
|
|
60
|
+
return instructions === undefined || instructions === "" ? undefined : { instructions };
|
|
61
|
+
}
|
|
62
|
+
/** Exported for its unit test; `./client` does not re-export it. */
|
|
63
|
+
export function toolHostFor(ctx, router, secrets, token) {
|
|
51
64
|
if (token === undefined)
|
|
52
65
|
return undefined;
|
|
53
66
|
const calls = createToolCalls({
|
|
@@ -58,11 +71,17 @@ function toolHostFor(ctx, router, secrets, token) {
|
|
|
58
71
|
turnSignal: () => router.activeSignal(),
|
|
59
72
|
secrets,
|
|
60
73
|
});
|
|
61
|
-
return createToolHost(calls, token);
|
|
74
|
+
return _acpBackendDeps.createToolHost(calls, token, toolHostOptions(ctx));
|
|
62
75
|
}
|
|
63
76
|
/** Permission requests and elicitations, decided by profile with the session's redaction set. */
|
|
64
77
|
function routerFor(ctx, secrets) {
|
|
65
|
-
const base = {
|
|
78
|
+
const base = {
|
|
79
|
+
profile: ctx.profile,
|
|
80
|
+
asks: ctx.asks,
|
|
81
|
+
secrets,
|
|
82
|
+
cwd: ctx.workdir,
|
|
83
|
+
...(ctx.sandbox?.kind === "policy" ? { sandbox: ctx.sandbox.policy } : {}),
|
|
84
|
+
};
|
|
66
85
|
return createInboundRouter((request, signal) => decidePermission(request, { ...base, signal }), (request, signal) => answerElicitation(request, { ...base, signal }));
|
|
67
86
|
}
|
|
68
87
|
/** One agent process: a new agent session, or `restore` restored in it (§6.3 step 1, §6.9). */
|
|
@@ -25,7 +25,8 @@ export function buildCapabilityRecord(init, entry) {
|
|
|
25
25
|
preApproval: entry?.preApproval !== undefined,
|
|
26
26
|
});
|
|
27
27
|
}
|
|
28
|
-
|
|
28
|
+
/** 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";
|
|
29
30
|
/** The first requirement this agent cannot meet, or undefined. The model is checked after session/new. */
|
|
30
31
|
export function unmetRequirement(record, req) {
|
|
31
32
|
if (isReadOnlyProfile(req.profile) && !record.readOnlyMode) {
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* nax#2500: nax's sandbox policy as the Claude Agent SDK `sandbox` session option
|
|
3
|
+
* (SDK 0.3.286 SandboxSettings; claude-agent-acp 0.85.1 passes it through and
|
|
4
|
+
* rebuilds the session when it changes). Same srt engine as nax's own launcher.
|
|
5
|
+
* Network: nax's absent allow-list means open, so no `network` key is sent and the
|
|
6
|
+
* permission layer answers Claude's network requests (permissions.ts) — unless
|
|
7
|
+
* the policy carries the loopback grant alone (#2538), which still needs sending.
|
|
8
|
+
*/
|
|
9
|
+
import type { SandboxPolicy } from "@nathapp/nax-agent";
|
|
10
|
+
export declare function claudeSandboxOptions(policy: SandboxPolicy): Readonly<Record<string, unknown>>;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* nax#2538: the SDK's `network` option, sent when the policy says anything about
|
|
3
|
+
* the network. An all-empty policy keeps today's behaviour: no key at all, which
|
|
4
|
+
* is what "open, decided by the permission layer" means to this SDK.
|
|
5
|
+
*/
|
|
6
|
+
function networkOption(network) {
|
|
7
|
+
if (network.allowedDomains === undefined && network.allowLocalBinding === undefined)
|
|
8
|
+
return {};
|
|
9
|
+
return {
|
|
10
|
+
network: {
|
|
11
|
+
...(network.allowedDomains === undefined ? {} : { allowedDomains: [...network.allowedDomains] }),
|
|
12
|
+
...(network.allowLocalBinding === undefined ? {} : { allowLocalBinding: network.allowLocalBinding }),
|
|
13
|
+
},
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
export function claudeSandboxOptions(policy) {
|
|
17
|
+
return {
|
|
18
|
+
enabled: true,
|
|
19
|
+
failIfUnavailable: true,
|
|
20
|
+
allowUnsandboxedCommands: false,
|
|
21
|
+
autoAllowBashIfSandboxed: true,
|
|
22
|
+
filesystem: {
|
|
23
|
+
allowWrite: [...policy.writeRoots],
|
|
24
|
+
denyWrite: [...policy.denyWrite],
|
|
25
|
+
denyRead: [...policy.denyRead],
|
|
26
|
+
},
|
|
27
|
+
...networkOption(policy.network),
|
|
28
|
+
};
|
|
29
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { SandboxPolicy } from "@nathapp/nax-agent";
|
|
2
|
+
export declare const OUTSIDE_WRITE_ROOTS_REASON = "the edit target is outside the sandbox write roots";
|
|
3
|
+
export declare const WRITE_KINDS: ReadonlySet<string>;
|
|
4
|
+
/** Test seam: the platform decides whether path comparison folds case (darwin and win32 filesystems are case-insensitive by default). */
|
|
5
|
+
export declare const _editTargetsDeps: {
|
|
6
|
+
platform: () => string;
|
|
7
|
+
};
|
|
8
|
+
export declare function editTargets(toolCall: unknown): readonly string[];
|
|
9
|
+
export declare function firstOutsidePolicy(targets: readonly string[], policy: SandboxPolicy, cwd: string | undefined): Promise<string | undefined>;
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* nax#2500 R4: Claude's Write/Edit/MultiEdit/NotebookEdit are not covered by the
|
|
3
|
+
* Bash sandbox, so under profile full their permission requests are checked
|
|
4
|
+
* against the same write roots. This reads the request's display fields
|
|
5
|
+
* (locations, rawInput paths) to DECIDE, deliberately overriding the D3-a "display
|
|
6
|
+
* only" rule in tool-display.ts: there is no other source for the target path.
|
|
7
|
+
* Known limitation (TOCTOU): the check runs at permission time; a path component
|
|
8
|
+
* swapped for a symlink between the check and the write is not caught (only Bash
|
|
9
|
+
* is under the OS sandbox).
|
|
10
|
+
*/
|
|
11
|
+
import { lstat, readlink, realpath } from "node:fs/promises";
|
|
12
|
+
import { homedir } from "node:os";
|
|
13
|
+
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
14
|
+
import { isRecord } from "#src/client/text";
|
|
15
|
+
export const OUTSIDE_WRITE_ROOTS_REASON = "the edit target is outside the sandbox write roots";
|
|
16
|
+
const RAW_PATH_KEYS = ["file_path", "notebook_path"];
|
|
17
|
+
const WRITE_PATH_KEYS = [...RAW_PATH_KEYS, "path", "filePath", "old_path", "new_path"];
|
|
18
|
+
export const WRITE_KINDS = new Set(["edit", "delete", "move"]);
|
|
19
|
+
/** Test seam: the platform decides whether path comparison folds case (darwin and win32 filesystems are case-insensitive by default). */
|
|
20
|
+
export const _editTargetsDeps = { platform: () => process.platform };
|
|
21
|
+
export function editTargets(toolCall) {
|
|
22
|
+
if (!isRecord(toolCall))
|
|
23
|
+
return [];
|
|
24
|
+
const fromLocations = Array.isArray(toolCall.locations)
|
|
25
|
+
? toolCall.locations.flatMap((l) => isRecord(l) && typeof l.path === "string" && l.path !== "" ? [l.path] : [])
|
|
26
|
+
: [];
|
|
27
|
+
const raw = isRecord(toolCall.rawInput) ? toolCall.rawInput : {};
|
|
28
|
+
const keys = typeof toolCall.kind === "string" && WRITE_KINDS.has(toolCall.kind) ? WRITE_PATH_KEYS : RAW_PATH_KEYS;
|
|
29
|
+
const fromRaw = keys.flatMap((k) => (typeof raw[k] === "string" && raw[k] !== "" ? [raw[k]] : []));
|
|
30
|
+
return [...new Set([...fromLocations, ...fromRaw])];
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Absolute form of a target, or undefined when it is relative and there is no cwd
|
|
34
|
+
* to resolve it against (fail closed: the caller treats that as outside).
|
|
35
|
+
*/
|
|
36
|
+
function expand(path, cwd) {
|
|
37
|
+
if (path === "~" || path.startsWith(`~${sep}`) || path.startsWith("~/"))
|
|
38
|
+
return join(homedir(), path.slice(1));
|
|
39
|
+
if (isAbsolute(path))
|
|
40
|
+
return path;
|
|
41
|
+
return cwd === undefined ? undefined : resolve(cwd, path);
|
|
42
|
+
}
|
|
43
|
+
/** R7: a `..` segment is outside, before any resolution (lexical `..` can disagree with the OS after a symlink). */
|
|
44
|
+
const SEPARATORS = sep === "/" ? /\// : /[/\\]/;
|
|
45
|
+
const hasDotDotSegment = (path) => path.split(SEPARATORS).includes("..");
|
|
46
|
+
/** Symlink bound for canonical(): a longer chain, or a loop, is treated as outside. */
|
|
47
|
+
const MAX_SYMLINK_HOPS = 40;
|
|
48
|
+
/** The raw target of a symlink at `path`, or undefined when it is not one (or cannot be read). */
|
|
49
|
+
async function symlinkTarget(path) {
|
|
50
|
+
try {
|
|
51
|
+
const stat = await lstat(path);
|
|
52
|
+
return stat.isSymbolicLink() ? await readlink(path) : undefined;
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return undefined;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
async function realpathOrUndefined(path) {
|
|
59
|
+
try {
|
|
60
|
+
return await realpath(path);
|
|
61
|
+
}
|
|
62
|
+
catch {
|
|
63
|
+
return undefined;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
/** Follows a dangling symlink (R6) to its target, bounded by MAX_SYMLINK_HOPS; the missing tail is re-appended. */
|
|
67
|
+
async function followLink(linkPath, link, tail, hops) {
|
|
68
|
+
if (hops >= MAX_SYMLINK_HOPS)
|
|
69
|
+
return undefined;
|
|
70
|
+
// R8: a raw `..` in the link target is outside: its meaning depends on the OS resolving it after symlinks.
|
|
71
|
+
if (hasDotDotSegment(link))
|
|
72
|
+
return undefined;
|
|
73
|
+
// R8b: a relative target resolves against the real parent directory (the link's own directory is real-resolved).
|
|
74
|
+
const parent = await realpathOrUndefined(dirname(linkPath));
|
|
75
|
+
if (parent === undefined)
|
|
76
|
+
return undefined;
|
|
77
|
+
const next = isAbsolute(link) ? link : resolve(parent, link);
|
|
78
|
+
const resolved = await canonical(next, hops + 1);
|
|
79
|
+
return resolved === undefined ? undefined : join(resolved, ...tail);
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Realpath of the deepest existing ancestor, with the missing tail re-appended. A
|
|
83
|
+
* dangling symlink is followed to its target (R6): a write through it lands there.
|
|
84
|
+
* Undefined = unresolvable (too many hops): the caller treats it as outside.
|
|
85
|
+
*/
|
|
86
|
+
async function canonical(path, hops = 0) {
|
|
87
|
+
let head = path;
|
|
88
|
+
let tail = [];
|
|
89
|
+
for (;;) {
|
|
90
|
+
const real = await realpathOrUndefined(head);
|
|
91
|
+
if (real !== undefined)
|
|
92
|
+
return join(real, ...tail);
|
|
93
|
+
const link = await symlinkTarget(head);
|
|
94
|
+
if (link !== undefined)
|
|
95
|
+
return followLink(head, link, tail, hops);
|
|
96
|
+
const parent = dirname(head);
|
|
97
|
+
if (parent === head)
|
|
98
|
+
return path;
|
|
99
|
+
tail = [basename(head), ...tail];
|
|
100
|
+
head = parent;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
/** Policy paths: an unresolvable one keeps its raw form (a deny entry still matches its own spelling). */
|
|
104
|
+
const canonicalPolicyPath = async (path) => (await canonical(path)) ?? path;
|
|
105
|
+
/** Both sides of every comparison are NFC-normalised (R8b). */
|
|
106
|
+
const nfc = (path) => path.normalize("NFC");
|
|
107
|
+
/** Case folding, only for denyWrite matching, on the platforms whose default filesystem ignores case (R8b). */
|
|
108
|
+
const foldCase = (path) => _editTargetsDeps.platform() === "darwin" || _editTargetsDeps.platform() === "win32" ? path.toLowerCase() : path;
|
|
109
|
+
const contains = (path, root) => path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
|
|
110
|
+
/** writeRoots containment: exact (case-sensitive) comparison. */
|
|
111
|
+
const withinRoot = (path, root) => contains(nfc(path), nfc(root));
|
|
112
|
+
/** denyWrite matching: case-folded on darwin and win32, so a differently cased spelling is still denied. */
|
|
113
|
+
const withinDenied = (path, denied) => contains(foldCase(nfc(path)), foldCase(nfc(denied)));
|
|
114
|
+
export async function firstOutsidePolicy(targets, policy, cwd) {
|
|
115
|
+
const roots = await Promise.all(policy.writeRoots.map(canonicalPolicyPath));
|
|
116
|
+
const denied = await Promise.all(policy.denyWrite.map(canonicalPolicyPath));
|
|
117
|
+
for (const target of targets) {
|
|
118
|
+
if (hasDotDotSegment(target))
|
|
119
|
+
return target;
|
|
120
|
+
const absolute = expand(target, cwd);
|
|
121
|
+
if (absolute === undefined)
|
|
122
|
+
return target;
|
|
123
|
+
const real = await canonical(absolute);
|
|
124
|
+
if (real === undefined)
|
|
125
|
+
return target;
|
|
126
|
+
if (denied.some((d) => withinDenied(real, d)) || !roots.some((r) => withinRoot(real, r)))
|
|
127
|
+
return target;
|
|
128
|
+
}
|
|
129
|
+
return undefined;
|
|
130
|
+
}
|
package/dist/client/launch.d.ts
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
import { type AgentApp, type Stream } from "@agentclientprotocol/sdk";
|
|
2
|
-
import { type AgentSessionError, type StderrTail } from "@nathapp/nax-agent";
|
|
2
|
+
import { type AgentSessionError, killProcessGroup, type StderrTail } from "@nathapp/nax-agent";
|
|
3
3
|
import type { LaunchCandidate } from "#src/client/registry";
|
|
4
|
+
/** Test seam for process-group signalling. */
|
|
5
|
+
export declare const _launchDeps: {
|
|
6
|
+
killProcessGroup: typeof killProcessGroup;
|
|
7
|
+
};
|
|
4
8
|
export type LaunchTarget = {
|
|
5
9
|
readonly kind: "stream";
|
|
6
10
|
readonly stream: Stream;
|
|
@@ -24,7 +28,7 @@ export interface LaunchedAgent {
|
|
|
24
28
|
readonly exited: Promise<AgentExit>;
|
|
25
29
|
/** The exit once the process has exited (and its stderr drained), or undefined after `waitMs`. */
|
|
26
30
|
whenGone(waitMs: number): Promise<AgentExit | undefined>;
|
|
27
|
-
/** Closes stdin, SIGTERMs the group, SIGKILLs
|
|
31
|
+
/** Closes stdin, SIGTERMs the group, SIGKILLs survivors on leader exit or after `graceMs`; resolves once exited. */
|
|
28
32
|
terminate(graceMs: number): Promise<void>;
|
|
29
33
|
/** SIGKILLs the group now. */
|
|
30
34
|
kill(): void;
|
package/dist/client/launch.js
CHANGED
|
@@ -15,6 +15,8 @@ import { agentTextExcerpt, backendUnavailable, EXCERPT_BYTES } from "#src/client
|
|
|
15
15
|
import { race } from "#src/client/race";
|
|
16
16
|
/** How long a transport failure waits for the exit status. */
|
|
17
17
|
const GONE_WAIT_MS = 1_000;
|
|
18
|
+
/** Test seam for process-group signalling. */
|
|
19
|
+
export const _launchDeps = { killProcessGroup };
|
|
18
20
|
/** How long, after the exit, the last stderr may take to arrive. */
|
|
19
21
|
const STDERR_DRAIN_MS = 200;
|
|
20
22
|
function isExecutableFile(path) {
|
|
@@ -96,8 +98,12 @@ function startedLaunch(child, stderr, maxMessageBytes) {
|
|
|
96
98
|
gone = true;
|
|
97
99
|
});
|
|
98
100
|
const kill = () => {
|
|
99
|
-
if (
|
|
100
|
-
|
|
101
|
+
if (pid === undefined)
|
|
102
|
+
return;
|
|
103
|
+
if (gone)
|
|
104
|
+
_launchDeps.killProcessGroup(pid, "SIGKILL", { singleProcessFallback: false });
|
|
105
|
+
else
|
|
106
|
+
_launchDeps.killProcessGroup(pid, "SIGKILL");
|
|
101
107
|
};
|
|
102
108
|
return {
|
|
103
109
|
target: { kind: "stream", stream },
|
|
@@ -113,14 +119,24 @@ function startedLaunch(child, stderr, maxMessageBytes) {
|
|
|
113
119
|
return exit.value;
|
|
114
120
|
},
|
|
115
121
|
async terminate(graceMs) {
|
|
116
|
-
if (
|
|
122
|
+
if (pid === undefined) {
|
|
123
|
+
await exited;
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
if (!gone)
|
|
117
127
|
child.stdin.end();
|
|
118
|
-
|
|
119
|
-
|
|
128
|
+
if (gone)
|
|
129
|
+
_launchDeps.killProcessGroup(pid, "SIGTERM", { singleProcessFallback: false });
|
|
130
|
+
else
|
|
131
|
+
_launchDeps.killProcessGroup(pid, "SIGTERM");
|
|
132
|
+
const timer = setTimeout(kill, graceMs);
|
|
133
|
+
try {
|
|
120
134
|
await exited;
|
|
135
|
+
kill();
|
|
136
|
+
}
|
|
137
|
+
finally {
|
|
121
138
|
clearTimeout(timer);
|
|
122
139
|
}
|
|
123
|
-
await exited;
|
|
124
140
|
},
|
|
125
141
|
};
|
|
126
142
|
}
|
package/dist/client/open.js
CHANGED
|
@@ -111,7 +111,8 @@ async function establish(o) {
|
|
|
111
111
|
});
|
|
112
112
|
if (unmet !== undefined)
|
|
113
113
|
throw capabilityUnsupported(unmet.capability, unmet.reason);
|
|
114
|
-
const
|
|
114
|
+
const sandbox = sandboxFor(o.ctx);
|
|
115
|
+
const setup = await sessionSetup(o, sandbox);
|
|
115
116
|
const session = o.restore === undefined
|
|
116
117
|
? await newSession(o, setup)
|
|
117
118
|
: await restoreSession(o.restore, record, setup, o.link, (label, request) => step(o, label, request));
|
|
@@ -134,10 +135,24 @@ async function newSession(o, setup) {
|
|
|
134
135
|
throw backendUnavailable("session/new returned no usable session id");
|
|
135
136
|
return { agentSessionId: created.sessionId, cwd: o.ctx.workdir, configOptions: created.configOptions ?? [] };
|
|
136
137
|
}
|
|
138
|
+
/** nax#2500: review/full sessions with an embedder sandbox; an unusable one refuses the open. */
|
|
139
|
+
function sandboxFor(ctx) {
|
|
140
|
+
if (ctx.profile !== "review" && ctx.profile !== "full")
|
|
141
|
+
return undefined;
|
|
142
|
+
if (ctx.sandbox === undefined)
|
|
143
|
+
return undefined;
|
|
144
|
+
if (ctx.sandbox.kind === "unavailable") {
|
|
145
|
+
throw capabilityUnsupported("profile", `the sandbox is unavailable: ${ctx.sandbox.reason}`);
|
|
146
|
+
}
|
|
147
|
+
return ctx.sandbox.policy;
|
|
148
|
+
}
|
|
137
149
|
/** §6.3 step 3: start the tool host when the session has tools; its entry and Claude's `_meta` (§6.6, #2365). */
|
|
138
|
-
async function sessionSetup(o) {
|
|
150
|
+
async function sessionSetup(o, sandbox) {
|
|
139
151
|
const kind = o.options.entry?.preApproval;
|
|
140
|
-
const meta = claudeSessionMeta(kind, o.ctx.tools.map((tool) => tool.name), readOnlyFor(o.ctx.profile, o.options.entry)
|
|
152
|
+
const meta = claudeSessionMeta(kind, o.ctx.tools.map((tool) => tool.name), readOnlyFor(o.ctx.profile, o.options.entry), {
|
|
153
|
+
...(sandbox === undefined ? {} : { sandbox }),
|
|
154
|
+
...(o.ctx.profile === "full" ? { lockSkipPermissions: true } : {}),
|
|
155
|
+
});
|
|
141
156
|
if (o.host === undefined)
|
|
142
157
|
return meta === undefined ? { mcpServers: [] } : { mcpServers: [], _meta: { ...meta } };
|
|
143
158
|
if (meta === undefined)
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* session/request_permission by profile (S4 spec §6.4 layer 2). none and read
|
|
3
|
-
* reject every request;
|
|
3
|
+
* reject every request; review allows commands (kind execute) only when a
|
|
4
|
+
* sandbox policy is present (fail closed) and rejects the rest; under review and full a sandbox network request follows the sandbox
|
|
5
|
+
* network policy (open: allow, allow-list: deny); full allows it; ask puts it in front of the caller through
|
|
4
6
|
* asks.requestApproval and answer(). Only options the agent offered are chosen,
|
|
5
7
|
* and only the *_once kinds: allow_always would outlive the session. Auto-decisions
|
|
6
8
|
* are recorded with decidedBy "profile". Fail closed: a deny or deadline answers
|
|
@@ -10,12 +12,17 @@
|
|
|
10
12
|
* like any other, because its title is display data (S4-4 D4-c).
|
|
11
13
|
*/
|
|
12
14
|
import type { RequestPermissionRequest, RequestPermissionResponse } from "@agentclientprotocol/sdk";
|
|
13
|
-
import type { AgentSessionProfile, SessionAskPort } from "@nathapp/nax-agent";
|
|
15
|
+
import type { AgentSessionProfile, SandboxPolicy, SessionAskPort } from "@nathapp/nax-agent";
|
|
14
16
|
export declare const NO_ALLOW_ONCE_REASON = "agent offered no allow-once option";
|
|
15
17
|
export declare const UNSHOWABLE_REASON = "the request could not be shown safely";
|
|
16
18
|
export declare const ASK_REASON = "the ACP agent asks permission";
|
|
17
19
|
export declare const FULL_REASON = "profile \"full\" allows every permission request";
|
|
18
20
|
export declare const UNKNOWN_PROFILE_REASON = "unknown profile";
|
|
21
|
+
export declare const REVIEW_EXECUTE_REASON = "profile \"review\" allows commands";
|
|
22
|
+
export declare const REVIEW_NO_SANDBOX_REASON = "profile \"review\" runs commands only inside the sandbox";
|
|
23
|
+
export declare const NETWORK_OPEN_REASON = "the sandbox network is open";
|
|
24
|
+
export declare const NETWORK_LISTED_REASON = "the sandbox network is an allow-list";
|
|
25
|
+
export declare function isNetworkRequest(toolCall: unknown): boolean;
|
|
19
26
|
export declare function readOnlyReason(profile: AgentSessionProfile): string;
|
|
20
27
|
export interface PermissionContext {
|
|
21
28
|
readonly profile: AgentSessionProfile;
|
|
@@ -23,6 +30,10 @@ export interface PermissionContext {
|
|
|
23
30
|
readonly secrets: readonly string[];
|
|
24
31
|
/** Aborts when the turn's binding is released or the agent process exits (D3-d). */
|
|
25
32
|
readonly signal: AbortSignal;
|
|
33
|
+
/** nax#2500: the session sandbox policy (review/full on claude); drives the network and R4 path rules. */
|
|
34
|
+
readonly sandbox?: SandboxPolicy;
|
|
35
|
+
/** nax#2500: the session cwd, for resolving relative edit targets (R4). */
|
|
36
|
+
readonly cwd?: string;
|
|
26
37
|
}
|
|
27
38
|
export interface OfferedOptions {
|
|
28
39
|
readonly allowOnce?: string;
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { editTargets, firstOutsidePolicy, OUTSIDE_WRITE_ROOTS_REASON, WRITE_KINDS } from "#src/client/edit-targets";
|
|
1
2
|
import { isRecord } from "#src/client/text";
|
|
2
3
|
import { describeToolCall } from "#src/client/tool-display";
|
|
3
4
|
export const NO_ALLOW_ONCE_REASON = "agent offered no allow-once option";
|
|
@@ -5,6 +6,18 @@ export const UNSHOWABLE_REASON = "the request could not be shown safely";
|
|
|
5
6
|
export const ASK_REASON = "the ACP agent asks permission";
|
|
6
7
|
export const FULL_REASON = 'profile "full" allows every permission request';
|
|
7
8
|
export const UNKNOWN_PROFILE_REASON = "unknown profile";
|
|
9
|
+
export const REVIEW_EXECUTE_REASON = 'profile "review" allows commands';
|
|
10
|
+
export const REVIEW_NO_SANDBOX_REASON = 'profile "review" runs commands only inside the sandbox';
|
|
11
|
+
export const NETWORK_OPEN_REASON = "the sandbox network is open";
|
|
12
|
+
export const NETWORK_LISTED_REASON = "the sandbox network is an allow-list";
|
|
13
|
+
/** claude-agent-acp 0.85.1 surfaces the SDK's sandbox network callback as a tool call titled with its tool name. */
|
|
14
|
+
const NETWORK_TOOL_TITLE = "SandboxNetworkAccess";
|
|
15
|
+
export function isNetworkRequest(toolCall) {
|
|
16
|
+
// title is agent-controlled display data: require the kind it renders with (absent or "other") too.
|
|
17
|
+
return (isRecord(toolCall) &&
|
|
18
|
+
toolCall.title === NETWORK_TOOL_TITLE &&
|
|
19
|
+
(toolCall.kind === undefined || toolCall.kind === null || toolCall.kind === "other"));
|
|
20
|
+
}
|
|
8
21
|
export function readOnlyReason(profile) {
|
|
9
22
|
return `profile "${profile}" rejects every permission request`;
|
|
10
23
|
}
|
|
@@ -45,16 +58,31 @@ export async function decidePermission(request, ctx) {
|
|
|
45
58
|
const offered = offeredOptions(request);
|
|
46
59
|
const display = describeToolCall(request.toolCall, ctx.secrets);
|
|
47
60
|
const auto = (reason, decision) => ctx.asks.recordAutoDecision({ ...eventFields(display), reason }, decision);
|
|
61
|
+
if ((ctx.profile === "review" || ctx.profile === "full") &&
|
|
62
|
+
ctx.sandbox !== undefined &&
|
|
63
|
+
isNetworkRequest(request.toolCall)) {
|
|
64
|
+
return decideNetwork(ctx.sandbox, offered, auto);
|
|
65
|
+
}
|
|
48
66
|
switch (ctx.profile) {
|
|
49
67
|
case "none":
|
|
50
68
|
case "read":
|
|
51
69
|
auto(readOnlyReason(ctx.profile), "deny");
|
|
52
70
|
return rejectWith(offered);
|
|
53
|
-
case "
|
|
71
|
+
case "review":
|
|
72
|
+
if (display.tool !== "execute") {
|
|
73
|
+
auto(readOnlyReason(ctx.profile), "deny");
|
|
74
|
+
return rejectWith(offered);
|
|
75
|
+
}
|
|
76
|
+
if (ctx.sandbox === undefined) {
|
|
77
|
+
auto(REVIEW_NO_SANDBOX_REASON, "deny");
|
|
78
|
+
return rejectWith(offered);
|
|
79
|
+
}
|
|
54
80
|
if (offered.allowOnce === undefined)
|
|
55
81
|
return denyNoAllowOnce(offered, auto);
|
|
56
|
-
auto(
|
|
82
|
+
auto(REVIEW_EXECUTE_REASON, "allow");
|
|
57
83
|
return selected(offered.allowOnce);
|
|
84
|
+
case "full":
|
|
85
|
+
return decideFull(request, display, offered, auto, ctx);
|
|
58
86
|
case "ask":
|
|
59
87
|
if (offered.allowOnce === undefined)
|
|
60
88
|
return denyNoAllowOnce(offered, auto);
|
|
@@ -69,6 +97,38 @@ export async function decidePermission(request, ctx) {
|
|
|
69
97
|
return rejectWith(offered);
|
|
70
98
|
}
|
|
71
99
|
}
|
|
100
|
+
/**
|
|
101
|
+
* ACP kinds exempt from the R4 path check (nax#2500 R5/R8): they do not write a path
|
|
102
|
+
* the sandbox has to police. execute is the Bash sandbox's job. Every other kind,
|
|
103
|
+
* including `other` and any unknown kind, is path-checked (fail closed).
|
|
104
|
+
*/
|
|
105
|
+
const READ_ONLY_KINDS = new Set(["read", "search", "think", "fetch", "switch_mode"]);
|
|
106
|
+
/** full allows every request, except (nax#2500 R4/R5) a write whose target is outside the sandbox write roots. */
|
|
107
|
+
async function decideFull(request, display, offered, auto, ctx) {
|
|
108
|
+
if (offered.allowOnce === undefined)
|
|
109
|
+
return denyNoAllowOnce(offered, auto);
|
|
110
|
+
const targets = editTargets(request.toolCall);
|
|
111
|
+
const unknownWrite = ctx.sandbox !== undefined && WRITE_KINDS.has(display.tool) && targets.length === 0;
|
|
112
|
+
const outside = ctx.sandbox !== undefined && display.tool !== "execute" && !READ_ONLY_KINDS.has(display.tool)
|
|
113
|
+
? await firstOutsidePolicy(targets, ctx.sandbox, ctx.cwd)
|
|
114
|
+
: undefined;
|
|
115
|
+
if (unknownWrite || outside !== undefined) {
|
|
116
|
+
auto(OUTSIDE_WRITE_ROOTS_REASON, "deny");
|
|
117
|
+
return rejectWith(offered);
|
|
118
|
+
}
|
|
119
|
+
auto(FULL_REASON, "allow");
|
|
120
|
+
return selected(offered.allowOnce);
|
|
121
|
+
}
|
|
122
|
+
function decideNetwork(policy, offered, auto) {
|
|
123
|
+
if (policy.network.allowedDomains !== undefined) {
|
|
124
|
+
auto(NETWORK_LISTED_REASON, "deny");
|
|
125
|
+
return rejectWith(offered);
|
|
126
|
+
}
|
|
127
|
+
if (offered.allowOnce === undefined)
|
|
128
|
+
return denyNoAllowOnce(offered, auto);
|
|
129
|
+
auto(NETWORK_OPEN_REASON, "allow");
|
|
130
|
+
return selected(offered.allowOnce);
|
|
131
|
+
}
|
|
72
132
|
function denyNoAllowOnce(offered, auto) {
|
|
73
133
|
auto(NO_ALLOW_ONCE_REASON, "deny");
|
|
74
134
|
return rejectWith(offered);
|
|
@@ -8,9 +8,16 @@
|
|
|
8
8
|
* Under none/read the entry's read-only enforcement adds the removed tools and its
|
|
9
9
|
* session options (#2366).
|
|
10
10
|
*/
|
|
11
|
+
import type { SandboxPolicy } from "@nathapp/nax-agent";
|
|
11
12
|
import type { AgentRegistryEntry, ReadOnlyEnforcement } from "#src/client/registry";
|
|
12
13
|
/** The ACP MCP server name; the agent sees the tools as `mcp__nax__<tool>`. */
|
|
13
14
|
export declare const TOOL_HOST_SERVER_NAME = "nax";
|
|
14
15
|
export declare function mcpToolRule(toolName: string): string;
|
|
16
|
+
export interface ClaudeMetaExtras {
|
|
17
|
+
/** nax#2500: the session sandbox (profiles review and full). */
|
|
18
|
+
readonly sandbox?: SandboxPolicy;
|
|
19
|
+
/** nax#2500: profile full pins allowDangerouslySkipPermissions false. */
|
|
20
|
+
readonly lockSkipPermissions?: boolean;
|
|
21
|
+
}
|
|
15
22
|
/** The session/new, resume and load `_meta` for Claude: tool rules and the read-only enforcement; undefined when empty. */
|
|
16
|
-
export declare function claudeSessionMeta(kind: AgentRegistryEntry["preApproval"], toolNames: readonly string[], readOnly: ReadOnlyEnforcement | undefined): Readonly<Record<string, unknown>> | undefined;
|
|
23
|
+
export declare function claudeSessionMeta(kind: AgentRegistryEntry["preApproval"], toolNames: readonly string[], readOnly: ReadOnlyEnforcement | undefined, extras?: ClaudeMetaExtras): Readonly<Record<string, unknown>> | undefined;
|
|
@@ -1,15 +1,18 @@
|
|
|
1
|
+
import { claudeSandboxOptions } from "#src/client/claude-sandbox";
|
|
1
2
|
/** The ACP MCP server name; the agent sees the tools as `mcp__nax__<tool>`. */
|
|
2
3
|
export const TOOL_HOST_SERVER_NAME = "nax";
|
|
3
4
|
export function mcpToolRule(toolName) {
|
|
4
5
|
return `mcp__${TOOL_HOST_SERVER_NAME}__${toolName}`;
|
|
5
6
|
}
|
|
6
7
|
/** The session/new, resume and load `_meta` for Claude: tool rules and the read-only enforcement; undefined when empty. */
|
|
7
|
-
export function claudeSessionMeta(kind, toolNames, readOnly) {
|
|
8
|
+
export function claudeSessionMeta(kind, toolNames, readOnly, extras = {}) {
|
|
8
9
|
if (kind !== "claudeCode.allowedTools")
|
|
9
10
|
return undefined;
|
|
10
11
|
const options = {
|
|
11
12
|
...(toolNames.length === 0 ? {} : { allowedTools: toolNames.map(mcpToolRule) }),
|
|
12
13
|
...(readOnly === undefined ? {} : { disallowedTools: [...readOnly.disallowedTools], ...readOnly.sessionOptions }),
|
|
14
|
+
...(extras.sandbox === undefined ? {} : { sandbox: claudeSandboxOptions(extras.sandbox) }),
|
|
15
|
+
...(extras.lockSkipPermissions === true ? { allowDangerouslySkipPermissions: false } : {}),
|
|
13
16
|
};
|
|
14
17
|
return Object.keys(options).length === 0 ? undefined : { claudeCode: { options } };
|
|
15
18
|
}
|
|
@@ -7,6 +7,15 @@ export declare const TOOL_HOST_PATH = "/mcp";
|
|
|
7
7
|
export declare const MAX_BODY_BYTES: number;
|
|
8
8
|
/** Past this many body bytes the 413 is sent at once and the connection closed. */
|
|
9
9
|
export declare const MAX_DRAIN_BYTES: number;
|
|
10
|
+
export interface ToolHostOptions {
|
|
11
|
+
/**
|
|
12
|
+
* nax#2517: the MCP `initialize` result's `instructions`, so the agent's own
|
|
13
|
+
* MCP client receives the same `## MCP servers` text a native session is
|
|
14
|
+
* given. The SDK drops an empty one (`server/index.js`), and so does the
|
|
15
|
+
* backend before it gets here.
|
|
16
|
+
*/
|
|
17
|
+
readonly instructions?: string;
|
|
18
|
+
}
|
|
10
19
|
export interface ToolHost {
|
|
11
20
|
/** Known before start(), so every redaction set can include it. */
|
|
12
21
|
readonly token: string;
|
|
@@ -22,4 +31,8 @@ export interface ToolHost {
|
|
|
22
31
|
stop(): Promise<void>;
|
|
23
32
|
}
|
|
24
33
|
export declare function newToolHostToken(): string;
|
|
25
|
-
|
|
34
|
+
/**
|
|
35
|
+
* `opts.instructions` (nax#2517) rides every MCP `initialize` this host answers:
|
|
36
|
+
* the agent's MCP client reads it there, not from the prompt.
|
|
37
|
+
*/
|
|
38
|
+
export declare function createToolHost(calls: ToolCalls, token?: string, opts?: ToolHostOptions): ToolHost;
|
package/dist/client/tool-host.js
CHANGED
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
* refuses to reuse a stateless transport. The token exists before the host
|
|
8
8
|
* listens, so it joins the session's redaction set from the start (D4-i). stop()
|
|
9
9
|
* revokes the token, aborts calls, drops open connections and closes the port
|
|
10
|
-
* (D4-l).
|
|
10
|
+
* (D4-l). The host's `initialize` result carries the session's provider
|
|
11
|
+
* instructions when the backend supplied them (#2517).
|
|
11
12
|
*/
|
|
12
13
|
import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
|
|
13
14
|
import { createServer } from "node:http";
|
|
@@ -91,7 +92,10 @@ function readBody(req) {
|
|
|
91
92
|
async function serveMcp(state, req, res, body) {
|
|
92
93
|
const gone = new AbortController();
|
|
93
94
|
const signal = AbortSignal.any([gone.signal, state.stopped.signal]);
|
|
94
|
-
const server = new Server(SERVER_INFO, {
|
|
95
|
+
const server = new Server(SERVER_INFO, {
|
|
96
|
+
capabilities: { tools: {} },
|
|
97
|
+
...(state.instructions === undefined ? {} : { instructions: state.instructions }),
|
|
98
|
+
});
|
|
95
99
|
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: state.calls.list() }));
|
|
96
100
|
server.setRequestHandler(CallToolRequestSchema, (request) => state.calls.call(request.params.name, request.params.arguments, signal));
|
|
97
101
|
const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
|
|
@@ -148,8 +152,18 @@ async function close(http) {
|
|
|
148
152
|
});
|
|
149
153
|
await race(closed, { timeoutMs: CLOSE_WAIT_MS });
|
|
150
154
|
}
|
|
151
|
-
|
|
152
|
-
|
|
155
|
+
/**
|
|
156
|
+
* `opts.instructions` (nax#2517) rides every MCP `initialize` this host answers:
|
|
157
|
+
* the agent's MCP client reads it there, not from the prompt.
|
|
158
|
+
*/
|
|
159
|
+
export function createToolHost(calls, token = newToolHostToken(), opts = {}) {
|
|
160
|
+
const state = {
|
|
161
|
+
token,
|
|
162
|
+
calls,
|
|
163
|
+
instructions: opts.instructions,
|
|
164
|
+
stopped: new AbortController(),
|
|
165
|
+
port: 0,
|
|
166
|
+
};
|
|
153
167
|
const http = createServer((req, res) => {
|
|
154
168
|
void handle(state, req, res).catch(() => failed(res));
|
|
155
169
|
});
|