@nathapp/nax-agent 0.3.1 → 0.85.0

package/dist/session/session-interaction.js

@@ -72,10 +72,29 @@ function runSafely(tool, input, ctx) {
         return { content: `Tool "${tool.name}" failed: ${cause}`, isError: true };
     });
 }
+/**
+ * Settle with `work`, or with `onAbort()` the moment `signal` aborts. The tool
+ * batch awaits interaction handlers with no abort race of its own, so a tool
+ * that ignores its signal would otherwise hang the turn (and `close()`, which
+ * awaits the turn). The abandoned work's late settlement is ignored.
+ */
+async function raceAbort(work, signal, onAbort) {
+    let listener = () => { };
+    const aborted = new Promise((resolve) => {
+        listener = () => resolve(onAbort());
+        signal.addEventListener("abort", listener, { once: true });
+    });
+    try {
+        return await Promise.race([work, aborted]);
+    }
+    finally {
+        signal.removeEventListener("abort", listener);
+    }
+}
 /**
  * Runs the tool, but answers at once when the turn aborts: the batch awaits
  * this handler with no abort race of its own, so a run that ignores its signal
- * would otherwise hang the turn. The abandoned run's late settlement is ignored.
+ * would otherwise hang the turn. See `raceAbort`.
  */
 async function invoke(tool, input, ctx) {
     const abandoned = {
@@ -84,17 +103,7 @@ async function invoke(tool, input, ctx) {
     };
     if (ctx.signal.aborted)
         return abandoned;
-    let onAbort = () => { };
-    const aborted = new Promise((resolve) => {
-        onAbort = () => resolve(abandoned);
-        ctx.signal.addEventListener("abort", onAbort, { once: true });
-    });
-    try {
-        return await Promise.race([runSafely(tool, input, ctx), aborted]);
-    }
-    finally {
-        ctx.signal.removeEventListener("abort", onAbort);
-    }
+    return raceAbort(runSafely(tool, input, ctx), ctx.signal, () => abandoned);
 }
 async function runEmbedderTool(deps, tool, request) {
     const toolCallId = request.toolCallId ?? "";
@@ -131,7 +140,14 @@ function toolCallContext(request) {
 async function runCodingTool(deps, request) {
     deps.setCurrentCallId(request.toolCallId);
     try {
-        const outcome = await deps.runtime.callTool(request.name, request.input ?? {}, toolCallContext(request));
+        const signal = request.signal ?? deps.turnSignal();
+        const abandoned = {
+            kind: "error",
+            content: `Tool "${request.name}" was abandoned: the turn ended.`,
+        };
+        const outcome = signal.aborted
+            ? abandoned
+            : await raceAbort(deps.runtime.callTool(request.name, request.input ?? {}, { ...toolCallContext(request), signal }), signal, () => abandoned);
         if (outcome.kind === "denied") {
             return { answer: `Denied: ${outcome.reason}`, denied: { reason: outcome.reason, breach: outcome.breach } };
         }

package/dist/session/session-types.d.ts

@@ -175,6 +175,14 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * facade sets it from `instructions`; nax leaves it unset. ACP ignores it.
      */
     systemPrompt?: string;
+    /** Native: repository-relative instruction scopes, independent of the file-tool root. */
+    instructionDirectories?: readonly string[];
+    /** Native: instruction Markdown basename; defaults to AGENTS.md and its legacy fallback chain. */
+    instructionFileName?: string;
+    /** Native: repository-relative paths excluded from automatic instruction reads. */
+    instructionDenyPaths?: readonly string[];
+    /** Native: host credential and trust-store paths excluded from instruction discovery. */
+    instructionProtectedPaths?: import("#src/tools/protected-paths").ProtectedPathsPolicy;
     /**
      * Native: resolved compaction settings. A resolved primitive, never NaxConfig —
      * src/agents/native/ must not read config (check:adapter-no-config-import).
@@ -192,6 +200,8 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * NaxConfig. ACP ignores it; its loop is bounded by `maxInteractions`.
      */
     spinBreaker?: import("#src/infra/spin-breaker/index").ResolvedSpinBreakerSettings;
+    /** Native: keep history written by another model (S5-3). */
+    readonly carryHistoryAcrossModels?: boolean;
 }
 /** Options for sendTurn(). */
 export interface SendTurnOpts {

package/dist/terminal-auth/index.d.ts

@@ -0,0 +1,4 @@
+/** Terminal login UI shared by `nax auth login` and `nax-agent login` (S5-4 M-28). */
+export { createTerminalAuthInteraction, type TerminalAuthOptions } from "./interaction.ts";
+export { _openUrlDeps, openUrl, spawnDetached } from "./open-url.ts";
+export { _terminalPromptDeps, PLAIN_STYLE, PromptCancelledError, type PromptStdin, promptForLine, promptForSecret, promptForSelect, type SelectChoice, type TerminalStyle, } from "./prompt.ts";

package/dist/terminal-auth/index.js

@@ -0,0 +1,4 @@
+/** Terminal login UI shared by `nax auth login` and `nax-agent login` (S5-4 M-28). */
+export { createTerminalAuthInteraction } from "./interaction.js";
+export { _openUrlDeps, openUrl, spawnDetached } from "./open-url.js";
+export { _terminalPromptDeps, PLAIN_STYLE, PromptCancelledError, promptForLine, promptForSecret, promptForSelect, } from "./prompt.js";

package/dist/terminal-auth/interaction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The terminal's side of a login (moved from nax's `terminalInteraction`, S5-4
+ * M-28). Shared by `nax auth login` and `nax-agent login`. Secrets go through
+ * the non-echoing prompt; any prompt type this mirror does not recognise is
+ * treated as a secret.
+ */
+import type { AuthInteraction } from "#src/native/auth-types";
+import { type TerminalStyle } from "#src/terminal-auth/prompt";
+export interface TerminalAuthOptions {
+    /** One line of output (no trailing newline). */
+    readonly log: (text: string) => void;
+    readonly style?: TerminalStyle;
+    readonly openUrl?: (url: string) => void;
+}
+export declare function createTerminalAuthInteraction(options: TerminalAuthOptions): AuthInteraction;

package/dist/terminal-auth/interaction.js

@@ -0,0 +1,55 @@
+import { openUrl as defaultOpenUrl } from "#src/terminal-auth/open-url";
+import { PLAIN_STYLE, promptForLine, promptForSecret, promptForSelect, } from "#src/terminal-auth/prompt";
+export function createTerminalAuthInteraction(options) {
+    const style = options.style ?? PLAIN_STYLE;
+    const open = options.openUrl ?? defaultOpenUrl;
+    // notify() is synchronous and the flow fires auth-url right before racing a
+    // manual-code prompt against its callback server, so the URL is parked and
+    // spent by the next prompt's Enter-on-empty.
+    let pendingUrl;
+    const manualCode = (message) => {
+        const url = pendingUrl;
+        if (url === undefined)
+            return promptForLine(message, undefined, style);
+        pendingUrl = undefined;
+        options.log(style.dim("Press Enter to open it in your browser."));
+        return promptForLine(message, () => {
+            options.log(style.dim("Opening your browser..."));
+            open(url);
+        }, style);
+    };
+    return {
+        prompt: async (prompt) => {
+            if (prompt.type === "manual-code")
+                return manualCode(prompt.message);
+            if (prompt.type === "text")
+                return promptForLine(prompt.message, undefined, style);
+            if (prompt.type === "select") {
+                return promptForSelect(prompt.message, prompt.options.map((option) => ({ id: option.id, label: option.label })), style);
+            }
+            return promptForSecret(prompt.message, style);
+        },
+        notify: (event) => {
+            switch (event.type) {
+                case "auth-url":
+                    // The flow's own instructions are dropped: nothing has opened a browser yet.
+                    options.log(`\n${style.bold("Open this URL to continue:")}\n  ${event.url}`);
+                    pendingUrl = event.url;
+                    return;
+                case "device-code":
+                    options.log(`\nGo to ${event.verificationUri} and enter code ${style.bold(event.userCode)}`);
+                    return;
+                case "info":
+                    options.log(event.message);
+                    for (const link of event.links ?? [])
+                        options.log(`  ${link.label ?? "Link"}: ${link.url}`);
+                    return;
+                case "progress":
+                    options.log(style.dim(event.message));
+                    return;
+                default:
+                // An event type this mirror does not recognise: say nothing.
+            }
+        },
+    };
+}

package/dist/terminal-auth/open-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Opening a URL in the user's browser (moved from the nax CLI, S5-4 M-28).
+ *
+ * Best-effort: the caller always prints the URL first, so a failure costs a
+ * copy-paste, not the login. The URL is its own argv entry, never a shell
+ * string. Node reports a missing opener asynchronously (an `error` event), so
+ * the child gets an error listener; without it a container with no xdg-open
+ * would crash the login (S5-4 Review Focus 2).
+ */
+import { type ChildProcess } from "node:child_process";
+export declare function spawnDetached(command: readonly string[]): ChildProcess;
+/** Test seam. */
+export declare const _openUrlDeps: {
+    spawn: (command: readonly string[]) => void;
+    platform: () => string;
+};
+export declare function openUrl(url: string): void;

package/dist/terminal-auth/open-url.js

@@ -0,0 +1,44 @@
+/**
+ * Opening a URL in the user's browser (moved from the nax CLI, S5-4 M-28).
+ *
+ * Best-effort: the caller always prints the URL first, so a failure costs a
+ * copy-paste, not the login. The URL is its own argv entry, never a shell
+ * string. Node reports a missing opener asynchronously (an `error` event), so
+ * the child gets an error listener; without it a container with no xdg-open
+ * would crash the login (S5-4 Review Focus 2).
+ */
+import { spawn } from "node:child_process";
+export function spawnDetached(command) {
+    const [file, ...args] = command;
+    // nax-git-env-allow: not git: browser opener argv
+    const child = spawn(file ?? "", args, { stdio: "ignore", detached: true, windowsHide: true });
+    child.on("error", () => {
+        // The URL is already on screen; a missing opener is not news.
+    });
+    child.unref();
+    return child;
+}
+/** Test seam. */
+export const _openUrlDeps = {
+    spawn: (command) => {
+        spawnDetached(command);
+    },
+    platform: () => process.platform,
+};
+/** The opener for a platform. Windows needs the empty "" title argument. */
+function openerFor(platform, url) {
+    if (platform === "darwin")
+        return ["open", url];
+    if (platform === "win32")
+        return ["cmd", "/c", "start", "", url];
+    return ["xdg-open", url];
+}
+export function openUrl(url) {
+    try {
+        // nax-git-env-allow: not git: browser opener argv
+        _openUrlDeps.spawn(openerFor(_openUrlDeps.platform(), url));
+    }
+    catch {
+        // Deliberately silent: the URL is already on screen.
+    }
+}

package/dist/terminal-auth/prompt.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Terminal prompts for credential entry (moved from the nax CLI, S5-4 M-28).
+ *
+ * Nothing typed into a secret prompt is echoed, and the terminal is restored on
+ * every exit path: submit, cancel, stream end and stream error. Ctrl+D cancels;
+ * it never submits (it once fell through to "submit" in nax's confirm prompt).
+ */
+/** Colours for the prompts; the caller supplies them (nax passes chalk). */
+export interface TerminalStyle {
+    accent(text: string): string;
+    dim(text: string): string;
+    bold(text: string): string;
+}
+export declare const PLAIN_STYLE: TerminalStyle;
+/** The slice of process.stdin these prompts drive. Injected so tests can stand one up. */
+export interface PromptStdin {
+    isTTY?: boolean;
+    setRawMode(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    setEncoding(encoding: string): unknown;
+    on(event: string, listener: (chunk: string) => void): unknown;
+    once(event: string, listener: () => void): unknown;
+    removeListener(event: string, listener: (...args: never[]) => void): unknown;
+}
+export declare class PromptCancelledError extends Error {
+    constructor();
+}
+/**
+ * Test seam. `stdin` is unset by default and resolved to `process.stdin` only
+ * when a prompt runs: this module is reachable from the public barrel, and
+ * touching `process.stdin` at import would open it for every consumer.
+ */
+export declare const _terminalPromptDeps: {
+    stdin: PromptStdin | undefined;
+    write: (text: string) => boolean;
+};
+/** Reads a secret. Nothing is echoed, not even a masking character. */
+export declare function promptForSecret(message: string, style?: TerminalStyle): Promise<string>;
+/** Reads a visible line, for non-secret answers such as a pasted auth code. */
+export declare function promptForLine(message: string, onEmptySubmit?: () => void, style?: TerminalStyle): Promise<string>;
+export interface SelectChoice {
+    readonly id: string;
+    readonly label: string;
+}
+/**
+ * Reads a choice with the arrow keys and returns the chosen option's id. The
+ * option block is redrawn in place. Enter commits the highlighted row, so a
+ * value that is not an option can never be returned.
+ */
+export declare function promptForSelect(message: string, choices: readonly SelectChoice[], style?: TerminalStyle): Promise<string>;

package/dist/terminal-auth/prompt.js

@@ -0,0 +1,196 @@
+/**
+ * Terminal prompts for credential entry (moved from the nax CLI, S5-4 M-28).
+ *
+ * Nothing typed into a secret prompt is echoed, and the terminal is restored on
+ * every exit path: submit, cancel, stream end and stream error. Ctrl+D cancels;
+ * it never submits (it once fell through to "submit" in nax's confirm prompt).
+ */
+/** Ctrl+C. */
+const ETX = "\u0003";
+/** Ctrl+D. Conventionally cancel, never submit. */
+const EOT = "\u0004";
+const CR = "\r";
+const LF = "\n";
+const BACKSPACE = "\u007F";
+const ARROW_UP = "\u001b[A";
+const ARROW_DOWN = "\u001b[B";
+const identity = (text) => text;
+export const PLAIN_STYLE = { accent: identity, dim: identity, bold: identity };
+export class PromptCancelledError extends Error {
+    constructor() {
+        super("Prompt cancelled");
+        this.name = "PromptCancelledError";
+    }
+}
+/**
+ * Test seam. `stdin` is unset by default and resolved to `process.stdin` only
+ * when a prompt runs: this module is reachable from the public barrel, and
+ * touching `process.stdin` at import would open it for every consumer.
+ */
+export const _terminalPromptDeps = {
+    stdin: undefined,
+    write: (text) => process.stdout.write(text),
+};
+function stdinOf() {
+    return _terminalPromptDeps.stdin ?? process.stdin;
+}
+/** What one typed character does to a line prompt. */
+function keyAction(char, bufferEmpty, hasEmptyHook) {
+    if (char === ETX || char === EOT)
+        return { kind: "cancel" };
+    if (char === CR || char === LF) {
+        return bufferEmpty && hasEmptyHook ? { kind: "empty-submit" } : { kind: "submit" };
+    }
+    if (char === BACKSPACE)
+        return { kind: "erase" };
+    return { kind: "append" };
+}
+/** Applies a non-terminal key to the buffer; echoes when the prompt is visible. */
+function applyEdit(action, char, buffer, echo, onEmptySubmit) {
+    if (action.kind === "empty-submit") {
+        onEmptySubmit?.();
+        return buffer;
+    }
+    if (action.kind === "erase") {
+        if (echo)
+            _terminalPromptDeps.write("\b \b");
+        return buffer.slice(0, -1);
+    }
+    if (echo)
+        _terminalPromptDeps.write(char);
+    return buffer + char;
+}
+/**
+ * `onEmptySubmit` turns Enter-on-an-empty-buffer into an action rather than a
+ * submission. An empty answer is meaningless for the prompts that use it (a
+ * pasted auth code), and spending the keystroke here keeps the whole login on a
+ * single stdin reader.
+ */
+function read(message, echo, onEmptySubmit, style) {
+    const stdin = stdinOf();
+    if (stdin.isTTY !== true)
+        return Promise.reject(new PromptCancelledError());
+    _terminalPromptDeps.write(`${style.accent("?")} ${message} `);
+    return new Promise((resolve, reject) => {
+        let buffer = "";
+        let settled = false;
+        const cleanup = () => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            stdin.removeListener("error", onEnd);
+            stdin.setRawMode(false);
+            stdin.pause();
+            _terminalPromptDeps.write("\n");
+        };
+        const onEnd = () => {
+            cleanup();
+            reject(new PromptCancelledError());
+        };
+        const onData = (chunk) => {
+            for (const char of chunk) {
+                const action = keyAction(char, buffer.length === 0, onEmptySubmit !== undefined);
+                if (action.kind === "cancel") {
+                    onEnd();
+                    return;
+                }
+                if (action.kind === "submit") {
+                    cleanup();
+                    resolve(buffer);
+                    return;
+                }
+                buffer = applyEdit(action, char, buffer, echo, onEmptySubmit);
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+        stdin.once("error", onEnd);
+    });
+}
+/** Reads a secret. Nothing is echoed, not even a masking character. */
+export function promptForSecret(message, style = PLAIN_STYLE) {
+    return read(message, false, undefined, style);
+}
+/** Reads a visible line, for non-secret answers such as a pasted auth code. */
+export function promptForLine(message, onEmptySubmit, style = PLAIN_STYLE) {
+    return read(message, true, onEmptySubmit, style);
+}
+/**
+ * Reads a choice with the arrow keys and returns the chosen option's id. The
+ * option block is redrawn in place. Enter commits the highlighted row, so a
+ * value that is not an option can never be returned.
+ */
+export function promptForSelect(message, choices, style = PLAIN_STYLE) {
+    const stdin = stdinOf();
+    if (stdin.isTTY !== true)
+        return Promise.reject(new PromptCancelledError());
+    // Never silently pick for the user: an empty list is a caller bug.
+    if (choices.length === 0)
+        return Promise.reject(new PromptCancelledError());
+    _terminalPromptDeps.write(`${style.accent("?")} ${message}\n`);
+    return new Promise((resolve, reject) => {
+        let index = 0;
+        let settled = false;
+        let drawn = false;
+        const render = () => {
+            if (drawn)
+                _terminalPromptDeps.write(`\u001b[${choices.length}A`);
+            drawn = true;
+            for (const [i, choice] of choices.entries()) {
+                const active = i === index;
+                const marker = active ? style.accent(">") : " ";
+                const label = active ? style.accent(choice.label) : choice.label;
+                _terminalPromptDeps.write(`\r\u001b[2K${marker} ${label}\n`);
+            }
+        };
+        const cleanup = () => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            stdin.removeListener("error", onEnd);
+            stdin.setRawMode(false);
+            stdin.pause();
+        };
+        const onEnd = () => {
+            cleanup();
+            reject(new PromptCancelledError());
+        };
+        const onData = (chunk) => {
+            // Whole-chunk matching: an arrow key is a three-byte escape sequence.
+            if (chunk.includes(ETX) || chunk.includes(EOT)) {
+                onEnd();
+                return;
+            }
+            if (chunk.includes(ARROW_UP)) {
+                index = (index - 1 + choices.length) % choices.length;
+                render();
+                return;
+            }
+            if (chunk.includes(ARROW_DOWN)) {
+                index = (index + 1) % choices.length;
+                render();
+                return;
+            }
+            if (chunk.includes(CR) || chunk.includes(LF)) {
+                const chosen = choices[index];
+                cleanup();
+                // biome-ignore lint/style/noNonNullAssertion: index is held in range by the modulo above.
+                resolve(chosen.id);
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+        stdin.once("error", onEnd);
+        render();
+    });
+}

package/dist/tools/denial-redirect.js

@@ -19,7 +19,7 @@
  * `grep -n x y` did not. 20 of 34 denials in the two runs after #1971 carried
  * no redirect (nax#1999). A single table cannot drift against itself.
  */
-const GIT_READ_VERBS = new Set(["diff", "log", "show", "status", "blame"]);
+const GIT_READ_VERBS = new Set(["diff", "log", "show", "status", "blame", "rev-parse"]);
 /**
  * Git verbs that stage or record a commit. Deliberately NOT every write verb:
  * `git restore` reverts, which `GitCommit` does not do, and naming it would be

package/dist/tools/git.js

@@ -24,7 +24,7 @@ import { cutToByteCap, READ_CEILING } from "./truncate.js";
  * Note what bounds these: the argv shape below, not the verb list. A read-only
  * verb still spans the whole repository unless its scope is stated.
  */
-export const GIT_READ_VERBS = ["diff", "log", "show", "status", "blame"];
+export const GIT_READ_VERBS = ["diff", "log", "show", "status", "blame", "rev-parse"];
 /**
  * Typed flag fields, and the verbs each one is valid on.
  *
@@ -164,6 +164,16 @@ export { GIT_ESCAPE_FLAGS } from "#src/tools/git-flags/index";
 function looksLikeFlag(value) {
     return value.startsWith("-");
 }
+function buildGitRootArgv(input) {
+    const extraFields = Object.keys(input).filter((field) => field !== "subcommand");
+    if (extraFields.length > 0) {
+        return { error: `rev-parse accepts no additional fields (received: ${extraFields.join(", ")})` };
+    }
+    return ["rev-parse", "--show-toplevel"];
+}
+function defaultGitExcludes(subcommand, excludes) {
+    return subcommand === "blame" ? [] : excludes;
+}
 /**
  * `defaultExcludes`: pathspecs appended to an unscoped call (the host's own
  * state, nax#2007); none by default.
@@ -173,6 +183,9 @@ export function buildGitArgv(input, defaultExcludes = []) {
     if (typeof subcommand !== "string" || !GIT_READ_VERBS.includes(subcommand)) {
         return { error: `subcommand must be one of: ${GIT_READ_VERBS.join(", ")}` };
     }
+    if (subcommand === "rev-parse") {
+        return buildGitRootArgv(input);
+    }
     const refs = Array.isArray(input.refs) ? input.refs : [];
     const paths = Array.isArray(input.paths) ? input.paths : [];
     // No `--relative` is injected. Since the single-frame redesign the permitted
@@ -281,8 +294,7 @@ export function buildGitArgv(input, defaultExcludes = []) {
         // requested path would be a worse failure than the one being fixed.
         // `blame` is exempt because git rejects exclude pathspecs on it and exits
         // 128; do not "unify" it back in.
-        if (subcommand !== "blame")
-            argv.push(...defaultExcludes);
+        argv.push(...defaultGitExcludes(subcommand, defaultExcludes));
         return argv;
     }
     for (const path of paths) {
@@ -296,11 +308,15 @@ export function buildGitArgv(input, defaultExcludes = []) {
 }
 export const gitTool = {
     name: "Git",
-    description: "Run a read-only git command (diff, log, show, status, blame) in the repository. Supply refs and pathspecs as arrays, not as a command line. Command-line flags are not accepted in any field; use the nameOnly, diffFilter, oneline, fullMessage and maxCount fields instead.",
+    description: "Run a read-only git command (diff, log, show, status, blame, rev-parse) in the repository. rev-parse is fixed to `git rev-parse --show-toplevel` and accepts no other fields. Supply refs and pathspecs as arrays, not as a command line. Command-line flags are not accepted in any field; use the nameOnly, diffFilter, oneline, fullMessage and maxCount fields instead.",
     inputSchema: {
         type: "object",
         properties: {
-            subcommand: { type: "string", enum: [...GIT_READ_VERBS], description: "Read-only git subcommand" },
+            subcommand: {
+                type: "string",
+                enum: [...GIT_READ_VERBS],
+                description: "Read-only git subcommand; rev-parse is fixed to --show-toplevel",
+            },
             refs: { type: "array", items: { type: "string" }, description: "Refs, e.g. ['HEAD~1','HEAD']" },
             paths: { type: "array", items: { type: "string" }, description: "Pathspecs, relative to the permitted root" },
             nameOnly: {

package/dist/tools/instruction-access.d.ts

@@ -0,0 +1,13 @@
+/** Transport-neutral scope hook, invoked only after coding-tool authorization. */
+import { stat } from "node:fs/promises";
+import type { ProtectedPathsPolicy } from "./protected-paths.ts";
+import type { ToolPolicy } from "./types.ts";
+type InstructionAccess = (paths: readonly string[], canRead: (path: string) => boolean, protectedPaths?: ProtectedPathsPolicy) => Promise<string | undefined>;
+export declare const _instructionAccessDeps: {
+    stat: typeof stat;
+};
+export declare function withInstructionAccess<T>(observer: InstructionAccess, run: () => Promise<T>): Promise<T>;
+export declare function discoverAuthorizedInstructions(name: string, paths: readonly string[], policy: ToolPolicy, protectedPaths?: ProtectedPathsPolicy): Promise<string | undefined>;
+/** A mutation must be proposed again after the model has received new guidance. */
+export declare function enforceInstructionAccess(name: string, paths: readonly string[], policy: ToolPolicy, protectedPaths?: ProtectedPathsPolicy): Promise<void>;
+export {};

package/dist/tools/instruction-access.js

@@ -0,0 +1,30 @@
+/** Transport-neutral scope hook, invoked only after coding-tool authorization. */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { NaxError } from "#src/infra/nax-error";
+import { credentialReadRefusal } from "./credential-read-deny.js";
+export const _instructionAccessDeps = { stat };
+const access = new AsyncLocalStorage();
+export function withInstructionAccess(observer, run) {
+    return access.run(observer, run);
+}
+export async function discoverAuthorizedInstructions(name, paths, policy, protectedPaths) {
+    if (!["Read", "Write", "Edit"].includes(name))
+        return;
+    const observer = access.getStore();
+    if (observer === undefined || paths.some((path) => credentialReadRefusal(protectedPaths, path) !== undefined))
+        return;
+    const targets = name === "Write" ? paths.map((path) => dirname(path)) : paths;
+    const present = await Promise.all(targets.map((path) => _instructionAccessDeps.stat(path).then((metadata) => (name === "Write" ? metadata.isDirectory() : metadata.isFile()), () => false)));
+    if (present.some((found) => !found))
+        return;
+    const guidance = await observer(paths, (path) => policy.check("Read", { pathFields: ["path"] }, { path }).allowed, protectedPaths);
+    return name === "Read" ? undefined : guidance || undefined;
+}
+/** A mutation must be proposed again after the model has received new guidance. */
+export async function enforceInstructionAccess(name, paths, policy, protectedPaths) {
+    const guidance = await discoverAuthorizedInstructions(name, paths, policy, protectedPaths);
+    if (guidance !== undefined)
+        throw new NaxError(guidance, "REPOSITORY_INSTRUCTIONS_DISCOVERED", { stage: "coding-tool" });
+}

package/dist/tools/runtime.js

@@ -17,6 +17,7 @@ import { gitTool } from "./git.js";
 import { gitCommitTool } from "./git-commit.js";
 import { globTool } from "./glob.js";
 import { grepTool } from "./grep.js";
+import { enforceInstructionAccess } from "./instruction-access.js";
 import { readTool } from "./read.js";
 import { getCodingTool, registerBuiltinTool } from "./registry.js";
 import { requestCapabilityTool } from "./request-capability.js";
@@ -224,7 +225,10 @@ export function createCodingToolRuntime(opts) {
                 log(tool, outcome, resultBytes, input, context, breach, reason, routineErrors, audit, resultBytesPreTruncation);
                 tap?.settle(outcome, audit?.approval?.decidedBy, audit?.executed === undefined
                     ? undefined
-                    : { executed: audit.executed, ...(audit.cwd !== undefined ? { cwd: audit.cwd } : {}) });
+                    : {
+                        executed: audit.executed,
+                        ...(audit.cwd !== undefined ? { cwd: audit.cwd } : {}),
+                    });
             };
             /**
              * Executes a permitted call and records its outcome. Shared by the
@@ -249,6 +253,7 @@ export function createCodingToolRuntime(opts) {
                 // scope.
                 const callSignal = context?.signal ?? signal;
                 try {
+                    await enforceInstructionAccess(target.name, resolvedPaths, opts.policy, opts.protectedPaths);
                     const result = await target.run(callInput, {
                         root: opts.policy.root,
                         resolvedPaths,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.3.1",
+  "version": "0.85.0",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -29,6 +29,10 @@
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
     }
   },
   "imports": {
@@ -42,7 +46,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
-    "@nathapp/nax-ai": "0.1.16",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@nathapp/nax-ai": "0.85.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {