@nathapp/nax-agent 0.2.0 → 0.3.0

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

@@ -1,19 +1,19 @@
 /**
  * Public types of the agent session facade (S3 spec section 4). The facade
  * drives the S1 AgentSessionAdapter; nothing here is backend-specific, so the
- * acpx backend (S4) reuses these types unchanged.
+ * @nathapp/nax-agent-acp backend (S4) reuses these types unchanged.
  */
 import type { CommandInterceptor } from "#src/command-interceptor/index";
-import type { BashApprovalMode } from "#src/config/bash-approval";
 import type { TokenUsage } from "#src/cost/standard-types";
-import type { NativeCatalogOverrides } from "#src/native/client";
-import type { CredentialSource } from "#src/native/credentials/session-source";
-import type { LoopHandlerSet } from "#src/native/session/loop-events/types";
 import type { TranscriptStore } from "#src/native/session/transcript-types";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
+import type { BackendInfo, SessionBackend } from "./session-backend.ts";
 import type { JSONSchema } from "./tool-descriptor.ts";
-/** What the session's agent may touch. Capability statements, not tool lists (spec 4.5). */
-export type AgentSessionProfile = "none" | "read" | "full";
+/**
+ * What the session's agent may touch. Capability statements, not tool lists
+ * (spec 4.5). `ask`: every mutating action is approved through `answer()`.
+ */
+export type AgentSessionProfile = "none" | "read" | "ask" | "full";
 export interface EmbedderToolContext {
     readonly sessionId: string;
     /** The provider's tool-call id: the same id as the `tool_call` / `tool_result` events. */
@@ -45,11 +45,10 @@ export interface AgentSessionHostPorts {
     readonly commandInterceptor?: CommandInterceptor;
 }
 export interface CreateAgentSessionOptions {
-    readonly backend: "native";
+    /** The driver: `nativeBackend({ model })`, or an ACP backend. Native-only options live on the backend. */
+    readonly backend: SessionBackend;
     /** The store key. Generated when absent. Letters, digits, `.`, `_`, `-`; starts with a letter or digit; at most 128 characters. */
     readonly sessionId?: string;
-    /** `"provider/model"`, optionally with an `[effort]` suffix. */
-    readonly model: string;
     readonly profile: AgentSessionProfile;
     /** An absolute directory. Required for `read` and `full`; `none` gets a private temporary root. */
     readonly workdir?: string;
@@ -65,22 +64,19 @@ export interface CreateAgentSessionOptions {
     readonly transcriptStore: TranscriptStore;
     /** How long an approval or question waits. Default 600000; 30000..3600000. */
     readonly approvalTimeoutMs?: number;
-    /** `full` only. Default `"gated"`. */
-    readonly bashApproval?: BashApprovalMode;
-    /** `full` only, and only with `bashApproval: "gated"`: run without a sandbox when none is usable. */
-    readonly allowUnsandboxed?: boolean;
-    /** Falls back to the `configureCredentials` slot when absent. */
-    readonly credentials?: CredentialSource;
-    readonly catalogOverrides?: NativeCatalogOverrides;
-    readonly loopHandlers?: LoopHandlerSet;
-    readonly hostPorts?: AgentSessionHostPorts;
-    /** Copied onto every event. */
-    readonly metadata?: Readonly<Record<string, string>>;
     /** Per-turn wall clock. Default 3600; 1..86400. */
     readonly turnTimeoutSeconds?: number;
+    /** Copied onto every event. */
+    readonly metadata?: Readonly<Record<string, string>>;
 }
 export type TurnEndStatus = "completed" | "cancelled" | "timed_out" | "interrupted" | "errored";
-export type ApprovalDecidedBy = "human" | "timeout" | "cancelled" | "unavailable" | "unshowable";
+export type ApprovalDecidedBy = "human" | "timeout" | "cancelled" | "unavailable" | "unshowable" | "profile";
+/**
+ * How a turn's `costUsd` was obtained (S4 spec 5.5). Absent means `computed`
+ * from the catalog (the native backend). `unpriced` rows carry `costUsd: 0`
+ * and must not be summed as a real cost.
+ */
+export type CostSource = "computed" | "reported" | "unpriced";
 export interface SessionEventBase {
     readonly sessionId: string;
     readonly turnId: string;
@@ -139,6 +135,7 @@ export type SessionEventBody = {
     readonly cacheRead?: number;
     readonly cacheWrite?: number;
     readonly costUsd: number;
+    readonly costSource?: CostSource;
 } | {
     readonly type: "compaction";
     readonly reason: "proactive" | "overflow";
@@ -149,6 +146,7 @@ export type SessionEventBody = {
     readonly output: string;
     readonly usage: TokenUsage;
     readonly costUsd: number;
+    readonly costSource?: CostSource;
     readonly error?: {
         readonly code: string;
         readonly message: string;
@@ -167,6 +165,8 @@ export type AnswerReply = {
 export type AnswerStatus = "accepted" | "expired" | "cancelled" | "unknown";
 export interface AgentSession {
     readonly id: string;
+    /** The backend that opened this session (`kind` and its capability summary). */
+    readonly backend: BackendInfo;
     /** Set after each `turn_end`; on resume, `interrupted` when a dead process left a turn running. Undefined otherwise. */
     readonly lastTurn: {
         readonly turnId: string;

package/dist/session/agent-session.js

@@ -1,32 +1,13 @@
-/**
- * createAgentSession: the conversational session facade (S3 spec 4, 5.1).
- * One NativeSessionAdapter per session. The facade fills the S1
- * OpenSessionOpts itself and talks to the backend through the S1 contract
- * only (openSession, sendTurn, closeSession), so the acpx backend (S4) slots
- * in behind the same API. resumeAgentSession reopens a stored session
- * (spec 4.2, 6.4).
- */
-import { DEFAULT_SPIN_BREAKER_SETTINGS } from "#src/infra/spin-breaker/index";
-import { NATIVE_AGENT } from "#src/native/models";
-import { NativeSessionAdapter } from "#src/native/session-adapter";
 import { _agentSessionDeps } from "./agent-session-deps.js";
 import { AgentSessionError } from "./agent-session-errors.js";
 import { resolveAgentSessionOptions } from "./agent-session-options.js";
-import { interruptedTurnOf, loadResumable, resumeInput } from "./agent-session-resume.js";
+import { checkBackendKind, interruptedTurnOf, loadResumable, resumeInput } from "./agent-session-resume.js";
 import { claimTurn } from "./agent-session-turn.js";
 import { createPendingAskTable } from "./pending-asks.js";
-import { createSessionAskLink, createSessionAskResolver } from "./session-ask-link.js";
-import { createSessionInteractionHandler, embedderToolDescriptor } from "./session-interaction.js";
-import { buildSessionToolSupport, defaultProtectedPaths, resolveSessionLauncher } from "./session-tool-support.js";
+import { createSessionAskPort } from "./session-ask-port.js";
 /** The handler's turn signal between turns: never aborts. */
 const IDLE_SIGNAL = new AbortController().signal;
-/**
- * nax's `agent.native.transportRetry` default. The loop retries a transport,
- * overloaded or rate-limit fault that arrives after events have streamed, and
- * emits `stream_reset` so the consumer voids that round's deltas (spec 5.3).
- */
-const SESSION_TRANSPORT_RETRY = { maxAttempts: 3, baseDelayMs: 2000 };
-class NativeAgentSession {
+class FacadeAgentSession {
     parts;
     active;
     last;
@@ -38,6 +19,10 @@ class NativeAgentSession {
     get id() {
         return this.parts.ctx.sessionId;
     }
+    get backend() {
+        const info = this.parts.opened.info;
+        return Object.freeze({ kind: info.kind, capabilities: Object.freeze({ ...info.capabilities }) });
+    }
     get lastTurn() {
         return this.last;
     }
@@ -76,6 +61,7 @@ class NativeAgentSession {
     }
     async shutdown() {
         const active = this.active;
+        this.parts.closeController.abort();
         this.parts.table.close();
         active?.cancel("session closed");
         await active?.settled;
@@ -83,7 +69,12 @@ class NativeAgentSession {
             await this.parts.ctx.adapter.closeSession(this.parts.ctx.handle);
         }
         finally {
-            await this.parts.cleanup();
+            try {
+                await this.parts.opened.close();
+            }
+            finally {
+                await this.parts.cleanup();
+            }
         }
     }
 }
@@ -98,78 +89,46 @@ async function sessionRoot(options) {
     }
     return { dir: workdir, cleanup: async () => { } };
 }
-function createAdapter(options) {
-    const overrides = options.raw.catalogOverrides ?? [];
-    const credentials = options.raw.credentials;
-    // A session with its own catalog or credentials owns its client; the rest share the process memo.
-    const owns = overrides.length > 0 || credentials !== undefined;
-    return new NativeSessionAdapter(overrides, {
-        ...(credentials !== undefined ? { credentials } : {}),
-        ...(owns ? { ownClient: true } : {}),
-    });
-}
 async function assemble(options, sessionId, root, opening) {
     const raw = options.raw;
-    // A supplied policy is merged over the default, so enabling GitCommit never drops the credential read-deny.
-    const protectedPaths = { ...defaultProtectedPaths(raw.credentials !== undefined), ...raw.hostPorts?.protectedPaths };
-    const launcher = await resolveSessionLauncher({
-        profile: raw.profile,
-        root: root.dir,
-        protectedPaths,
-        bashApproval: options.bashApproval,
-        allowUnsandboxed: options.allowUnsandboxed,
-    });
     const table = createPendingAskTable(options.approvalTimeoutMs);
-    const slot = { turn: undefined, callId: undefined };
-    const asks = { table, emit: (body) => slot.turn?.emit(body), currentCallId: () => slot.callId };
-    const { support, grants } = buildSessionToolSupport({
-        profile: raw.profile,
-        root: root.dir,
-        sessionName: sessionId,
-        protectedPaths,
-        bashApproval: options.bashApproval,
-        launcher,
-        askResolver: createSessionAskResolver(createSessionAskLink(asks)),
-        interceptor: raw.hostPorts?.commandInterceptor,
-    });
-    const interactionHandler = createSessionInteractionHandler({
+    const slot = { turn: undefined };
+    const closeController = new AbortController();
+    const asks = createSessionAskPort({ table, emit: (body) => slot.turn?.emit(body), turn: () => slot.turn });
+    const opened = await raw.backend.open({
         sessionId,
-        runtime: support.runtime,
-        embedderTools: new Map(options.tools.map((tool) => [tool.name, tool])),
-        asks,
-        turnSignal: () => slot.turn?.signal ?? IDLE_SIGNAL,
-        setCurrentCallId: (callId) => {
-            slot.callId = callId;
-        },
-    });
-    const adapter = createAdapter(options);
-    const handle = await adapter.openSession(sessionId, {
-        agentName: NATIVE_AGENT,
         workdir: root.dir,
-        resolvedPermissions: { mode: "default", toolGrants: grants, bashApproval: options.bashApproval },
-        modelDef: { provider: options.provider, model: raw.model },
-        timeoutSeconds: options.turnTimeoutSeconds,
+        profile: raw.profile,
+        instructions: raw.instructions,
+        tools: options.tools,
         transcriptStore: raw.transcriptStore,
-        retainOnClose: true,
-        resume: opening.resume,
-        spinBreaker: DEFAULT_SPIN_BREAKER_SETTINGS,
-        transportRetry: SESSION_TRANSPORT_RETRY,
-        // An empty instructions is no system prompt: `system: ""` on the wire invites provider quirks.
-        ...(raw.instructions !== undefined && raw.instructions !== "" ? { systemPrompt: raw.instructions } : {}),
-    });
-    const ctx = {
-        sessionId,
-        adapter,
-        handle,
-        store: raw.transcriptStore,
-        codingTools: [...support.tools, ...options.tools.map(embedderToolDescriptor)],
-        interactionHandler,
-        loopHandlers: raw.loopHandlers,
-        loopHandlerContext: { sessionName: sessionId, workdir: root.dir, model: raw.model, provider: options.provider },
+        resume: opening.doc === undefined ? undefined : { doc: opening.doc },
+        asks,
+        turnSignal: () => slot.turn?.signal ?? IDLE_SIGNAL,
+        currentTurnId: () => slot.turn?.turnId,
         turnTimeoutSeconds: options.turnTimeoutSeconds,
         metadata: options.metadata,
-    };
-    return new NativeAgentSession({ ctx, table, slot, cleanup: root.cleanup }, opening.lastTurn);
+        openSignal: closeController.signal,
+    });
+    try {
+        const ctx = {
+            sessionId,
+            adapter: opened.adapter,
+            handle: opened.handle,
+            store: raw.transcriptStore,
+            turnOpts: () => opened.turnOpts(),
+            turnTimeoutSeconds: options.turnTimeoutSeconds,
+            metadata: options.metadata,
+        };
+        return new FacadeAgentSession({ ctx, table, slot, opened, closeController, cleanup: root.cleanup }, opening.lastTurn);
+    }
+    catch (err) {
+        // No step after backend.open throws today; a future backend's must not leak
+        // the opened resources. open() still removes the root and lets open()'s own
+        // failure propagate untouched.
+        await opened.close().catch(() => undefined);
+        throw err;
+    }
 }
 /** Opens the backend session under a fresh root; a failure removes the root. */
 async function open(options, sessionId, opening) {
@@ -188,7 +147,7 @@ export async function createAgentSession(input) {
     if ((await options.raw.transcriptStore.load(sessionId)) !== null) {
         throw new AgentSessionError(`Session "${sessionId}" already exists in the transcript store; resume it instead`, "AGENT_SESSION_EXISTS", { sessionId });
     }
-    return open(options, sessionId, { resume: false, lastTurn: undefined });
+    return open(options, sessionId, { doc: undefined, lastTurn: undefined });
 }
 /**
  * Spec 6.4: the turn a dead process left running is marked ended, so the next
@@ -212,9 +171,11 @@ async function endInterruptedTurn(session, store, sessionId, turnId) {
 export async function resumeAgentSession(sessionId, input) {
     const options = resolveAgentSessionOptions(resumeInput(sessionId, input));
     const store = options.raw.transcriptStore;
-    const interrupted = interruptedTurnOf(await loadResumable(store, sessionId, options.raw.model));
+    const doc = await loadResumable(store, sessionId);
+    checkBackendKind(doc, sessionId, options.raw.backend.kind);
+    const interrupted = interruptedTurnOf(doc);
     const session = await open(options, sessionId, {
-        resume: true,
+        doc,
         lastTurn: interrupted === undefined ? undefined : { turnId: interrupted, status: "interrupted" },
     });
     if (interrupted !== undefined)

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

@@ -0,0 +1,24 @@
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { NativeCatalogOverrides } from "#src/native/client";
+import type { CredentialSource } from "#src/native/credentials/session-source";
+import type { LoopHandlerSet } from "#src/native/session/loop-events/types";
+import type { AgentSessionHostPorts, AgentSessionProfile } from "./agent-session-types.ts";
+export interface NativeBackendOptions {
+    readonly model: string;
+    readonly credentials?: CredentialSource;
+    readonly catalogOverrides?: NativeCatalogOverrides;
+    readonly loopHandlers?: LoopHandlerSet;
+    readonly hostPorts?: AgentSessionHostPorts;
+    readonly bashApproval?: BashApprovalMode;
+    readonly allowUnsandboxed?: boolean;
+}
+export interface ResolvedNativeOptions {
+    /** The caller's object, unchanged. */
+    readonly raw: NativeBackendOptions;
+    readonly provider: string;
+}
+export declare function parseNativeBackendOptions(input: unknown): ResolvedNativeOptions;
+export declare function nativeProfileRules(profile: AgentSessionProfile, raw: NativeBackendOptions): {
+    readonly bashApproval: BashApprovalMode;
+    readonly allowUnsandboxed: boolean;
+};

package/dist/session/native-backend-options.js

@@ -0,0 +1,81 @@
+/**
+ * nativeBackend's options (S4 spec 5.2): the native half of the facade's
+ * createAgentSession options, validated here rather than by the facade. zod
+ * checks the shape; the caller's own object is kept as `raw` (zod returns
+ * copies, which would break identity for handlers the caller owns).
+ */
+import { z } from "zod";
+import { parseNativeModel } from "#src/native/models";
+import { AgentSessionError } from "./agent-session-errors.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasMethods(names) {
+    return (value) => isRecord(value) && names.every((name) => typeof value[name] === "function");
+}
+const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+const OptionsSchema = z.strictObject({
+    model: z.string().min(1),
+    credentials: z
+        .custom((value) => isRecord(value) && (value.kind === "memory" || value.kind === "exec"), "must be a memory or exec source")
+        .optional(),
+    catalogOverrides: z.array(z.custom(isRecord, "must be a catalog override object")).optional(),
+    loopHandlers: z.array(z.custom(isRecord, "must be a loop handler entry")).optional(),
+    hostPorts: z
+        .strictObject({
+        protectedPaths: z
+            .custom((value) => isRecord(value) && isStringArray(value.gitExcludePathspecs) && isStringArray(value.gitIgnorePatterns), "must be a protected-paths policy with gitExcludePathspecs and gitIgnorePatterns string arrays")
+            .optional(),
+        commandInterceptor: z.custom(hasMethods(["intercept"]), "must implement intercept").optional(),
+    })
+        .optional(),
+    bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
+    allowUnsandboxed: z.boolean().optional(),
+});
+function invalid(message, context = {}) {
+    return new AgentSessionError(`Invalid agent session options: ${message}`, "AGENT_SESSION_INVALID_OPTIONS", context);
+}
+function checkShape(input) {
+    if (isRecord(input) && isRecord(input.hostPorts) && "runDeclaredCommand" in input.hostPorts) {
+        throw invalid("hostPorts.runDeclaredCommand is deferred to a later release", {
+            path: "backend.hostPorts.runDeclaredCommand",
+        });
+    }
+    const parsed = OptionsSchema.safeParse(input);
+    if (parsed.success)
+        return input;
+    const issue = parsed.error.issues[0];
+    const path = issue === undefined || issue.path.length === 0 ? "backend" : `backend.${issue.path.join(".")}`;
+    throw invalid(`${path}: ${issue?.message ?? "invalid"}`, { path });
+}
+function providerOf(model) {
+    try {
+        return parseNativeModel(model).provider;
+    }
+    catch {
+        throw invalid(`model: "${model}" is not "provider/model[effort]"`, { path: "backend.model" });
+    }
+}
+export function parseNativeBackendOptions(input) {
+    const options = checkShape(input);
+    return { raw: options, provider: providerOf(options.model) };
+}
+export function nativeProfileRules(profile, raw) {
+    const tools = profile === "full" || profile === "ask";
+    if (!tools && raw.bashApproval !== undefined) {
+        throw invalid('bashApproval applies to profiles "ask" and "full" only', { path: "backend.bashApproval" });
+    }
+    if (!tools && raw.allowUnsandboxed !== undefined) {
+        throw invalid('allowUnsandboxed applies to profiles "ask" and "full" only', { path: "backend.allowUnsandboxed" });
+    }
+    const bashApproval = raw.bashApproval ?? "gated";
+    if (profile === "ask" && bashApproval !== "gated") {
+        throw invalid('profile "ask" requires bashApproval "gated" (other modes run Bash without asking)', {
+            path: "backend.bashApproval",
+        });
+    }
+    if (raw.allowUnsandboxed === true && bashApproval !== "gated") {
+        throw invalid('allowUnsandboxed requires bashApproval "gated"', { path: "backend.allowUnsandboxed" });
+    }
+    return { bashApproval, allowUnsandboxed: raw.allowUnsandboxed === true };
+}

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

@@ -0,0 +1,4 @@
+import { type NativeBackendOptions } from "./native-backend-options.ts";
+import type { SessionBackend } from "./session-backend.ts";
+export declare const NATIVE_BACKEND_KIND = "native";
+export declare function nativeBackend(options: NativeBackendOptions): SessionBackend;

package/dist/session/native-backend.js

@@ -0,0 +1,106 @@
+/**
+ * The native backend (S4 spec 5.2): the S3 facade's native half behind the
+ * SessionBackend seam. Sandbox floor, profile tools, the interaction handler
+ * with built-in and embedder tools, the NativeSessionAdapter, loop handlers
+ * and the resume model check.
+ */
+import { DEFAULT_SPIN_BREAKER_SETTINGS } from "#src/infra/spin-breaker/index";
+import { NATIVE_AGENT } from "#src/native/models";
+import { transcriptModelIdentity } from "#src/native/session/transcript-identity";
+import { NativeSessionAdapter } from "#src/native/session-adapter";
+import { AgentSessionError } from "./agent-session-errors.js";
+import { nativeProfileRules, parseNativeBackendOptions, } from "./native-backend-options.js";
+import { createSessionAskLink, createSessionAskResolver } from "./session-ask-link.js";
+import { createSessionInteractionHandler, embedderToolDescriptor } from "./session-interaction.js";
+import { buildSessionToolSupport, defaultProtectedPaths, resolveSessionLauncher } from "./session-tool-support.js";
+export const NATIVE_BACKEND_KIND = "native";
+/** nax's agent.native.transportRetry default (S3 spec 5.3). */
+const SESSION_TRANSPORT_RETRY = { maxAttempts: 3, baseDelayMs: 2000 };
+function createAdapter(raw) {
+    const overrides = raw.catalogOverrides ?? [];
+    const owns = overrides.length > 0 || raw.credentials !== undefined;
+    return new NativeSessionAdapter(overrides, {
+        ...(raw.credentials !== undefined ? { credentials: raw.credentials } : {}),
+        ...(owns ? { ownClient: true } : {}),
+    });
+}
+function checkResumeModel(doc, sessionId, model) {
+    const resuming = transcriptModelIdentity(model);
+    if (doc.model !== undefined && doc.model !== resuming) {
+        throw new AgentSessionError(`Session "${sessionId}" was written by model "${doc.model}"; resume it with that model, not "${resuming}"`, "AGENT_SESSION_MODEL_MISMATCH", { sessionId });
+    }
+}
+async function openNative(resolved, ctx) {
+    const raw = resolved.raw;
+    if (ctx.resume !== undefined)
+        checkResumeModel(ctx.resume.doc, ctx.sessionId, raw.model);
+    const { bashApproval, allowUnsandboxed } = nativeProfileRules(ctx.profile, raw);
+    const protectedPaths = { ...defaultProtectedPaths(raw.credentials !== undefined), ...raw.hostPorts?.protectedPaths };
+    const launcher = await resolveSessionLauncher({
+        profile: ctx.profile,
+        root: ctx.workdir,
+        protectedPaths,
+        bashApproval,
+        allowUnsandboxed,
+    });
+    let callId;
+    const { support, grants } = buildSessionToolSupport({
+        profile: ctx.profile,
+        root: ctx.workdir,
+        sessionName: ctx.sessionId,
+        protectedPaths,
+        bashApproval,
+        launcher,
+        askResolver: createSessionAskResolver(createSessionAskLink({ port: ctx.asks, currentCallId: () => callId })),
+        interceptor: raw.hostPorts?.commandInterceptor,
+    });
+    const interactionHandler = createSessionInteractionHandler({
+        sessionId: ctx.sessionId,
+        runtime: support.runtime,
+        embedderTools: new Map(ctx.tools.map((tool) => [tool.name, tool])),
+        asks: ctx.asks,
+        turnSignal: ctx.turnSignal,
+        setCurrentCallId: (id) => {
+            callId = id;
+        },
+    });
+    const adapter = createAdapter(raw);
+    const handle = await adapter.openSession(ctx.sessionId, {
+        agentName: NATIVE_AGENT,
+        workdir: ctx.workdir,
+        resolvedPermissions: { mode: "default", toolGrants: grants, bashApproval },
+        modelDef: { provider: resolved.provider, model: raw.model },
+        timeoutSeconds: ctx.turnTimeoutSeconds,
+        transcriptStore: ctx.transcriptStore,
+        retainOnClose: true,
+        resume: ctx.resume !== undefined,
+        spinBreaker: DEFAULT_SPIN_BREAKER_SETTINGS,
+        transportRetry: SESSION_TRANSPORT_RETRY,
+        ...(ctx.instructions !== undefined && ctx.instructions !== "" ? { systemPrompt: ctx.instructions } : {}),
+    });
+    const codingTools = [...support.tools, ...ctx.tools.map(embedderToolDescriptor)];
+    const loopHandlerContext = {
+        sessionName: ctx.sessionId,
+        workdir: ctx.workdir,
+        model: raw.model,
+        provider: resolved.provider,
+    };
+    return {
+        adapter,
+        handle,
+        info: { kind: NATIVE_BACKEND_KIND, capabilities: {} },
+        turnOpts: () => ({
+            interactionHandler,
+            codingTools,
+            loopHandlerContext,
+            ...(raw.loopHandlers !== undefined ? { loopHandlers: raw.loopHandlers } : {}),
+        }),
+        // Native owns no per-session resource beyond the adapter, which
+        // closeSession (the facade's step before this) already releases.
+        close: async () => { },
+    };
+}
+export function nativeBackend(options) {
+    const resolved = parseNativeBackendOptions(options);
+    return { kind: NATIVE_BACKEND_KIND, open: (ctx) => openNative(resolved, ctx) };
+}

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

@@ -4,15 +4,14 @@
  * whose approval is "always". Asks are serial in practice: the tool batch
  * runs one call at a time.
  */
-import { type AskLink, type AskLinkOutcome, type AskResolver } from "#src/permissions/index";
+import { type AskLink, type AskResolver } from "#src/permissions/index";
 import type { SessionEventBody } from "./agent-session-types.ts";
 import type { PendingAskTable } from "./pending-asks.ts";
+import type { SessionAskPort } from "./session-backend.ts";
 export interface SessionAskDeps {
     readonly table: PendingAskTable;
     /** Emits on the running turn's event stream. */
     readonly emit: (body: SessionEventBody) => void;
-    /** The tool call being answered right now, if any. */
-    readonly currentCallId: () => string | undefined;
 }
 export interface ApprovalAsk {
     readonly tool: string;
@@ -21,6 +20,14 @@ export interface ApprovalAsk {
     readonly reason: string;
     readonly callId?: string;
 }
-export declare function askPerson(deps: SessionAskDeps, ask: ApprovalAsk, signal: AbortSignal | undefined): Promise<AskLinkOutcome>;
-export declare function createSessionAskLink(deps: SessionAskDeps): AskLink;
+export declare function askPerson(deps: SessionAskDeps, ask: ApprovalAsk, signal: AbortSignal | undefined): Promise<{
+    readonly decision: "allow" | "deny";
+    readonly decidedBy: "human" | "timeout" | "cancelled";
+}>;
+export interface SessionAskLinkDeps {
+    readonly port: SessionAskPort;
+    /** The tool call being answered right now, if any. */
+    readonly currentCallId: () => string | undefined;
+}
+export declare function createSessionAskLink(deps: SessionAskLinkDeps): AskLink;
 export declare function createSessionAskResolver(link: AskLink): AskResolver;

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

@@ -36,13 +36,14 @@ export function createSessionAskLink(deps) {
             if (masked !== undefined && !masked.ok)
                 return Promise.resolve(UNSHOWABLE);
             const callId = deps.currentCallId();
-            return askPerson(deps, {
+            return deps.port.requestApproval({
                 tool: req.tool,
                 summary: req.summary,
                 ...(masked !== undefined ? { command: masked.masked } : {}),
                 reason: req.reason ?? `matched ${req.rule}`,
                 ...(callId !== undefined ? { callId } : {}),
-            }, control?.signal);
+                ...(control?.signal !== undefined ? { signal: control.signal } : {}),
+            });
         },
     };
 }

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() });
+        },
+    };
+}