@nathapp/nax-agent 0.1.0 → 0.3.0

package/dist/session/pending-asks.js

@@ -0,0 +1,77 @@
+/**
+ * The session's pending approvals and questions (spec 4.2 answer, 6.1). Each
+ * request settles once: by answer(), by its deadline, or by its turn signal.
+ * Ids are kept for the session's lifetime, so a late click gets a status
+ * rather than a throw; only a never-issued id or a kind mismatch throws.
+ */
+import { _agentSessionDeps } from "./agent-session-deps.js";
+import { AgentSessionError } from "./agent-session-errors.js";
+/** The kind a reply answers, or undefined for a malformed reply (callers may be plain JS). */
+function replyKind(reply) {
+    const value = reply;
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    if ("decision" in value)
+        return value.decision === "allow" || value.decision === "deny" ? "approval" : undefined;
+    return "text" in value && typeof value.text === "string" ? "question" : undefined;
+}
+function kindMismatch(requestId, kind) {
+    const expected = kind === "approval" ? "an approval: reply with { decision }" : "a question: reply with { text }";
+    return new AgentSessionError(`Request "${requestId}" is ${expected}`, "AGENT_SESSION_INVALID_ANSWER", {
+        requestId,
+        kind,
+    });
+}
+export function createPendingAskTable(timeoutMs) {
+    const entries = new Map();
+    let closed = false;
+    function issue(kind, signal) {
+        const requestId = _agentSessionDeps.randomUUID();
+        const expiresAt = new Date(_agentSessionDeps.now() + timeoutMs).toISOString();
+        const settled = new Promise((resolve) => {
+            let timer;
+            const onAbort = () => finish({ by: "cancelled" });
+            function finish(settlement) {
+                if (entries.get(requestId)?.state !== "pending")
+                    return;
+                _agentSessionDeps.clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                entries.set(requestId, { kind, state: settlement.by });
+                resolve(settlement);
+            }
+            entries.set(requestId, { kind, state: "pending", finish });
+            timer = _agentSessionDeps.setTimeout(() => finish({ by: "timeout" }), timeoutMs);
+            if (closed || signal?.aborted === true)
+                finish({ by: "cancelled" });
+            else
+                signal?.addEventListener("abort", onAbort, { once: true });
+        });
+        return { requestId, expiresAt, settled };
+    }
+    function answer(requestId, reply) {
+        if (closed)
+            return "unknown";
+        const entry = entries.get(requestId);
+        if (entry === undefined) {
+            throw new AgentSessionError(`No request "${requestId}" was issued by this session`, "AGENT_SESSION_INVALID_ANSWER", {
+                requestId,
+            });
+        }
+        if (replyKind(reply) !== entry.kind)
+            throw kindMismatch(requestId, entry.kind);
+        if (entry.state === "pending") {
+            entry.finish?.({ by: "human", reply });
+            return "accepted";
+        }
+        return entry.state === "cancelled" ? "cancelled" : "expired";
+    }
+    function cancelAll() {
+        for (const entry of [...entries.values()])
+            entry.finish?.({ by: "cancelled" });
+    }
+    function close() {
+        cancelAll();
+        closed = true;
+    }
+    return { issue, answer, cancelAll, close };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Raises approvals to the person through the session's events (spec 6.1).
+ * askPerson is shared by the coding tools' AskLink and by embedder tools
+ * whose approval is "always". Asks are serial in practice: the tool batch
+ * runs one call at a time.
+ */
+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;
+}
+export interface ApprovalAsk {
+    readonly tool: string;
+    readonly summary: string;
+    readonly command?: string;
+    readonly reason: string;
+    readonly callId?: string;
+}
+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

@@ -0,0 +1,53 @@
+/**
+ * Raises approvals to the person through the session's events (spec 6.1).
+ * askPerson is shared by the coding tools' AskLink and by embedder tools
+ * whose approval is "always". Asks are serial in practice: the tool batch
+ * runs one call at a time.
+ */
+import { chainAskLinks, maskForPrompt, } from "#src/permissions/index";
+export async function askPerson(deps, ask, signal) {
+    const { requestId, expiresAt, settled } = deps.table.issue("approval", signal);
+    deps.emit({
+        type: "approval_requested",
+        requestId,
+        ...(ask.callId !== undefined ? { callId: ask.callId } : {}),
+        tool: ask.tool,
+        summary: ask.summary,
+        ...(ask.command !== undefined ? { command: ask.command } : {}),
+        reason: ask.reason,
+        expiresAt,
+    });
+    const settlement = await settled;
+    const allowed = settlement.by === "human" && "decision" in settlement.reply && settlement.reply.decision === "allow";
+    const decision = allowed ? "allow" : "deny";
+    deps.emit({ type: "approval_resolved", requestId, decision, decidedBy: settlement.by });
+    return { decision, decidedBy: settlement.by };
+}
+const UNSHOWABLE = { decision: "deny", decidedBy: "unshowable" };
+export function createSessionAskLink(deps) {
+    return {
+        name: "agent-session",
+        resolve(req, control) {
+            // A request whose text could not be shown safely is never put in front of a person.
+            if (req.unshowable === true)
+                return Promise.resolve(UNSHOWABLE);
+            // As nax's human link: the command is masked, and one whose secret cannot be masked safely is unshowable.
+            const masked = req.command === undefined ? undefined : maskForPrompt(req.command);
+            if (masked !== undefined && !masked.ok)
+                return Promise.resolve(UNSHOWABLE);
+            const callId = deps.currentCallId();
+            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 !== undefined ? { signal: control.signal } : {}),
+            });
+        },
+    };
+}
+export function createSessionAskResolver(link) {
+    const chain = chainAskLinks([link]);
+    return { humanReachable: true, resolve: (req, control) => chain.resolve(req, control) };
+}

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-event-channel.d.ts

@@ -0,0 +1,17 @@
+import type { SessionEvent } from "./agent-session-types.ts";
+export interface SessionEventChannelOptions {
+    /** Undelivered control events tolerated before onStall fires. */
+    readonly controlCap: number;
+    /** The consumer's first next(): the turn starts here. May push synchronously. */
+    readonly onFirstPull: () => void;
+    /** The consumer called return() before the channel ended. */
+    readonly onReturn: () => void;
+    readonly onStall: () => void;
+}
+export interface SessionEventChannel {
+    push(event: SessionEvent): void;
+    /** No more events: the iterator completes once the buffer drains. */
+    end(): void;
+    readonly iterator: AsyncIterator<SessionEvent>;
+}
+export declare function createSessionEventChannel(options: SessionEventChannelOptions): SessionEventChannel;

package/dist/session/session-event-channel.js

@@ -0,0 +1,132 @@
+/**
+ * The push-to-pull channel behind send()'s iterator (spec 4.4). The turn
+ * pushes; one consumer pulls. While the consumer lags, adjacent deltas of the
+ * same type and round merge. Control events are never merged or dropped; past
+ * `controlCap` undelivered ones the channel reports a stall, once. One
+ * consumer only: a second next() while one is pending rejects (for await
+ * never makes one). return() before the first next() never starts the turn.
+ *
+ * The buffer is two slots: a `queue` of non-mergeable events (FIFO, indexed)
+ * and a `tail` that is always a delta the next push can merge into. push is
+ * amortized O(1) — a `queue.push` and the `tail` swap are O(1), and the
+ * merge's string concat is O(merged-text length), which is the same cost the
+ * old design paid, just without the per-merge buffer copy. The pop is a
+ * `queue[head++]` read, not an `Array.shift()`. The old implementation
+ * copied the whole buffer on every merge (`[...buffer.slice(0, -1), combined]`),
+ * which made a high-rate delta stream quadratic.
+ */
+import { AgentSessionError } from "./agent-session-errors.js";
+const DONE = { done: true, value: undefined };
+function isDelta(event) {
+    return event !== undefined && (event.type === "text_delta" || event.type === "thinking_delta");
+}
+function canMergeInto(into, next) {
+    return into.type === next.type && into.round === next.round;
+}
+export function createSessionEventChannel(options) {
+    let queue = [];
+    let head = 0;
+    let tail;
+    let waiter;
+    let undeliveredControl = 0;
+    let ended = false;
+    let consumerGone = false;
+    let pulled = false;
+    let stalled = false;
+    function deliver(result) {
+        if (waiter === undefined)
+            return false;
+        const resolve = waiter;
+        waiter = undefined;
+        resolve(result);
+        return true;
+    }
+    /** Drop the consumed prefix; O(1) when the buffer is fully drained. */
+    function compact() {
+        if (head > 0 && head === queue.length) {
+            queue = [];
+            head = 0;
+        }
+    }
+    function enqueue(event) {
+        if (isDelta(event)) {
+            if (tail !== undefined && canMergeInto(tail, event)) {
+                // Replace, don't mutate: DeltaEvent.text is readonly. O(1) — a
+                // string concat, not a buffer copy.
+                tail = { ...tail, text: tail.text + event.text };
+                return;
+            }
+            if (tail !== undefined)
+                queue.push(tail);
+            tail = event;
+            return;
+        }
+        // Control events: never held in `tail` (so a later delta sees no merge
+        // partner and the cap math stays correct).
+        if (tail !== undefined) {
+            queue.push(tail);
+            tail = undefined;
+        }
+        queue.push(event);
+        undeliveredControl += 1;
+        if (!stalled && undeliveredControl > options.controlCap) {
+            stalled = true;
+            options.onStall();
+        }
+    }
+    function push(event) {
+        if (ended || consumerGone)
+            return;
+        if (deliver({ value: event, done: false }))
+            return;
+        enqueue(event);
+    }
+    function end() {
+        if (ended)
+            return;
+        ended = true;
+        if (queue.length === head && tail === undefined)
+            deliver(DONE);
+    }
+    async function next() {
+        if (consumerGone)
+            return DONE;
+        if (waiter !== undefined) {
+            throw new AgentSessionError("send() iterables support one next() at a time", "AGENT_SESSION_BUSY");
+        }
+        if (!pulled) {
+            pulled = true;
+            options.onFirstPull();
+        }
+        if (head < queue.length) {
+            const event = queue[head++];
+            compact();
+            if (!isDelta(event))
+                undeliveredControl -= 1;
+            return { value: event, done: false };
+        }
+        if (tail !== undefined) {
+            const event = tail;
+            tail = undefined;
+            return { value: event, done: false };
+        }
+        if (ended)
+            return DONE;
+        return new Promise((resolve) => {
+            waiter = resolve;
+        });
+    }
+    async function leave() {
+        if (consumerGone)
+            return DONE;
+        consumerGone = true;
+        queue = [];
+        head = 0;
+        tail = undefined;
+        deliver(DONE);
+        if (!ended)
+            options.onReturn();
+        return DONE;
+    }
+    return { push, end, iterator: { next, return: leave } };
+}

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

@@ -0,0 +1,20 @@
+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 { 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: SessionAskPort;
+    /** The running turn's signal (a never-aborting one between turns). */
+    readonly turnSignal: () => AbortSignal;
+    readonly setCurrentCallId: (callId: string | undefined) => void;
+}
+/** What the model sees of an embedder tool. The facade's handler runs it; this run is never reached. */
+export declare function embedderToolDescriptor(tool: EmbedderTool): CodingTool;
+export declare function defaultSummary(input: unknown): string;
+export declare function createSessionInteractionHandler(deps: SessionInteractionDeps): InteractionHandler;

package/dist/session/session-interaction.js

@@ -0,0 +1,161 @@
+/**
+ * The facade's InteractionHandler (spec 5.1, 4.3, 6.1). Routes each loop
+ * request:
+ * - question -> the pending-ask table (null on timeout or cancel, which the
+ *   loop answers with its no-operator text);
+ * - an embedder tool -> its own run, after an approval when it is "always";
+ * - a built-in coding tool -> the session's CodingToolRuntime, with the call
+ *   id in the current-call slot so a policy ask can name it.
+ * A failed tool is reported by throwing: the tool batch turns a handler throw
+ * into an isError result whose content is the thrown message.
+ */
+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";
+/** Byte cap on an embedder approval's default summary. */
+export const EMBEDDER_SUMMARY_BYTES = 1024;
+/**
+ * Redaction scans at most this many bytes of an embedder tool input; the
+ * summary keeps far fewer. Same 16x pattern as `turn-event-emitter.ts`'s
+ * `REDACTION_SCAN_BYTES` so the bound is comparable to a tool-call input.
+ */
+const EMBEDDER_SCAN_BYTES = EMBEDDER_SUMMARY_BYTES * 16;
+/** What the model sees of an embedder tool. The facade's handler runs it; this run is never reached. */
+export function embedderToolDescriptor(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        scope: { pathFields: [] },
+        async run() {
+            return { content: `"${tool.name}" runs through the agent session, not the coding-tool runtime.`, isError: true };
+        },
+    };
+}
+export function defaultSummary(input) {
+    let json;
+    try {
+        // Cap before redactSecrets walks: a multi-MB tool input must not run
+        // every SECRET_VALUE_PATTERNS regex (PEM block up to 64KB per match)
+        // over megabytes. The post-serialize cutToByteCap is the display cap;
+        // this is the scan cap.
+        json = JSON.stringify(redactSecrets(capStrings(input, EMBEDDER_SCAN_BYTES))) ?? "null";
+    }
+    catch {
+        return "[input not serializable]";
+    }
+    return cutToByteCap(json, EMBEDDER_SUMMARY_BYTES);
+}
+function toolError(message, tool) {
+    return new NaxError(message, "AGENT_SESSION_TOOL_ERROR", { stage: "agent-session", tool });
+}
+function summaryFor(tool, input) {
+    if (tool.describe === undefined)
+        return defaultSummary(input);
+    try {
+        // Same bound as defaultSummary: cap first, then redact, then display-cut.
+        // capStrings preserves the string's type at runtime; the cast is the
+        // single point where the generic is recovered for cutToByteCap.
+        const described = redactSecrets(capStrings(String(tool.describe(input)), EMBEDDER_SCAN_BYTES));
+        return cutToByteCap(described, EMBEDDER_SUMMARY_BYTES);
+    }
+    catch {
+        return defaultSummary(input);
+    }
+}
+function runSafely(tool, input, ctx) {
+    return Promise.resolve()
+        .then(() => tool.run(input, ctx))
+        .catch((err) => {
+        const cause = err instanceof Error ? err.message : String(err);
+        return { content: `Tool "${tool.name}" failed: ${cause}`, isError: true };
+    });
+}
+/**
+ * Runs the tool, but answers at once when the turn aborts: the batch awaits
+ * this handler with no abort race of its own, so a run that ignores its signal
+ * would otherwise hang the turn. The abandoned run's late settlement is ignored.
+ */
+async function invoke(tool, input, ctx) {
+    const abandoned = {
+        content: `Tool "${tool.name}" was abandoned: the turn ended.`,
+        isError: true,
+    };
+    if (ctx.signal.aborted)
+        return abandoned;
+    let onAbort = () => { };
+    const aborted = new Promise((resolve) => {
+        onAbort = () => resolve(abandoned);
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([runSafely(tool, input, ctx), aborted]);
+    }
+    finally {
+        ctx.signal.removeEventListener("abort", onAbort);
+    }
+}
+async function runEmbedderTool(deps, tool, request) {
+    const toolCallId = request.toolCallId ?? "";
+    const signal = request.signal ?? deps.turnSignal();
+    const input = request.input ?? {};
+    if (tool.approval === "always") {
+        const ask = {
+            tool: tool.name,
+            summary: summaryFor(tool, input),
+            reason: `"${tool.name}" asks before every run`,
+            callId: toolCallId,
+        };
+        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 } };
+        }
+    }
+    const result = await invoke(tool, input, { sessionId: deps.sessionId, toolCallId, signal });
+    if (result.isError === true)
+        throw toolError(result.content, tool.name);
+    return { answer: result.content };
+}
+function toolCallContext(request) {
+    return {
+        ...(request.turnId !== undefined ? { turnId: request.turnId } : {}),
+        ...(request.roundTrips !== undefined ? { roundTrips: request.roundTrips } : {}),
+        ...(request.toolCallId !== undefined ? { toolCallId: request.toolCallId } : {}),
+        ...(request.deferModelTruncation !== undefined ? { deferModelTruncation: request.deferModelTruncation } : {}),
+        ...(request.signal !== undefined ? { signal: request.signal } : {}),
+        ...(request.onWaiting !== undefined ? { onWaiting: request.onWaiting } : {}),
+    };
+}
+async function runCodingTool(deps, request) {
+    deps.setCurrentCallId(request.toolCallId);
+    try {
+        const outcome = await deps.runtime.callTool(request.name, request.input ?? {}, toolCallContext(request));
+        if (outcome.kind === "denied") {
+            return { answer: `Denied: ${outcome.reason}`, denied: { reason: outcome.reason, breach: outcome.breach } };
+        }
+        if (outcome.kind === "error")
+            throw toolError(outcome.content, request.name);
+        return { answer: outcome.content };
+    }
+    finally {
+        deps.setCurrentCallId(undefined);
+    }
+}
+async function answerQuestion(deps, text) {
+    const answer = await deps.asks.askQuestion(text);
+    return answer === null ? null : { answer };
+}
+export function createSessionInteractionHandler(deps) {
+    return {
+        async onInteraction(request) {
+            if (request.kind === "question")
+                return answerQuestion(deps, request.text);
+            if (request.kind === "context-tool")
+                throw toolError(`Unknown tool "${request.name}"`, request.name);
+            const tool = deps.embedderTools.get(request.name);
+            return tool !== undefined ? runEmbedderTool(deps, tool, request) : runCodingTool(deps, request);
+        },
+    };
+}