@nathapp/nax-agent 0.1.0

package/dist/command-safety/systemone-client.js

@@ -0,0 +1,92 @@
+/**
+ * One POST to a SystemOne endpoint (spec 6.2).
+ *
+ * Total by construction: every failure maps to a ModelResult, so the promise
+ * never rejects. It never retries (a retry adds load to a local model for data
+ * that decides nothing) and never truncates (an oversize command is recorded
+ * as `oversize`). The timeout is a config value, applied as an AbortSignal.
+ */
+import { buildRequest } from "./questions.js";
+import { HARM_OPTIONS, QUESTION_IDS } from "./types.js";
+/** Injectable seams: tests drive the timeout by hand instead of waiting on it. */
+export const _systemOneClientDeps = {
+    fetch: (input, init) => fetch(input, init),
+    timeoutSignal: (ms) => AbortSignal.timeout(ms),
+    now: () => performance.now(),
+};
+const isTimeout = (err) => typeof err === "object" && err !== null && "name" in err && err.name === "TimeoutError";
+export function createSystemOneClient(opts) {
+    return async (command) => {
+        const started = _systemOneClientDeps.now();
+        const elapsed = () => Math.round(_systemOneClientDeps.now() - started);
+        const unavailable = (error) => ({ status: "unavailable", error, latencyMs: elapsed() });
+        let res;
+        try {
+            res = await _systemOneClientDeps.fetch(opts.url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(opts.token !== undefined && opts.token.length > 0 ? { authorization: `Bearer ${opts.token}` } : {}),
+                },
+                body: JSON.stringify(buildRequest(command)),
+                signal: _systemOneClientDeps.timeoutSignal(opts.timeoutMs),
+            });
+        }
+        catch (err) {
+            return unavailable(isTimeout(err) ? "timeout" : "network");
+        }
+        if (res.status === 413)
+            return { status: "oversize", latencyMs: elapsed() };
+        if (res.status === 401)
+            return unavailable("unauthorized");
+        if (res.status !== 200)
+            return unavailable(`http_${res.status}`);
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch (err) {
+            return unavailable(isTimeout(err) ? "timeout" : "malformed");
+        }
+        return parseAnswer(body, elapsed());
+    };
+}
+const isProbability = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
+/** Map a 200 body to a ModelResult. Anything short of all seven valid answers is `malformed`. */
+export function parseAnswer(body, latencyMs) {
+    const malformed = { status: "unavailable", error: "malformed", latencyMs };
+    const top = record(body);
+    if (top === undefined)
+        return malformed;
+    const decision = record(top.x_proxy)?.decision_id;
+    const decisionId = typeof decision === "string" ? decision : undefined;
+    if (record(top.error)?.kind === "provider_blocked") {
+        return { status: "blocked", ...(decisionId !== undefined ? { decisionId } : {}), latencyMs };
+    }
+    const answers = record(top.answers);
+    const probabilities = record(record(answers?.harm)?.probabilities);
+    if (answers === undefined || probabilities === undefined)
+        return malformed;
+    const harm = {};
+    for (const option of HARM_OPTIONS) {
+        const p = probabilities[option];
+        if (!isProbability(p))
+            return malformed;
+        harm[option] = p;
+    }
+    const noul = {};
+    for (const id of QUESTION_IDS) {
+        const p = record(answers[id])?.noul;
+        if (!isProbability(p))
+            return malformed;
+        noul[id] = p;
+    }
+    return {
+        status: "answered",
+        answers: { harm: harm, noul: noul },
+        ...(typeof top.model === "string" ? { model: top.model } : {}),
+        ...(decisionId !== undefined ? { decisionId } : {}),
+        latencyMs,
+    };
+}

package/dist/command-safety/tap.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The only code runtime.callTool calls (spec 4.2).
+ *
+ * Takes plain values rather than tool types, so src/command-safety imports
+ * nothing from src/tools. Only the `Bash` and `Exec` identities are observed;
+ * a RunCommand verb call runs a user-declared command and never is (D14).
+ */
+import { type CallIdentifiers } from "./identifiers.ts";
+import type { CommandShadow, ExecRun, LedgerOutcome, MechanicalVerdict } from "./types.ts";
+export interface ShadowTap {
+    /**
+     * `run` is what the Exec tool actually ran (argv after normalization, and
+     * its cwd). It is forwarded to the shadow only for an `Exec` observation; a
+     * `Bash` row drops it, since its executed argv is `[shell, "-c", command]`
+     * and its cwd (when the caller supplied `root`) is already on the observation.
+     */
+    settle(ledger: LedgerOutcome, decidedBy?: string, run?: ExecRun): void;
+}
+export interface ShadowCall extends CallIdentifiers {
+    readonly key: string;
+    readonly identity: string;
+    readonly command: unknown;
+    readonly argv: unknown;
+    /** The policy root. A Bash command starts there, so it becomes the observation's cwd. */
+    readonly root?: string;
+    readonly verdict: {
+        readonly allowed: boolean;
+        readonly outcome?: string;
+        readonly breach?: boolean;
+        readonly rule?: string;
+    };
+    readonly stage: string;
+    readonly storyId?: string;
+}
+export declare function toMechanical(verdict: ShadowCall["verdict"]): MechanicalVerdict;
+/** Observe now; settle later, exactly once. Never throws. */
+export declare function openShadowTap(shadow: CommandShadow | undefined, call: ShadowCall): ShadowTap;

package/dist/command-safety/tap.js

@@ -0,0 +1,77 @@
+/**
+ * The only code runtime.callTool calls (spec 4.2).
+ *
+ * Takes plain values rather than tool types, so src/command-safety imports
+ * nothing from src/tools. Only the `Bash` and `Exec` identities are observed;
+ * a RunCommand verb call runs a user-declared command and never is (D14).
+ */
+import { callIdentifiers } from "./identifiers.js";
+const NO_TAP = { settle: () => undefined };
+export function toMechanical(verdict) {
+    if (verdict.allowed)
+        return { verdict: "allow", breach: false };
+    return {
+        verdict: verdict.outcome === "ask" ? "ask" : "deny",
+        breach: verdict.breach === true,
+        ...(verdict.rule !== undefined ? { rule: verdict.rule } : {}),
+    };
+}
+function toObservation(call) {
+    const base = {
+        stage: call.stage,
+        ...(call.storyId !== undefined ? { storyId: call.storyId } : {}),
+        mechanical: toMechanical(call.verdict),
+        ...callIdentifiers(call),
+    };
+    if (call.identity === "Bash" && typeof call.command === "string") {
+        return {
+            command: call.command,
+            identity: "Bash",
+            ...base,
+            ...(call.root !== undefined ? { cwd: call.root } : {}),
+        };
+    }
+    if (call.identity === "Exec" && Array.isArray(call.argv) && call.argv.every((a) => typeof a === "string")) {
+        const argv = call.argv.map(String);
+        return { command: argv.join(" "), identity: "Exec", argv, ...base };
+    }
+    return undefined;
+}
+/** Observe now; settle later, exactly once. Never throws. */
+export function openShadowTap(shadow, call) {
+    if (shadow === undefined)
+        return NO_TAP;
+    try {
+        const obs = toObservation(call);
+        if (obs === undefined)
+            return NO_TAP;
+        shadow.observe(call.key, obs);
+        let settled = false;
+        return {
+            settle(ledger, decidedBy, run) {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    const outcome = { ledger, ...(decidedBy !== undefined ? { decidedBy } : {}) };
+                    // Forward `run` for an Exec observation only: a Bash row's executed
+                    // argv is `[shell, "-c", command]`, which the row's own `command`
+                    // already states, so passing it would add a redundant key.
+                    if (obs.identity === "Exec" && run !== undefined) {
+                        shadow.settle(call.key, outcome, run);
+                    }
+                    else {
+                        shadow.settle(call.key, outcome);
+                    }
+                }
+                catch {
+                    // A shadow failure stops the row, never the call (spec 4.3).
+                }
+            },
+        };
+    }
+    catch {
+        // Same contract as settle: the tap is total.
+        return NO_TAP;
+    }
+}

package/dist/command-safety/temp-only.d.ts

@@ -0,0 +1,6 @@
+/** True when the command touches only temp paths, `$TMPDIR`, paths under
+ * `cwd`, and the three allowlisted /dev entries — and at least one of those
+ * paths is a literal temp root. A refused lex, an undefined `cwd`, or any
+ * unjudgeable token (URL, attached short option, opaque non-`$TMPDIR`, or a
+ * relative path after an unresolvable cd) returns false. */
+export declare function isTempOnly(command: string, cwd: string | undefined): boolean;

package/dist/command-safety/temp-only.js

@@ -0,0 +1,215 @@
+/**
+ * Conservative temp-only predicate (US-002).
+ *
+ * Returns true when every path-like token and redirect target in `command`
+ * names a temp path, a `$TMPDIR` expansion that resolves to one, a path
+ * under `cwd`, or `/dev/null` / `/dev/stdout` / `/dev/stderr` — AND at
+ * least one of them is a temp path. Two unjudgeable shapes force `false`:
+ * an attached short-option value containing `/` (e.g. `-C/etc`) and a URL
+ * (any token containing `://`).
+ *
+ * The frame (working-directory proxy) advances through `cd` segments the
+ * same way `detectTmpWrite` does, with one difference: when a `cd` target is
+ * an opaque word (`$D`) or a `~` reference — anything the lexer did not
+ * literalize — the frame becomes unknown, and any later relative path-like
+ * token fails the predicate. A refused lex or an undefined `cwd` also
+ * fails it.
+ *
+ * This is a no-ask filter; a `false` return is information only, never a
+ * decision.
+ */
+import { posix } from "node:path";
+import { lexBashCommand } from "#src/permissions/index";
+/** The literal temp roots a temp path must land in. */
+const TEMP_ROOTS = ["/tmp", "/private/tmp"];
+/** The two opaque variable names accepted as temp path expansions. */
+const TMPDIR_BARE = "$TMPDIR";
+const TMPDIR_BRACE = "$" + "{TMPDIR}";
+/** The three /dev entries allowed as safe redirect targets. */
+const DEV_ALLOWLIST = new Set(["/dev/null", "/dev/stdout", "/dev/stderr"]);
+/** True when `token` looks like a path the predicate must judge:
+ * contains a `/`, equals `.` or `..`, or starts with `~`. */
+function isPathLike(token) {
+    return token.includes("/") || token === "." || token === ".." || token.startsWith("~");
+}
+/** True when `token` is a shell option flag the predicate must skip past to
+ * find a real target: starts with `-` but is not itself path-like and has no
+ * `--flag=value` to extract. `cd -P /tmp` has `-P` as the option and `/tmp`
+ * as the target. */
+function isOptionFlag(token) {
+    if (token === "-")
+        return false;
+    if (!token.startsWith("-"))
+        return false;
+    if (isPathLike(token))
+        return false;
+    if (flagValue(token) !== undefined)
+        return false;
+    return true;
+}
+/** The judged value of a `--flag=value` token, or undefined when `token` is
+ * not of that form. Anything else is judged as-is. */
+function flagValue(token) {
+    if (!token.startsWith("--"))
+        return undefined;
+    const eq = token.indexOf("=");
+    return eq === -1 ? undefined : token.slice(eq + 1);
+}
+/** True when `path` is or lies under one of the literal temp roots. */
+function isTempPath(path) {
+    return TEMP_ROOTS.some((root) => path === root || path.startsWith(`${root}/`));
+}
+/** True when `path` equals `cwd` or lies under it. */
+function isUnderCwd(path, cwd) {
+    return path === cwd || path.startsWith(`${cwd}/`);
+}
+/** True when `text` contains a `..` path segment anywhere — used to refuse
+ * `$TMPDIR/../x` shapes that would climb out of the temp root at runtime. */
+function hasParentSegment(text) {
+    return text.split("/").includes("..");
+}
+/** True when `token` is exactly `$TMPDIR` / `${TMPDIR}` or one of them
+ * followed by `/` and a remainder with no `..` segment. False when it is a
+ * different opaque word, undefined when the token is not opaque. */
+function isTmpDirExpansion(token) {
+    if (!token.opaque)
+        return undefined;
+    if (token.text === TMPDIR_BARE || token.text === TMPDIR_BRACE)
+        return true;
+    if (token.text.startsWith(`${TMPDIR_BARE}/`)) {
+        return !hasParentSegment(token.text.slice(TMPDIR_BARE.length + 1));
+    }
+    if (token.text.startsWith(`${TMPDIR_BRACE}/`)) {
+        return !hasParentSegment(token.text.slice(TMPDIR_BRACE.length + 1));
+    }
+    return false;
+}
+/** True when `token` is an attached short option value the predicate cannot
+ * split (`-C/etc`), or a `--flag=value` form. The value, when present, is
+ * classified recursively. */
+function shortOptionVerdict(token, frame, cwd) {
+    if (!token.text.startsWith("-") || !token.text.includes("/"))
+        return undefined;
+    if (token.text.startsWith("--")) {
+        const value = flagValue(token.text);
+        if (value !== undefined)
+            return classify({ text: value, opaque: token.opaque }, frame, cwd);
+    }
+    return "refuse";
+}
+/** True when `token` is an unjudgeable shape (URL, `~` path, opaque word
+ * other than `$TMPDIR`). Callers must check `isTmpDirExpansion` first. */
+function unjudgeable(token) {
+    if (token.text.includes("://"))
+        return true;
+    if (token.text.startsWith("~"))
+        return true;
+    return token.opaque;
+}
+/** Classifies a literal (non-opaque, non-short-option, non-flag) absolute or
+ * relative path against the temp-root, /dev allowlist, cwd, and frame. */
+function classifyLiteral(token, frame, cwd) {
+    if (token.text.startsWith("/")) {
+        const normalized = posix.normalize(token.text);
+        if (isTempPath(normalized))
+            return "temp";
+        if (DEV_ALLOWLIST.has(normalized))
+            return "allowed";
+        return isUnderCwd(normalized, cwd) ? "allowed" : "refuse";
+    }
+    if (frame === undefined)
+        return "refuse";
+    const resolved = posix.normalize(posix.join(frame, token.text));
+    if (isTempPath(resolved))
+        return "temp";
+    return isUnderCwd(resolved, cwd) ? "allowed" : "refuse";
+}
+/** Classifies one path-like `token` (or redirect target) against the rules.
+ * Returns `temp` when the path is a temp path (the credit), `allowed` when
+ * it is some other safe value (cwd, /dev, `$TMPDIR` expansion), and `refuse`
+ * when it cannot be judged or falls outside the safe set. */
+function classify(token, frame, cwd) {
+    const short = shortOptionVerdict(token, frame, cwd);
+    if (short !== undefined)
+        return short;
+    const tmpdir = isTmpDirExpansion(token);
+    if (tmpdir !== undefined)
+        return tmpdir ? "temp" : "refuse";
+    if (unjudgeable(token))
+        return "refuse";
+    return classifyLiteral(token, frame, cwd);
+}
+/** The frame a `cd <target>` segment leaves behind. When the cd target is
+ * not a literal, cwd-rooted, or $TMPDIR path the frame is lost. Any option
+ * flags the user wrote before the target (`-P`, `-L`, `--`) are skipped, so
+ * `cd -P $D` classifies `$D` (opaque, unresolvable) and clears the frame
+ * instead of joining a synthetic one from the option word. */
+function frameAfter(segment, frame, cwd) {
+    const [command, ...rest] = segment.tokens;
+    if (command?.text !== "cd")
+        return frame;
+    const target = rest.find((token) => !isOptionFlag(token.text));
+    if (target === undefined)
+        return frame;
+    if (target.text === "-")
+        return undefined;
+    if (classify({ text: target.text, opaque: target.opaque }, frame, cwd) === "refuse")
+        return undefined;
+    if (target.text.startsWith("/"))
+        return posix.normalize(target.text);
+    return frame === undefined ? undefined : posix.normalize(posix.join(frame, target.text));
+}
+/** Classifies every path-like token and redirect target in one segment.
+ * Returns `true` when any verdict was `temp` (so far). Returns `false` when
+ * any verdict was `refuse`; the caller then returns false from the whole
+ * predicate. A `--flag=value` token is judged by its VALUE — the flag name
+ * hides any `/`, `.`, `..`, or `~` the value contains, so the whole token
+ * would not look path-like on its own. */
+function classifySegment(segment, frame, cwd) {
+    let hasTempPath = false;
+    for (const redirect of segment.redirects) {
+        const verdict = classify({ text: redirect.target, opaque: redirect.opaque }, frame, cwd);
+        if (verdict === "refuse")
+            return { hasTempPath, refused: true };
+        if (verdict === "temp")
+            hasTempPath = true;
+    }
+    for (const token of segment.tokens) {
+        const value = flagValue(token.text);
+        const judgedText = value ?? token.text;
+        if (!isPathLike(judgedText))
+            continue;
+        const verdict = classify({ text: judgedText, opaque: token.opaque }, frame, cwd);
+        if (verdict === "refuse")
+            return { hasTempPath, refused: true };
+        if (verdict === "temp")
+            hasTempPath = true;
+    }
+    return { hasTempPath, refused: false };
+}
+/** True when the command touches only temp paths, `$TMPDIR`, paths under
+ * `cwd`, and the three allowlisted /dev entries — and at least one of those
+ * paths is a literal temp root. A refused lex, an undefined `cwd`, or any
+ * unjudgeable token (URL, attached short option, opaque non-`$TMPDIR`, or a
+ * relative path after an unresolvable cd) returns false. */
+export function isTempOnly(command, cwd) {
+    if (cwd === undefined || cwd === "")
+        return false;
+    const lexed = lexBashCommand(command);
+    if (lexed.kind === "refused")
+        return false;
+    const normalizedCwd = posix.normalize(cwd);
+    if (normalizedCwd === "" || normalizedCwd === ".")
+        return false;
+    let frame = normalizedCwd;
+    let hasTempPath = false;
+    for (const segment of lexed.segments) {
+        const outcome = classifySegment(segment, frame, normalizedCwd);
+        if (outcome.refused)
+            return false;
+        if (outcome.hasTempPath)
+            hasTempPath = true;
+        frame = frameAfter(segment, frame, normalizedCwd);
+    }
+    return hasTempPath;
+}

package/dist/command-safety/tmp-write.d.ts

@@ -0,0 +1,2 @@
+/** True when the command writes to a literal /tmp or /private/tmp path outside nax's own dirs. */
+export declare function detectTmpWrite(command: string, cwd?: string): boolean;

package/dist/command-safety/tmp-write.js

@@ -0,0 +1,112 @@
+/**
+ * Observable literal-temp-write signal (US-005).
+ *
+ * Records, never decides. True when a command writes to a literal `/tmp` or
+ * `/private/tmp` path outside nax's own temp trees — the shared `/tmp/nax/`
+ * parent of every run root and the per-user `/tmp/nax-<uid>` fallback — so the
+ * frequency of that scratch-write habit is measurable. The caller only stores
+ * the boolean on the shadow row: it is not a `QuestionId`, not in
+ * `rules.hits`, and changes no verdict.
+ *
+ * Total by construction: `lexBashCommand` is safe-by-refusal and does no I/O,
+ * so a refused lex scans its lexable prefix instead of throwing.
+ */
+import { posix } from "node:path";
+import { lexBashCommand } from "#src/permissions/index";
+/** The literal temp roots a flagged write must land in. */
+const TEMP_ROOTS = ["/tmp", "/private/tmp"];
+/** nax's shared temp parent, a directory directly under a temp root. */
+const NAX_PARENT_SEGMENT = "nax";
+/** nax's per-user fallback parent, whose `<uid>` keeps it outside the shared parent's subtree. */
+const NAX_FALLBACK_SEGMENT = "nax-";
+/** First tokens whose later non-flag words are all write targets. */
+const ARG_TARGET_COMMANDS = new Set(["tee", "touch", "mkdir"]);
+/** First tokens whose LAST non-flag word is the write target. */
+const LAST_TARGET_COMMANDS = new Set(["cp", "mv"]);
+/** Every write target of one segment, in the order the lexer saw them. */
+function writeTargets(segment) {
+    const targets = [];
+    for (const redirect of segment.redirects) {
+        // Input redirects (`<`, and the refused `<<` / `<<<`) read; they do not write.
+        if (redirect.operator.startsWith("<"))
+            continue;
+        targets.push({ text: redirect.target, opaque: redirect.opaque });
+    }
+    const first = segment.tokens[0]?.text;
+    if (first !== undefined && ARG_TARGET_COMMANDS.has(first)) {
+        for (const token of segment.tokens.slice(1)) {
+            if (!token.text.startsWith("-"))
+                targets.push(token);
+        }
+    }
+    else if (first !== undefined && LAST_TARGET_COMMANDS.has(first)) {
+        const words = segment.tokens.slice(1).filter((token) => !token.text.startsWith("-"));
+        const last = words[words.length - 1];
+        if (last !== undefined)
+            targets.push(last);
+    }
+    return targets;
+}
+/**
+ * The absolute path `target` names under `frame`, or undefined when it cannot
+ * be read literally: an opaque (expansion-bearing) word, a `~` home reference,
+ * or a relative word with no known frame.
+ */
+function resolveTarget(target, frame) {
+    if (target.opaque || target.text.startsWith("~"))
+        return undefined;
+    if (target.text.startsWith("/"))
+        return posix.normalize(target.text);
+    return frame === undefined ? undefined : posix.normalize(posix.join(frame, target.text));
+}
+/** True when `path` lies in nax's own temp tree under `root`, never counted.
+ *  Two trees are exempt: the shared parent `<root>/nax/` (parent of every run
+ *  root) and the per-user fallback `<root>/nax-<digits>` whose `<digits>` is
+ *  the WHOLE path segment after `nax-` (the literal UID in `/tmp/nax-<uid>`).
+ *  Anything else — `/tmp/nax-red-check`, `/tmp/nax-r1/...`, `/tmp/nax-501x`
+ *  — is a real write, because the confined sandbox denies writes to those
+ *  directories and they are user- or run-named, not nax-owned. */
+function isNaxTempTree(path, root) {
+    if (path.startsWith(`${root}/${NAX_PARENT_SEGMENT}/`))
+        return true;
+    const fallbackPrefix = `${root}/${NAX_FALLBACK_SEGMENT}`;
+    if (!path.startsWith(fallbackPrefix))
+        return false;
+    const afterDash = path.slice(fallbackPrefix.length);
+    const firstSlash = afterDash.indexOf("/");
+    const segment = firstSlash === -1 ? afterDash : afterDash.slice(0, firstSlash);
+    return /^\d+$/.test(segment);
+}
+/** True when `path` is a temp root or lies under one, but not under nax's own subtree. */
+function isTmpPath(path) {
+    for (const root of TEMP_ROOTS) {
+        if (path !== root && !path.startsWith(`${root}/`))
+            continue;
+        return !isNaxTempTree(path, root);
+    }
+    return false;
+}
+/** The frame a `cd <target>` segment leaves behind; otherwise the frame unchanged. */
+function frameAfter(segment, frame) {
+    const [command, target] = segment.tokens;
+    if (command?.text !== "cd" || target === undefined)
+        return frame;
+    return resolveTarget(target, frame) ?? frame;
+}
+/** True when the command writes to a literal /tmp or /private/tmp path outside nax's own dirs. */
+export function detectTmpWrite(command, cwd) {
+    const lexed = lexBashCommand(command);
+    // A refused lex still exposes the part it read: the gate refuses on the
+    // unreadable construct, not on the prefix before it.
+    const segments = lexed.kind === "ok" ? lexed.segments : lexed.prefix;
+    let frame = cwd === undefined ? undefined : posix.normalize(cwd);
+    for (const segment of segments) {
+        for (const target of writeTargets(segment)) {
+            const resolved = resolveTarget(target, frame);
+            if (resolved !== undefined && isTmpPath(resolved))
+                return true;
+        }
+        frame = frameAfter(segment, frame);
+    }
+    return false;
+}