@nathapp/nax-agent 0.1.0 → 0.3.0

package/dist/sandbox/policy-builder.js

@@ -10,7 +10,6 @@ import { isAbsolute, join, resolve } from "node:path";
 import { NaxError } from "#src/infra/index";
 import { realOrRaw } from "#src/internal/realpath";
 import { SANDBOX_GLOB_CHARS } from "../config/schemas-sandbox.js";
-import { NAX_ALWAYS_DENIED_ENTRIES, NAX_SCRATCHPAD_ENTRY, naxWriteOptIns, QUEUE_CONTROL_FILES, } from "../tools/nax-owned-writes.js";
 import { BUILTIN_CACHE_WRITE_ROOTS, BUILTIN_CREDENTIAL_READ_DENIES, MACOS_CACHE_WRITE_ROOT, SRT_MACOS_TMPDIR, SRT_MACOS_TMPDIR_DENIES, } from "./defaults.js";
 import { WORKTREE_COMMON_WRITE_DIRS, WORKTREE_CONFIG_FILE } from "./git-guards.js";
 function expandHome(p, home) {
@@ -62,13 +61,15 @@ function worktreeGitWriteRoots(git) {
     return [git.gitDir, ...WORKTREE_COMMON_WRITE_DIRS.map((dir) => join(git.commonDir, dir))];
 }
 /**
- * nax#2260: every top-level `.nax/` entry, whole, plus the ones nax reads even
- * when absent -- except the scratchpad and entries opted in via allowWrite.
- * srt applies deny over allow and on Linux turns every literal deny into a
- * bind mount, so whole entries (one `features` deny, not one per PRD) keep
- * both the protection and the per-command cost bounded.
+ * nax#2260: every top-level project-state entry, whole, plus the ones the host
+ * loads even when absent (`ownedPaths.deniedEntries`) -- except the scratchpad
+ * and entries opted in via allowWrite. The ENTRIES come from the owned-paths
+ * port; the DIRECTORY comes from `projectStateDir`, and its absence denies
+ * nothing. srt applies deny over allow and on Linux turns every literal deny
+ * into a bind mount, so whole entries (one `features` deny, not one per PRD)
+ * keep both the protection and the per-command cost bounded.
  *
- * Only `<root>/.nax` is covered. A monorepo package's own `.nax/`
+ * Only `<root>/<projectStateDir>` is covered. A monorepo package's own `.nax/`
  * (`packages/<pkg>/.nax/`) is deliberately excluded: what lives there --
  * cache/, scratchpad/, status.json, the features' acceptance tests and run
  * artifacts -- is gitignored and rebuilt or regenerated, so deleting it is
@@ -77,11 +78,14 @@ function worktreeGitWriteRoots(git) {
  * into prompts; covering it needs package discovery, because a `.nax/` at any
  * depth also matches test-fixture projects (`test/fixtures/<p>/.nax/`).
  */
-function naxDenies(root, entries, allowWrite) {
-    const optIns = naxWriteOptIns(root, allowWrite);
-    return [...new Set([...entries, ...NAX_ALWAYS_DENIED_ENTRIES])]
-        .filter((name) => name !== NAX_SCRATCHPAD_ENTRY && !optIns.has(name))
-        .map((name) => join(root, ".nax", name));
+function projectStateDenies(input) {
+    const { root, projectStateDir, ownedPaths } = input;
+    if (projectStateDir === undefined)
+        return [];
+    const optIns = ownedPaths.writeOptIns(root, input.config.filesystem.allowWrite);
+    return [...new Set([...input.naxEntries, ...ownedPaths.deniedEntries])]
+        .filter((name) => name !== ownedPaths.scratchpadEntry && !optIns.has(name))
+        .map((name) => join(root, projectStateDir, name));
 }
 export function buildSandboxPolicy(input) {
     const { root, home, config } = input;
@@ -131,8 +135,8 @@ export function buildSandboxPolicy(input) {
         }),
     ]);
     const denyWrite = literal([
-        ...naxDenies(root, input.naxEntries, config.filesystem.allowWrite),
-        ...[...QUEUE_CONTROL_FILES].map((name) => join(root, name)),
+        ...projectStateDenies(input),
+        ...input.ownedPaths.rootWriteDenies.map((name) => join(root, name)),
         ...gitDenies(root, input.git),
         ...input.gitGuardFiles,
         ...(input.approvalsFile !== undefined ? [input.approvalsFile] : []),

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

@@ -0,0 +1,12 @@
+/** Undelivered control events a turn may queue before it is cancelled as stalled (spec 4.4). */
+export declare const MAX_UNDELIVERED_CONTROL_EVENTS = 1000;
+export declare const _agentSessionDeps: {
+    now: () => number;
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+    randomUUID: () => string;
+    isDirectory: (path: string) => Promise<boolean>;
+    makeScratchRoot: () => Promise<string>;
+    removeScratchRoot: (dir: string) => Promise<void>;
+    controlEventCap: number;
+};

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

@@ -0,0 +1,28 @@
+/**
+ * Injectable clock, timers, ids and filesystem for the agent session facade.
+ * Tests replace members (paired with withDepsRestore) to fire deadlines
+ * without sleeping and to lower the control-event cap. Exported on ./internal.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Undelivered control events a turn may queue before it is cancelled as stalled (spec 4.4). */
+export const MAX_UNDELIVERED_CONTROL_EVENTS = 1000;
+export const _agentSessionDeps = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    randomUUID: () => randomUUID(),
+    isDirectory: async (path) => {
+        try {
+            return (await stat(path)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+    makeScratchRoot: () => mkdtemp(join(tmpdir(), "nax-agent-session-")),
+    removeScratchRoot: (dir) => rm(dir, { recursive: true, force: true }),
+    controlEventCap: MAX_UNDELIVERED_CONTROL_EVENTS,
+};

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

@@ -0,0 +1,11 @@
+/**
+ * The agent session facade's public error (S3 spec section 7). Every code is
+ * namespaced AGENT_SESSION_* so it cannot collide with nax's SESSION_* codes
+ * or registerCodingTool's TOOL_NAME_RESERVED.
+ */
+import { NaxError } from "#src/infra/nax-error";
+export type AgentSessionErrorCode = "AGENT_SESSION_INVALID_OPTIONS" | "AGENT_SESSION_EXISTS" | "AGENT_SESSION_BUSY" | "AGENT_SESSION_CLOSED" | "AGENT_SESSION_INVALID_ANSWER" | "AGENT_SESSION_NOT_FOUND" | "AGENT_SESSION_SCHEMA_UNSUPPORTED" | "AGENT_SESSION_MODEL_MISMATCH" | "AGENT_SESSION_SANDBOX_UNAVAILABLE" | "AGENT_SESSION_TOOL_NAME_RESERVED" | "AGENT_SESSION_BACKEND_UNAVAILABLE" | "AGENT_SESSION_AUTH_REQUIRED" | "AGENT_SESSION_CAPABILITY_UNSUPPORTED" | "AGENT_SESSION_BACKEND_MISMATCH";
+export declare class AgentSessionError extends NaxError {
+    readonly code: AgentSessionErrorCode;
+    constructor(message: string, code: AgentSessionErrorCode, context?: Record<string, unknown>);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * The agent session facade's public error (S3 spec section 7). Every code is
+ * namespaced AGENT_SESSION_* so it cannot collide with nax's SESSION_* codes
+ * or registerCodingTool's TOOL_NAME_RESERVED.
+ */
+import { NaxError } from "#src/infra/nax-error";
+export class AgentSessionError extends NaxError {
+    constructor(message, code, context = {}) {
+        super(message, code, { stage: "agent-session", ...context });
+        this.name = "AgentSessionError";
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { CreateAgentSessionOptions, EmbedderTool } from "./agent-session-types.ts";
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS = 600000;
+export declare const DEFAULT_TURN_TIMEOUT_SECONDS = 3600;
+export interface ResolvedAgentSessionOptions {
+    /** The caller's object, unchanged (tool objects keep their `this`). */
+    readonly raw: CreateAgentSessionOptions;
+    readonly approvalTimeoutMs: number;
+    readonly turnTimeoutSeconds: number;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly tools: readonly EmbedderTool[];
+}
+export declare function resolveAgentSessionOptions(input: unknown): ResolvedAgentSessionOptions;

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

@@ -0,0 +1,96 @@
+/**
+ * Validates createAgentSession's shared options (spec 4.1, 7): the backend
+ * plus the options every backend reads. Native-only options live on
+ * `nativeBackend` (S4). zod checks the shape; the result keeps the caller's
+ * own objects (zod returns copies, which would detach a class-based tool's
+ * methods from `this`).
+ */
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { ASK_HUMAN_TOOL_NAME } from "#src/native/session/ask-human";
+import { RESERVED_TOOL_NAMES } from "#src/tools/registry";
+import { AgentSessionError } from "./agent-session-errors.js";
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 600_000;
+export const DEFAULT_TURN_TIMEOUT_SECONDS = 3600;
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const TOOL_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const STORE_METHODS = ["load", "save", "retainFailed", "delete", "markTurn"];
+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 isFunction = (value) => typeof value === "function";
+const EmbedderToolSchema = z.object({
+    name: z.string().regex(TOOL_NAME, "must be a letter, then letters, digits, _ or -, at most 64 characters"),
+    description: z.string().min(1),
+    inputSchema: z.custom(isRecord, "must be a JSON Schema object"),
+    approval: z.enum(["never", "always"]),
+    describe: z.custom(isFunction, "must be a function").optional(),
+    run: z.custom(isFunction, "must be a function"),
+});
+const OptionsSchema = z.strictObject({
+    backend: z.custom((value) => isRecord(value) && typeof value.kind === "string" && value.kind.length > 0 && typeof value.open === "function", "must be a SessionBackend (for example nativeBackend({ model }))"),
+    sessionId: z
+        .string()
+        .regex(SESSION_ID, "must be 1-128 letters, digits, '.', '_' or '-', starting with a letter or digit")
+        .optional(),
+    profile: z.enum(["none", "read", "ask", "full"]),
+    workdir: z
+        .string()
+        .refine((dir) => isAbsolute(dir), "must be an absolute path")
+        .optional(),
+    instructions: z.string().optional(),
+    tools: z.array(EmbedderToolSchema).optional(),
+    transcriptStore: z.custom(hasMethods(STORE_METHODS), `must implement ${STORE_METHODS.join(", ")}`),
+    approvalTimeoutMs: z.number().int().min(30_000).max(3_600_000).optional(),
+    metadata: z.record(z.string(), z.string()).optional(),
+    turnTimeoutSeconds: z.number().int().min(1).max(86_400).optional(),
+});
+function invalid(message, context = {}) {
+    return new AgentSessionError(`Invalid agent session options: ${message}`, "AGENT_SESSION_INVALID_OPTIONS", context);
+}
+function checkShape(input) {
+    if (isRecord(input) && "mcpServers" in input) {
+        throw invalid("mcpServers is reserved for a later release (an MCP client for embedder tools)", {
+            path: "mcpServers",
+        });
+    }
+    const parsed = OptionsSchema.safeParse(input);
+    if (parsed.success)
+        return input;
+    const issue = parsed.error.issues[0];
+    const path = issue === undefined || issue.path.length === 0 ? "options" : issue.path.join(".");
+    throw invalid(`${path}: ${issue?.message ?? "invalid"}`, { path });
+}
+function checkProfileRules(options) {
+    if (options.profile !== "none" && options.workdir === undefined) {
+        throw invalid(`workdir is required for profile "${options.profile}"`, { path: "workdir" });
+    }
+}
+function checkToolNames(tools) {
+    const reserved = new Set([...RESERVED_TOOL_NAMES, ASK_HUMAN_TOOL_NAME]);
+    const seen = new Set();
+    for (const tool of tools) {
+        if (reserved.has(tool.name)) {
+            throw new AgentSessionError(`Embedder tool name "${tool.name}" is reserved for a built-in tool`, "AGENT_SESSION_TOOL_NAME_RESERVED", { tool: tool.name });
+        }
+        if (seen.has(tool.name))
+            throw invalid(`tools: duplicate tool name "${tool.name}"`, { path: "tools" });
+        seen.add(tool.name);
+    }
+}
+export function resolveAgentSessionOptions(input) {
+    const options = checkShape(input);
+    checkProfileRules(options);
+    const tools = options.tools ?? [];
+    checkToolNames(tools);
+    return {
+        raw: options,
+        approvalTimeoutMs: options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
+        turnTimeoutSeconds: options.turnTimeoutSeconds ?? DEFAULT_TURN_TIMEOUT_SECONDS,
+        metadata: options.metadata ?? {},
+        tools,
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { TranscriptDoc, TranscriptStore } from "#src/native/session/transcript-types";
+import type { CreateAgentSessionOptions } from "./agent-session-types.ts";
+/**
+ * The options to validate for a resume: the argument is the session id. A
+ * different `options.sessionId` is a caller bug, refused before the store is
+ * read. Non-object options pass through for the option validator to reject.
+ */
+export declare function resumeInput(sessionId: string, options: CreateAgentSessionOptions): unknown;
+/** The stored document a resume starts from. Throws when there is none or this session may not read it. */
+export declare function loadResumable(store: TranscriptStore, sessionId: string): Promise<TranscriptDoc>;
+/** The stored document's backend (absent means native) must be the resuming backend's (S4 spec 5.5). */
+export declare function checkBackendKind(doc: TranscriptDoc, sessionId: string, kind: string): void;
+/** The turn a dead process left running (spec 6.4), or undefined. */
+export declare function interruptedTurnOf(doc: TranscriptDoc): string | undefined;

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

@@ -0,0 +1,49 @@
+/**
+ * resumeAgentSession's checks on the stored document (S3 spec 4.2, 6.4). They
+ * run before any backend opens: the id comes from the argument, the document
+ * exists, this build reads its schema, its messages are an array, and the
+ * backend that wrote it is the one resuming (S4 spec 5.5). A backend's own
+ * model rule (an effort suffix is not a different model) runs in its `open`.
+ */
+import { NaxError } from "#src/infra/nax-error";
+import { AgentSessionError } from "./agent-session-errors.js";
+/**
+ * The options to validate for a resume: the argument is the session id. A
+ * different `options.sessionId` is a caller bug, refused before the store is
+ * read. Non-object options pass through for the option validator to reject.
+ */
+export function resumeInput(sessionId, options) {
+    if (typeof options !== "object" || options === null)
+        return options;
+    if (options.sessionId !== undefined && options.sessionId !== sessionId) {
+        throw new AgentSessionError(`Invalid agent session options: sessionId "${options.sessionId}" is not the session being resumed ("${sessionId}")`, "AGENT_SESSION_INVALID_OPTIONS", { path: "sessionId" });
+    }
+    return { ...options, sessionId };
+}
+/** The stored document a resume starts from. Throws when there is none or this session may not read it. */
+export async function loadResumable(store, sessionId) {
+    const doc = await store.load(sessionId);
+    if (doc === null) {
+        throw new AgentSessionError(`Session "${sessionId}" has no document in the transcript store`, "AGENT_SESSION_NOT_FOUND", { sessionId });
+    }
+    const version = doc.schemaVersion;
+    if (version !== undefined && version !== 1) {
+        throw new AgentSessionError(`Session "${sessionId}" has transcript schemaVersion ${String(version)}; this build reads 1`, "AGENT_SESSION_SCHEMA_UNSUPPORTED", { sessionId });
+    }
+    if (!Array.isArray(doc.messages)) {
+        throw new NaxError(`transcript for session "${sessionId}" is unreadable: messages is not an array`, "TRANSCRIPT_CORRUPT", { stage: "agent-session", sessionId });
+    }
+    return doc;
+}
+/** The stored document's backend (absent means native) must be the resuming backend's (S4 spec 5.5). */
+export function checkBackendKind(doc, sessionId, kind) {
+    const stored = doc.backend ?? "native";
+    if (stored !== kind) {
+        throw new AgentSessionError(`Session "${sessionId}" was written by backend "${stored}"; it cannot be resumed with "${kind}"`, "AGENT_SESSION_BACKEND_MISMATCH", { sessionId, stored, kind });
+    }
+}
+/** The turn a dead process left running (spec 6.4), or undefined. */
+export function interruptedTurnOf(doc) {
+    const turn = doc.turn;
+    return turn?.state === "running" && typeof turn.turnId === "string" ? turn.turnId : undefined;
+}

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

@@ -0,0 +1,41 @@
+import type { TranscriptStore } from "#src/native/session/transcript-types";
+import type { SessionEvent, SessionEventBody, TurnEndStatus } from "./agent-session-types.ts";
+import type { TurnContribution } from "./session-backend.ts";
+import { type AgentSessionAdapter, type SessionHandle, type TurnResult } from "./session-types.ts";
+/** The ask_human budget per turn: nax's agent.maxInteractionTurns default. */
+export declare const ASK_HUMAN_BUDGET = 10;
+export interface TurnRunContext {
+    readonly sessionId: string;
+    readonly adapter: AgentSessionAdapter;
+    readonly handle: SessionHandle;
+    readonly store: TranscriptStore;
+    /** The backend's per-turn contribution, read at each sendTurn. */
+    readonly turnOpts: () => TurnContribution;
+    readonly turnTimeoutSeconds: number;
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/** The running turn, as the ask link and the interaction handler see it. */
+export interface LiveTurn {
+    readonly turnId: string;
+    readonly signal: AbortSignal;
+    emit(body: SessionEventBody): void;
+}
+export interface ClaimedTurn {
+    readonly turnId: string;
+    readonly iterable: AsyncIterable<SessionEvent>;
+    /** Resolves once the turn has ended, or at once for a claim voided before it started. */
+    readonly settled: Promise<void>;
+    cancel(reason: string): void;
+}
+export interface ClaimTurnHooks {
+    readonly onStart: (live: LiveTurn) => void;
+    /** Runs before turn_end is emitted. `status` is undefined for a voided claim. */
+    readonly onSettle: (turnId: string, status: TurnEndStatus | undefined) => void;
+}
+type TurnEndBody = Extract<SessionEventBody, {
+    readonly type: "turn_end";
+}>;
+/** Maps a returned TurnResult to turn_end. Exported for its unit test. */
+export declare function turnEndFromResult(result: TurnResult): TurnEndBody;
+export declare function claimTurn(ctx: TurnRunContext, message: string, hooks: ClaimTurnHooks): ClaimedTurn;
+export {};

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

@@ -0,0 +1,177 @@
+import { NaxError } from "#src/infra/nax-error";
+import { redactSecrets } from "#src/internal/redact";
+import { readNativeTurnFailureUsage } from "#src/native/session/turn-types";
+import { _agentSessionDeps } from "./agent-session-deps.js";
+import { AgentSessionError } from "./agent-session-errors.js";
+import { createSessionEventChannel } from "./session-event-channel.js";
+import { SessionTurnError } from "./session-types.js";
+/** The ask_human budget per turn: nax's agent.maxInteractionTurns default. */
+export const ASK_HUMAN_BUDGET = 10;
+/** Codes of the turn signal's abort reasons. AbortSignal keeps the first reason, so the first cause wins. */
+const CANCELLED = "AGENT_SESSION_CANCELLED";
+const TIMED_OUT = "AGENT_SESSION_TURN_TIMEOUT";
+const STALLED = "AGENT_SESSION_CONSUMER_STALLED";
+const ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
+function abortReason(code, message) {
+    return new NaxError(message, code, { stage: "agent-session" });
+}
+function abortCode(signal) {
+    return signal.aborted && signal.reason instanceof NaxError ? signal.reason.code : undefined;
+}
+function failure(code, message) {
+    return { code, message: redactSecrets(message) };
+}
+function haltOf(result) {
+    if (result.spinStopped === true) {
+        return failure("AGENT_SESSION_SPIN_STOPPED", "The turn was stopped: the agent repeated calls without progress.");
+    }
+    if (result.invalidCallBudgetExceeded === true) {
+        const call = result.invalidToolCall;
+        const detail = call === undefined ? "" : ` (${call.tool}.${call.property}: expected ${call.expected}, got ${call.actual})`;
+        return failure("AGENT_SESSION_INVALID_TOOL_CALLS", `The turn was stopped after repeated invalid tool calls${detail}.`);
+    }
+    if (result.turnIncomplete === true) {
+        return failure("AGENT_SESSION_TURN_INCOMPLETE", "The turn ended with tool calls still pending.");
+    }
+    return undefined;
+}
+/** Maps a returned TurnResult to turn_end. Exported for its unit test. */
+export function turnEndFromResult(result) {
+    const base = {
+        type: "turn_end",
+        output: result.output,
+        usage: result.tokenUsage,
+        costUsd: result.exactCostUsd ?? result.estimatedCostUsd,
+        ...(result.costSource !== undefined ? { costSource: result.costSource } : {}),
+    };
+    if (result.timedOut === true)
+        return { ...base, status: "timed_out" };
+    const halt = haltOf(result);
+    return halt === undefined ? { ...base, status: "completed" } : { ...base, status: "errored", error: halt };
+}
+function errorOf(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof SessionTurnError && err.adapterFailure !== undefined)
+        return failure(err.adapterFailure.outcome, message);
+    if (err instanceof NaxError)
+        return failure(err.code, message);
+    return failure("AGENT_SESSION_TURN_FAILED", message);
+}
+function spendOf(err) {
+    const recorded = readNativeTurnFailureUsage(err);
+    if (recorded !== undefined)
+        return { usage: recorded.tokenUsage, costUsd: recorded.costUsd };
+    if (err instanceof SessionTurnError)
+        return { usage: err.tokenUsage ?? ZERO_USAGE, costUsd: err.estimatedCostUsd ?? 0 };
+    return { usage: ZERO_USAGE, costUsd: 0 };
+}
+function fromError(err, signal) {
+    const base = { type: "turn_end", output: "", ...spendOf(err) };
+    const code = abortCode(signal);
+    if (code === STALLED) {
+        const message = `More than ${_agentSessionDeps.controlEventCap} control events went undelivered; the turn was cancelled.`;
+        return { ...base, status: "errored", error: failure(STALLED, message) };
+    }
+    if (code === TIMED_OUT)
+        return { ...base, status: "timed_out" };
+    if (signal.aborted)
+        return { ...base, status: "cancelled" };
+    return { ...base, status: "errored", error: errorOf(err) };
+}
+function sendTurn(ctx, live, message) {
+    return ctx.adapter.sendTurn(ctx.handle, message, {
+        ...ctx.turnOpts(),
+        maxInteractions: ASK_HUMAN_BUDGET,
+        turnId: live.turnId,
+        signal: live.signal,
+        onTurnEvent: (event) => live.emit(event),
+    });
+}
+/** Writes the turn marker; a failure is returned, not thrown. */
+async function markTurn(ctx, turnId, state) {
+    try {
+        await ctx.store.markTurn(ctx.sessionId, { turnId, state });
+        return undefined;
+    }
+    catch (error) {
+        return { error };
+    }
+}
+async function runTurn(ctx, live, message) {
+    live.emit({ type: "turn_start" });
+    const started = await markTurn(ctx, live.turnId, "running");
+    if (started !== undefined)
+        return fromError(started.error, live.signal);
+    let end;
+    try {
+        end = turnEndFromResult(await sendTurn(ctx, live, message));
+    }
+    catch (err) {
+        end = fromError(err, live.signal);
+    }
+    const ended = await markTurn(ctx, live.turnId, "ended");
+    // A failed end marker fails the turn (spec 5.5) but keeps its output and spend.
+    return ended === undefined ? end : { ...end, status: "errored", error: errorOf(ended.error) };
+}
+function singleUse(iterator, sessionId) {
+    let taken = false;
+    return {
+        [Symbol.asyncIterator]() {
+            if (taken) {
+                throw new AgentSessionError("send() returns a single-use iterable; iterate it once", "AGENT_SESSION_BUSY", {
+                    sessionId,
+                });
+            }
+            taken = true;
+            return iterator;
+        },
+    };
+}
+export function claimTurn(ctx, message, hooks) {
+    const turnId = _agentSessionDeps.randomUUID();
+    const controller = new AbortController();
+    let state = "claimed";
+    let resolveSettled = () => { };
+    const settled = new Promise((resolve) => {
+        resolveSettled = resolve;
+    });
+    const channel = createSessionEventChannel({
+        controlCap: _agentSessionDeps.controlEventCap,
+        onFirstPull: () => start(),
+        onReturn: () => cancel("iterator closed"),
+        onStall: () => controller.abort(abortReason(STALLED, "consumer stalled")),
+    });
+    const emit = (body) => {
+        const at = new Date(_agentSessionDeps.now()).toISOString();
+        channel.push({ sessionId: ctx.sessionId, turnId, at, metadata: ctx.metadata, ...body });
+    };
+    const live = { turnId, signal: controller.signal, emit };
+    function settle(end) {
+        state = "settled";
+        hooks.onSettle(turnId, end?.status);
+        if (end !== undefined)
+            emit(end);
+        channel.end();
+        resolveSettled();
+    }
+    function start() {
+        if (state !== "claimed")
+            return;
+        state = "running";
+        const timer = _agentSessionDeps.setTimeout(() => controller.abort(abortReason(TIMED_OUT, "turn deadline")), ctx.turnTimeoutSeconds * 1000);
+        hooks.onStart(live);
+        void runTurn(ctx, live, message)
+            .catch((err) => fromError(err, controller.signal))
+            .then((end) => {
+            _agentSessionDeps.clearTimeout(timer);
+            settle(end);
+        });
+    }
+    function cancel(reason) {
+        if (state === "claimed")
+            settle(undefined);
+        else if (state === "running")
+            controller.abort(abortReason(CANCELLED, reason));
+    }
+    return { turnId, iterable: singleUse(channel.iterator, ctx.sessionId), settled, cancel };
+}