@nathapp/nax-agent 0.91.6 → 0.91.7-canary.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/dist/coding-tools/coding-tool-extras.d.ts +52 -0
  3. package/dist/coding-tools/coding-tool-extras.js +56 -0
  4. package/dist/coding-tools/coding-tool-support.d.ts +9 -0
  5. package/dist/coding-tools/coding-tool-support.js +12 -1
  6. package/dist/config/catalog-overrides.d.ts +9 -0
  7. package/dist/index.d.ts +4 -2
  8. package/dist/index.js +2 -1
  9. package/dist/internal/argv-exec.d.ts +6 -0
  10. package/dist/internal/argv-exec.js +158 -63
  11. package/dist/mcp/connect.js +26 -3
  12. package/dist/mcp/types.d.ts +7 -0
  13. package/dist/native/adapter-deps.d.ts +2 -0
  14. package/dist/native/adapter-deps.js +2 -0
  15. package/dist/native/models.js +2 -0
  16. package/dist/native/session/loop-events/types.d.ts +5 -0
  17. package/dist/native/session-adapter.js +19 -5
  18. package/dist/permissions/approval-memory.d.ts +18 -0
  19. package/dist/permissions/approval-memory.js +88 -0
  20. package/dist/permissions/index.d.ts +1 -0
  21. package/dist/permissions/index.js +1 -0
  22. package/dist/permissions/types.d.ts +6 -0
  23. package/dist/runtime/node-runtime.js +5 -0
  24. package/dist/sandbox/claude-settings.d.ts +2 -1
  25. package/dist/sandbox/claude-settings.js +7 -3
  26. package/dist/sandbox/defaults.js +1 -0
  27. package/dist/sandbox/launcher.js +7 -0
  28. package/dist/sandbox/types.d.ts +6 -0
  29. package/dist/session/agent-session-command.d.ts +19 -0
  30. package/dist/session/agent-session-command.js +38 -0
  31. package/dist/session/agent-session-types.d.ts +26 -0
  32. package/dist/session/agent-session.js +86 -1
  33. package/dist/session/native-backend-options.d.ts +37 -2
  34. package/dist/session/native-backend-options.js +39 -3
  35. package/dist/session/native-backend.js +55 -5
  36. package/dist/session/native-posture-rules.d.ts +18 -0
  37. package/dist/session/native-posture-rules.js +33 -0
  38. package/dist/session/session-ask-link.d.ts +6 -0
  39. package/dist/session/session-ask-link.js +5 -0
  40. package/dist/session/session-ask-port.js +4 -0
  41. package/dist/session/session-backend.d.ts +23 -1
  42. package/dist/session/session-interaction.d.ts +2 -0
  43. package/dist/session/session-interaction.js +8 -1
  44. package/dist/session/session-tool-support.d.ts +49 -3
  45. package/dist/session/session-tool-support.js +66 -11
  46. package/dist/session-store/index.d.ts +3 -0
  47. package/dist/session-store/index.js +3 -0
  48. package/dist/session-store/session-lock-guard.d.ts +6 -0
  49. package/dist/session-store/session-lock-guard.js +85 -0
  50. package/dist/session-store/session-lock.d.ts +39 -0
  51. package/dist/session-store/session-lock.js +178 -0
  52. package/dist/session-store/session-meta.d.ts +27 -0
  53. package/dist/session-store/session-meta.js +20 -0
  54. package/dist/session-store/storage.d.ts +39 -0
  55. package/dist/session-store/storage.js +164 -0
  56. package/dist/tools/ask-request.d.ts +18 -0
  57. package/dist/tools/ask-request.js +30 -0
  58. package/dist/tools/bash-background.d.ts +74 -0
  59. package/dist/tools/bash-background.js +151 -0
  60. package/dist/tools/bash.d.ts +11 -0
  61. package/dist/tools/bash.js +77 -17
  62. package/dist/tools/git.js +10 -3
  63. package/dist/tools/policy-match.d.ts +2 -2
  64. package/dist/tools/policy-match.js +9 -6
  65. package/dist/tools/policy-paths-branch.js +4 -1
  66. package/dist/tools/provider-advertise.d.ts +7 -0
  67. package/dist/tools/provider-advertise.js +13 -1
  68. package/dist/tools/provider-types.d.ts +6 -0
  69. package/dist/tools/run-command-exec.js +12 -0
  70. package/dist/tools/run-command-surface.d.ts +28 -0
  71. package/dist/tools/run-command-surface.js +109 -0
  72. package/dist/tools/run-command.d.ts +17 -16
  73. package/dist/tools/run-command.js +48 -68
  74. package/dist/tools/runtime-calltool.d.ts +101 -0
  75. package/dist/tools/runtime-calltool.js +112 -3
  76. package/dist/tools/runtime.d.ts +12 -0
  77. package/dist/tools/runtime.js +36 -18
  78. package/dist/tools/types.d.ts +8 -0
  79. package/package.json +3 -3
@@ -20,7 +20,7 @@ import { openShadowTap } from "#src/command-safety/index";
20
20
  import { errorMessage } from "#src/infra/errors";
21
21
  import { getSafeLogger } from "#src/infra/index";
22
22
  import { ASK_CANCELLED_REASON } from "#src/permissions/index";
23
- import { askDenyReason, askSummary } from "./ask-request.js";
23
+ import { askDenyReason, askSummary, unsandboxedReasonSuffix } from "./ask-request.js";
24
24
  import { redirectForArgv, redirectForCommand, redirectForVerb } from "./denial-redirect.js";
25
25
  import { BASH_TOOL_NAME, EXEC_TOOL_NAME } from "./types.js";
26
26
  /**
@@ -38,6 +38,98 @@ export function resolvePolicyIdentity(name, tool, input) {
38
38
  const policyIdentity = hasArgv ? EXEC_TOOL_NAME : name;
39
39
  return { policyIdentity, argvField, hasArgv };
40
40
  }
41
+ /** The content of the refusal a disabled escape request gets (spec US-005). */
42
+ const UNSANDBOXED_NOT_ENABLED = "unsandboxed commands are not enabled for this session (allowUnsandboxedCommands)";
43
+ /**
44
+ * US-005: the sandbox-escape gate, run once per call BEFORE the policy.
45
+ *
46
+ * Whether an escape is PERMITTED is the runtime's decision, not the tool's:
47
+ * the tool only knows what the call asked for, and it runs exactly as it
48
+ * always did once this gate lets it through. Three conditions narrow the field
49
+ * to the calls that really are escape requests — the tool declares an
50
+ * `unsandboxedField`, the policy identity is one the flag is defined for, and
51
+ * the value is exactly `true` (a `"true"` string is not an escape: an opted-in
52
+ * session's schema rejects it at the transport, and every other session reads
53
+ * it as the ordinary call it is).
54
+ *
55
+ * - `error` — this session was not opened with `unsandboxed.enabled`, so the
56
+ * call never reaches the policy, an ask or a spawn. Deciding it here rather
57
+ * than in the tool is what makes "disabled" mean disabled.
58
+ * - `unsandboxed` — the escape is allowed. `suffix` is the clause an ask this
59
+ * call raises must carry, so the person approving it is told the command
60
+ * runs outside the sandbox; `asksOnAllow` says whether an ALLOW still has to
61
+ * be raised as one (US-006). The policy itself is evaluated unchanged: the
62
+ * flag is not a policy input, so the verdict is the one the call would get
63
+ * without it.
64
+ *
65
+ * The mode is read from the runtime's option rather than the compiled policy:
66
+ * `bashApproval` decides how an ENABLED request is ROUTED, which is the
67
+ * runtime's business, while the policy line answers only "is this command
68
+ * form granted". An `Exec` (argv) call is routed by the same mode — it is the
69
+ * other model-authored identity, and no separate Exec approval mode exists.
70
+ */
71
+ export function resolveUnsandboxedCall(p) {
72
+ const field = p.tool.scope.unsandboxedField;
73
+ if (field === undefined)
74
+ return undefined;
75
+ if (p.identity !== BASH_TOOL_NAME && p.identity !== EXEC_TOOL_NAME)
76
+ return undefined;
77
+ if (p.input[field] !== true)
78
+ return undefined;
79
+ if (p.option?.enabled !== true)
80
+ return { kind: "error", content: UNSANDBOXED_NOT_ENABLED };
81
+ return {
82
+ kind: "unsandboxed",
83
+ suffix: unsandboxedReasonSuffix(p.input),
84
+ asksOnAllow: p.option.alwaysAsk === true || p.option.bashApproval !== "raw",
85
+ };
86
+ }
87
+ /** The reason a converted allow carries (spec US-006), before the suffix. */
88
+ const UNSANDBOXED_ASK_REASON = "unsandboxed run requested";
89
+ /**
90
+ * US-006: the ask a permitted escape request raises where the policy only
91
+ * allowed it.
92
+ *
93
+ * An allow says "this command form is granted", nothing about the sandbox:
94
+ * under `gated` that same grant runs the command WRAPPED, and under `escalate`
95
+ * only a grant MISS asks. So an escape request the policy merely allowed would
96
+ * otherwise run unwrapped with nobody told, which is the whole thing the
97
+ * approval exists to prevent. `raw` is exempt (`asksOnAllow`), and a verdict
98
+ * that already asks or denies is left to the ordinary paths.
99
+ *
100
+ * The rule is SYNTHETIC — `Unsandboxed(<identity>)` is expressible in no
101
+ * config — so it goes on `rule` only; `matchedRule` stays unset (see
102
+ * `SYNTHETIC_UNSANDBOXED_RULE`). `resolvedPaths` is carried over so an
103
+ * approved call admits exactly what the policy resolved.
104
+ */
105
+ export function convertUnsandboxedAllow(p) {
106
+ if (p.unsandboxed?.kind !== "unsandboxed" || !p.unsandboxed.asksOnAllow)
107
+ return undefined;
108
+ if (!p.verdict.allowed)
109
+ return undefined;
110
+ return {
111
+ allowed: false,
112
+ outcome: "ask",
113
+ breach: false,
114
+ rule: `Unsandboxed(${p.identity})`,
115
+ reason: UNSANDBOXED_ASK_REASON,
116
+ resolvedPaths: p.verdict.resolvedPaths,
117
+ };
118
+ }
119
+ /**
120
+ * The verdict this call raises an ask with, or undefined when it raises none.
121
+ *
122
+ * One place decides both the ask the policy itself produced (US-005) and the
123
+ * one an ALLOWED escape request is converted into (US-006), so `callTool`
124
+ * keeps a single ask branch and the conversion cannot drift from the ordinary
125
+ * route. A denial that is final — `outcome` absent or "denied" — is NOT an
126
+ * ask and comes back undefined, leaving `resolveDenialOutcome` to answer it.
127
+ */
128
+ export function resolveAskVerdict(p) {
129
+ if (p.verdict.allowed)
130
+ return convertUnsandboxedAllow(p);
131
+ return p.verdict.outcome === "ask" ? p.verdict : undefined;
132
+ }
41
133
  /**
42
134
  * P5: observe the command now (not awaited), settled from the caller's
43
135
  * logCall below. Undefined whenever the runtime has no shadow configured.
@@ -127,6 +219,20 @@ export async function resolveGuardDenial(p) {
127
219
  return undefined;
128
220
  }
129
221
  }
222
+ /**
223
+ * US-004: `Unsandboxed(<identity>)` is the SYNTHETIC rule US-006's
224
+ * converted-allow verdict carries — not an ask rule anyone configured. It is
225
+ * kept on `rule` (the request has to name what it is) but never becomes
226
+ * `matchedRule`, because a remembered approval derives its `origin` from that
227
+ * field and would then remember a rule that exists in no config.
228
+ */
229
+ const SYNTHETIC_UNSANDBOXED_RULE = /^Unsandboxed\(.*\)$/;
230
+ /** The configured ask rule behind a verdict, or undefined when there is none. */
231
+ function matchedRuleOf(verdict) {
232
+ if (verdict.rule === undefined)
233
+ return undefined;
234
+ return SYNTHETIC_UNSANDBOXED_RULE.test(verdict.rule) ? undefined : verdict.rule;
235
+ }
130
236
  /**
131
237
  * The ask branch: a call the policy gates matched an ask rule, so an
132
238
  * AskResolver decides. US-003: build the AskControl from the per-call
@@ -141,21 +247,24 @@ export async function resolveAskOutcome(p) {
141
247
  ...(context?.onWaiting !== undefined ? { onWaiting: context.onWaiting } : {}),
142
248
  };
143
249
  const ask = askSummary(p.identity, tool.scope, input);
250
+ const askReason = p.unsandboxed === undefined ? verdict.reason : `${verdict.reason}${p.unsandboxed.suffix}`;
251
+ const matchedRule = matchedRuleOf(verdict);
144
252
  let askVerdict;
145
253
  try {
146
254
  askVerdict = await p.askResolver.resolve({
147
255
  tool: p.identity,
148
256
  stage: p.stage ?? "unknown",
149
257
  rule: verdict.rule ?? verdict.reason,
150
- ...(verdict.rule !== undefined ? { matchedRule: verdict.rule } : {}),
258
+ ...(matchedRule !== undefined ? { matchedRule } : {}),
151
259
  summary: ask.summary,
152
260
  ...(ask.unshowable ? { unshowable: true } : {}),
153
261
  ...(typeof input[tool.scope.commandField ?? ""] === "string"
154
262
  ? { command: input[tool.scope.commandField] }
155
263
  : {}),
156
264
  root: p.root,
157
- reason: verdict.reason,
265
+ reason: askReason,
158
266
  ...(p.storyId !== undefined ? { storyId: p.storyId } : {}),
267
+ ...(p.unsandboxed !== undefined ? { unsandboxed: true } : {}),
159
268
  }, askControl);
160
269
  }
161
270
  catch (err) {
@@ -10,6 +10,7 @@
10
10
  */
11
11
  import type { CommandInterceptor } from "#src/command-interceptor/index";
12
12
  import type { CommandShadow } from "#src/command-safety/index";
13
+ import type { BashApprovalMode } from "#src/config/bash-approval";
13
14
  import { getSafeLogger } from "#src/infra/index";
14
15
  import { type AskResolver } from "#src/permissions/index";
15
16
  import type { OwnedPathsPolicy } from "./owned-paths.ts";
@@ -149,4 +150,15 @@ export declare function createCodingToolRuntime(opts: {
149
150
  protectedPaths?: ProtectedPathsPolicy;
150
151
  /** S3-2 port: placed on every ToolRunContext this runtime builds. */
151
152
  ownedPaths?: OwnedPathsPolicy;
153
+ /**
154
+ * US-005: whether this session may run one call OUTSIDE the OS sandbox, and
155
+ * the Bash mode that routes an enabled request. ABSENT means disabled: a
156
+ * `Bash`/`Exec` call carrying `unsandboxed: true` is then refused before the
157
+ * policy evaluates it.
158
+ */
159
+ unsandboxed?: {
160
+ readonly enabled: boolean;
161
+ readonly bashApproval: BashApprovalMode;
162
+ readonly alwaysAsk?: boolean;
163
+ };
152
164
  }): CodingToolRuntime;
@@ -21,7 +21,7 @@ import { enforceInstructionAccess } from "./instruction-access.js";
21
21
  import { readTool } from "./read.js";
22
22
  import { getCodingTool, registerBuiltinTool } from "./registry.js";
23
23
  import { requestCapabilityTool } from "./request-capability.js";
24
- import { openCallShadowTap, resolveAskOutcome, resolveDenialOutcome, resolveGuardDenial, resolvePolicyIdentity, } from "./runtime-calltool.js";
24
+ import { openCallShadowTap, resolveAskOutcome, resolveAskVerdict, resolveDenialOutcome, resolveGuardDenial, resolvePolicyIdentity, resolveUnsandboxedCall, } from "./runtime-calltool.js";
25
25
  import { scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.js";
26
26
  import { applyModelTruncationPolicy } from "./spill.js";
27
27
  import { createNoOpToolAuditSink } from "./tool-audit.js";
@@ -199,9 +199,35 @@ export function createCodingToolRuntime(opts) {
199
199
  return { kind: "denied", reason, breach: false };
200
200
  }
201
201
  const { policyIdentity, argvField, hasArgv } = resolvePolicyIdentity(name, tool, input);
202
+ // Settled by `logCall`, which is declared FIRST so the refusal that
203
+ // precedes the policy can ledger through the same wrapper. Undefined
204
+ // until the shadow opens: nothing observed, nothing to settle.
205
+ let tap;
206
+ // Every ledger outcome of this call settles the tap exactly once, with
207
+ // `denied:ask` and `decidedBy` intact -- which CodingToolOutcome.kind
208
+ // alone would lose (spec 4.2). The audit is a named parameter, not a
209
+ // rest-array index: `log`'s positional shape can then change without
210
+ // silently shifting what the tap settles with.
211
+ const logCall = (tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation) => {
212
+ log(tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation);
213
+ tap?.settle(outcome, audit?.approval?.decidedBy, audit?.executed === undefined
214
+ ? undefined
215
+ : {
216
+ executed: audit.executed,
217
+ ...(audit.cwd !== undefined ? { cwd: audit.cwd } : {}),
218
+ });
219
+ };
220
+ // US-005: a `Bash`/`Exec` escape request is answered before the policy,
221
+ // the ask chain and any spawn — refused when this session never enabled
222
+ // it, and otherwise marked so the ask below carries the reason suffix.
223
+ const unsandboxed = resolveUnsandboxedCall({ identity: policyIdentity, tool, input, option: opts.unsandboxed });
224
+ if (unsandboxed?.kind === "error") {
225
+ logCall(policyIdentity, "error", unsandboxed.content.length, input, context, false, unsandboxed.content);
226
+ return unsandboxed;
227
+ }
202
228
  const verdict = opts.policy.check(policyIdentity, tool.scope, input);
203
229
  // P5: observe the command now (not awaited), settle from logCall below.
204
- const tap = openCallShadowTap({
230
+ tap = openCallShadowTap({
205
231
  shadow: opts.commandShadow,
206
232
  identity: policyIdentity,
207
233
  tool,
@@ -216,20 +242,6 @@ export function createCodingToolRuntime(opts) {
216
242
  context,
217
243
  verdict,
218
244
  });
219
- // Every ledger outcome of this call settles the tap exactly once, with
220
- // `denied:ask` and `decidedBy` intact -- which CodingToolOutcome.kind
221
- // alone would lose (spec 4.2). The audit is a named parameter, not a
222
- // rest-array index: `log`'s positional shape can then change without
223
- // silently shifting what the tap settles with.
224
- const logCall = (tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation) => {
225
- log(tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation);
226
- tap?.settle(outcome, audit?.approval?.decidedBy, audit?.executed === undefined
227
- ? undefined
228
- : {
229
- executed: audit.executed,
230
- ...(audit.cwd !== undefined ? { cwd: audit.cwd } : {}),
231
- });
232
- };
233
245
  /**
234
246
  * Executes a permitted call and records its outcome. Shared by the
235
247
  * ordinary allow path and an ask verdict an AskResolver approved, so an
@@ -283,13 +295,17 @@ export function createCodingToolRuntime(opts) {
283
295
  return { kind: "error", content };
284
296
  }
285
297
  }
286
- if (!verdict.allowed && verdict.outcome === "ask") {
298
+ // US-005/US-006: the ONE ask route. A verdict the policy raised as an
299
+ // ask goes there as it always did; an ALLOWED escape request is
300
+ // converted into one unless the mode already let it run (`raw`).
301
+ const askVerdict = resolveAskVerdict({ identity: policyIdentity, verdict, unsandboxed });
302
+ if (askVerdict !== undefined) {
287
303
  return resolveAskOutcome({
288
304
  identity: policyIdentity,
289
305
  tool,
290
306
  input,
291
307
  context,
292
- verdict,
308
+ verdict: askVerdict,
293
309
  runtimeSignal: signal,
294
310
  askResolver,
295
311
  stage: opts.pipelineStage,
@@ -297,6 +313,8 @@ export function createCodingToolRuntime(opts) {
297
313
  root: opts.policy.root,
298
314
  logCall,
299
315
  runTool,
316
+ // US-004/US-005: the ask says the command runs outside the sandbox.
317
+ ...(unsandboxed?.kind === "unsandboxed" ? { unsandboxed: { suffix: unsandboxed.suffix } } : {}),
300
318
  });
301
319
  }
302
320
  if (!verdict.allowed) {
@@ -110,6 +110,14 @@ export interface ToolScope {
110
110
  * tool declaring it must be granted explicitly, since no profile grants one.
111
111
  */
112
112
  readonly commandField?: string;
113
+ /**
114
+ * US-003: the input field by which a call asks to run OUTSIDE the OS sandbox
115
+ * (`Bash`'s `unsandboxed`). Declared unconditionally, so the runtime can read
116
+ * the field whether or not the session advertises it; whether the argument is
117
+ * OFFERED (schema + description) is the session's `unsandboxedCommands`
118
+ * option, and whether a call is PERMITTED is the runtime's decision.
119
+ */
120
+ readonly unsandboxedField?: string;
113
121
  }
114
122
  /**
115
123
  * `breach` separates "you may not write there" from "that path is not in this
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nathapp/nax-agent",
3
- "version": "0.91.6",
3
+ "version": "0.91.7-canary.10",
4
4
  "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
5
5
  "license": "MIT",
6
6
  "author": "William Khoo",
@@ -47,13 +47,13 @@
47
47
  "dependencies": {
48
48
  "@anthropic-ai/sandbox-runtime": "0.0.77",
49
49
  "@modelcontextprotocol/sdk": "^1.32.1",
50
- "@nathapp/nax-ai": "0.91.6",
50
+ "@nathapp/nax-ai": "0.91.7-canary.10",
51
51
  "zod": "^4.3.6"
52
52
  },
53
53
  "publishConfig": {
54
54
  "access": "public",
55
55
  "registry": "https://registry.npmjs.org/",
56
56
  "provenance": true,
57
- "tag": "latest"
57
+ "tag": "canary"
58
58
  }
59
59
  }