@nathapp/nax-agent 0.2.0 → 0.3.0

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

@@ -260,6 +260,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

@@ -53,6 +53,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.2.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",