@nathapp/nax-agent 0.1.0 → 0.3.0

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

@@ -0,0 +1,182 @@
+/**
+ * Public types of the agent session facade (S3 spec section 4). The facade
+ * drives the S1 AgentSessionAdapter; nothing here is backend-specific, so the
+ * @nathapp/nax-agent-acp backend (S4) reuses these types unchanged.
+ */
+import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { TokenUsage } from "#src/cost/standard-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). `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. */
+    readonly toolCallId: string;
+    /** Aborts when the turn is cancelled, times out or the session closes. */
+    readonly signal: AbortSignal;
+}
+export interface EmbedderToolResult {
+    readonly content: string;
+    readonly isError?: boolean;
+}
+/** An in-process tool the embedder supplies (spec 4.3). */
+export interface EmbedderTool {
+    /** The name the model sees. A letter, then letters, digits, `_` or `-`; at most 64 characters. */
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JSONSchema;
+    /** `always` asks the person through `answer()` before every run. */
+    readonly approval: "never" | "always";
+    /** The approval summary. Default: the redacted, byte-capped JSON of the input. */
+    describe?(input: unknown): string;
+    /** A throw, or `isError: true`, reaches the model as an error result. */
+    run(input: unknown, ctx: EmbedderToolContext): Promise<EmbedderToolResult>;
+}
+/** Host ports an embedder may supply (spec 6.2). */
+export interface AgentSessionHostPorts {
+    /** Paths the sandbox and the read tools deny. Default: the configured credentials directory, if any. */
+    readonly protectedPaths?: ProtectedPathsPolicy;
+    readonly commandInterceptor?: CommandInterceptor;
+}
+export interface CreateAgentSessionOptions {
+    /** 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;
+    readonly profile: AgentSessionProfile;
+    /** An absolute directory. Required for `read` and `full`; `none` gets a private temporary root. */
+    readonly workdir?: string;
+    /** The embedder's system prompt. */
+    readonly instructions?: string;
+    readonly tools?: readonly EmbedderTool[];
+    /**
+     * Where the conversation lives. The session keeps its document on close, so
+     * `resumeAgentSession` can reopen it. A file store's failed-close prune counts
+     * every transcript in its directory, so do not share a file-store directory
+     * with sessions that are closed as failed.
+     */
+    readonly transcriptStore: TranscriptStore;
+    /** How long an approval or question waits. Default 600000; 30000..3600000. */
+    readonly approvalTimeoutMs?: number;
+    /** 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" | "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;
+    /** ISO 8601. */
+    readonly at: string;
+    readonly metadata: Readonly<Record<string, string>>;
+}
+export type SessionEventBody = {
+    readonly type: "turn_start";
+} | {
+    readonly type: "text_delta";
+    readonly round: number;
+    readonly text: string;
+} | {
+    readonly type: "thinking_delta";
+    readonly round: number;
+    readonly text: string;
+} | {
+    readonly type: "stream_reset";
+    readonly round: number;
+    readonly attempt: number;
+} | {
+    readonly type: "tool_call";
+    readonly callId: string;
+    readonly name: string;
+    readonly input: unknown;
+} | {
+    readonly type: "tool_result";
+    readonly callId: string;
+    readonly isError: boolean;
+    readonly preview: string;
+} | {
+    readonly type: "approval_requested";
+    readonly requestId: string;
+    readonly callId?: string;
+    readonly tool: string;
+    readonly summary: string;
+    readonly command?: string;
+    readonly reason: string;
+    readonly expiresAt: string;
+} | {
+    readonly type: "approval_resolved";
+    readonly requestId: string;
+    readonly decision: "allow" | "deny";
+    readonly decidedBy: ApprovalDecidedBy;
+} | {
+    readonly type: "question";
+    readonly requestId: string;
+    readonly text: string;
+    readonly expiresAt: string;
+} | {
+    readonly type: "usage";
+    readonly round: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheRead?: number;
+    readonly cacheWrite?: number;
+    readonly costUsd: number;
+    readonly costSource?: CostSource;
+} | {
+    readonly type: "compaction";
+    readonly reason: "proactive" | "overflow";
+} | {
+    readonly type: "turn_end";
+    readonly status: TurnEndStatus;
+    /** The final round's text, as `TurnResult.output`. Empty when the turn did not complete. */
+    readonly output: string;
+    readonly usage: TokenUsage;
+    readonly costUsd: number;
+    readonly costSource?: CostSource;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+/**
+ * One event of a `send()` (spec 4.4). Deltas are provisional: the transcript
+ * and `turn_end.output` are authoritative. `turn_end` is always last.
+ */
+export type SessionEvent = SessionEventBase & SessionEventBody;
+export type AnswerReply = {
+    readonly decision: "allow" | "deny";
+} | {
+    readonly text: string;
+};
+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;
+        readonly status: TurnEndStatus;
+    } | undefined;
+    /** Claims the session's single turn slot synchronously; the turn starts on the first `next()`. */
+    send(message: string): AsyncIterable<SessionEvent>;
+    answer(requestId: string, reply: AnswerReply): AnswerStatus;
+    /** Aborts the running turn; a no-op when none runs. */
+    cancel(reason?: string): void;
+    /** Idempotent. Cancels a running turn, waits for it, keeps the document in the store. */
+    close(): Promise<void>;
+}

package/dist/session/agent-session-types.js

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

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

@@ -0,0 +1,8 @@
+import type { AgentSession, CreateAgentSessionOptions } from "./agent-session-types.ts";
+export declare function createAgentSession(input: CreateAgentSessionOptions): Promise<AgentSession>;
+/**
+ * Reopens a stored session (spec 4.2). `options` are a create's options; the
+ * session id is the argument. Instructions, tools and profile are not stored:
+ * pass them again.
+ */
+export declare function resumeAgentSession(sessionId: string, input: CreateAgentSessionOptions): Promise<AgentSession>;

package/dist/session/agent-session.js

@@ -0,0 +1,184 @@
+import { _agentSessionDeps } from "./agent-session-deps.js";
+import { AgentSessionError } from "./agent-session-errors.js";
+import { resolveAgentSessionOptions } from "./agent-session-options.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 { createSessionAskPort } from "./session-ask-port.js";
+/** The handler's turn signal between turns: never aborts. */
+const IDLE_SIGNAL = new AbortController().signal;
+class FacadeAgentSession {
+    parts;
+    active;
+    last;
+    closing;
+    constructor(parts, last) {
+        this.parts = parts;
+        this.last = last;
+    }
+    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;
+    }
+    send(message) {
+        if (this.closing !== undefined) {
+            throw new AgentSessionError(`Session "${this.id}" is closed`, "AGENT_SESSION_CLOSED", { sessionId: this.id });
+        }
+        if (this.active !== undefined) {
+            throw new AgentSessionError(`Session "${this.id}" already has a turn in flight`, "AGENT_SESSION_BUSY", {
+                sessionId: this.id,
+            });
+        }
+        const turn = claimTurn(this.parts.ctx, message, {
+            onStart: (live) => {
+                this.parts.slot.turn = live;
+            },
+            onSettle: (turnId, status) => {
+                this.active = undefined;
+                this.parts.slot.turn = undefined;
+                if (status !== undefined)
+                    this.last = { turnId, status };
+            },
+        });
+        this.active = turn;
+        return turn.iterable;
+    }
+    answer(requestId, reply) {
+        return this.parts.table.answer(requestId, reply);
+    }
+    cancel(reason = "cancelled") {
+        this.active?.cancel(reason);
+    }
+    close() {
+        this.closing ??= this.shutdown();
+        return this.closing;
+    }
+    async shutdown() {
+        const active = this.active;
+        this.parts.closeController.abort();
+        this.parts.table.close();
+        active?.cancel("session closed");
+        await active?.settled;
+        try {
+            await this.parts.ctx.adapter.closeSession(this.parts.ctx.handle);
+        }
+        finally {
+            try {
+                await this.parts.opened.close();
+            }
+            finally {
+                await this.parts.cleanup();
+            }
+        }
+    }
+}
+async function sessionRoot(options) {
+    const workdir = options.raw.workdir;
+    if (workdir === undefined) {
+        const dir = await _agentSessionDeps.makeScratchRoot();
+        return { dir, cleanup: () => _agentSessionDeps.removeScratchRoot(dir) };
+    }
+    if (!(await _agentSessionDeps.isDirectory(workdir))) {
+        throw new AgentSessionError(`Invalid agent session options: workdir "${workdir}" is not a directory`, "AGENT_SESSION_INVALID_OPTIONS", { path: "workdir" });
+    }
+    return { dir: workdir, cleanup: async () => { } };
+}
+async function assemble(options, sessionId, root, opening) {
+    const raw = options.raw;
+    const table = createPendingAskTable(options.approvalTimeoutMs);
+    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,
+        workdir: root.dir,
+        profile: raw.profile,
+        instructions: raw.instructions,
+        tools: options.tools,
+        transcriptStore: raw.transcriptStore,
+        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,
+        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) {
+    const root = await sessionRoot(options);
+    try {
+        return await assemble(options, sessionId, root, opening);
+    }
+    catch (err) {
+        await root.cleanup();
+        throw err;
+    }
+}
+export async function createAgentSession(input) {
+    const options = resolveAgentSessionOptions(input);
+    const sessionId = options.raw.sessionId ?? _agentSessionDeps.randomUUID();
+    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, { doc: undefined, lastTurn: undefined });
+}
+/**
+ * Spec 6.4: the turn a dead process left running is marked ended, so the next
+ * send starts clean. A failure closes the session and rethrows the store's
+ * error; a close failure would only mask it.
+ */
+async function endInterruptedTurn(session, store, sessionId, turnId) {
+    try {
+        await store.markTurn(sessionId, { turnId, state: "ended" });
+    }
+    catch (err) {
+        await session.close().catch(() => undefined);
+        throw err;
+    }
+}
+/**
+ * Reopens a stored session (spec 4.2). `options` are a create's options; the
+ * session id is the argument. Instructions, tools and profile are not stored:
+ * pass them again.
+ */
+export async function resumeAgentSession(sessionId, input) {
+    const options = resolveAgentSessionOptions(resumeInput(sessionId, input));
+    const store = options.raw.transcriptStore;
+    const doc = await loadResumable(store, sessionId);
+    checkBackendKind(doc, sessionId, options.raw.backend.kind);
+    const interrupted = interruptedTurnOf(doc);
+    const session = await open(options, sessionId, {
+        doc,
+        lastTurn: interrupted === undefined ? undefined : { turnId: interrupted, status: "interrupted" },
+    });
+    if (interrupted !== undefined)
+        await endInterruptedTurn(session, store, sessionId, interrupted);
+    return session;
+}

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

@@ -0,0 +1,24 @@
+import type { AnswerReply, AnswerStatus } from "./agent-session-types.ts";
+export type PendingAskKind = "approval" | "question";
+export type AskSettlement = {
+    readonly by: "human";
+    readonly reply: AnswerReply;
+} | {
+    readonly by: "timeout";
+} | {
+    readonly by: "cancelled";
+};
+export interface IssuedAsk {
+    readonly requestId: string;
+    readonly expiresAt: string;
+    readonly settled: Promise<AskSettlement>;
+}
+export interface PendingAskTable {
+    issue(kind: PendingAskKind, signal: AbortSignal | undefined): IssuedAsk;
+    answer(requestId: string, reply: AnswerReply): AnswerStatus;
+    /** Settles every pending request as cancelled. */
+    cancelAll(): void;
+    /** cancelAll; afterwards every answer() returns "unknown" and every issue() settles cancelled. */
+    close(): void;
+}
+export declare function createPendingAskTable(timeoutMs: number): PendingAskTable;