@nathapp/nax-agent 0.1.0

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

@@ -0,0 +1,32 @@
+import type { CommandGuard, GuardDecision, ModelResult, RuleResult } from "./types.ts";
+/**
+ * The pure scorer: rules + classifier + temp-only state + threshold.
+ *
+ * `model` is `undefined` when the temp-only check skipped the classifier
+ * (the shadow's row still classifies, but the guard does not consult it).
+ * The temp-only basis still applies the rule score — a temp-only command
+ * that trips a non-`outside_project` rule (e.g. `rm -rf /tmp/x` hits
+ * `deletes_data`) flags, while `outside_project` alone scores 0.
+ */
+export declare function scoreGuard(input: {
+    readonly rules: RuleResult;
+    readonly model: ModelResult | undefined;
+    readonly tempOnly: boolean;
+    readonly threshold: number;
+}): GuardDecision;
+/**
+ * Build a `CommandGuard` from the shadow's rule scorer and the cached
+ * classifier promise it shares with the shadow.
+ *
+ * The guard never throws: every step of `assess` (rule scoring, the temp-
+ * only check, the cached classify, the decision table) is wrapped in a
+ * single try/catch that falls through to a no-rule / no-model rules-only
+ * decision with score 0. The shadow classifies once per command; `assess`
+ * awaits the cached promise rather than re-classifying.
+ */
+export declare function createCommandGuard(opts: {
+    readonly threshold: number;
+    readonly scoreRules: (command: string, cwd: string | undefined) => RuleResult;
+    /** Returns the cached classifier promise for `command`. */
+    readonly classifyCached: (command: string) => Promise<ModelResult>;
+}): CommandGuard;

package/dist/command-safety/guard.js

@@ -0,0 +1,179 @@
+/**
+ * The P5 flag-for-review guard (US-003).
+ *
+ * The shadow observes every command. The guard, when configured, composes a
+ * score from the same rule result and the same classifier promise the shadow
+ * awaits, decides whether to flag, and names the dominant category. It is
+ * total by construction — it never rejects, never asks, never denies; the
+ * caller (US-004's tool ask routing) decides what a flag means downstream.
+ *
+ * `scoreGuard` is the pure decision table `assess` composes. It is exported
+ * so two rules `assess` alone cannot express — the temp-only exemption's
+ * `outside_project` skip and the harm-tie-breaker — stay unit-testable.
+ */
+import { isTempOnly } from "./temp-only.js";
+import { QUESTION_IDS } from "./types.js";
+/**
+ * The first category in `QUESTION_IDS` order that `hits` sets to true.
+ * `skip` removes categories the caller has already accounted for
+ * (temp-only drops `outside_project`).
+ */
+function firstHit(hits, skip = new Set()) {
+    for (const id of QUESTION_IDS) {
+        if (skip.has(id))
+            continue;
+        if (hits[id])
+            return id;
+    }
+    return undefined;
+}
+/**
+ * `harm = 1 - P(none)`; `noulMax = max P(yes)` over the six noul questions;
+ * `modelScore = (harm + noulMax) / 2`.
+ *
+ * The harm category other than `none` with the highest probability names
+ * the decision; ties go to `QUESTION_IDS` order. Both halves are bounded
+ * by `[0, 1]`, so the score is too.
+ */
+function scoreFromAnswer(answer) {
+    const harm = 1 - answer.answers.harm.none;
+    const noulMax = Math.max(...QUESTION_IDS.map((id) => answer.answers.noul[id]));
+    let topProb = -Infinity;
+    let topId;
+    for (const id of QUESTION_IDS) {
+        const p = answer.answers.harm[id];
+        if (p > topProb) {
+            topProb = p;
+            topId = id;
+        }
+    }
+    return { score: (harm + noulMax) / 2, category: topId };
+}
+/** True when any of the six rule categories hits. `outside_project` is included. */
+function ruleScore(rules) {
+    return QUESTION_IDS.some((id) => rules.hits[id]) ? 1 : 0;
+}
+/**
+ * Temp-only variant of `ruleScore`: `outside_project` is skipped, since the
+ * temp-only exemption routes around it. A path entirely outside the project
+ * is acceptable while the sandbox confines temp writes; the classifier is
+ * not consulted for the assessment.
+ */
+function ruleScoreTempOnly(rules) {
+    return QUESTION_IDS.some((id) => id !== "outside_project" && rules.hits[id]) ? 1 : 0;
+}
+/**
+ * The pure scorer: rules + classifier + temp-only state + threshold.
+ *
+ * `model` is `undefined` when the temp-only check skipped the classifier
+ * (the shadow's row still classifies, but the guard does not consult it).
+ * The temp-only basis still applies the rule score — a temp-only command
+ * that trips a non-`outside_project` rule (e.g. `rm -rf /tmp/x` hits
+ * `deletes_data`) flags, while `outside_project` alone scores 0.
+ */
+export function scoreGuard(input) {
+    const { rules, model, tempOnly, threshold } = input;
+    // Temp-only path: the classifier is skipped. A rule hit scores 1;
+    // `outside_project` is exempt. An empty hit set scores 0. The basis
+    // names the exemption even when a rule carries the flag.
+    if (tempOnly) {
+        const score = ruleScoreTempOnly(rules);
+        const flagged = score >= threshold;
+        // Per spec: category is present when a rule hit carries the flag.
+        // `outside_project` is exempt under the temp-only check, so it never
+        // names a temp-only decision.
+        const category = flagged ? firstHit(rules.hits, new Set(["outside_project"])) : undefined;
+        return {
+            flagged,
+            score,
+            threshold,
+            basis: "temp-only",
+            ...(category !== undefined ? { category } : {}),
+        };
+    }
+    // Classifier unreachable / oversized / rejected / unavailable: rules-only.
+    if (model === undefined || model.status === "oversize" || model.status === "unavailable") {
+        const score = ruleScore(rules);
+        const flagged = score >= threshold;
+        const category = flagged ? firstHit(rules.hits) : undefined;
+        return {
+            flagged,
+            score,
+            threshold,
+            basis: "rules",
+            ...(category !== undefined ? { category } : {}),
+        };
+    }
+    if (model.status === "blocked") {
+        // The server refuses to score; the guard treats that as a hard flag.
+        // A rule hit still carries its category.
+        const category = firstHit(rules.hits);
+        return {
+            flagged: true,
+            score: 1,
+            threshold,
+            basis: "model",
+            ...(category !== undefined ? { category } : {}),
+        };
+    }
+    // Answered. The model score composites over the rule score; the higher
+    // wins. The category names the dominant harm, never an `outside_project`
+    // temp-only skip (the temp-only branch above has already exited).
+    const { score: modelScore, category: modelCategory } = scoreFromAnswer(model);
+    const rs = ruleScore(rules);
+    const score = Math.max(rs, modelScore);
+    const flagged = score >= threshold;
+    // Rule hits always name the decision (first hit in QUESTION_IDS order);
+    // the harm top otherwise carries it — but the spec drops the category on
+    // any unflagged decision, so a benign answered row never names a harm.
+    const category = rs === 1 ? firstHit(rules.hits) : flagged ? modelCategory : undefined;
+    return {
+        flagged,
+        score,
+        threshold,
+        basis: "model",
+        ...(category !== undefined ? { category } : {}),
+    };
+}
+/**
+ * Build a `CommandGuard` from the shadow's rule scorer and the cached
+ * classifier promise it shares with the shadow.
+ *
+ * The guard never throws: every step of `assess` (rule scoring, the temp-
+ * only check, the cached classify, the decision table) is wrapped in a
+ * single try/catch that falls through to a no-rule / no-model rules-only
+ * decision with score 0. The shadow classifies once per command; `assess`
+ * awaits the cached promise rather than re-classifying.
+ */
+export function createCommandGuard(opts) {
+    const { threshold, scoreRules: rules, classifyCached } = opts;
+    async function assess(input) {
+        // Safe defaults for the catch path: no rule hit, no classifier consulted,
+        // so the rules-only branch scores 0 with no category. Anything that
+        // throws — an injected scoreRules that rejects, lexBashCommand on a
+        // non-string command, a malformed ModelResult passed directly — lands
+        // here without ever propagating a rejection to the caller.
+        const fallback = { version: 0, hits: emptyHits() };
+        try {
+            const scoredRules = rules(input.command, input.cwd);
+            const tempOnly = input.tempConfined && isTempOnly(input.command, input.cwd);
+            let model;
+            if (!tempOnly) {
+                // `classifyCached` is total by contract (a synchronous throw inside
+                // the shadow already maps to `unavailable/threw`); the try is the
+                // belt for a genuine rejection.
+                model = await classifyCached(input.command);
+            }
+            return scoreGuard({ rules: scoredRules, model, tempOnly, threshold });
+        }
+        catch {
+            return scoreGuard({ rules: fallback, model: undefined, tempOnly: false, threshold });
+        }
+    }
+    return { threshold, assess };
+}
+/** Six `false` rule hits, kept here so the catch path never reaches for
+ *  partial state. `version` is `0` to mark the result as "did not score". */
+function emptyHits() {
+    return Object.freeze(Object.fromEntries(QUESTION_IDS.map((id) => [id, false])));
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Tool-call correlation identifiers, shared by the tap, the Observation and
+ * the durable row.
+ *
+ * Shadow rows could not be joined to tool-audit (review #12) because none of
+ * these reached them. Each field is optional and is copied only when its
+ * source defines it: an absent source yields an object WITHOUT the key, never
+ * one holding `undefined` -- the same rule runtime.ts's tool-audit record
+ * follows, so a shadow row and its audit row join on identical values.
+ */
+export interface CallIdentifiers {
+    /** The `callOp` invocation this call happened under (1:N over turns). */
+    readonly callId?: string;
+    /** Caller-defined region spanning many `callOp` invocations. */
+    readonly scopeId?: string;
+    /** The turn this call happened in. Native sessions only. */
+    readonly turnId?: string;
+    /** Model round-trip index WITHIN the turn, 1-based. Native sessions only. */
+    readonly roundTrips?: number;
+    /** Provider-assigned `tool_use` id, verbatim. ACP calls carry none. */
+    readonly toolCallId?: string;
+}
+/** The defined subset of `source`, key by key. Nothing is defaulted. */
+export declare function callIdentifiers(source: CallIdentifiers): CallIdentifiers;

package/dist/command-safety/identifiers.js

@@ -0,0 +1,20 @@
+/**
+ * Tool-call correlation identifiers, shared by the tap, the Observation and
+ * the durable row.
+ *
+ * Shadow rows could not be joined to tool-audit (review #12) because none of
+ * these reached them. Each field is optional and is copied only when its
+ * source defines it: an absent source yields an object WITHOUT the key, never
+ * one holding `undefined` -- the same rule runtime.ts's tool-audit record
+ * follows, so a shadow row and its audit row join on identical values.
+ */
+/** The defined subset of `source`, key by key. Nothing is defaulted. */
+export function callIdentifiers(source) {
+    return {
+        ...(source.callId !== undefined ? { callId: source.callId } : {}),
+        ...(source.scopeId !== undefined ? { scopeId: source.scopeId } : {}),
+        ...(source.turnId !== undefined ? { turnId: source.turnId } : {}),
+        ...(source.roundTrips !== undefined ? { roundTrips: source.roundTrips } : {}),
+        ...(source.toolCallId !== undefined ? { toolCallId: source.toolCallId } : {}),
+    };
+}

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

@@ -0,0 +1,17 @@
+export type { BuildCommandShadowOptions } from "./build.ts";
+export { buildCommandShadow, COMMAND_SAFETY_DIR } from "./build.ts";
+export { createCommandGuard, scoreGuard } from "./guard.ts";
+export type { SystemOneQuestion, SystemOneRequest } from "./questions.ts";
+export { buildRequest, HARM_QUESTION_ID, QUESTION_SET_VERSION, SYSTEMONE_MODEL_LABEL } from "./questions.ts";
+export { appendCommandSafetyRow } from "./row.ts";
+export { RULE_SET_VERSION, type RuleContext, scoreRules } from "./rule-scorer.ts";
+export type { CommandShadowOptions } from "./shadow.ts";
+export { _commandShadowDeps, createCommandShadow, shadowCacheKey } from "./shadow.ts";
+export type { Classify, SystemOneClientOptions } from "./systemone-client.ts";
+export { _systemOneClientDeps, createSystemOneClient, parseAnswer } from "./systemone-client.ts";
+export type { ShadowCall, ShadowTap } from "./tap.ts";
+export { openShadowTap, toMechanical } from "./tap.ts";
+export { isTempOnly } from "./temp-only.ts";
+export { detectTmpWrite } from "./tmp-write.ts";
+export type { CommandGuard, CommandSafetyRow, CommandShadow, ExecRun, FinalOutcome, GuardDecision, GuardInput, HarmOption, LedgerOutcome, MechanicalVerdict, ModelAnswers, ModelResult, Observation, QuestionId, RuleResult, } from "./types.ts";
+export { HARM_OPTIONS, QUESTION_IDS } from "./types.ts";

package/dist/command-safety/index.js

@@ -0,0 +1,11 @@
+export { buildCommandShadow, COMMAND_SAFETY_DIR } from "./build.js";
+export { createCommandGuard, scoreGuard } from "./guard.js";
+export { buildRequest, HARM_QUESTION_ID, QUESTION_SET_VERSION, SYSTEMONE_MODEL_LABEL } from "./questions.js";
+export { appendCommandSafetyRow } from "./row.js";
+export { RULE_SET_VERSION, scoreRules } from "./rule-scorer.js";
+export { _commandShadowDeps, createCommandShadow, shadowCacheKey } from "./shadow.js";
+export { _systemOneClientDeps, createSystemOneClient, parseAnswer } from "./systemone-client.js";
+export { openShadowTap, toMechanical } from "./tap.js";
+export { isTempOnly } from "./temp-only.js";
+export { detectTmpWrite } from "./tmp-write.js";
+export { HARM_OPTIONS, QUESTION_IDS } from "./types.js";

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

@@ -0,0 +1,19 @@
+export declare const QUESTION_SET_VERSION = 1;
+export declare const HARM_QUESTION_ID = "harm";
+/** Recorded and ignored by SystemOne servers; the backend is chosen server-side. */
+export declare const SYSTEMONE_MODEL_LABEL = "nax-command-safety";
+export interface SystemOneQuestion {
+    readonly type: "choice" | "noul";
+    readonly instructions: string;
+    /** choice: option -> meaning text; noul: { true, false } meaning text. */
+    readonly criteria: Readonly<Record<string, string>>;
+}
+export interface SystemOneRequest {
+    readonly model: string;
+    readonly state: {
+        readonly command: string;
+    };
+    readonly questions: Readonly<Record<string, SystemOneQuestion>>;
+}
+/** The SystemOne body for one command. The state carries the command verbatim and nothing else. */
+export declare function buildRequest(command: string): SystemOneRequest;

package/dist/command-safety/questions.js

@@ -0,0 +1,60 @@
+export const QUESTION_SET_VERSION = 1;
+export const HARM_QUESTION_ID = "harm";
+/** Recorded and ignored by SystemOne servers; the backend is chosen server-side. */
+export const SYSTEMONE_MODEL_LABEL = "nax-command-safety";
+const HARM_CRITERIA = {
+    none: "No harm. Reads, builds, tests or makes a normal change.",
+    deletes_data: "Deletes source files or data.",
+    discards_work: "Throws away uncommitted work or git history.",
+    outside_project: "Touches files outside the project.",
+    system_change: "Changes system configuration, services or global packages.",
+    network_send: "Sends data to a remote host.",
+    privilege: "Uses sudo or changes permissions or ownership.",
+};
+const NOUL = {
+    deletes_data: {
+        instructions: "Does `command` delete files or directories?",
+        yes: "yes: source files, data or directories are removed or emptied",
+        no: "no: nothing is removed, or only build output or caches",
+    },
+    discards_work: {
+        instructions: "Does `command` discard uncommitted changes or git history, for example git reset --hard, git clean, git checkout --, or git stash drop?",
+        yes: "yes: uncommitted edits, untracked files, stashes, branches or commits are thrown away",
+        no: "no: git history and working changes are kept",
+    },
+    outside_project: {
+        instructions: "Does `command` read or write paths outside the current project directory?",
+        yes: "yes: it touches the home directory, system paths or another project",
+        no: "no: it stays inside the current project",
+    },
+    system_change: {
+        instructions: "Does `command` change system configuration, services, scheduled jobs, or globally installed packages?",
+        yes: "yes: the machine's configuration, services, schedules or global tools change",
+        no: "no: only the project changes",
+    },
+    network_send: {
+        instructions: "Does `command` send data to a remote host?",
+        yes: "yes: data leaves this machine",
+        no: "no: nothing is sent over the network",
+    },
+    privilege: {
+        instructions: "Does `command` use sudo or change file permissions or ownership?",
+        yes: "yes: it runs as root or changes permissions or ownership",
+        no: "no: it runs with normal rights",
+    },
+};
+const QUESTIONS = Object.freeze({
+    [HARM_QUESTION_ID]: {
+        type: "choice",
+        instructions: "Which harm does `command` cause?",
+        criteria: { ...HARM_CRITERIA },
+    },
+    ...Object.fromEntries(Object.entries(NOUL).map(([id, q]) => [
+        id,
+        { type: "noul", instructions: q.instructions, criteria: { true: q.yes, false: q.no } },
+    ])),
+});
+/** The SystemOne body for one command. The state carries the command verbatim and nothing else. */
+export function buildRequest(command) {
+    return { model: SYSTEMONE_MODEL_LABEL, state: { command }, questions: QUESTIONS };
+}

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

@@ -0,0 +1,2 @@
+import type { CommandSafetyRow } from "./types.ts";
+export declare function appendCommandSafetyRow(dir: string, runId: string, row: CommandSafetyRow): Promise<void>;

package/dist/command-safety/row.js

@@ -0,0 +1,14 @@
+/**
+ * Appends one shadow row (spec 7.3). One JSON object per line, mirroring
+ * src/permissions/approval-audit.ts. JSON.stringify escapes control
+ * characters, so a command containing a newline still occupies one line.
+ * String leaves pass through redactRowStrings so a secret in the command is
+ * masked in the row while shell syntax after the span stays forensic.
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { redactRowStrings } from "#src/permissions/index";
+export async function appendCommandSafetyRow(dir, runId, row) {
+    await mkdir(dir, { recursive: true });
+    await appendFile(join(dir, `${runId}.jsonl`), `${JSON.stringify(redactRowStrings(row))}\n`, "utf8");
+}

package/dist/command-safety/rule-scorer.d.ts

@@ -0,0 +1,9 @@
+import { type RuleResult } from "./types.ts";
+export declare const RULE_SET_VERSION = 3;
+/** Context the scorer may use; every field is optional and absent means v1 behaviour. */
+export interface RuleContext {
+    /** The project root the command runs against (the Bash call's cwd). */
+    readonly root?: string;
+}
+/** Per-category hits. Total: a pattern failure yields no hits plus `error`, never a throw. */
+export declare function scoreRules(command: string, context?: RuleContext): RuleResult;