@nathapp/nax-agent 0.1.0

package/dist/tools/runtime-calltool.js

@@ -0,0 +1,223 @@
+/**
+ * `callTool`'s branch bodies, extracted from `runtime.ts` for the A13
+ * complexity drain (docs/plans/STATUS-complexity-drain.md).
+ *
+ * Each helper is one free function taking a single options object; the
+ * closure-bound collaborators (`logCall`, `runTool`, the session-wide
+ * `signal`) arrive BY REFERENCE and are read at call time, so the
+ * `_codingToolDeps` seam stays defined in `runtime.ts` exactly as the barrel
+ * (`src/tools/index.ts`) re-exports it. This file imports `runtime.ts`
+ * TYPE-ONLY — a runtime import would cycle back to the factory.
+ *
+ * One asymmetry is preserved on purpose: the denial-path breach warn below and the
+ * rejected-guard warn (US-004) call the module-level `getSafeLogger` import
+ * directly, while the ledger `log` in `runtime.ts` reads
+ * `_codingToolDeps.getLogger()`. Both behaved that way before the extraction;
+ * the seam stub in the mirror suites has never covered either warn.
+ */
+import { randomUUID } from "node:crypto";
+import { openShadowTap } from "#src/command-safety/index";
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { ASK_CANCELLED_REASON } from "#src/permissions/index";
+import { askDenyReason, askSummary } from "./ask-request.js";
+import { redirectForArgv, redirectForCommand, redirectForVerb } from "./denial-redirect.js";
+import { BASH_TOOL_NAME, EXEC_TOOL_NAME } from "./types.js";
+/**
+ * A call carrying the tool's declared argv field (RunCommand's `Exec`
+ * branch) is checked, and ledgered, under the `Exec` identity rather
+ * than the tool's own name. Left as `name`, an `Exec(...)` grant would
+ * never be consulted — the call would run under RunCommand's own grant
+ * (often a wildcard for its declared commands), making the allowlist
+ * decorative. The tool's registered name is unaffected; this changes
+ * only which identity the policy and ledger see for THIS call.
+ */
+export function resolvePolicyIdentity(name, tool, input) {
+    const argvField = tool.scope.argvField;
+    const hasArgv = argvField !== undefined && input[argvField] !== undefined;
+    const policyIdentity = hasArgv ? EXEC_TOOL_NAME : name;
+    return { policyIdentity, argvField, hasArgv };
+}
+/**
+ * P5: observe the command now (not awaited), settled from the caller's
+ * logCall below. Undefined whenever the runtime has no shadow configured.
+ */
+export function openCallShadowTap(p) {
+    if (p.shadow === undefined)
+        return undefined;
+    return openShadowTap(p.shadow, {
+        key: randomUUID(),
+        identity: p.identity,
+        command: p.tool.scope.commandField === undefined ? undefined : p.input[p.tool.scope.commandField],
+        argv: p.hasArgv && p.argvField !== undefined ? p.input[p.argvField] : undefined,
+        root: p.root,
+        verdict: p.verdict,
+        stage: p.stage ?? "unknown",
+        ...(p.storyId !== undefined ? { storyId: p.storyId } : {}),
+        ...(p.callId !== undefined ? { callId: p.callId } : {}),
+        ...(p.scopeId !== undefined ? { scopeId: p.scopeId } : {}),
+        ...(p.context?.turnId !== undefined ? { turnId: p.context.turnId } : {}),
+        ...(p.context?.roundTrips !== undefined ? { roundTrips: p.context.roundTrips } : {}),
+        ...(p.context?.toolCallId !== undefined ? { toolCallId: p.context.toolCallId } : {}),
+    });
+}
+/**
+ * The command string the guard assesses, or undefined for an identity the
+ * guard does not cover. `Bash` reports its `command` field; `Exec` — the
+ * identity a `RunCommand` call carrying `argv` resolves to — reports the argv
+ * joined with single spaces, exactly the string the shadow observes and
+ * classifies. Any other identity (and a malformed command / argv) is not
+ * guarded; the policy has already refused that input.
+ */
+function guardCommand(p) {
+    if (p.identity === BASH_TOOL_NAME) {
+        const field = p.tool.scope.commandField;
+        const value = field === undefined ? undefined : p.input[field];
+        return typeof value === "string" ? value : undefined;
+    }
+    if (p.identity !== EXEC_TOOL_NAME || p.argvField === undefined)
+        return undefined;
+    const argv = p.input[p.argvField];
+    if (!Array.isArray(argv) || !argv.every((a) => typeof a === "string"))
+        return undefined;
+    return argv.join(" ");
+}
+/**
+ * US-004: the guard's flag-for-review route for an ALLOWED command.
+ *
+ * Returns the ask-shaped denial the flagged call routes through
+ * `resolveAskOutcome`, and undefined in every other case — no guard
+ * configured, an identity other than `Bash`/`Exec`, or an unflagged
+ * assessment — so the caller runs the tool exactly as it did before the guard
+ * existed. The guard is total by contract (US-003); a rejection, or a resolved
+ * decision the type does not actually hold, means that contract broke, so the
+ * call runs unguarded rather than being refused, and the failure is logged once
+ * per broken call.
+ */
+export async function resolveGuardDenial(p) {
+    const { guard } = p;
+    if (guard === undefined)
+        return undefined;
+    const command = guardCommand(p);
+    if (command === undefined)
+        return undefined;
+    // The whole decision — the assessment AND reading its fields — sits inside
+    // the fail-open try: the guard is total by contract, so anything that
+    // escapes here means the contract broke, including a resolved decision whose
+    // `score`/`threshold` is not the number the type promises. Both fail the
+    // same way: the call runs unguarded rather than erroring out of callTool.
+    try {
+        const decision = await guard.assess({ command, cwd: p.root, tempConfined: p.tempConfined });
+        if (!decision.flagged)
+            return undefined;
+        const { category, score, threshold } = decision;
+        return {
+            allowed: false,
+            outcome: "ask",
+            breach: false,
+            rule: "command-safety",
+            reason: `flagged for review by command safety: ${category ?? "blocked"} (score ${score.toFixed(2)} >= ${threshold})`,
+            resolvedPaths: p.resolvedPaths,
+        };
+    }
+    catch (err) {
+        getSafeLogger()?.warn("command-safety", "Command-safety guard failed; the call runs unguarded", {
+            error: errorMessage(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * The ask branch: a call the policy gates matched an ask rule, so an
+ * AskResolver decides. US-003: build the AskControl from the per-call
+ * context. The turn's abort signal is forwarded verbatim, and onWaiting is
+ * wired so the resolver can tell the turn loop a human prompt is pending.
+ */
+export async function resolveAskOutcome(p) {
+    const { context, input, tool, verdict } = p;
+    const callSignal = context?.signal ?? p.runtimeSignal;
+    const askControl = {
+        ...(callSignal !== undefined ? { signal: callSignal } : {}),
+        ...(context?.onWaiting !== undefined ? { onWaiting: context.onWaiting } : {}),
+    };
+    const ask = askSummary(p.identity, tool.scope, input);
+    let askVerdict;
+    try {
+        askVerdict = await p.askResolver.resolve({
+            tool: p.identity,
+            stage: p.stage ?? "unknown",
+            rule: verdict.rule ?? verdict.reason,
+            ...(verdict.rule !== undefined ? { matchedRule: verdict.rule } : {}),
+            summary: ask.summary,
+            ...(ask.unshowable ? { unshowable: true } : {}),
+            ...(typeof input[tool.scope.commandField ?? ""] === "string"
+                ? { command: input[tool.scope.commandField] }
+                : {}),
+            root: p.root,
+            reason: verdict.reason,
+            ...(p.storyId !== undefined ? { storyId: p.storyId } : {}),
+        }, askControl);
+    }
+    catch (err) {
+        const content = errorMessage(err);
+        p.logCall(p.identity, "error", content.length, input, context, false, content);
+        return { kind: "error", content };
+    }
+    const approval = {
+        decidedBy: askVerdict.decidedBy,
+        remembered: false,
+        latencyMs: askVerdict.latencyMs,
+    };
+    if (askVerdict.decision === "allow") {
+        // US-003 AC11: recheck the turn signal AFTER the resolver returned
+        // allow. A resolver that approves after the turn has been cancelled
+        // would otherwise race ahead and execute the tool; we deny instead
+        // with the same cancelled reason, so the agent never sees a tool
+        // result from a turn that has already ended.
+        if (callSignal?.aborted === true) {
+            const reason = `${verdict.reason} -- ${ASK_CANCELLED_REASON}`;
+            p.logCall(p.identity, "denied:ask", reason.length, input, context, false, reason, undefined, {
+                approval,
+            });
+            return { kind: "denied", reason, breach: false };
+        }
+        return p.runTool(tool, input, verdict.resolvedPaths ?? [], approval);
+    }
+    const reason = `${verdict.reason} -- ${askDenyReason(askVerdict.decidedBy)}`;
+    p.logCall(p.identity, "denied:ask", reason.length, input, context, false, reason, undefined, { approval });
+    return { kind: "denied", reason, breach: false };
+}
+/**
+ * The deny branch: a final policy refusal, sharpened where possible with a
+ * redirect naming an advertised tool that serves the call's intent.
+ */
+export function resolveDenialOutcome(p) {
+    const { input, context, verdict } = p;
+    if (verdict.breach) {
+        // In band so an unattended run survives one bad path guess, but loud:
+        // a path escaping the root can indicate prompt injection.
+        getSafeLogger()?.warn("tools", "[policy] path resolved outside the permitted root", {
+            tool: p.identity,
+            reason: verdict.reason,
+            root: p.root,
+        });
+    }
+    const commandField = p.tool.scope.commandField;
+    const rawCommand = commandField === undefined ? undefined : input[commandField];
+    const rawArgv = p.argvField === undefined ? undefined : input[p.argvField];
+    const verbField = p.tool.scope.verbField;
+    const rawVerb = verbField === undefined ? undefined : input[verbField];
+    const declared = p.declaredCommands ?? new Set();
+    // An argv call and a verb call deny through different policy branches;
+    // before #1971 only the first could reach a redirect at all.
+    const extra = typeof rawCommand === "string"
+        ? redirectForCommand(rawCommand, p.advertisedNames, declared)
+        : Array.isArray(rawArgv)
+            ? redirectForArgv(rawArgv, p.advertisedNames, declared)
+            : typeof rawVerb === "string"
+                ? redirectForVerb(p.name, rawVerb, p.advertisedNames, declared)
+                : undefined;
+    const reason = extra === undefined ? verdict.reason : `${verdict.reason} -- ${extra}`;
+    p.logCall(p.identity, "denied", reason.length, input, context, verdict.breach, reason);
+    return { kind: "denied", reason, breach: verdict.breach };
+}

package/dist/tools/runtime.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Pairs the compiled policy with the tool registry and answers one call.
+ *
+ * nax-permission-mode-allow: consumes grants resolved by resolvePermissions;
+ * makes no permission decision of its own.
+ *
+ * The three outcomes are kept structurally distinct. Reusing one channel for a
+ * refusal and a crash would make a denied permission look like a recoverable
+ * tool error, which ADR-029 section 5 forbids.
+ */
+import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { CommandShadow } from "#src/command-safety/index";
+import { getSafeLogger } from "#src/infra/index";
+import { type AskResolver } from "#src/permissions/index";
+import type { ProtectedPathsPolicy } from "./protected-paths.ts";
+import { type CodingTool } from "./registry.ts";
+import { type ToolAuditSink } from "./tool-audit.ts";
+import type { ToolPolicy } from "./types.ts";
+/** Per-call output ceiling, mirroring ToolDescriptor.maxTokensPerCall in spirit. */
+export declare const DEFAULT_TOOL_MAX_BYTES = 40000;
+/**
+ * Largest file a tool will read whole or write at all.
+ *
+ * Distinct from DEFAULT_TOOL_MAX_BYTES because they answer different questions:
+ * that one is how much the model may be told, this one is how much file a tool
+ * will handle. Edit must read and rewrite a file entirely, so it cannot use the
+ * output ceiling without refusing ordinary source files.
+ *
+ * Generous on purpose. Nothing an LLM legitimately edits approaches it, and a
+ * limit that fires during normal work would be worked around rather than
+ * respected.
+ */
+export declare const DEFAULT_TOOL_MAX_FILE_BYTES = 2000000;
+export type CodingToolOutcome = {
+    readonly kind: "ok" | "error";
+    readonly content: string;
+    /** Records the final model-facing content when shaping was deferred. */
+    readonly finalizeAudit?: (content: string) => void;
+} | {
+    readonly kind: "denied";
+    readonly reason: string;
+    readonly breach: boolean;
+};
+/** Injectable logger seam, mirroring _pullToolsDeps.getLogger. */
+export declare const _codingToolDeps: {
+    getLogger: typeof getSafeLogger;
+};
+/** Per-call context. Identity fields are recorded on the audit ledger. */
+export interface ToolCallContext {
+    readonly turnId?: string;
+    readonly roundTrips?: number;
+    readonly toolCallId?: string;
+    /** Return the full result so a downstream model-facing chokepoint can shape it. */
+    readonly deferModelTruncation?: boolean;
+    /**
+     * US-002: the turn's abort signal, forwarded from the native coding-tool
+     * request. `runTool` copies it onto the `ToolRunContext` so the tool can
+     * stop in-flight work (Bash/Exec SIGKILL their process group) when the
+     * turn is cancelled, exactly as the runtime-level `signal` does when no
+     * per-call signal is present.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * US-002: notifies the runtime's caller (and through it the turn loop)
+     * that this tool is about to WAIT on something external, so an idle
+     * watchdog does not time it out. Forwarded from the native coding-tool
+     * request; tools that wait on a human call it before blocking.
+     */
+    readonly onWaiting?: () => void;
+}
+export interface CodingToolRuntime {
+    /** Op declaration intersected with policy grants. Both can only narrow. */
+    advertised(declared: readonly string[]): readonly CodingTool[];
+    callTool(name: string, input: Record<string, unknown>, context?: ToolCallContext): Promise<CodingToolOutcome>;
+}
+/** Idempotent: the registry is process-global, the runtime is per-session. */
+export declare function registerBuiltinCodingTools(): void;
+/** @internal Test-only: pairs with _resetRegistryForTest. */
+export declare function _resetBuiltinsForTest(): void;
+export declare function createCodingToolRuntime(opts: {
+    policy: ToolPolicy;
+    maxBytes?: number;
+    maxFileBytes?: number;
+    /**
+     * Tool-layer I/O bound. Defaults to `READ_CEILING` when absent — tools
+     * bound their reads to this ceiling before any model-facing truncation
+     * policy runs. Distinct from `maxBytes` (model-facing) and `maxFileBytes`
+     * (whole-file Edit/Write cap).
+     */
+    readCeiling?: number;
+    /**
+     * Aborts in-flight tool work (US-001). Bash and RunCommand's argv branch
+     * forward it to their launcher / runArgv call, which SIGKILLs the process
+     * group. Optional so existing callers compile unchanged.
+     */
+    signal?: AbortSignal;
+    storyId?: string;
+    callId?: string;
+    scopeId?: string;
+    sink?: ToolAuditSink;
+    extraTools?: readonly CodingTool[];
+    /**
+     * Advertised provider tool name -> owning provider id. Lets the ledger carry
+     * the provider explicitly instead of splitting the namespaced name apart.
+     */
+    providerIdByTool?: ReadonlyMap<string, string>;
+    /** Declared command names, so a denial can name `testScoped` only when the project has one. */
+    declaredCommands?: ReadonlySet<string>;
+    /**
+     * Repo-configurable glob denylist (nax#1972, `execution.denyPaths`),
+     * forwarded verbatim into every ToolRunContext this runtime builds. See
+     * src/tools/deny-paths.ts for the matching semantics; today only Delete
+     * consults it.
+     */
+    denyPaths?: readonly string[];
+    /**
+     * Answers an `ask` verdict (spec R1/R6). Defaults to the headless resolver,
+     * which always denies: an unattended run has no human to approve. A runtime
+     * capability, not config — injected where the runtime is created.
+     */
+    askResolver?: AskResolver;
+    /**
+     * PipelineStage this runtime serves, carried verbatim into every
+     * `AskRequest`. A resolver decides on the stage as much as on the tool --
+     * "yes during rectification, no during review" is the first policy anyone
+     * writes -- so it is threaded in rather than defaulted at the call site.
+     */
+    pipelineStage?: string;
+    /**
+     * P5 shadow classifier (spec 2026-09-23-p5-command-safety-shadow-design.md).
+     * The shadow itself is observational: it never changes a verdict, delays or
+     * fails a call. Its optional `guard` (US-004) is the one exception the
+     * master plan allows (D4a) — a flag-for-review guardrail, never an
+     * auto-approver: a flagged ALLOWED `Bash`/`Exec` call is routed through the
+     * existing ask channel, which decides.
+     */
+    commandShadow?: CommandShadow;
+    /**
+     * US-004: whether the session's sandbox confines temp writes to this run's
+     * own temp root (#2285). Forwarded to the guard's temp-only exemption;
+     * absent reads as false, the shared-temp posture every pre-US-002 launcher
+     * has. Derived from `isTempConfined(launcher)` in coding-tool-support.
+     */
+    tempConfined?: boolean;
+    /** Port 7: placed on every ToolRunContext this runtime builds. */
+    interceptor?: CommandInterceptor;
+    /** Port 6: placed on every ToolRunContext this runtime builds. */
+    protectedPaths?: ProtectedPathsPolicy;
+}): CodingToolRuntime;