@nathapp/nax-agent 0.2.0 → 0.3.1

package/dist/session/session-ask-port.d.ts

@@ -0,0 +1,12 @@
+import type { SessionEventBody } from "./agent-session-types.ts";
+import type { PendingAskTable } from "./pending-asks.ts";
+import type { SessionAskPort } from "./session-backend.ts";
+export interface SessionAskPortDeps {
+    readonly table: PendingAskTable;
+    readonly emit: (body: SessionEventBody) => void;
+    readonly turn: () => {
+        readonly turnId: string;
+        readonly signal: AbortSignal;
+    } | undefined;
+}
+export declare function createSessionAskPort(deps: SessionAskPortDeps): SessionAskPort;

package/dist/session/session-ask-port.js

@@ -0,0 +1,64 @@
+/**
+ * The session's ask port (S4 spec 5.1): approvals and questions any backend
+ * raises, on top of the pending-ask table. A request needs a running turn: its
+ * events go on that turn's stream and its turn signal settles it. Profile
+ * auto-decisions and informational questions are emitted, never queued.
+ */
+import { NaxError } from "#src/infra/nax-error";
+import { _agentSessionDeps } from "./agent-session-deps.js";
+import { askPerson } from "./session-ask-link.js";
+const ALREADY_ABORTED = AbortSignal.abort();
+function noTurn() {
+    return new NaxError("No turn is running; an approval needs a running turn", "AGENT_SESSION_TURN_FAILED", {
+        stage: "agent-session",
+        detail: "no-turn",
+    });
+}
+export function createSessionAskPort(deps) {
+    const askDeps = { table: deps.table, emit: deps.emit };
+    const now = () => new Date(_agentSessionDeps.now()).toISOString();
+    return {
+        async requestApproval(req) {
+            const turn = deps.turn();
+            if (turn === undefined)
+                throw noTurn();
+            const signal = req.signal === undefined ? turn.signal : AbortSignal.any([turn.signal, req.signal]);
+            const { signal: _ignored, ...ask } = req;
+            return askPerson(askDeps, ask, signal);
+        },
+        // Informational only. The requestId is emitted but never put in the pending
+        // table, so session.answer() on it is not answerable, and expiresAt is the
+        // emit time (the auto-decision is already resolved), not a real deadline.
+        recordAutoDecision(req, decision) {
+            if (deps.turn() === undefined)
+                return;
+            const requestId = _agentSessionDeps.randomUUID();
+            deps.emit({
+                type: "approval_requested",
+                requestId,
+                ...(req.callId !== undefined ? { callId: req.callId } : {}),
+                tool: req.tool,
+                summary: req.summary,
+                reason: req.reason,
+                expiresAt: now(),
+            });
+            deps.emit({ type: "approval_resolved", requestId, decision, decidedBy: "profile" });
+        },
+        async askQuestion(text, opts) {
+            const turn = deps.turn();
+            if (turn === undefined)
+                return null;
+            const signal = opts?.signal === undefined ? turn.signal : AbortSignal.any([turn.signal, opts.signal]);
+            const { requestId, expiresAt, settled } = deps.table.issue("question", signal);
+            deps.emit({ type: "question", requestId, text, expiresAt });
+            const settlement = await settled;
+            return settlement.by === "human" && "text" in settlement.reply ? settlement.reply.text : null;
+        },
+        noteQuestion(text) {
+            if (deps.turn() === undefined)
+                return;
+            const { requestId } = deps.table.issue("question", ALREADY_ABORTED);
+            deps.emit({ type: "question", requestId, text, expiresAt: now() });
+        },
+    };
+}

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

@@ -0,0 +1,79 @@
+/**
+ * The backend seam (S4 spec §5.1). A `SessionBackend` opens an
+ * `OpenedBackend`: the S1 `AgentSessionAdapter` plus the per-turn options it
+ * contributes, the ask port it reaches the facade through, and the info the
+ * facade records. The native backend and the out-of-tree ACP backend both
+ * satisfy this contract; nothing here is backend-specific.
+ */
+import type { TranscriptDoc, TranscriptStore } from "#src/native/session/transcript-types";
+import type { AgentSessionProfile, ApprovalDecidedBy, EmbedderTool } from "./agent-session-types.ts";
+import type { AgentSessionAdapter, SendTurnOpts, SessionHandle } from "./session-types.ts";
+export interface BackendInfo {
+    /** "native" or "acp:<agent>"; recorded in the transcript document. */
+    readonly kind: string;
+    /** Read-only, JSON-safe capability summary. `{}` for native. */
+    readonly capabilities: Readonly<Record<string, unknown>>;
+}
+export interface ApprovalRequest {
+    readonly callId?: string;
+    readonly tool: string;
+    readonly summary: string;
+    readonly command?: string;
+    readonly reason: string;
+    /** Extra abort source, combined with the turn signal (for example a tool-level abort). */
+    readonly signal?: AbortSignal;
+}
+export interface SessionAskPort {
+    /** Throws NaxError AGENT_SESSION_TURN_FAILED (context.detail "no-turn") when no turn is running. */
+    requestApproval(req: ApprovalRequest): Promise<{
+        readonly decision: "allow" | "deny";
+        readonly decidedBy: ApprovalDecidedBy;
+    }>;
+    /** Emits approval_requested then approval_resolved (decidedBy "profile"). No-op when no turn is running. */
+    recordAutoDecision(req: Omit<ApprovalRequest, "command" | "signal">, decision: "allow" | "deny"): void;
+    /**
+     * The person's text, or null on deadline, cancel or no running turn. `opts.signal`
+     * is an extra abort source combined with the turn signal, as for approvals (for
+     * example a backend's per-request scope that ends before the turn does).
+     */
+    askQuestion(text: string, opts?: {
+        readonly signal?: AbortSignal;
+    }): Promise<string | null>;
+    /** An informational question event; answer() on its id returns "cancelled". No-op when no turn is running. */
+    noteQuestion(text: string): void;
+}
+/** What a backend contributes to every sendTurn. */
+export type TurnContribution = Pick<SendTurnOpts, "interactionHandler"> & Partial<Pick<SendTurnOpts, "codingTools" | "loopHandlers" | "loopHandlerContext">>;
+export interface BackendOpenContext {
+    readonly sessionId: string;
+    /** The facade's resolved root: the workdir, or a private scratch root for profile "none". */
+    readonly workdir: string;
+    readonly profile: AgentSessionProfile;
+    readonly instructions: string | undefined;
+    readonly tools: readonly EmbedderTool[];
+    readonly transcriptStore: TranscriptStore;
+    /** The stored document on resume (already presence-, schema- and kind-checked by the facade). */
+    readonly resume: {
+        readonly doc: TranscriptDoc;
+    } | undefined;
+    readonly asks: SessionAskPort;
+    /** Re-read at use time: the running turn's signal, or a never-aborting one between turns. */
+    readonly turnSignal: () => AbortSignal;
+    readonly currentTurnId: () => string | undefined;
+    readonly turnTimeoutSeconds: number;
+    readonly metadata: Readonly<Record<string, string>>;
+    /** Aborted when the session starts closing. */
+    readonly openSignal: AbortSignal;
+}
+export interface OpenedBackend {
+    readonly adapter: AgentSessionAdapter;
+    readonly handle: SessionHandle;
+    readonly info: BackendInfo;
+    turnOpts(): TurnContribution;
+    /** Releases backend resources after adapter.closeSession. Idempotent. */
+    close(): Promise<void>;
+}
+export interface SessionBackend {
+    readonly kind: string;
+    open(ctx: BackendOpenContext): Promise<OpenedBackend>;
+}

package/dist/session/session-backend.js

@@ -0,0 +1 @@
+export {};

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

@@ -2,14 +2,14 @@ import type { CodingTool } from "#src/tools/registry";
 import type { CodingToolRuntime } from "#src/tools/runtime";
 import type { EmbedderTool } from "./agent-session-types.ts";
 import type { InteractionHandler } from "./interaction-handler.ts";
-import { type SessionAskDeps } from "./session-ask-link.ts";
+import type { SessionAskPort } from "./session-backend.ts";
 /** Byte cap on an embedder approval's default summary. */
 export declare const EMBEDDER_SUMMARY_BYTES = 1024;
 export interface SessionInteractionDeps {
     readonly sessionId: string;
     readonly runtime: CodingToolRuntime;
     readonly embedderTools: ReadonlyMap<string, EmbedderTool>;
-    readonly asks: SessionAskDeps;
+    readonly asks: SessionAskPort;
     /** The running turn's signal (a never-aborting one between turns). */
     readonly turnSignal: () => AbortSignal;
     readonly setCurrentCallId: (callId: string | undefined) => void;

package/dist/session/session-interaction.js

@@ -13,7 +13,6 @@ import { NaxError } from "#src/infra/nax-error";
 import { capStrings, redactSecrets } from "#src/internal/redact";
 import { askDenyReason } from "#src/tools/ask-request";
 import { cutToByteCap } from "#src/tools/truncate";
-import { askPerson } from "./session-ask-link.js";
 /** Byte cap on an embedder approval's default summary. */
 export const EMBEDDER_SUMMARY_BYTES = 1024;
 /**
@@ -108,7 +107,7 @@ async function runEmbedderTool(deps, tool, request) {
             reason: `"${tool.name}" asks before every run`,
             callId: toolCallId,
         };
-        const outcome = await askPerson(deps.asks, ask, signal);
+        const outcome = await deps.asks.requestApproval({ ...ask, signal });
         if (outcome.decision !== "allow") {
             const reason = askDenyReason(outcome.decidedBy);
             return { answer: `Denied: ${reason}`, denied: { reason, breach: false } };
@@ -145,10 +144,8 @@ async function runCodingTool(deps, request) {
     }
 }
 async function answerQuestion(deps, text) {
-    const { requestId, expiresAt, settled } = deps.asks.table.issue("question", deps.turnSignal());
-    deps.asks.emit({ type: "question", requestId, text, expiresAt });
-    const settlement = await settled;
-    return settlement.by === "human" && "text" in settlement.reply ? { answer: settlement.reply.text } : null;
+    const answer = await deps.asks.askQuestion(text);
+    return answer === null ? null : { answer };
 }
 export function createSessionInteractionHandler(deps) {
     return {

package/dist/session/session-tool-support.d.ts

@@ -11,11 +11,11 @@ export declare const SESSION_STAGE = "session";
 export declare function declaredToolsFor(profile: AgentSessionProfile, protectedPaths: ProtectedPathsPolicy): readonly CodingToolName[];
 export declare function grantsFor(declared: readonly CodingToolName[]): readonly ToolGrant[];
 /**
- * Under "gated", every Bash command is put to the person: an unconditional ask
- * rule on top of the unconditional grant (ask rules are evaluated after
- * grants). "raw" and "escalate" add none.
+ * Ask rules evaluate after grants. Under "gated" every Bash command is put to
+ * the person. Under the "ask" profile every mutating path tool is too, and the
+ * profile forces "gated", so Bash always asks there.
  */
-export declare function askRulesFor(declared: readonly CodingToolName[], bashApproval: BashApprovalMode): readonly ToolGrant[];
+export declare function askRulesFor(declared: readonly CodingToolName[], bashApproval: BashApprovalMode, profile: AgentSessionProfile): readonly ToolGrant[];
 /**
  * The embedder default (spec 6.2). A session with its own credentials source
  * (memory or exec) has no credentials directory on disk; one that falls back
@@ -29,7 +29,7 @@ export interface SessionLauncherArgs {
     readonly bashApproval: BashApprovalMode;
     readonly allowUnsandboxed: boolean;
 }
-/** The sandbox floor (spec 6.3): "full" needs a usable sandbox unless gated + allowUnsandboxed. */
+/** The sandbox floor (spec 6.3): "ask" and "full" need a usable sandbox unless gated + allowUnsandboxed. */
 export declare function resolveSessionLauncher(args: SessionLauncherArgs): Promise<CommandLauncher | undefined>;
 export interface SessionToolSupportArgs {
     readonly profile: AgentSessionProfile;

package/dist/session/session-tool-support.js

@@ -15,6 +15,7 @@ import { AgentSessionError } from "./agent-session-errors.js";
 export const SESSION_STAGE = "session";
 const READ_TOOLS = ["Read", "Glob", "Grep", "Git"];
 const WRITE_TOOLS = ["Write", "Edit", "Delete", "Bash"];
+const ASK_PROFILE_TOOLS = ["Write", "Edit", "Delete", "GitCommit"];
 export function declaredToolsFor(profile, protectedPaths) {
     if (profile === "none")
         return [...UNIVERSAL_CODING_TOOLS];
@@ -28,12 +29,14 @@ export function grantsFor(declared) {
     return declared.map((tool) => ({ tool, patterns: ["*"] }));
 }
 /**
- * Under "gated", every Bash command is put to the person: an unconditional ask
- * rule on top of the unconditional grant (ask rules are evaluated after
- * grants). "raw" and "escalate" add none.
+ * Ask rules evaluate after grants. Under "gated" every Bash command is put to
+ * the person. Under the "ask" profile every mutating path tool is too, and the
+ * profile forces "gated", so Bash always asks there.
  */
-export function askRulesFor(declared, bashApproval) {
-    return bashApproval === "gated" && declared.includes("Bash") ? [{ tool: "Bash", patterns: ["*"] }] : [];
+export function askRulesFor(declared, bashApproval, profile) {
+    const bash = bashApproval === "gated" && declared.includes("Bash") ? ["Bash"] : [];
+    const mutating = profile === "ask" ? ASK_PROFILE_TOOLS.filter((tool) => declared.includes(tool)) : [];
+    return [...mutating, ...bash].map((tool) => ({ tool, patterns: ["*"] }));
 }
 /** The configured credentials directory; undefined when configureCredentials was never called. */
 function configuredCredentialDir() {
@@ -54,9 +57,9 @@ export function defaultProtectedPaths(ownCredentials) {
     const credentialDir = ownCredentials ? undefined : configuredCredentialDir();
     return credentialDir === undefined ? base : { ...base, credentialDir };
 }
-/** The sandbox floor (spec 6.3): "full" needs a usable sandbox unless gated + allowUnsandboxed. */
+/** The sandbox floor (spec 6.3): "ask" and "full" need a usable sandbox unless gated + allowUnsandboxed. */
 export async function resolveSessionLauncher(args) {
-    if (args.profile !== "full")
+    if (args.profile !== "full" && args.profile !== "ask")
         return undefined;
     const launcher = await resolveSessionSandbox({
         config: DEFAULT_SANDBOX_CONFIG,
@@ -70,12 +73,12 @@ export async function resolveSessionLauncher(args) {
     if (args.bashApproval === "gated" && args.allowUnsandboxed)
         return undefined;
     const reason = launcher.state.kind === "unavailable" ? launcher.state.reason : "the sandbox is disabled";
-    throw new AgentSessionError(`Profile "full" needs a usable sandbox (${reason}). Pass bashApproval "gated" with allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
+    throw new AgentSessionError(`Profile "${args.profile}" needs a usable sandbox (${reason}). Pass bashApproval "gated" with allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
 }
 export function buildSessionToolSupport(args) {
     const declared = declaredToolsFor(args.profile, args.protectedPaths);
     const grants = grantsFor(declared);
-    const askRules = askRulesFor(declared, args.bashApproval);
+    const askRules = askRulesFor(declared, args.bashApproval, args.profile);
     const support = buildCodingToolSupport({
         root: args.root,
         commandCwd: args.root,

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

@@ -136,6 +136,16 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * scratch dir reaches the adapter otherwise. ACP ignores it.
      */
     transcriptDir?: string;
+    /**
+     * S4b spec 7.4: where an S1 adapter that writes its own tool-audit ledger (nax's
+     * ACP adapter) writes it, and the run-scoped header stamped on it. nax fills it
+     * from the same resolution the native coding tools use. nax-agent itself does not
+     * read it; native takes its sink from coding-tool support.
+     */
+    toolAudit?: {
+        readonly dir: string;
+        readonly header: import("#src/tools/tool-audit").ToolAuditHeader;
+    };
     /**
      * Native: identity that owns this session's transcript — the op invocation's
      * `scopeId ?? callId`. Stable across the retries and hops of one invocation,
@@ -260,6 +270,8 @@ export interface TurnResult {
     estimatedCostUsd: number;
     /** Exact cost reported by wire protocol (when available). */
     exactCostUsd?: number;
+    /** Absent means computed. */
+    costSource?: import("./agent-session-types.ts").CostSource;
     /** Number of session.prompt() calls made. */
     internalRoundTrips: number;
     /**

package/dist/session/turn-event.d.ts

@@ -43,6 +43,13 @@ export type TurnEvent = {
     readonly callId: string;
     readonly isError: boolean;
     readonly preview: string;
+    /** UTF-8 byte length of the full result before the preview cap (S4b spec 7.4). Absent when unknown. */
+    readonly resultBytes?: number;
+}
+/** A running tool's liveness beat (an ACP heartbeat); carries no content. Not a session event. */
+ | {
+    readonly type: "tool_progress";
+    readonly callId: string;
 } | {
     readonly type: "usage";
     readonly round: number;
@@ -53,6 +60,11 @@ export type TurnEvent = {
     /** Absent when the call reported no cache data -- never coerced to 0. */
     readonly cacheWrite?: number;
     readonly costUsd: number;
+    /**
+     * Absent means computed from the catalog (the native backend). `unpriced`
+     * rows carry `costUsd: 0` and must not be summed as a real cost.
+     */
+    readonly costSource?: import("./agent-session-types.ts").CostSource;
 } | {
     readonly type: "compaction";
     readonly reason: "proactive" | "overflow";

package/dist/session/turn-spend.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The spend a failed turn had already incurred, attached to the error it throws
+ * (#2367). Keyed on the error's identity, so the error itself is rethrown
+ * unchanged and keeps its own code. The facade's turn_end reads it on every
+ * error path; the native loop writes it through recordNativeTurnFailureUsage
+ * (nax#1840), an ACP backend through attachTurnSpend.
+ */
+import type { TokenUsage } from "#src/cost/standard-types";
+import type { CostSource } from "./agent-session-types.ts";
+export interface FailedTurnSpend {
+    readonly tokenUsage: TokenUsage;
+    readonly costUsd: number;
+    readonly costSource?: CostSource;
+}
+/** Attaches the spend a failed turn had already incurred to the error it throws. */
+export declare function attachTurnSpend(err: object, spend: FailedTurnSpend): void;
+/** The spend attached to `err`, if any. */
+export declare function readTurnSpend(err: unknown): FailedTurnSpend | undefined;

package/dist/session/turn-spend.js

@@ -0,0 +1,9 @@
+const spendByError = new WeakMap();
+/** Attaches the spend a failed turn had already incurred to the error it throws. */
+export function attachTurnSpend(err, spend) {
+    spendByError.set(err, Object.freeze({ ...spend }));
+}
+/** The spend attached to `err`, if any. */
+export function readTurnSpend(err) {
+    return typeof err === "object" && err !== null ? spendByError.get(err) : undefined;
+}

package/dist/tools/ask-request.js

@@ -6,7 +6,7 @@
  * `maskForPrompt` before they leave the process; a secret that cannot be
  * shown safely withholds the arguments entirely (`unshowable`, review #9).
  */
-import { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNSHOWABLE_REASON, maskForPrompt, } from "#src/permissions/index";
+import { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNSHOWABLE_REASON, maskForPrompt, } from "#src/permissions/index";
 /** Ceiling for the one-line call description an AskResolver receives. */
 export const MAX_ASK_SUMMARY_CHARS = 200;
 /**
@@ -53,5 +53,7 @@ export function askDenyReason(decidedBy) {
         return ASK_CANCELLED_REASON;
     if (decidedBy === "unshowable")
         return ASK_UNSHOWABLE_REASON;
+    if (decidedBy === "profile")
+        return ASK_PROFILE_REASON;
     return ASK_NO_CHANNEL_REASON;
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",