@nathapp/nax-agent 0.1.0 → 0.2.0

package/dist/tools/policy.js

@@ -16,7 +16,7 @@
 import { relative, resolve, sep } from "node:path";
 import { realOrRaw } from "#src/internal/realpath";
 import { validateArgv } from "./exec-guard.js";
-import { naxOwnedWriteRefusal, naxWriteOptIns } from "./nax-owned-writes.js";
+import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
 import { commandBranch } from "./policy-command-branch.js";
 import { compileArgvPattern, compileRuleMap, globToRegExp, matchedArgvSource, matchedGlobSource, matchedRulePatterns, matchesAny, matchesArgvGrant, } from "./policy-match.js";
 import { pathsBranch, resolveWithin } from "./policy-paths-branch.js";
@@ -35,13 +35,14 @@ function isFieldlessScope(scope) {
 }
 export function compileToolPolicy(grants, root, options) {
     const resolvedRoot = realOrRaw(root);
+    const owned = options?.ownedPaths ?? EMPTY_OWNED_PATHS_POLICY;
     // nax#2115: the SAME transform `relativeTo` applies to every checked path, so
     // the guard compares like with like. A path outside the root yields a
     // ".."-prefixed rel that can never equal a checked path's, exempting nothing.
     const ownedWriteExemption = options?.ownedWriteExemption === undefined
         ? undefined
         : relative(resolvedRoot, realOrRaw(options.ownedWriteExemption)).split(sep).join("/");
-    const naxOptIns = naxWriteOptIns(root, options?.naxAllowWrite ?? []);
+    const naxOptIns = owned.writeOptIns(root, options?.naxAllowWrite ?? []);
     const denyBy = compileRuleMap(options?.denyRules);
     const askBy = compileRuleMap(options?.askRules);
     const bashApproval = options?.bashApproval ?? "gated";
@@ -87,9 +88,9 @@ export function compileToolPolicy(grants, root, options) {
      * denied and an ask on an ungranted call never becomes an approval prompt.
      */
     function applyPathRules(tool, rel, state) {
-        const naxOwned = naxOwnedWriteRefusal(tool, rel, ownedWriteExemption, naxOptIns);
-        if (naxOwned !== undefined)
-            return deny(`${tool} may not modify ${naxOwned}`);
+        const ownedRefusal = owned.writeRefusal(tool, rel, { exemptRel: ownedWriteExemption, optIns: naxOptIns });
+        if (ownedRefusal !== undefined)
+            return deny(`${tool} may not modify ${ownedRefusal}`);
         const denyEntry = denyBy.get(tool);
         const askEntry = askBy.get(tool);
         if (denyEntry !== undefined && (denyEntry.unconditional || matchesAny(denyEntry.matchers, rel))) {
@@ -187,7 +188,7 @@ export function compileToolPolicy(grants, root, options) {
      * the nested helpers below stay authoritative, and the sibling reads them at
      * call time — `pathsBranch` itself lives in `./policy-paths-branch`.
      */
-    const pathsBranchContext = { resolvedRoot, deny, askVerdict, applyPathRules };
+    const pathsBranchContext = { resolvedRoot, deny, askVerdict, applyPathRules, ownedPaths: owned };
     return {
         root: resolvedRoot,
         grantedTools() {
@@ -217,10 +218,11 @@ export function compileToolPolicy(grants, root, options) {
                 bashApproval,
                 rawBashRefusal: options?.rawBashRefusal,
                 sandboxWrapped: options?.sandboxWrapped,
+                ownedPaths: owned,
                 resolvedRoot,
                 denyBy,
                 askBy,
-                resolvePath: (candidate, cwd) => resolveWithin(resolvedRoot, resolve(cwd, candidate)),
+                resolvePath: (candidate, cwd) => resolveWithin(resolvedRoot, resolve(cwd, candidate), owned),
                 deny,
                 askVerdict,
             }) ??

package/dist/tools/protected-paths.d.ts

@@ -9,12 +9,12 @@ export interface ProtectedPathsPolicy {
     readonly gitExcludePathspecs: readonly string[];
     /** Gitignore patterns GitCommit refuses to stage. */
     readonly gitIgnorePatterns: readonly string[];
-    /** Project-relative directory whose top-level entries the sandbox policy lists. */
-    readonly projectStateDir: string;
-    /** Directory whose `credentials*` files the sandbox denies. */
-    readonly credentialDir: string;
-    /** File the sandbox denies writes to: the trust store deciding whether repository code runs. */
-    readonly trustStoreFile: string;
+    /** Project-relative directory whose top-level entries the sandbox policy lists. Absent: the sandbox skips it (S3 spec 6.2). */
+    readonly projectStateDir?: string;
+    /** Directory whose `credentials*` files the sandbox denies. Absent: the sandbox skips it (S3 spec 6.2). */
+    readonly credentialDir?: string;
+    /** File the sandbox denies writes to: the trust store deciding whether repository code runs. Absent: the sandbox skips it (S3 spec 6.2). */
+    readonly trustStoreFile?: string;
 }
 /** The Git tool's default excludes; none when the session carries no policy. */
 export declare function gitExcludePathspecsOf(ctx: {

package/dist/tools/read.js

@@ -22,6 +22,7 @@
  * both.
  */
 import { readPrefix } from "#src/internal/bounded-io";
+import { credentialReadRefusal } from "./credential-read-deny.js";
 import { applyCapCut, limitStopFooter, shouldAppendLimitStopFooter } from "./read-continuation.js";
 import { MODEL_MAX_BYTES, MODEL_MAX_LINES, READ_CEILING, splitModelLines } from "./truncate.js";
 /** Range arguments models invent instead of offset/limit -- rejected by name, never silently dropped. */
@@ -41,6 +42,34 @@ function countLines(prefix) {
     const trimmed = prefix.endsWith("\n") ? prefix.slice(0, -1) : prefix;
     return trimmed.split("\n").length;
 }
+/**
+ * The range half of Read's input: the unsupported-alias rejection (#1923) plus
+ * offset/limit parsing. Extracted from `run` so the credential read-deny adds
+ * no complexity there.
+ */
+function parseRange(input) {
+    const usedAlias = UNSUPPORTED_RANGE_ALIASES.find((alias) => input[alias] !== undefined);
+    if (usedAlias !== undefined) {
+        return {
+            error: `"${usedAlias}" is not a supported Read argument -- use offset (1-based line number) and/or limit (line count) instead`,
+        };
+    }
+    let offset = 1;
+    if (input.offset !== undefined) {
+        const parsed = parsePositiveInt(input.offset, "offset");
+        if (typeof parsed === "string")
+            return { error: parsed };
+        offset = parsed;
+    }
+    let limit;
+    if (input.limit !== undefined) {
+        const parsed = parsePositiveInt(input.limit, "limit");
+        if (typeof parsed === "string")
+            return { error: parsed };
+        limit = parsed;
+    }
+    return { offset, limit };
+}
 export const readTool = {
     name: "Read",
     description: "Read a UTF-8 text file from the repository. Paths are relative to the repository root. " +
@@ -64,15 +93,18 @@ export const readTool = {
         const [target] = ctx.resolvedPaths;
         if (target === undefined)
             return { content: "no path supplied", isError: true };
-        const usedAlias = UNSUPPORTED_RANGE_ALIASES.find((alias) => input[alias] !== undefined);
-        if (usedAlias !== undefined) {
-            return {
-                content: `"${usedAlias}" is not a supported Read argument -- use offset (1-based line number) and/or limit (line count) instead`,
-                isError: true,
-            };
+        // S3 spec 6.3: a workdir may resolve onto the host's credential directory
+        // or trust store; the read tools refuse those regardless of grant.
+        const credential = credentialReadRefusal(ctx.protectedPaths, target);
+        if (credential !== undefined) {
+            return { content: `path "${String(input.path)}" ${credential}`, isError: true };
         }
         const hasOffset = input.offset !== undefined;
         const hasLimit = input.limit !== undefined;
+        const range = parseRange(input);
+        if ("error" in range)
+            return { content: range.error, isError: true };
+        const { offset, limit } = range;
         try {
             if (!hasOffset && !hasLimit) {
                 // Leading [N lines] header so an agent has a way to count the lines it
@@ -106,20 +138,6 @@ export const readTool = {
                 });
                 return { content: result.content };
             }
-            let offset = 1;
-            if (hasOffset) {
-                const parsed = parsePositiveInt(input.offset, "offset");
-                if (typeof parsed === "string")
-                    return { content: parsed, isError: true };
-                offset = parsed;
-            }
-            let limit;
-            if (hasLimit) {
-                const parsed = parsePositiveInt(input.limit, "limit");
-                if (typeof parsed === "string")
-                    return { content: parsed, isError: true };
-                limit = parsed;
-            }
             // Read up to maxFileBytes, not maxBytes: the requested range may start
             // past the display ceiling, and we still need to reach it to slice.
             const body = await readPrefix(target, ctx.maxFileBytes);

package/dist/tools/registry.d.ts

@@ -12,6 +12,7 @@
 import type { CommandInterceptor } from "#src/command-interceptor/index";
 import type { JSONSchema } from "#src/session/tool-descriptor";
 import type { SandboxRecord } from "../sandbox/index.ts";
+import type { OwnedPathsPolicy } from "./owned-paths.ts";
 import type { ProtectedPathsPolicy } from "./protected-paths.ts";
 import type { CodingToolName, ToolScope } from "./types.ts";
 export interface ToolResult {
@@ -96,6 +97,8 @@ export interface ToolRunContext {
     readonly interceptor?: CommandInterceptor;
     /** Host-owned paths (S1 spec port 6). Absent: the Git tools exclude and skip nothing extra. */
     readonly protectedPaths?: ProtectedPathsPolicy;
+    /** Host-owned path rules (S3-2 port). Absent: no owned-path refusals. */
+    readonly ownedPaths?: OwnedPathsPolicy;
 }
 export interface CodingTool {
     readonly name: string;

package/dist/tools/run-command-exec.js

@@ -112,6 +112,7 @@ export async function runExecBranch(input, ctx, opts) {
         packageWorkdir: opts.exec.packageWorkdir,
         packageRelPath,
         allowScripts: opts.exec.allowScripts,
+        ownedPaths: ctx.ownedPaths,
         ...(opts.exec.packageName !== undefined ? { packageName: opts.exec.packageName } : {}),
     });
     if ("error" in normalized)

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.2.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;