@nathapp/nax-agent 0.1.0

package/dist/internal/argv-exec.js

@@ -0,0 +1,224 @@
+/**
+ * Run an argv with no shell, a deadline, and a process-group kill.
+ *
+ * Extracted from worktree/dependencies.ts so its two callers cannot drift.
+ * The three behaviours here were each a defect once and must not be rewritten
+ * from scratch: MEM-4 (a postinstall grandchild survived proc.kill() and kept
+ * running against a deleted worktree), BUG-13 (a hung install had no deadline),
+ * and the concurrent drain (a child that fills a pipe buffer never reaches
+ * `exited`, defeating the timeout).
+ *
+ * US-001 adds three more invariants on the same shape:
+ * - `signal?: AbortSignal` aborts the process group and reports `aborted`.
+ * - An already-aborted signal never spawns and resolves with exitCode -1.
+ * - After `exited`, both readers get `DRAIN_GRACE_MS` to close; if either
+ *   stays open, the group is SIGKILLed and `orphansKilled: true` is set with
+ *   whatever the readers captured so far.
+ */
+import { runtimeSpawn } from "#src/runtime/index";
+import { killProcessGroup } from "./process-kill.js";
+/**
+ * Time, in milliseconds, the readers are allowed to drain after `exited`
+ * before runArgv SIGKILLs the whole group and reports `orphansKilled`. US-001.
+ * Injectable for tests; not exposed as user configuration.
+ */
+export const DRAIN_GRACE_MS = 500;
+/** Injectable seam, mirroring _worktreeDependencyDeps. */
+export const _argvExecDeps = {
+    spawn: runtimeSpawn,
+    killProcessGroup,
+    /**
+     * The post-exit drain grace (US-001). A real test can shrink it to keep the
+     * "background process holding the pipe" case under a second; production
+     * stays at the DRAIN_GRACE_MS constant.
+     */
+    drainGraceMs: DRAIN_GRACE_MS,
+    /**
+     * Injectable timer pair — lets the BUG-13 "hung install" test drive the
+     * timeout off a virtual clock instead of waiting the full 1s schema minimum.
+     * Mirrors `_heartbeatDeps` / `_idleWatchdogDeps` / `_authDeps`.
+     *
+     * @internal
+     */
+    setTimeout: ((fn, ms) => setTimeout(fn, ms)),
+    clearTimeout: ((id) => clearTimeout(id)),
+};
+/**
+ * Build the child's env only when the caller actually asked for stripping or
+ * an overlay. Leaving it `undefined` otherwise means `Bun.spawn` inherits
+ * `process.env` on its own, which is both the cheaper path and what every
+ * caller without those options already relied on before this seam existed.
+ */
+function buildEnv(options) {
+    const hasStrip = (options.stripEnvVars?.length ?? 0) > 0;
+    const hasOverlay = options.env !== undefined && Object.keys(options.env).length > 0;
+    if (!hasStrip && !hasOverlay)
+        return undefined;
+    const env = { ...process.env };
+    for (const name of options.stripEnvVars ?? [])
+        delete env[name];
+    Object.assign(env, options.env ?? {});
+    return env;
+}
+/**
+ * Read a ReadableStream<Uint8Array> to EOF, accumulating text. Resolves when
+ * the stream closes (done). The caller races this against a wall-clock
+ * deadline to detect an open-after-exit pipe (the `&`ed background case).
+ *
+ * `Response.text()` doesn't honour a deadline, so the reader is its own
+ * function (US-001 "Read stdout and stderr incrementally/concurrently").
+ *
+ * When `signal` aborts, the reader is cancelled so the pending `read()`
+ * resolves with `{done: true}`. The caller uses this to bound settlement
+ * after a process-group kill: a child that ignores the kill cannot pin
+ * runArgv forever on its still-open pipe.
+ */
+async function drainToEof(stream, signal) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    const onAbort = () => {
+        // Closing the stream forces the in-flight `read()` below to resolve with
+        // `{done: true}`; any bytes already captured stay in `text`.
+        reader.cancel().catch(() => {
+            // Cancelling after the pipe already closed is a no-op race; ignore.
+        });
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done === true)
+                break;
+            if (value !== undefined)
+                text += decoder.decode(value, { stream: true });
+        }
+    }
+    catch {
+        // Stream cancelled by SIGKILL on the process group; the partial text
+        // is still in `text`, so resolve with closed=false and let the caller
+        // decide.
+    }
+    text += decoder.decode();
+    if (signal !== undefined)
+        signal.removeEventListener("abort", onAbort);
+    try {
+        reader.releaseLock();
+    }
+    catch {
+        // Already released; nothing to do.
+    }
+    return { text, closed: true };
+}
+export async function runArgv(options) {
+    const signal = options.signal;
+    // Already-aborted signal: never spawn. The caller gets `aborted: true` with
+    // a sentinel exitCode so a misread of the field can't masquerade as a real
+    // process completing (US-001 AC7).
+    if (signal?.aborted === true) {
+        return { exitCode: -1, stdout: "", stderr: "", timedOut: false, aborted: true, orphansKilled: false };
+    }
+    const env = buildEnv(options);
+    // nax-git-env-allow: generic argv executor; caller-supplied argv, not routed through gitSpawnEnv
+    const proc = _argvExecDeps.spawn([...options.argv], {
+        cwd: options.cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+        ...(env !== undefined ? { env } : {}),
+        // MEM-4: setsid() makes this pid the process-group id, so a group kill
+        // reaches grandchildren (a package manager's postinstall) rather than only
+        // the direct child.
+        detached: true,
+    });
+    let timedOut = false;
+    let aborted = false;
+    let orphansKilled = false;
+    const killGroup = () => {
+        _argvExecDeps.killProcessGroup(proc.pid, "SIGKILL");
+    };
+    const stdoutController = new AbortController();
+    const stderrController = new AbortController();
+    const stopReaders = () => {
+        stdoutController.abort();
+        stderrController.abort();
+    };
+    // BUG-13: unlike every git call (routed through gitWithTimeout), a spawn
+    // with no deadline can block its caller forever on a hung install
+    // (registry/NFS stall).
+    const timerId = _argvExecDeps.setTimeout(() => {
+        timedOut = true;
+        // MEM-4: proc.kill() reaches only the direct child, orphaning postinstall
+        // grandchildren. killProcessGroup(pid, "SIGKILL") kills the whole group
+        // (negative pid), falling back to the single process on ESRCH.
+        killGroup();
+        stopReaders();
+    }, options.timeoutMs);
+    // US-001: an abort races the timeout. One listener, removed on every settle
+    // path so a never-aborted signal never leaks a registration (AC10).
+    const onAbort = () => {
+        aborted = true;
+        killGroup();
+        stopReaders();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    // Read stdout/stderr concurrently with the exit wait — a process that
+    // fills a pipe's OS buffer before being read would otherwise block on the
+    // write and never reach `exited`, defeating the timeout's own SIGKILL.
+    // Each reader has its own controller so a still-pending one can be forced
+    // to settle (via reader.cancel()) after we kill the process group. US-001
+    // requires that settlement stay bounded even when a background process
+    // inherits the pipe and ignores the SIGKILL.
+    const stdoutPromise = drainToEof(proc.stdout, stdoutController.signal);
+    const stderrPromise = drainToEof(proc.stderr, stderrController.signal);
+    const exitCode = await proc.exited;
+    // Post-exit drain grace. After exit, the streams MUST close — they were
+    // owned by the shell, which is now dead. Background processes that
+    // inherited the pipe (the `&` case) keep it open: that's the orphan.
+    const graceMs = _argvExecDeps.drainGraceMs;
+    // Cleared on every settle path: a successful command whose readers close
+    // before the grace elapses would otherwise leave a pending timer whose
+    // callback fires 500ms later and resolves an orphaned promise. Under load
+    // the leaked registrations accumulate in the timer wheel for nothing.
+    let graceTimerId;
+    const gracePromise = new Promise((resolve) => {
+        graceTimerId = _argvExecDeps.setTimeout(() => resolve("expired"), graceMs);
+    });
+    const stdoutSettled = await Promise.race([
+        stdoutPromise,
+        gracePromise.then(() => "expired"),
+    ]);
+    const stderrSettled = await Promise.race([
+        stderrPromise,
+        gracePromise.then(() => "expired"),
+    ]);
+    if (graceTimerId !== undefined)
+        _argvExecDeps.clearTimeout(graceTimerId);
+    const stdoutClosed = stdoutSettled !== "expired";
+    const stderrClosed = stderrSettled !== "expired";
+    if (!stdoutClosed || !stderrClosed) {
+        orphansKilled = true;
+        killGroup();
+        // The OS should close the pipes once the group dies; race that against
+        // a small post-kill budget. If a holdout somehow ignores SIGKILL or is
+        // not yet reaped, abort the matching reader controller — that drives
+        // `reader.cancel()` in drainToEof, which forces the pending `read()` to
+        // resolve with `done: true` and bounds settlement.
+        if (!stdoutClosed)
+            stdoutController.abort();
+        if (!stderrClosed)
+            stderrController.abort();
+    }
+    // Always await the readers to harvest whatever they captured.
+    const stdoutFinal = stdoutClosed ? stdoutSettled : await stdoutPromise;
+    const stderrFinal = stderrClosed ? stderrSettled : await stderrPromise;
+    _argvExecDeps.clearTimeout(timerId);
+    signal?.removeEventListener("abort", onAbort);
+    return {
+        exitCode,
+        stdout: stdoutFinal.text,
+        stderr: stderrFinal.text,
+        timedOut,
+        aborted,
+        orphansKilled,
+    };
+}

package/dist/internal/bounded-io.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ceilings that bound the WORK, not just the answer.
+ *
+ * Every tool honoured `maxBytes` on the way out, but produced its output by
+ * reading a whole file or draining a whole stream first. The ceiling described
+ * what the model was told while the memory it took to get there was unbounded,
+ * so a large but entirely permitted in-root file was enough to exhaust it --
+ * no traversal, no escape, nothing the permission policy could see.
+ *
+ * Both helpers deliberately return up to `maxBytes + 1` bytes. That extra byte
+ * is what lets a caller distinguish "this is the whole thing" from "there was
+ * more", without a second stat or read.
+ */
+/** Read at most `maxBytes + 1` bytes of a UTF-8 file, never the whole file. */
+export declare function readPrefix(path: string, maxBytes: number): Promise<string>;
+/**
+ * Consume a stream until `maxBytes + 1` bytes have arrived, then stop.
+ *
+ * Cancelling the reader is the point: a subprocess whose output is no longer
+ * being consumed blocks on its own pipe and is then reaped by its caller's
+ * timeout, instead of being allowed to fill memory for as long as that timeout
+ * permits. `git log -p` on a large repository is the case in mind.
+ */
+export declare function drainBounded(stream: ReadableStream<Uint8Array>, maxBytes: number): Promise<string>;

package/dist/internal/bounded-io.js

@@ -0,0 +1,51 @@
+/**
+ * Ceilings that bound the WORK, not just the answer.
+ *
+ * Every tool honoured `maxBytes` on the way out, but produced its output by
+ * reading a whole file or draining a whole stream first. The ceiling described
+ * what the model was told while the memory it took to get there was unbounded,
+ * so a large but entirely permitted in-root file was enough to exhaust it --
+ * no traversal, no escape, nothing the permission policy could see.
+ *
+ * Both helpers deliberately return up to `maxBytes + 1` bytes. That extra byte
+ * is what lets a caller distinguish "this is the whole thing" from "there was
+ * more", without a second stat or read.
+ */
+import { open } from "node:fs/promises";
+/** Read at most `maxBytes + 1` bytes of a UTF-8 file, never the whole file. */
+export async function readPrefix(path, maxBytes) {
+    const handle = await open(path, "r");
+    try {
+        const buffer = Buffer.alloc(maxBytes + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Consume a stream until `maxBytes + 1` bytes have arrived, then stop.
+ *
+ * Cancelling the reader is the point: a subprocess whose output is no longer
+ * being consumed blocks on its own pipe and is then reaped by its caller's
+ * timeout, instead of being allowed to fill memory for as long as that timeout
+ * permits. `git log -p` on a large repository is the case in mind.
+ */
+export async function drainBounded(stream, maxBytes) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let out = "";
+    try {
+        while (Buffer.byteLength(out, "utf8") <= maxBytes) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            out += decoder.decode(value, { stream: true });
+        }
+        return out;
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}

package/dist/internal/command-spec/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A declared quality command. A plain string is one shell command (the
+ * historical shape). A list means "run every entry, report every failure" —
+ * the form that exists because `a && b` short-circuits, hiding each failure
+ * after the first from an agent that pays a full round trip per invocation
+ * (nax#1990).
+ */
+export type QualityCommandSpec = string | string[];
+/**
+ * Flatten a spec to the list of commands to actually run. Blank entries are
+ * dropped so a stray "" in a list cannot spawn an empty shell; a spec that is
+ * entirely blank returns [], which callers treat as "not declared".
+ */
+export declare function normalizeCommandSpec(spec: QualityCommandSpec | undefined): string[];
+/**
+ * True when any entry chains with `&&`. Used only to warn: a chain still runs
+ * exactly as it always did, it just hides later failures.
+ */
+export declare function containsShellChain(spec: QualityCommandSpec | undefined): boolean;
+/** True when any command entry includes the supplied literal fragment. */
+export declare function commandSpecIncludes(spec: QualityCommandSpec | undefined, fragment: string): boolean;
+/** Apply a literal replacement to every command entry without changing its shape. */
+export declare function replaceInCommandSpec(spec: QualityCommandSpec, searchValue: string, replacement: string): QualityCommandSpec;
+/**
+ * Render a spec as the single string that prompt and context surfaces show a
+ * reader. `" && "` is what a human recognises and would type, even though a
+ * list does not actually short-circuit when it runs.
+ */
+export declare function renderCommandSpec(spec: QualityCommandSpec | undefined): string | undefined;

package/dist/internal/command-spec/index.js

@@ -0,0 +1,36 @@
+/**
+ * Flatten a spec to the list of commands to actually run. Blank entries are
+ * dropped so a stray "" in a list cannot spawn an empty shell; a spec that is
+ * entirely blank returns [], which callers treat as "not declared".
+ */
+export function normalizeCommandSpec(spec) {
+    if (spec === undefined)
+        return [];
+    const entries = typeof spec === "string" ? [spec] : spec;
+    return entries.map((entry) => entry.trim()).filter((entry) => entry !== "");
+}
+/**
+ * True when any entry chains with `&&`. Used only to warn: a chain still runs
+ * exactly as it always did, it just hides later failures.
+ */
+export function containsShellChain(spec) {
+    return normalizeCommandSpec(spec).some((entry) => entry.includes("&&"));
+}
+/** True when any command entry includes the supplied literal fragment. */
+export function commandSpecIncludes(spec, fragment) {
+    return normalizeCommandSpec(spec).some((entry) => entry.includes(fragment));
+}
+/** Apply a literal replacement to every command entry without changing its shape. */
+export function replaceInCommandSpec(spec, searchValue, replacement) {
+    const replace = (command) => command.replaceAll(searchValue, replacement);
+    return typeof spec === "string" ? replace(spec) : spec.map(replace);
+}
+/**
+ * Render a spec as the single string that prompt and context surfaces show a
+ * reader. `" && "` is what a human recognises and would type, even though a
+ * list does not actually short-circuit when it runs.
+ */
+export function renderCommandSpec(spec) {
+    const steps = normalizeCommandSpec(spec);
+    return steps.length === 0 ? undefined : steps.join(" && ");
+}

package/dist/internal/describe-value-type.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Vocabulary shared by the tool-input validator (`src/agents/native/session/
+ * tool-input-validation.ts`, nax#2047) and `run-command.ts`'s own `values`
+ * shape guard (#1924): the "actual" half of a violation reads exactly the
+ * way run-command.ts itself would have phrased the same shape, so the gate
+ * and the tool produce the same wording.
+ */
+export declare function describeValuesType(value: unknown): string;

package/dist/internal/describe-value-type.js

@@ -0,0 +1,14 @@
+/**
+ * Vocabulary shared by the tool-input validator (`src/agents/native/session/
+ * tool-input-validation.ts`, nax#2047) and `run-command.ts`'s own `values`
+ * shape guard (#1924): the "actual" half of a violation reads exactly the
+ * way run-command.ts itself would have phrased the same shape, so the gate
+ * and the tool produce the same wording.
+ */
+export function describeValuesType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return `a ${typeof value}`;
+}

package/dist/internal/exec-framing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Frame a finished spawn result the way the model expects to see it: an
+ * aborted call opens with the cancellation line, an orphansKilled call appends
+ * the `[nax]` footer, a timed-out call reports the deadline, and everything
+ * else gets `exit N\nstdout\nstderr` (US-001 AC14/AC15).
+ *
+ * One function shared by the `Bash` tool and `RunCommand` (Exec) so the two
+ * ladders a model reads interchangeably cannot drift — the deadline label is
+ * the only difference between the call sites, so it is a parameter.
+ */
+export declare function formatExecBody(launched: {
+    aborted?: boolean;
+    orphansKilled?: boolean;
+    timedOut: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}, timeoutMs: number): string;

package/dist/internal/exec-framing.js

@@ -0,0 +1,22 @@
+/**
+ * Frame a finished spawn result the way the model expects to see it: an
+ * aborted call opens with the cancellation line, an orphansKilled call appends
+ * the `[nax]` footer, a timed-out call reports the deadline, and everything
+ * else gets `exit N\nstdout\nstderr` (US-001 AC14/AC15).
+ *
+ * One function shared by the `Bash` tool and `RunCommand` (Exec) so the two
+ * ladders a model reads interchangeably cannot drift — the deadline label is
+ * the only difference between the call sites, so it is a parameter.
+ */
+export function formatExecBody(launched, timeoutMs) {
+    if (launched.aborted === true) {
+        return `Cancelled: the turn ended while this command was running.\nexit ${launched.exitCode}\n${launched.stdout}\n${launched.stderr}`;
+    }
+    if (launched.orphansKilled === true) {
+        return `exit ${launched.exitCode}\n${launched.stdout}\n${launched.stderr}\n[nax] background processes still holding the output were killed`;
+    }
+    if (launched.timedOut) {
+        return `timed out after ${timeoutMs}ms`;
+    }
+    return `exit ${launched.exitCode}\n${launched.stdout}\n${launched.stderr}`;
+}

package/dist/internal/file-lock.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared single-file lock used by `withPathFileLock` and `withQueueFileLock`.
+ *
+ * Mutual exclusion derives from the atomicity of an exclusive create: the
+ * lock is ONE file at `<target>.lock`, and the writer whose
+ * `writeFile(path, pid, { flag: "wx" })` succeeds holds the lock. There is
+ * no candidate ordering, no filesystem birthtime, and no polling race.
+ *
+ * #1731: the previous design created timestamped candidate files and polled
+ * until it saw itself as the "oldest live" candidate. That protocol is only
+ * sound if candidate order matches creation order, which it did not: the
+ * sort key was `(stat().birthtimeMs, name.localeCompare)` — on Linux CI
+ * filesystems birthtimeMs is degenerate so order collapsed to the random
+ * uuid tail of the name, and a poll whose readdir completed before a
+ * competitor's create landed missed that competitor entirely. A
+ * later-created candidate could therefore sort before the holder, also
+ * conclude it was oldest, and enter — two writers inside the critical
+ * section, one write silently lost. An exclusive create cannot exhibit any
+ * of those failure modes: exactly one create ever succeeds.
+ *
+ * Staleness (BUG-10 / BUG-25, carried over from the candidate design):
+ * - The holder's pid is stored in the lock file. A waiter that loses the
+ *   create race reads the pid; a PROVEN-dead holder (ESRCH) means the lock
+ *   is abandoned and may be reclaimed.
+ * - Content that cannot be parsed (e.g. the creator crashed between the
+ *   create and the pid write) is respected until it ages past
+ *   `EMPTY_LOCK_EVICT_AGE_MS` — a live holder writes its pid within the
+ *   same tick as the create, so old unparseable content proves abandonment.
+ *   Inconclusive liveness fails closed: the waiter times out and throws
+ *   rather than entering over a possible holder.
+ *
+ * Reclamation is serialized by a claim file (`<target>.lock.claim`), whose
+ * exclusive create elects a single "gravedigger" at a time. This closes the
+ * steal race: without it, two waiters that both observed the dead holder
+ * could interleave (stealer A's create landing between stealer B's
+ * re-verification and its unlink), letting B unlink A's fresh live lock and
+ * enter over it. Under the claim:
+ * - Only the claim holder may unlink the lock file, so no unlink can make
+ *   the path absent during another gravedigger's verify→unlink window.
+ * - The gravedigger RE-VERIFIES abandonment after winning the claim (a
+ *   stale observation must not kill a lock that a new live holder has
+ *   since created) and only then unlinks.
+ * - If two gravediggers ever do overlap (only possible via the claim's own
+ *   age-based steal), both re-verify the same dead file, both unlink (the
+ *   second gets ENOENT), and the exclusive create on the fixed lock path
+ *   still admits exactly one holder.
+ * The claim itself is held for microseconds, so it is stolen purely on age
+ * (`CLAIM_MAX_AGE_MS`): a claim older than that proves its gravedigger died
+ * mid-reclaim. A crashed gravedigger otherwise pauses reclamation until
+ * then — fail closed, never fail into someone else's live lock.
+ *
+ * Release unlinks the lock file in the `finally` block. The unlink is
+ * swallowed because release runs from the same process that created the
+ * file — a double-cleanup on retry paths must not throw. A crashed holder
+ * leaks the file, which the dead-pid reclamation above reclaims.
+ *
+ * Mixed versions: the pre-#1731 design wrote `<target>.lock.<time>.<pid>.<uuid>`
+ * candidate files, which this design deliberately does NOT scan for — they
+ * are inert leftovers here (and legacy candidate files are never GC'd). An
+ * old-version process and a new-version process must therefore not run
+ * concurrently against the same target during a one-release transition
+ * window: each would see only its own lock format and could enter
+ * concurrently. This self-heals once old-version processes exit.
+ */
+import { readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { isProcessAlive } from "./process-alive.ts";
+export interface FileLockOptions {
+    /** Milliseconds between acquisition retries. Default 10. */
+    retryMs?: number;
+    /** Maximum time to wait for the lock before throwing. Default 5000. */
+    timeoutMs?: number;
+    /** Lock family used in the timeout error, e.g. "path" or "queue". */
+    lockName: string;
+    /** Log/error prefix, e.g. "[path-lock]". */
+    errorPrefix: string;
+}
+export declare const _fileLockDeps: {
+    writeFile: typeof writeFile;
+    readFile: typeof readFile;
+    stat: typeof stat;
+    unlink: typeof unlink;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    isPidAlive: typeof isProcessAlive;
+};
+/**
+ * Serialize `operation` against any other process holding the lock at
+ * `lockPath`. See the module doc for the acquisition, staleness, and
+ * release semantics.
+ */
+export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, options: FileLockOptions): Promise<T>;