@nathapp/nax-agent 0.1.0

package/dist/tools/registry.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Name-to-tool registry, mirroring PULL_TOOL_REGISTRY in the context engine.
+ *
+ * Open to third-party registration, with two rules that make that safe:
+ * built-in names are reserved (a registered "Write" would shadow the gated
+ * implementation), and a verb-gated tool must declare the verbs it permits so
+ * the policy can never be granted a subcommand the tool itself disallows.
+ *
+ * Registration is in-process — another nax module or plugin. This is an
+ * extension point, not a plugin download path.
+ */
+import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { JSONSchema } from "#src/session/tool-descriptor";
+import type { SandboxRecord } from "../sandbox/index.ts";
+import type { ProtectedPathsPolicy } from "./protected-paths.ts";
+import type { CodingToolName, ToolScope } from "./types.ts";
+export interface ToolResult {
+    readonly content: string;
+    readonly isError?: boolean;
+    /**
+     * Set only by RunCommand's argv branch (`Exec`), which is the one call
+     * shape whose executed argv can differ from what the model requested
+     * (normalization scopes it to a workspace member and may append a
+     * no-scripts mechanism). Returned here rather than re-derived by the
+     * runtime so the ledger records the argv that actually ran. Task 7 reads
+     * this to write `executed`/`target` onto the ledger row; this task only
+     * defines and returns it.
+     *
+     * The `Git` tool also sets `audit` when a command interceptor rewrote its
+     * argv — there `target` is absent, because the repoRoot/package distinction
+     * does not apply to a git read.
+     */
+    readonly audit?: {
+        readonly executed: readonly string[];
+        readonly target?: "repoRoot" | "package";
+        /** Exec only: the directory the argv ran in. Read by the command-safety shadow, not the ledger. */
+        readonly cwd?: string;
+        /** P4: how an agent-authored Bash/Exec command ran; absent for every other tool. */
+        readonly sandbox?: SandboxRecord;
+        /**
+         * Bash only: the shell's exit code, present when nax did NOT kill the
+         * process group -- absent under `timedOut` (deadline kill) and `aborted`
+         * (turn cancellation), present under `orphansKilled` (the shell exited by
+         * itself; only background processes were reaped). What N means depends on
+         * the command in `executed` (exit 1 is "no match" for grep, "failures" for
+         * a test runner), and N >= 128 may still be a signal nax did not send.
+         */
+        readonly exitCode?: number;
+    };
+    /**
+     * Result size in bytes BEFORE the tool truncated to `ctx.maxBytes`. Set by
+     * tools whose payload is unbounded by nature — an MCP graph query can return
+     * megabytes. `resultBytes` on the ledger is measured after the slice, so
+     * without this a 2 MB result and a 40 KB one are indistinguishable and "how
+     * much did we discard" is unanswerable.
+     */
+    readonly resultBytesPreTruncation?: number;
+}
+export interface ToolRunContext {
+    /** Absolute, symlink-resolved permitted root. */
+    readonly root: string;
+    /** Paths the policy already resolved and approved, in pathFields order. */
+    readonly resolvedPaths: readonly string[];
+    /** Output ceiling in bytes; the tool truncates rather than the caller. */
+    readonly maxBytes: number;
+    /**
+     * Largest file this tool may read whole or write. Bounds the work, where
+     * maxBytes bounds only what the model is told -- see src/tools/bounded.ts.
+     */
+    readonly maxFileBytes: number;
+    /**
+     * Tool-layer I/O bound. Optional so existing `ToolRunContext` literals
+     * compile unchanged; resolves to `READ_CEILING` when absent. Distinct
+     * from `maxFileBytes` (whole-file Edit/Write cap) and `maxBytes` (the
+     * model-facing ceiling owned by `after_tool`).
+     */
+    readonly readCeiling?: number;
+    /**
+     * Repo-configurable glob denylist (nax#1972, `execution.denyPaths` in
+     * config), narrowing what a tool may act on beyond containment and grants.
+     * Currently consumed by Delete only -- see src/tools/deny-paths.ts. Absent
+     * or empty means no additional narrowing.
+     */
+    readonly denyPaths?: readonly string[];
+    /**
+     * Aborts the turn's process execution; Bash and Exec forward it to the
+     * launcher and runArgv, which SIGKILL the process group. US-001.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * The run's command interceptor (US-003; S1 spec section 4.2, port 7). The
+     * same object for every tool of a run, so the Git and Bash sites share one
+     * binary probe and one mode. Absent when the run installed none: interception
+     * then does not apply, the fail-safe both sites state.
+     */
+    readonly interceptor?: CommandInterceptor;
+    /** Host-owned paths (S1 spec port 6). Absent: the Git tools exclude and skip nothing extra. */
+    readonly protectedPaths?: ProtectedPathsPolicy;
+}
+export interface CodingTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JSONSchema;
+    readonly scope: ToolScope;
+    /**
+     * True when an `isError` result is a routine part of using this tool rather
+     * than a fault worth an operator's attention. Only `RunCommand` sets it: a
+     * non-zero exit from a project command is the agent's own red/green loop, and
+     * on the acpx transport that loop runs inside the spawned agent where nax
+     * never observes it. Such calls are recorded at debug — the JSONL and the
+     * audit sink still get them, the console does not. Everything else defaults
+     * to false, so a malformed Read or a failed GitCommit stays visible.
+     */
+    readonly routineErrors?: boolean;
+    run(input: Record<string, unknown>, ctx: ToolRunContext): Promise<ToolResult>;
+}
+/** Built-in names may never be re-registered. */
+export declare const RESERVED_TOOL_NAMES: readonly CodingToolName[];
+export declare function registerCodingTool(tool: CodingTool): void;
+/** Register a nax built-in, bypassing the reserved-name check by design. */
+export declare function registerBuiltinTool(tool: CodingTool): void;
+export declare function getCodingTool(name: string): CodingTool | undefined;
+export declare function listCodingTools(): readonly CodingTool[];
+/** @internal Test-only: clears registrations between cases. */
+export declare function _resetRegistryForTest(): void;

package/dist/tools/registry.js

@@ -0,0 +1,67 @@
+/**
+ * Name-to-tool registry, mirroring PULL_TOOL_REGISTRY in the context engine.
+ *
+ * Open to third-party registration, with two rules that make that safe:
+ * built-in names are reserved (a registered "Write" would shadow the gated
+ * implementation), and a verb-gated tool must declare the verbs it permits so
+ * the policy can never be granted a subcommand the tool itself disallows.
+ *
+ * Registration is in-process — another nax module or plugin. This is an
+ * extension point, not a plugin download path.
+ */
+import { NaxError } from "#src/infra/index";
+/** Built-in names may never be re-registered. */
+export const RESERVED_TOOL_NAMES = [
+    "Read",
+    "Glob",
+    "Grep",
+    "Write",
+    "Edit",
+    "Delete",
+    "Git",
+    "GitCommit",
+    "RunCommand",
+    "RequestCapability",
+    "Exec",
+    "Bash",
+    "ScratchpadWrite",
+    "ScratchpadRead",
+    "ScratchpadList",
+];
+const registry = new Map();
+export function registerCodingTool(tool) {
+    if (RESERVED_TOOL_NAMES.includes(tool.name) && !internalRegistration) {
+        throw new NaxError(`Tool name "${tool.name}" is reserved for a nax built-in and cannot be re-registered.`, "TOOL_NAME_RESERVED", { stage: "tools", tool: tool.name });
+    }
+    if (registry.has(tool.name)) {
+        throw new NaxError(`Tool "${tool.name}" is already registered.`, "TOOL_ALREADY_REGISTERED", {
+            stage: "tools",
+            tool: tool.name,
+        });
+    }
+    if (tool.scope.verbField !== undefined && tool.scope.allowedVerbs === undefined) {
+        throw new NaxError(`Tool "${tool.name}" declares verbField but no allowedVerbs; the policy would have no bound to enforce.`, "TOOL_SCOPE_INCOMPLETE", { stage: "tools", tool: tool.name });
+    }
+    registry.set(tool.name, tool);
+}
+let internalRegistration = false;
+/** Register a nax built-in, bypassing the reserved-name check by design. */
+export function registerBuiltinTool(tool) {
+    internalRegistration = true;
+    try {
+        registerCodingTool(tool);
+    }
+    finally {
+        internalRegistration = false;
+    }
+}
+export function getCodingTool(name) {
+    return registry.get(name);
+}
+export function listCodingTools() {
+    return [...registry.values()];
+}
+/** @internal Test-only: clears registrations between cases. */
+export function _resetRegistryForTest() {
+    registry.clear();
+}

package/dist/tools/request-capability.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Declares a capability the model wanted and could not reach. Runs nothing.
+ *
+ * A denial is only produced if the model attempts a call, and a model told it
+ * has no shell will not attempt one -- so the absence of denials would be
+ * indistinguishable from the absence of need. Issue #1800 is the worked
+ * example: a reviewer said in prose "I have no file/shell access tool in this
+ * environment" and then returned a pass, and nothing structured captured it.
+ *
+ * The refusal is the point. The value is the row it leaves behind.
+ */
+import type { CodingTool } from "./registry.ts";
+export declare const requestCapabilityTool: CodingTool;

package/dist/tools/request-capability.js

@@ -0,0 +1,23 @@
+export const requestCapabilityTool = {
+    name: "RequestCapability",
+    description: "Declare a capability you need but do not have (for example a shell command you would have run). This grants nothing and runs nothing; it records the need so the tool set can be widened later.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            capability: { type: "string", description: "What you would have run or reached, verbatim" },
+            reason: { type: "string", description: "Why you needed it, in one sentence" },
+        },
+        required: ["capability"],
+    },
+    scope: { pathFields: [] },
+    async run(input, _ctx) {
+        const capability = input.capability;
+        if (typeof capability !== "string" || capability.trim() === "") {
+            return { content: "capability must be a non-empty string", isError: true };
+        }
+        return {
+            content: `Recorded: "${capability}" is not available on this path. Continue without it, or stop and say you cannot proceed.`,
+            isError: true,
+        };
+    },
+};

package/dist/tools/run-command-exec.d.ts

@@ -0,0 +1,14 @@
+import type { ToolResult, ToolRunContext } from "./registry.ts";
+import type { RunCommandToolOptions } from "./run-command.ts";
+/**
+ * Deadline for the argv branch's spawn (`runExecBranch`).
+ *
+ * Deliberately longer than the declared branch's own default deadline
+ * (120_000ms, in the project's quality-command runner): a declared quality
+ * command runs entirely on code already on disk, while an install-shaped
+ * argv call here talks to a package registry over the network and may run
+ * a vendor postinstall script — both routinely take longer than a
+ * project's own test/lint/typecheck command.
+ */
+export declare const EXEC_TIMEOUT_MS = 300000;
+export declare function runExecBranch(input: Record<string, unknown>, ctx: ToolRunContext, opts: RunCommandToolOptions): Promise<ToolResult>;

package/dist/tools/run-command-exec.js

@@ -0,0 +1,161 @@
+/**
+ * RunCommand's second, allowlisted call shape (`Exec`): a model-authored argv
+ * rather than a declared command key.
+ *
+ * Split out of run-command.ts (fix round 1, Minor) so the no-shell guarantee
+ * is structural rather than a comment pinned to file layout: this file must
+ * never import the declared branch's shell-templated command executor
+ * (the RunCommand sibling module resolves and spawns those through a real
+ * shell) or its shell-argument quoting helper (there is no shell string
+ * here to quote). `test/unit/tools/run-command-exec.test.ts` reads this
+ * file WHOLE and asserts neither one appears anywhere in it — a whole-file
+ * check that cannot be defeated by moving functions around within it,
+ * unlike the prior slice-from-a-known-function-name guard.
+ *
+ * Order matters and is fixed: `validateArgv` (shape/metacharacters) runs
+ * before `runExecBranch` is even reached — the runtime's policy check
+ * already ran it against the raw argv before `run()` was called at all, see
+ * `src/tools/policy.ts`. It is re-checked here too, because this function
+ * must also be safe to call directly, bypassing the runtime (as this file's
+ * own tests do). Then `deniedFlag` (source/destination-redirecting flags a
+ * verb-prefix grant cannot see), then `normalizeExec` (install-shaped
+ * hardening and workspace scoping), then `runArgv`.
+ */
+import { relative } from "node:path";
+import { agentOutputOverlay } from "#src/internal/agent-output-env";
+import { runArgv } from "#src/internal/argv-exec";
+import { formatExecBody } from "#src/internal/exec-framing";
+import { deniedFlag, validateArgv } from "./exec-guard.js";
+import { normalizeExec } from "./package-managers.js";
+import { cutToByteCap, READ_CEILING } from "./truncate.js";
+/**
+ * Deadline for the argv branch's spawn (`runExecBranch`).
+ *
+ * Deliberately longer than the declared branch's own default deadline
+ * (120_000ms, in the project's quality-command runner): a declared quality
+ * command runs entirely on code already on disk, while an install-shaped
+ * argv call here talks to a package registry over the network and may run
+ * a vendor postinstall script — both routinely take longer than a
+ * project's own test/lint/typecheck command.
+ */
+export const EXEC_TIMEOUT_MS = 300_000;
+/**
+ * Layer the AGENT=1 overlay onto an existing Exec env (or build a fresh env
+ * with just the overlay). Returns undefined when both inputs are undefined
+ * so the caller can omit the `env` key entirely and let `Bun.spawn` inherit
+ * the parent's environment on its own — the same shape `withAgentOutputEnv`
+ * applied via `normalizeEnvironment` in the verification runner, but here the
+ * inputs are partial: the Exec env is optional and the overlay may also be
+ * undefined when a marker is inherited or AGENT is stripped.
+ */
+function mergedExecEnv(execEnv, strippedVars) {
+    const agentOverlay = agentOutputOverlay(strippedVars);
+    if (agentOverlay === undefined)
+        return execEnv !== undefined ? { ...execEnv } : undefined;
+    return { ...(execEnv ?? {}), ...agentOverlay };
+}
+/**
+ * Spawn the normalized argv through the launcher when one is configured and
+ * fall back to a direct `runArgv` call otherwise. The launcher branch carries
+ * the `stripEnvVars` as a shared array (Bun.spawn reads it once), while the
+ * direct branch spreads it so the deps seam sees the same shape every other
+ * `_argvExecDeps.spawn` test stubs.
+ */
+async function launchExec(req) {
+    if (req.launcher !== undefined) {
+        return await req.launcher.run({
+            spec: { kind: "argv", argv: req.argv },
+            root: req.root,
+            cwd: req.cwd,
+            timeoutMs: EXEC_TIMEOUT_MS,
+            stripEnvVars: req.stripEnvVars,
+            ...(req.mergedEnv !== undefined ? { env: req.mergedEnv } : {}),
+            ...(req.signal !== undefined ? { signal: req.signal } : {}),
+        });
+    }
+    return {
+        ...(await runArgv({
+            argv: req.argv,
+            cwd: req.cwd,
+            timeoutMs: EXEC_TIMEOUT_MS,
+            stripEnvVars: [...req.stripEnvVars],
+            // Yarn 2+ carries its no-scripts mechanism here rather than in argv.
+            ...(req.mergedEnv !== undefined ? { env: req.mergedEnv } : {}),
+            ...(req.signal !== undefined ? { signal: req.signal } : {}),
+        })),
+        sandbox: undefined,
+    };
+}
+export async function runExecBranch(input, ctx, opts) {
+    if (opts.exec === undefined)
+        return { content: "argv is not available on this path", isError: true };
+    const invalid = validateArgv(input.argv);
+    if (invalid !== undefined)
+        return { content: invalid, isError: true };
+    const argv = input.argv;
+    // Real narrowing, not a cast: validateArgv above already rejected an
+    // empty argv, so this destructure cannot actually miss -- kept as a
+    // defensive fallback (matching package-managers.ts's own "unreachable"
+    // comments) rather than a postfix `!` or an `as string`.
+    const [binary] = argv;
+    if (binary === undefined)
+        return { content: "argv must not be empty", isError: true };
+    const flag = deniedFlag(argv);
+    if (flag !== undefined)
+        return { content: `flag ${flag} is not permitted`, isError: true };
+    const target = input.target === "repoRoot" ? "repoRoot" : "package";
+    const packageRelPath = relative(opts.exec.repoRoot, opts.exec.packageWorkdir);
+    const normalized = normalizeExec({
+        argv,
+        target,
+        repoRoot: opts.exec.repoRoot,
+        packageWorkdir: opts.exec.packageWorkdir,
+        packageRelPath,
+        allowScripts: opts.exec.allowScripts,
+        ...(opts.exec.packageName !== undefined ? { packageName: opts.exec.packageName } : {}),
+    });
+    if ("error" in normalized)
+        return { content: normalized.error, isError: true };
+    // US-004: opt the child into agent-friendly output. The Exec branch never
+    // rewrites the argv (that's the model's command), and the overlay is only
+    // `AGENT=1` — same rule the quality and verification runners apply. An
+    // inherited marker (`CLAUDECODE`/`REPL_ID`) speaks for itself, and a
+    // stripped AGENT stays stripped. The overlay is layered on top of any Exec
+    // env (the Yarn no-scripts key) so the latter survives wrapping alongside.
+    const mergedEnv = mergedExecEnv(normalized.env, opts.stripEnvVars ?? []);
+    try {
+        const launched = await launchExec({
+            argv: normalized.argv,
+            root: ctx.root,
+            cwd: normalized.cwd,
+            launcher: opts.exec.launcher,
+            mergedEnv,
+            stripEnvVars: opts.stripEnvVars ?? [],
+            signal: ctx.signal,
+        });
+        // US-001: match Bash's framing so an aborted Exec is rendered as an
+        // error with the cancellation banner (AC14 mirror) and an orphansKilled
+        // Exec appends the same `[nax]` footer (AC15 mirror).
+        const text = formatExecBody(launched, EXEC_TIMEOUT_MS);
+        return {
+            content: cutToByteCap(text, ctx.readCeiling ?? READ_CEILING),
+            isError: launched.timedOut || launched.exitCode !== 0 || launched.aborted === true,
+            // Task 7 reads this to write `executed` and `target` onto the ledger
+            // row. Returning it here, rather than re-deriving it in the runtime,
+            // keeps the recorded argv the one that actually ran.
+            audit: {
+                executed: normalized.argv,
+                target,
+                cwd: normalized.cwd,
+                ...(launched.sandbox !== undefined ? { sandbox: launched.sandbox } : {}),
+            },
+        };
+    }
+    catch (err) {
+        // A spawn-time failure (e.g. an unresolvable cwd) throws rather than
+        // resolving with a non-zero exit; surfaced as a normal tool error so it
+        // is indistinguishable, to the caller, from any other refusal above.
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: message, isError: true };
+    }
+}

package/dist/tools/run-command.d.ts

@@ -0,0 +1,107 @@
+import type { QualityCommandSpec } from "#src/internal/command-spec/index";
+import { type CommandLauncher } from "../sandbox/index.ts";
+import type { CodingTool } from "./registry.ts";
+/**
+ * Context for RunCommand's allowlisted, model-authored argv branch (`Exec`).
+ *
+ * Populated only when the operation declared the `Exec` marker
+ * (`buildCodingToolSupport` in `src/agents/coding-tool-support.ts`).
+ */
+export interface RunCommandExecOptions {
+    readonly repoRoot: string;
+    readonly packageWorkdir: string;
+    /** Manifest name, required by yarn/cargo's package-scoping form; absent when unresolvable. */
+    readonly packageName?: string;
+    readonly allowScripts: boolean;
+    /**
+     * The Exec tool's compiled grant patterns, as `resolvePermissions` produced
+     * them for THIS project/stage -- not `BUILT_IN_EXEC_PATTERNS` imported
+     * directly, because a project's own `Exec(...)` expression REPLACES that
+     * built-in list rather than extending it (see the comment on
+     * `BUILT_IN_EXEC_PATTERNS` in src/config/permissions.ts). Read only to
+     * render the tool description (#1937): the policy check itself still runs
+     * against the runtime's own compiled grant in policy.ts, so this field
+     * being stale or absent could make the description wrong but can never
+     * widen what actually executes.
+     */
+    readonly patterns: readonly string[];
+    /** P4: how the argv runs. Absent = direct runArgv (unit tests). */
+    readonly launcher?: CommandLauncher;
+}
+/** What RunCommand hands the runner for one declared command. */
+export interface DeclaredCommandRequest {
+    readonly commandName: string;
+    readonly command: QualityCommandSpec;
+    readonly workdir: string;
+    readonly stripEnvVars: string[];
+    readonly origin: "agent-tool";
+}
+/** What RunCommand reads back. */
+export interface DeclaredCommandResult {
+    readonly success: boolean;
+    readonly exitCode: number;
+    readonly output: string;
+}
+/** Runs one declared command; nax supplies `runQualityCommand` (S1 spec port 7). */
+export type DeclaredCommandRunner = (request: DeclaredCommandRequest) => Promise<DeclaredCommandResult>;
+export interface RunCommandToolOptions {
+    /** Secret environment variables excluded from agent-triggered commands. */
+    readonly stripEnvVars?: readonly string[];
+    /** See `RunCommandExecOptions`. */
+    readonly exec?: RunCommandExecOptions;
+    /**
+     * Execution cwd for the DECLARED (non-Exec) branch below, independent of
+     * `ctx.root` (tool containment). Falls back to `ctx.root` when absent —
+     * post-PR2 (single-frame redesign) `ctx.root` is the story's repo-rooted
+     * execution root, so an omitted `commandCwd` runs the declared command at
+     * the repo root, NOT the package dir. Every production caller threads
+     * `commandCwd` (see the `buildCodingToolSupport` producer below); the
+     * fallback is effectively unreachable in production and only fires from
+     * tests that bypass the support seam — see the use site for the exact
+     * behavior.
+     *
+     * PRODUCER: src/agents/coding-tool-support.ts (`buildCodingToolSupport`'s
+     * `commandCwd` arg).
+     */
+    readonly commandCwd?: string;
+    /**
+     * Runs a DECLARED (non-Exec) command (S1 spec section 4.2, port 7). nax
+     * supplies `runQualityCommand` through `resolveCodingToolSupport`; absent,
+     * the tool answers `exit 1` and spawns nothing.
+     */
+    readonly runDeclaredCommand?: DeclaredCommandRunner;
+}
+/**
+ * An ARRAY value is quoted per element and joined; a string value is quoted
+ * whole. The distinction carries the element boundaries through substitution,
+ * which a pre-joined string cannot: the join would be re-split and a path
+ * under `/tmp/my dir/` would become two arguments (nax#1998).
+ */
+export declare function substituteCommand(template: string, values: Record<string, string | readonly string[]>): string | {
+    error: string;
+};
+/**
+ * Apply placeholder substitution across a spec. A list substitutes into every
+ * entry and fails as a whole if any entry fails, so a partially-substituted
+ * list can never reach the shell.
+ *
+ * Each entry only receives the subset of `values` it actually declares
+ * placeholders for -- list entries commonly have different placeholder needs
+ * (e.g. `["tsc --noEmit", "bun test {{files}}"]`), and `substituteCommand`
+ * rejects a value that isn't a placeholder in the template it's checking, by
+ * design (it's what stops a value silently going nowhere). Passing the full
+ * shared `values` object to every entry would make every entry without
+ * {{files}} fail that check.
+ *
+ * But per-entry filtering alone would let a value that no entry in the whole
+ * spec declares vanish silently (every entry's filtered set would just be
+ * empty, and every entry would substitute cleanly) -- so before filtering
+ * per entry, every key in `values` is checked against the UNION of
+ * placeholders declared across the whole spec, and rejected with the same
+ * "unrecognized value" contract `substituteCommand` gives the single-string
+ * case if it isn't declared anywhere.
+ */
+export declare function substituteCommandSpec(spec: QualityCommandSpec, values: Record<string, string | readonly string[]>): QualityCommandSpec | {
+    error: string;
+};
+export declare function createRunCommandTool(declared: ReadonlyMap<string, QualityCommandSpec>, opts?: RunCommandToolOptions): CodingTool;