@nathapp/nax-agent 0.3.0 → 0.84.0

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/index.d.ts

@@ -28,7 +28,7 @@ export type { CodingToolOutcome, CodingToolRuntime, ToolCallContext } from "./ru
 export { _codingToolDeps, _resetBuiltinsForTest, createCodingToolRuntime, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, registerBuiltinCodingTools, } from "./runtime.ts";
 export { SCRATCHPAD_DIR, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.ts";
 export { _spillDeps, applyModelTruncationPolicy, type ModelTruncationOptions, SPILL_DIR, type SpillRequest, spillRelativePath, writeSpill, } from "./spill.ts";
-export type { RegisteredSink, ToolAuditSink, ToolCallRecord } from "./tool-audit.ts";
+export type { RegisteredSink, ToolAuditHeader, ToolAuditSink, ToolCallRecord } from "./tool-audit.ts";
 export { createNoOpToolAuditSink, createToolAuditSink, flushOpenToolAuditSinks, registerToolAuditSink, unregisterToolAuditSink, } from "./tool-audit.ts";
 export { cutBufferToByteCap, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, READ_CEILING, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, } from "./truncate.ts";
 export type { CodingToolName, PolicyVerdict, ToolGrant, ToolPolicy, ToolScope } from "./types.ts";

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.0",
+  "version": "0.84.0",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
-    "@nathapp/nax-ai": "0.1.16",
+    "@nathapp/nax-ai": "0.84.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {