@nathapp/nax-agent 0.1.0 → 0.3.0

package/dist/tools/runtime.d.ts

@@ -12,6 +12,7 @@ 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 { OwnedPathsPolicy } from "./owned-paths.ts";
 import type { ProtectedPathsPolicy } from "./protected-paths.ts";
 import { type CodingTool } from "./registry.ts";
 import { type ToolAuditSink } from "./tool-audit.ts";
@@ -146,4 +147,6 @@ export declare function createCodingToolRuntime(opts: {
     interceptor?: CommandInterceptor;
     /** Port 6: placed on every ToolRunContext this runtime builds. */
     protectedPaths?: ProtectedPathsPolicy;
+    /** S3-2 port: placed on every ToolRunContext this runtime builds. */
+    ownedPaths?: OwnedPathsPolicy;
 }): CodingToolRuntime;

package/dist/tools/runtime.js

@@ -80,6 +80,7 @@ function contextPorts(opts) {
     return {
         ...(opts.interceptor !== undefined ? { interceptor: opts.interceptor } : {}),
         ...(opts.protectedPaths !== undefined ? { protectedPaths: opts.protectedPaths } : {}),
+        ...(opts.ownedPaths !== undefined ? { ownedPaths: opts.ownedPaths } : {}),
     };
 }
 export function createCodingToolRuntime(opts) {

package/dist/tools/scratchpad.js

@@ -17,6 +17,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, sep } from "node:path";
 import { fileSizeOrZero } from "#src/internal/file-size";
 import { getAgentRuntime } from "#src/runtime/index";
+import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
 import { resolveWithin } from "./policy.js";
 import { readFileSlice } from "./read-file.js";
 import { READ_CEILING } from "./truncate.js";
@@ -185,7 +186,7 @@ export const scratchpadListTool = {
         for (const hit of sorted) {
             if (files.length >= MAX_MATCHES)
                 break;
-            if (resolveWithin(ctx.root, hit) === null)
+            if (resolveWithin(ctx.root, hit, ctx.ownedPaths ?? EMPTY_OWNED_PATHS_POLICY) === null)
                 continue;
             files.push(hit.split(sep).join("/"));
         }

package/dist/tools/types.d.ts

@@ -63,8 +63,8 @@ export interface ToolScope {
      * Root-relative subdirectory the tool's path fields are confined to.
      * Containment runs against `<root>/<confineTo>` instead of `<root>`, so a
      * path-bearing tool can never reach the rest of the repository even under
-     * an unconditional grant. Grant globs, deny rules and `naxOwnedWriteRefusal`
-     * keep seeing the canonical repo-root-relative spelling: containment is the
+     * an unconditional grant. Grant globs, deny rules and the injected policy's
+     * `writeRefusal` keep seeing the canonical repo-root-relative spelling: containment is the
      * single seam, only its ROOT shifts. Tool-declared, never config-declared --
      * a mis-set `pathFields` grant must not be able to widen the tool's reach.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -48,7 +48,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "provenance": false,
+    "provenance": true,
     "tag": "latest"
   }
 }

package/dist/tools/nax-owned-writes.d.ts

@@ -1,135 +0,0 @@
-/**
- * Which paths nax refuses to let an agent touch, and to which tools.
- *
- * A separate file rather than an addition to src/tools/policy.ts, for the same
- * reason src/tools/deny-paths.ts is one: that file carries the containment
- * seam and sits at the project's file-size ratchet, while this is a narrower
- * concern -- it has nothing to do with resolving or containing a path, only
- * with refusing one containment would otherwise allow.
- *
- * Segment-exact, never a prefix or substring match: `.naxignore`,
- * `docs/nax/config.json` and `.nax/mono/api/notes.md` are ordinary paths a
- * tool must still reach.
- */
-/**
- * The one top-level `.nax/` entry agents may write freely: the scratchpad.
- * Must equal the last segment of SCRATCHPAD_DIR (pinned by a test; importing
- * it here would close a scratchpad -> policy -> nax-owned-writes cycle).
- */
-export declare const NAX_SCRATCHPAD_ENTRY = "scratchpad";
-/**
- * Entries nax loads as human-authored input. The sandbox denies these even
- * when absent, so an agent cannot create one: a new `.nax/rules/x.md` would be
- * injected into every later session's prompt, and `hooks.json` / `plugins/`
- * run unsandboxed on the next `nax run`. `templates/` and `prompts/` are where
- * `prompts.overrides` points. nax creates none of them mid-run (CLI only).
- */
-export declare const NAX_ALWAYS_DENIED_ENTRIES: readonly string[];
-/**
- * Top-level `.nax/` entries a human opened for agent writes by listing them in
- * `execution.sandbox.filesystem.allowWrite` (nax#2260). Only an exact entry
- * counts -- `.nax/rules`, never `.nax/rules/a.md` -- and never the scratchpad
- * (always open) or a NAX_NEVER_OPT_IN entry. Relative entries resolve against
- * `root`, as the sandbox's own write roots do.
- */
-export declare function naxWriteOptIns(root: string, allowWrite: readonly string[]): ReadonlySet<string>;
-/**
- * Is `resolved` one of nax's own CONFIG files, relative to `root`?
- *
- * `.nax/config.json`, and `.nax/mono/<package>/config.json` in a monorepo.
- *
- * Why these at all: `quality.commands` and `acceptance.command` are run by key
- * through a shell and never pass the permission gate -- they are trusted
- * because a HUMAN wrote them. That trust rests entirely on a model being
- * unable to write them. An agent holding `Write` under the default
- * `unrestricted` profile could otherwise add a quality command and receive an
- * ungated shell on the next run, routing around every `Bash(...)` rule, the
- * lexer's construct refusals and containment itself.
- *
- * Refused to EVERY tool, reads included -- this is the pre-existing behaviour
- * and it is deliberate.
- */
-export declare function isNaxConfigFile(root: string, resolved: string): boolean;
-/**
- * The path-bearing tools that MUTATE. Read, Grep, Glob and Git are read-only
- * and are deliberately absent: an agent legitimately reads its own PRD, and
- * refusing that would break ordinary work to close one hole.
- *
- * Bash and Exec are absent because they carry no path fields -- a shell
- * redirect into `.nax/` is gated by the human-authored `Bash(...)` rules and
- * the lexer, which is a different seam from this one.
- */
-export declare const NAX_OWNED_WRITE_TOOLS: ReadonlySet<string>;
-/**
- * nax's run-control files at the root: the command channel an agent could
- * otherwise use to PAUSE, ABORT or SKIP stories without writing any code.
- *
- * `.queue.txt.processing` is the atomic-rename target the queue handler reads
- * from (src/execution/queue-handler.ts), so guarding only `.queue.txt` would
- * leave the same hole one rename downstream.
- */
-export declare const QUEUE_CONTROL_FILES: ReadonlySet<string>;
-/**
- * The kinds of nax-owned path the raw Bash screen refuses by name.
- * `"config"` is produced by the lexical `isNaxConfigFile` pass, never by
- * `naxOwnedKind` -- see that function.
- */
-export type NaxOwnedKind = "prd" | "queue" | "config";
-/**
- * Is this path one nax owns the writes to, independent of WHICH tool is asking?
- *
- * `naxOwnedWriteRefusal` answers the same question for the four file-writing
- * tools and returns prose. This predicate is the tool-agnostic half, extracted
- * so the `raw` bash screen (ADR-030) can consult exactly the same path set
- * without being in `NAX_OWNED_WRITE_TOOLS`. One definition, two callers.
- *
- * @param rel - Path relative to the permitted root, `/`-joined.
- */
-export declare function isNaxOwnedWritePath(rel: string): boolean;
-/**
- * Which kind of nax-owned write path `rel` is, or undefined when it is not one.
- *
- * `/`-joined and root-relative, like `isNaxOwnedWritePath`. Never returns
- * `"config"` -- nax config files are recognised by the lexical
- * `isNaxConfigFile` pass, which callers (`protectedHit` in policy-bash-raw.ts)
- * run FIRST. Keeping the two apart is what lets the raw screen name the kind it
- * matched without duplicating the config rule here.
- */
-export declare function naxOwnedKind(rel: string): "prd" | "queue" | undefined;
-/**
- * Refusal text for a Bash command that names (verb "names") or redirects into
- * (verb "redirects into") a nax-owned file.
- *
- * Kind-specific on purpose. The previous screen returned one modification-only
- * sentence for every kind, which read as "you cannot WRITE this" -- so an agent
- * that only wanted to READ a PRD retried a command it will never be allowed to
- * run. Each branch now says what the file IS and what the agent can do instead.
- *
- * The text never spells `.nax/features/` literally: `src/tools/` is covered by
- * the `check:feature-dir-ssot` gate, so the PRD branch names the token the agent
- * used (`hit`) rather than the tree layout.
- *
- * US-002: `opts.sandboxWrapped` (an available launcher) swaps only the PRD
- * sentence -- reading through Bash is then allowed, writing still is not.
- * `config` and `queue` are unchanged in both modes.
- */
-export declare function naxOwnedBashRefusal(tool: string, kind: NaxOwnedKind, hit: string, verb: "names" | "redirects into", opts?: {
-    sandboxWrapped?: boolean;
-}): string;
-/**
- * Why `tool` may not touch `rel`, or `undefined` when it may.
- *
- * `rel` MUST be the canonical, posix-separated, root-relative spelling the
- * policy itself derived -- never the caller's own. Matching the caller's
- * spelling means this guard and the policy that approved the call are reading
- * different strings, and every alternate spelling ("./x", "a/../x") walks past
- * the guard. Same rule, and the same reason, as `matchesDenyPaths`.
- *
- * The PRD defines the acceptance criteria the story is judged against. An
- * agent that can rewrite it can pass any review without writing any code,
- * which defeats the review layer without touching a config file.
- *
- * The queue file is the other half of the same concern: it is the run-control
- * channel, and a write there can pause, abort or skip stories outright.
- */
-export declare function naxOwnedWriteRefusal(tool: string, rel: string, exemptRel?: string, optIns?: ReadonlySet<string>): string | undefined;

package/dist/tools/nax-owned-writes.js

@@ -1,259 +0,0 @@
-/**
- * Which paths nax refuses to let an agent touch, and to which tools.
- *
- * A separate file rather than an addition to src/tools/policy.ts, for the same
- * reason src/tools/deny-paths.ts is one: that file carries the containment
- * seam and sits at the project's file-size ratchet, while this is a narrower
- * concern -- it has nothing to do with resolving or containing a path, only
- * with refusing one containment would otherwise allow.
- *
- * Segment-exact, never a prefix or substring match: `.naxignore`,
- * `docs/nax/config.json` and `.nax/mono/api/notes.md` are ordinary paths a
- * tool must still reach.
- */
-import { isAbsolute, relative, resolve, sep } from "node:path";
-import { realOrRaw } from "#src/internal/realpath";
-/**
- * The one top-level `.nax/` entry agents may write freely: the scratchpad.
- * Must equal the last segment of SCRATCHPAD_DIR (pinned by a test; importing
- * it here would close a scratchpad -> policy -> nax-owned-writes cycle).
- */
-export const NAX_SCRATCHPAD_ENTRY = "scratchpad";
-/**
- * Top-level `.nax/` entries an allowWrite opt-in can never open (nax#2260):
- * config is the trust anchor for ungated commands, `mono` holds package
- * configs, and `features` holds every PRD plus the running feature's state.
- */
-const NAX_NEVER_OPT_IN = new Set(["config.json", "mono", "features"]);
-/**
- * Entries nax loads as human-authored input. The sandbox denies these even
- * when absent, so an agent cannot create one: a new `.nax/rules/x.md` would be
- * injected into every later session's prompt, and `hooks.json` / `plugins/`
- * run unsandboxed on the next `nax run`. `templates/` and `prompts/` are where
- * `prompts.overrides` points. nax creates none of them mid-run (CLI only).
- */
-export const NAX_ALWAYS_DENIED_ENTRIES = [
-    "config.json",
-    "mono",
-    "rules",
-    "context.md",
-    "hooks.json",
-    "plugins",
-    "templates",
-    "prompts",
-];
-/**
- * A test file directly inside a feature dir: the acceptance and suggested
- * tests under their per-language names (`.nax-acceptance.test.ts`,
- * `_nax_acceptance_test.py`, `.nax-acceptance.rs`, ...) or a custom
- * `acceptance.testPath`, which is itself a test file name.
- */
-const FEATURE_TEST_FILE = /^\.nax-(acceptance|suggested)|[._-](test|spec)\.[a-z0-9]+$/i;
-const NO_OPT_INS = new Set();
-/**
- * Top-level `.nax/` entries a human opened for agent writes by listing them in
- * `execution.sandbox.filesystem.allowWrite` (nax#2260). Only an exact entry
- * counts -- `.nax/rules`, never `.nax/rules/a.md` -- and never the scratchpad
- * (always open) or a NAX_NEVER_OPT_IN entry. Relative entries resolve against
- * `root`, as the sandbox's own write roots do.
- */
-export function naxWriteOptIns(root, allowWrite) {
-    const naxDir = resolve(root, ".nax");
-    const names = allowWrite
-        .map((p) => relative(naxDir, isAbsolute(p) ? resolve(p) : resolve(root, p)))
-        .filter((rel) => rel !== "" && !rel.startsWith("..") && !rel.includes(sep) && !isAbsolute(rel))
-        .filter((name) => name !== NAX_SCRATCHPAD_ENTRY && !NAX_NEVER_OPT_IN.has(name));
-    return new Set(names);
-}
-/** `.nax/config.json`, or `.nax/mono/<package...>/config.json`, as root-relative segments. */
-function isNaxConfigSegments(segments) {
-    if (segments[0] !== ".nax" || segments[segments.length - 1] !== "config.json")
-        return false;
-    return segments.length === 2 || (segments.length >= 4 && segments[1] === "mono");
-}
-/**
- * Is `resolved` one of nax's own CONFIG files, relative to `root`?
- *
- * `.nax/config.json`, and `.nax/mono/<package>/config.json` in a monorepo.
- *
- * Why these at all: `quality.commands` and `acceptance.command` are run by key
- * through a shell and never pass the permission gate -- they are trusted
- * because a HUMAN wrote them. That trust rests entirely on a model being
- * unable to write them. An agent holding `Write` under the default
- * `unrestricted` profile could otherwise add a quality command and receive an
- * ungated shell on the next run, routing around every `Bash(...)` rule, the
- * lexer's construct refusals and containment itself.
- *
- * Refused to EVERY tool, reads included -- this is the pre-existing behaviour
- * and it is deliberate.
- */
-export function isNaxConfigFile(root, resolved) {
-    const rel = relative(realOrRaw(root), resolved);
-    if (rel === "" || rel.startsWith(".."))
-        return false;
-    // `.nax/config.json` (2), or `.nax/mono/<package>/config.json` at ANY package
-    // depth (>= 4). The real override path is nested -- `loadConfigForWorkdir`
-    // reads `.nax/mono/<packageDir>/config.json` where packageDir is the
-    // repo-relative package path (`src/config/loader.ts:382`), so a normal
-    // `packages/*` layout is 5 segments, not 4. A length-exact rule left every
-    // such override writable whenever the story's root was the repo root.
-    return isNaxConfigSegments(rel.split(sep));
-}
-/**
- * The path-bearing tools that MUTATE. Read, Grep, Glob and Git are read-only
- * and are deliberately absent: an agent legitimately reads its own PRD, and
- * refusing that would break ordinary work to close one hole.
- *
- * Bash and Exec are absent because they carry no path fields -- a shell
- * redirect into `.nax/` is gated by the human-authored `Bash(...)` rules and
- * the lexer, which is a different seam from this one.
- */
-export const NAX_OWNED_WRITE_TOOLS = new Set(["Write", "Edit", "Delete", "GitCommit"]);
-/**
- * nax's run-control files at the root: the command channel an agent could
- * otherwise use to PAUSE, ABORT or SKIP stories without writing any code.
- *
- * `.queue.txt.processing` is the atomic-rename target the queue handler reads
- * from (src/execution/queue-handler.ts), so guarding only `.queue.txt` would
- * leave the same hole one rename downstream.
- */
-export const QUEUE_CONTROL_FILES = new Set([".queue.txt", ".queue.txt.processing"]);
-/**
- * Is this path one nax owns the writes to, independent of WHICH tool is asking?
- *
- * `naxOwnedWriteRefusal` answers the same question for the four file-writing
- * tools and returns prose. This predicate is the tool-agnostic half, extracted
- * so the `raw` bash screen (ADR-030) can consult exactly the same path set
- * without being in `NAX_OWNED_WRITE_TOOLS`. One definition, two callers.
- *
- * @param rel - Path relative to the permitted root, `/`-joined.
- */
-export function isNaxOwnedWritePath(rel) {
-    return naxOwnedKind(rel) !== undefined;
-}
-/**
- * Which kind of nax-owned write path `rel` is, or undefined when it is not one.
- *
- * `/`-joined and root-relative, like `isNaxOwnedWritePath`. Never returns
- * `"config"` -- nax config files are recognised by the lexical
- * `isNaxConfigFile` pass, which callers (`protectedHit` in policy-bash-raw.ts)
- * run FIRST. Keeping the two apart is what lets the raw screen name the kind it
- * matched without duplicating the config rule here.
- */
-export function naxOwnedKind(rel) {
-    const segments = rel.split("/");
-    // SEC-5: the run-control file lives at the root, so match it exactly there
-    // and not at any other depth -- a nested `sub/.queue.txt` is an ordinary
-    // file, not the queue nax reads.
-    if (segments.length === 1 && QUEUE_CONTROL_FILES.has(segments[0] ?? ""))
-        return "queue";
-    if (segments[0] === ".nax" && segments[1] === "features" && segments[segments.length - 1] === "prd.json") {
-        return "prd";
-    }
-    return undefined;
-}
-/**
- * Refusal text for a Bash command that names (verb "names") or redirects into
- * (verb "redirects into") a nax-owned file.
- *
- * Kind-specific on purpose. The previous screen returned one modification-only
- * sentence for every kind, which read as "you cannot WRITE this" -- so an agent
- * that only wanted to READ a PRD retried a command it will never be allowed to
- * run. Each branch now says what the file IS and what the agent can do instead.
- *
- * The text never spells `.nax/features/` literally: `src/tools/` is covered by
- * the `check:feature-dir-ssot` gate, so the PRD branch names the token the agent
- * used (`hit`) rather than the tree layout.
- *
- * US-002: `opts.sandboxWrapped` (an available launcher) swaps only the PRD
- * sentence -- reading through Bash is then allowed, writing still is not.
- * `config` and `queue` are unchanged in both modes.
- */
-export function naxOwnedBashRefusal(tool, kind, hit, verb, opts) {
-    switch (kind) {
-        case "prd":
-            return (`${tool} command ${verb} "${hit}", which holds this story's acceptance criteria. ` +
-                "nax updates it itself during the run, so it shows as modified. " +
-                (opts?.sandboxWrapped === true
-                    ? "Reading it through Bash is allowed; writing it is not -- nax updates it itself. "
-                    : "Bash commands naming it are refused, reads included -- leave it as is. ") +
-                "To view it, use the `Read` tool.");
-        case "queue":
-            return (`${tool} command ${verb} "${hit}", which is nax's run-control queue. ` +
-                "Bash commands naming it are refused, reads included -- change the run through the queue command.");
-        case "config":
-            return (`${tool} command ${verb} "${hit}", which is nax configuration. ` +
-                "Bash commands naming it are refused, reads included -- nax configuration is not changed from inside a run.");
-    }
-}
-/**
- * Why `tool` may not touch `rel`, or `undefined` when it may.
- *
- * `rel` MUST be the canonical, posix-separated, root-relative spelling the
- * policy itself derived -- never the caller's own. Matching the caller's
- * spelling means this guard and the policy that approved the call are reading
- * different strings, and every alternate spelling ("./x", "a/../x") walks past
- * the guard. Same rule, and the same reason, as `matchesDenyPaths`.
- *
- * The PRD defines the acceptance criteria the story is judged against. An
- * agent that can rewrite it can pass any review without writing any code,
- * which defeats the review layer without touching a config file.
- *
- * The queue file is the other half of the same concern: it is the run-control
- * channel, and a write there can pause, abort or skip stories outright.
- */
-export function naxOwnedWriteRefusal(tool, rel, exemptRel, optIns = NO_OPT_INS) {
-    if (!NAX_OWNED_WRITE_TOOLS.has(tool))
-        return undefined;
-    if (!isNaxOwnedWritePath(rel)) {
-        return exemptRel !== undefined && rel === exemptRel ? undefined : naxStateRefusal(rel, optIns);
-    }
-    const segments = rel.split("/");
-    // SEC-5: the run-control file lives at the root, so match it exactly
-    // there and not at any other depth -- a nested `sub/.queue.txt` is an
-    // ordinary file, not the queue nax reads.
-    if (segments.length === 1) {
-        return `"${rel}" is nax's own run state: it carries the PAUSE/ABORT/SKIP commands that control this run, so no tool may modify it. Change the run through the queue command, not by writing its file.`;
-    }
-    // nax#2115: the plan session is the ONE writer of a PRD -- its op declares
-    // `fileOutput: (input) => input.outputPath` and every plan prompt instructs
-    // the agent to write the PRD there rather than reply with it. #2095 added
-    // this guard without an exemption, which severed that contract and left
-    // `nax plan` unable to produce a PRD in ANY mode.
-    //
-    // The exemption is PATH-EXACT, not role-shaped: the plan session may write
-    // the single path its own op declared, and nothing else. A sibling feature's
-    // PRD stays refused even to the plan session, so a planner cannot reach
-    // across features to rewrite criteria it is not authoring. `exemptRel` must
-    // be the caller's canonical, posix-separated, root-relative spelling --
-    // derived by the policy itself, never taken from the agent's own arguments.
-    if (exemptRel !== undefined && rel === exemptRel)
-        return undefined;
-    return `"${rel}" is nax's own run state: it holds the acceptance criteria this story is judged against, so no tool may modify it. Change the code, not the criteria.`;
-}
-/**
- * nax#2260: everything else under `.nax/` is nax's own state. Writable: the
- * scratchpad, test files directly inside a feature dir (FEATURE_TEST_FILE --
- * the tool-audit ledgers show these are the only file-tool writes agents need
- * there; the feature's context.md, spec and state files stay refused), and
- * opted-in entries. Config files are left to the earlier, more specific
- * `isNaxConfigFile` refusal, which covers reads too.
- *
- * Only a leading `.nax/` segment is matched, so a monorepo package's own
- * `.nax/` is excluded on purpose -- see `naxDenies` in
- * src/sandbox/policy-builder.ts for why that is mostly safe to delete and
- * where the one gap (package `rules/`) remains.
- */
-function naxStateRefusal(rel, optIns) {
-    const segments = rel.split("/");
-    if (segments[0] !== ".nax" || isNaxConfigSegments(segments))
-        return undefined;
-    const entry = segments[1];
-    if (segments.length > 2 && (entry === NAX_SCRATCHPAD_ENTRY || optIns.has(entry ?? "")))
-        return undefined;
-    if (segments.length === 4 && entry === "features" && FEATURE_TEST_FILE.test(segments[3] ?? ""))
-        return undefined;
-    return (`"${rel}" is nax's own state, which agents do not modify. Under .nax/, write only to your scratchpad ` +
-        "(.nax/scratchpad/) or to a feature's acceptance test file. " +
-        "A human can open a path for a story by listing it in execution.sandbox.filesystem.allowWrite in the project config.");
-}