@nathapp/nax-agent 0.1.0 → 0.2.0

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

@@ -0,0 +1,16 @@
+import type { BashApprovalMode } from "#src/config/bash-approval";
+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 provider: string;
+    readonly approvalTimeoutMs: number;
+    readonly turnTimeoutSeconds: number;
+    readonly bashApproval: BashApprovalMode;
+    readonly allowUnsandboxed: boolean;
+    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,137 @@
+/**
+ * Validates createAgentSession's options (spec 4.1, 7). 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 { parseNativeModel } from "#src/native/models";
+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 isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+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.literal("native"),
+    sessionId: z
+        .string()
+        .regex(SESSION_ID, "must be 1-128 letters, digits, '.', '_' or '-', starting with a letter or digit")
+        .optional(),
+    model: z.string().min(1),
+    profile: z.enum(["none", "read", "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(),
+    bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
+    allowUnsandboxed: z.boolean().optional(),
+    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(),
+    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",
+        });
+    }
+    if (isRecord(input) && isRecord(input.hostPorts) && "runDeclaredCommand" in input.hostPorts) {
+        throw invalid("hostPorts.runDeclaredCommand is deferred to a later release", {
+            path: "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 ? "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" });
+    }
+    if (options.profile !== "full" && options.bashApproval !== undefined) {
+        throw invalid('bashApproval applies to profile "full" only', { path: "bashApproval" });
+    }
+    if (options.profile !== "full" && options.allowUnsandboxed !== undefined) {
+        throw invalid('allowUnsandboxed applies to profile "full" only', { path: "allowUnsandboxed" });
+    }
+    if (options.allowUnsandboxed === true && (options.bashApproval ?? "gated") !== "gated") {
+        throw invalid('allowUnsandboxed requires bashApproval "gated"', { path: "allowUnsandboxed" });
+    }
+}
+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);
+    }
+}
+function providerOf(model) {
+    try {
+        return parseNativeModel(model).provider;
+    }
+    catch {
+        throw invalid(`model: "${model}" is not "provider/model[effort]"`, { path: "model" });
+    }
+}
+export function resolveAgentSessionOptions(input) {
+    const options = checkShape(input);
+    checkProfileRules(options);
+    const tools = options.tools ?? [];
+    checkToolNames(tools);
+    return {
+        raw: options,
+        provider: providerOf(options.model),
+        approvalTimeoutMs: options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
+        turnTimeoutSeconds: options.turnTimeoutSeconds ?? DEFAULT_TURN_TIMEOUT_SECONDS,
+        bashApproval: options.bashApproval ?? "gated",
+        allowUnsandboxed: options.allowUnsandboxed === true,
+        metadata: options.metadata ?? {},
+        tools,
+    };
+}

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

@@ -0,0 +1,12 @@
+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, model: string): Promise<TranscriptDoc>;
+/** 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,47 @@
+/**
+ * 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
+ * model that wrote it is the one resuming. The model rule is the loop's own
+ * (transcriptModelIdentity): an effort suffix is not a different model.
+ */
+import { NaxError } from "#src/infra/nax-error";
+import { transcriptModelIdentity } from "#src/native/session/transcript-identity";
+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, model) {
+    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 });
+    }
+    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 });
+    }
+    return doc;
+}
+/** 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,45 @@
+import type { LoopHandlerContext, LoopHandlerSet } from "#src/native/session/loop-events/types";
+import type { TranscriptStore } from "#src/native/session/transcript-types";
+import type { CodingTool } from "#src/tools/registry";
+import type { SessionEvent, SessionEventBody, TurnEndStatus } from "./agent-session-types.ts";
+import type { InteractionHandler } from "./interaction-handler.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;
+    readonly codingTools: readonly CodingTool[];
+    readonly interactionHandler: InteractionHandler;
+    readonly loopHandlers: LoopHandlerSet | undefined;
+    readonly loopHandlerContext: LoopHandlerContext;
+    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,179 @@
+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,
+    };
+    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, {
+        interactionHandler: ctx.interactionHandler,
+        codingTools: ctx.codingTools,
+        maxInteractions: ASK_HUMAN_BUDGET,
+        turnId: live.turnId,
+        signal: live.signal,
+        onTurnEvent: (event) => live.emit(event),
+        loopHandlerContext: ctx.loopHandlerContext,
+        ...(ctx.loopHandlers !== undefined ? { loopHandlers: ctx.loopHandlers } : {}),
+    });
+}
+/** 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 };
+}

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
+ * acpx 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 { 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";
+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 {
+    readonly backend: "native";
+    /** 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;
+    /** 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;
+    /** `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;
+}
+export type TurnEndStatus = "completed" | "cancelled" | "timed_out" | "interrupted" | "errored";
+export type ApprovalDecidedBy = "human" | "timeout" | "cancelled" | "unavailable" | "unshowable";
+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 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 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;
+    /** 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>;