@nathapp/nax-agent 0.87.0 → 0.88.0-canary.1

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 (39) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/coding-tools/coding-tool-support.d.ts +15 -1
  3. package/dist/coding-tools/coding-tool-support.js +19 -8
  4. package/dist/command-safety/rule-scorer.d.ts +1 -1
  5. package/dist/command-safety/rule-scorer.js +11 -113
  6. package/dist/index.d.ts +1 -1
  7. package/dist/internal.d.ts +1 -0
  8. package/dist/internal.js +1 -0
  9. package/dist/native/errors.js +7 -0
  10. package/dist/native/session/session.d.ts +3 -0
  11. package/dist/native/session/session.js +7 -0
  12. package/dist/native/session/transcript-archive.d.ts +28 -0
  13. package/dist/native/session/transcript-archive.js +43 -0
  14. package/dist/session/session-types.d.ts +19 -0
  15. package/dist/tools/denial-redirect.d.ts +22 -7
  16. package/dist/tools/denial-redirect.js +29 -13
  17. package/dist/tools/git-flags/locate.d.ts +47 -0
  18. package/dist/tools/git-flags/locate.js +361 -0
  19. package/dist/tools/index.d.ts +1 -1
  20. package/dist/tools/nax-dirs.d.ts +22 -0
  21. package/dist/tools/nax-dirs.js +89 -0
  22. package/dist/tools/nax-evasion.d.ts +19 -0
  23. package/dist/tools/nax-evasion.js +88 -0
  24. package/dist/tools/nax-revert.d.ts +34 -0
  25. package/dist/tools/nax-revert.js +233 -0
  26. package/dist/tools/nax-state-guard.d.ts +18 -0
  27. package/dist/tools/nax-state-guard.js +496 -0
  28. package/dist/tools/policy-bash-raw.d.ts +3 -0
  29. package/dist/tools/policy-bash-raw.js +40 -12
  30. package/dist/tools/policy-bash.d.ts +3 -0
  31. package/dist/tools/policy-bash.js +38 -9
  32. package/dist/tools/policy-command-branch.d.ts +3 -0
  33. package/dist/tools/policy-command-branch.js +3 -1
  34. package/dist/tools/policy.js +4 -0
  35. package/dist/tools/provider-advertise.d.ts +18 -0
  36. package/dist/tools/provider-advertise.js +16 -5
  37. package/dist/tools/tool-audit.d.ts +42 -0
  38. package/dist/tools/tool-audit.js +5 -1
  39. package/package.json +3 -3
@@ -28,6 +28,8 @@
28
28
  import { lexBashCommand } from "#src/permissions/index";
29
29
  import { cdTargetsFor, nextWorkingDirectories } from "./bash-cwd.js";
30
30
  import { deniedFlag } from "./exec-guard.js";
31
+ import { isCoveringExclusion } from "./nax-revert.js";
32
+ import { naxStateRefusalInText } from "./nax-state-guard.js";
31
33
  function deny(reason, breach = false, escalatable = false) {
32
34
  return { kind: "deny", reason, breach, escalatable };
33
35
  }
@@ -119,7 +121,8 @@ function checkPayload(args, segment, cwd) {
119
121
  if (flag !== undefined)
120
122
  return { refusal: deny(`flag ${flag} is not permitted in a Bash command`) };
121
123
  for (const token of segment.tokens) {
122
- if (token.opaque || hasUnmodelledExpansion(token.text)) {
124
+ // The exact covering pathspec (a quoted glob) is git pathspec magic, not shell expansion (#2493).
125
+ if (token.opaque || (hasUnmodelledExpansion(token.text) && !isCoveringExclusion(token.text))) {
123
126
  return { refusal: deny(`token "${token.text}" depends on shell expansion this gate cannot resolve`) };
124
127
  }
125
128
  const target = containmentTarget(token.text);
@@ -188,12 +191,39 @@ function checkPayload(args, segment, cwd) {
188
191
  }
189
192
  return { cdTargets };
190
193
  }
191
- export function checkBashCommand(args) {
192
- const { command, tool } = args;
194
+ /** The shape guards: a non-string or blank command is refused before anything is lexed. */
195
+ function invalidCommandDenial(command) {
193
196
  if (typeof command !== "string")
194
197
  return deny(`"command" must be a string`);
195
- if (command.trim() === "")
196
- return deny(`"command" must not be empty`);
198
+ return command.trim() === "" ? deny(`"command" must not be empty`) : undefined;
199
+ }
200
+ /**
201
+ * nax's run state (#2490): revert, index-hiding and stash in any segment,
202
+ * nested shell or unreadable construct. Never escalatable, and checked BEFORE
203
+ * any escalatable refusal so a user approval can never run it.
204
+ */
205
+ function stateDenial(args) {
206
+ const refusal = naxStateRefusalInText(String(args.command), {
207
+ frames: [args.initialPath],
208
+ root: args.initialPath,
209
+ ...(args.naxDirs !== undefined ? { naxDirs: args.naxDirs } : {}),
210
+ });
211
+ return refusal === undefined ? undefined : deny(refusal);
212
+ }
213
+ function lexicalDenial(lexed) {
214
+ if (lexed.kind !== "refused")
215
+ return undefined;
216
+ return deny(`command contains ${lexed.construct}, which cannot be analysed and is therefore refused -- ` +
217
+ "rewrite it without that construct, or use a structured tool", false, true);
218
+ }
219
+ export function checkBashCommand(args) {
220
+ const { command, tool } = args;
221
+ const invalid = invalidCommandDenial(command);
222
+ if (invalid !== undefined)
223
+ return invalid;
224
+ const state = stateDenial(args);
225
+ if (state !== undefined)
226
+ return state;
197
227
  const lexed = lexBashCommand(command);
198
228
  // On a refusal the gate still runs its deny and payload checks -- over the
199
229
  // lexable prefix, the part before the unreadable construct. The prefix is
@@ -212,10 +242,9 @@ export function checkBashCommand(args) {
212
242
  return result.refusal;
213
243
  cwd = nextWorkingDirectories(segment, cwd, result.cdTargets);
214
244
  }
215
- if (lexed.kind === "refused") {
216
- return deny(`command contains ${lexed.construct}, which cannot be analysed and is therefore refused -- ` +
217
- "rewrite it without that construct, or use a structured tool", false, true);
218
- }
245
+ const lexical = lexicalDenial(lexed);
246
+ if (lexical !== undefined)
247
+ return lexical;
219
248
  for (const segment of segments) {
220
249
  if (args.grant.unconditional || matchesSegment(args.grant, segment))
221
250
  continue;
@@ -10,6 +10,7 @@
10
10
  * reaching `resolveWithin` back would close a cycle.
11
11
  */
12
12
  import type { BashApprovalMode } from "#src/config/bash-approval";
13
+ import type { NaxDirIndex } from "./nax-dirs.ts";
13
14
  import type { OwnedPathsPolicy } from "./owned-paths.ts";
14
15
  import type { CompiledEntry } from "./policy-match.ts";
15
16
  import type { PolicyVerdict, ToolScope } from "./types.ts";
@@ -26,6 +27,8 @@ export interface BashCommandBranchArgs {
26
27
  /** S3-2: host-owned path rules; the `raw` screen hands it one candidate per live frame. */
27
28
  readonly ownedPaths: OwnedPathsPolicy;
28
29
  readonly resolvedRoot: string;
30
+ /** Per-policy cache of the `.nax` directories below the root, shared by every Bash call (#2493). */
31
+ readonly naxDirs?: NaxDirIndex;
29
32
  readonly denyBy: ReadonlyMap<string, CompiledEntry>;
30
33
  readonly askBy: ReadonlyMap<string, CompiledEntry>;
31
34
  readonly resolvePath: (candidate: string, cwd: string) => string | null;
@@ -12,7 +12,7 @@
12
12
  import { checkBashCommand } from "./policy-bash.js";
13
13
  import { screenRawBashCommand } from "./policy-bash-raw.js";
14
14
  export function commandBranch(args) {
15
- const { tool, scope, input, grant, bashApproval, rawBashRefusal, sandboxWrapped, ownedPaths, resolvedRoot, denyBy, askBy, resolvePath, deny, askVerdict, } = args;
15
+ const { tool, scope, input, grant, bashApproval, rawBashRefusal, sandboxWrapped, ownedPaths, resolvedRoot, naxDirs, denyBy, askBy, resolvePath, deny, askVerdict, } = args;
16
16
  if (scope.commandField === undefined)
17
17
  return undefined;
18
18
  if (bashApproval === "raw") {
@@ -23,6 +23,7 @@ export function commandBranch(args) {
23
23
  command: input[scope.commandField],
24
24
  initialPath: resolvedRoot,
25
25
  root: resolvedRoot,
26
+ ...(naxDirs !== undefined ? { naxDirs } : {}),
26
27
  sandboxWrapped: sandboxWrapped === true,
27
28
  resolvePath,
28
29
  ownedPaths,
@@ -40,6 +41,7 @@ export function commandBranch(args) {
40
41
  ...(denyEntry !== undefined ? { denyEntry } : {}),
41
42
  ...(askEntry !== undefined ? { askEntry } : {}),
42
43
  initialPath: resolvedRoot,
44
+ ...(naxDirs !== undefined ? { naxDirs } : {}),
43
45
  resolvePath,
44
46
  });
45
47
  if (result.kind === "deny") {
@@ -16,6 +16,7 @@
16
16
  import { relative, resolve, sep } from "node:path";
17
17
  import { realOrRaw } from "#src/internal/realpath";
18
18
  import { validateArgv } from "./exec-guard.js";
19
+ import { createNaxDirIndex } from "./nax-dirs.js";
19
20
  import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
20
21
  import { commandBranch } from "./policy-command-branch.js";
21
22
  import { compileArgvPattern, compileRuleMap, globToRegExp, matchedArgvSource, matchedGlobSource, matchedRulePatterns, matchesAny, matchesArgvGrant, } from "./policy-match.js";
@@ -35,6 +36,8 @@ function isFieldlessScope(scope) {
35
36
  }
36
37
  export function compileToolPolicy(grants, root, options) {
37
38
  const resolvedRoot = realOrRaw(root);
39
+ // One downward `.nax` scan per compiled policy, shared by every Bash call it checks (#2493).
40
+ const naxDirs = createNaxDirIndex();
38
41
  const owned = options?.ownedPaths ?? EMPTY_OWNED_PATHS_POLICY;
39
42
  // nax#2115: the SAME transform `relativeTo` applies to every checked path, so
40
43
  // the guard compares like with like. A path outside the root yields a
@@ -220,6 +223,7 @@ export function compileToolPolicy(grants, root, options) {
220
223
  sandboxWrapped: options?.sandboxWrapped,
221
224
  ownedPaths: owned,
222
225
  resolvedRoot,
226
+ naxDirs,
223
227
  denyBy,
224
228
  askBy,
225
229
  resolvePath: (candidate, cwd) => resolveWithin(resolvedRoot, resolve(cwd, candidate), owned),
@@ -9,6 +9,24 @@ export interface ResolvedProviderTools {
9
9
  providerId: string;
10
10
  reason: string;
11
11
  }[];
12
+ /**
13
+ * Providers whose configured `stages` exclude this hop's stage, with the
14
+ * stages they were configured for (#2410 gap 2: a misconfigured `stages`
15
+ * must be visible, not silent). The scope-none arm contributes the
16
+ * whole-layer `provider-scope:none` row (permission profile `safe`, or a
17
+ * `rules` scope that resolved no providers).
18
+ */
19
+ readonly skipped: readonly {
20
+ providerId: string;
21
+ reason: "stage-mismatch" | "provider-scope:none";
22
+ stages: readonly string[];
23
+ }[];
24
+ /** Sanitised tools a scoped stage's `admits` rejected (#2410 gap 1). */
25
+ readonly withheld: readonly {
26
+ providerId: string;
27
+ localName: string;
28
+ reason: "not-admitted";
29
+ }[];
12
30
  /**
13
31
  * Advertised tool name -> owning provider id, carried explicitly so the
14
32
  * ledger never has to parse the `<id>__<local>` name apart (a naming
@@ -2,9 +2,13 @@
2
2
  * Per-hop resolution of provider tools.
3
3
  *
4
4
  * A provider whose `tools()` rejects is DROPPED, not fatal: a broken provider
5
- * must never wedge a run. The failure is logged by the caller, which owns the
6
- * logger; this module stays pure so it can be tested without one.
5
+ * must never wedge a run. The failure reason is carried in `failures` and
6
+ * logged by the caller, which owns the logger. Stage mismatches and
7
+ * `admits`-rejected tools are carried in `skipped`/`withheld` (#2410) and the
8
+ * stage skip is logged once here at debug — the null-safe logger keeps the
9
+ * module testable without one.
7
10
  */
11
+ import { getSafeLogger } from "#src/infra/index";
8
12
  import { adaptProviderTool } from "./provider-adapt.js";
9
13
  import { expandProviderGrants } from "./provider-grants.js";
10
14
  import { sanitizeProviderTools } from "./provider-sanitize.js";
@@ -13,16 +17,23 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
13
17
  const tools = [];
14
18
  const entries = [];
15
19
  const failures = [];
20
+ const skipped = [];
21
+ const withheld = [];
16
22
  const providerIdByTool = new Map();
17
23
  for (const provider of providers) {
18
- if (!providerAttachesTo(provider, stage))
24
+ if (!providerAttachesTo(provider, stage)) {
25
+ skipped.push({ providerId: provider.id, reason: "stage-mismatch", stages: provider.stages });
26
+ getSafeLogger()?.debug("mcp", `[provider] ${provider.id} not attached`, { stage, stages: provider.stages });
19
27
  continue;
28
+ }
20
29
  try {
21
30
  const sanitized = sanitizeProviderTools(provider.kind, await provider.tools(workdir));
22
31
  const localNames = [];
23
32
  for (const tool of sanitized) {
24
- if (options?.admits !== undefined && !options.admits(provider.id, tool.localName))
33
+ if (options?.admits !== undefined && !options.admits(provider.id, tool.localName)) {
34
+ withheld.push({ providerId: provider.id, localName: tool.localName, reason: "not-admitted" });
25
35
  continue;
36
+ }
26
37
  const adapted = adaptProviderTool(provider.id, tool);
27
38
  tools.push(adapted);
28
39
  providerIdByTool.set(adapted.name, provider.id);
@@ -34,7 +45,7 @@ export async function resolveProviderTools(providers, stage, workdir, options) {
34
45
  failures.push({ providerId: provider.id, reason: String(error) });
35
46
  }
36
47
  }
37
- return { tools, grants: expandProviderGrants(entries), failures, providerIdByTool, entries };
48
+ return { tools, grants: expandProviderGrants(entries), failures, skipped, withheld, providerIdByTool, entries };
38
49
  }
39
50
  /**
40
51
  * Bytes a tool list costs the prompt, paid on EVERY hop whether or not any
@@ -164,8 +164,50 @@ export interface ToolAuditHeader {
164
164
  readonly storyId?: string;
165
165
  readonly sessionRole?: string;
166
166
  }
167
+ /**
168
+ * Which MCP provider tools a session was OFFERED — the delivery-side twin of
169
+ * the per-call `calls` rows (#2410 gap 1). Present in the file body as
170
+ * `toolSurface` whenever a session's hop resolved provider tools, so
171
+ * "the model ignored the tool" can be told apart from "the tool was never
172
+ * advertised".
173
+ */
174
+ export interface ToolSurfaceDraft {
175
+ /** The pipeline stage the session was resolved for. */
176
+ readonly stage: string;
177
+ /** The op's materialized declaration (what the profile/delivery decision saw). */
178
+ readonly declaredTools: readonly string[];
179
+ /** Provider tools actually offered: (providerId, local names) with content. */
180
+ readonly advertised: readonly {
181
+ providerId: string;
182
+ names: readonly string[];
183
+ }[];
184
+ /** Provider tools resolved but not offered, with why. */
185
+ readonly withheld: readonly {
186
+ providerId: string;
187
+ name?: string;
188
+ reason: string;
189
+ }[];
190
+ /** Providers skipped whole, with why. */
191
+ readonly skippedProviders: readonly {
192
+ id: string;
193
+ reason: string;
194
+ stages?: readonly string[];
195
+ }[];
196
+ /** Providers whose `tools()` rejected (same rows as `failures`). */
197
+ readonly failures: readonly {
198
+ providerId: string;
199
+ reason: string;
200
+ }[];
201
+ }
202
+ /** A draft stamped with the transport (and, on ACP, the narrowed profile). */
203
+ export interface ToolSurfaceRecord extends ToolSurfaceDraft {
204
+ readonly transport: "native" | "acp";
205
+ readonly profile?: "full" | "read";
206
+ }
167
207
  export declare function createToolAuditSink(opts: {
168
208
  dir: string;
169
209
  sessionName: string;
170
210
  header?: ToolAuditHeader;
211
+ /** The session's MCP tool surface (#2410): present ⇒ the file is written even with zero calls. */
212
+ toolSurface?: ToolSurfaceRecord;
171
213
  }): RegisteredSink;
@@ -129,7 +129,10 @@ export function createToolAuditSink(opts) {
129
129
  // may still run afterwards must not write a second, non-partial file.
130
130
  let partialFlushed = false;
131
131
  const write = async (partial) => {
132
- if (calls.length === 0)
132
+ // Zero calls normally means "nothing to audit" — but a surface with no
133
+ // calls is exactly the never-called session #2410 exists to expose, so it
134
+ // must still produce its file.
135
+ if (calls.length === 0 && opts.toolSurface === undefined)
133
136
  return;
134
137
  await mkdir(opts.dir, { recursive: true });
135
138
  const body = JSON.stringify({
@@ -139,6 +142,7 @@ export function createToolAuditSink(opts) {
139
142
  // Additive and optional: absent on a normal flush, `true` only when the
140
143
  // shutdown path persisted a buffer its hop never closed.
141
144
  ...(partial ? { partial: true } : {}),
145
+ ...(opts.toolSurface !== undefined ? { toolSurface: opts.toolSurface } : {}),
142
146
  calls: redactRowStrings(calls),
143
147
  }, null, 2);
144
148
  const prefix = runId !== undefined ? `${runId}-` : "";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nathapp/nax-agent",
3
- "version": "0.87.0",
3
+ "version": "0.88.0-canary.1",
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.87.0",
50
+ "@nathapp/nax-ai": "0.88.0-canary.1",
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
  }