agents 0.26.0 → 0.28.0

package/dist/stall-watchdog-BpRF2uwG.js

@@ -0,0 +1,195 @@
+import { t as CHAT_MESSAGE_TYPES } from "./protocol-eXeJxhgu.js";
+import { jsonSchema, tool } from "ai";
+//#region src/chat/client-tools.ts
+/**
+* Converts client tool schemas to AI SDK tool format.
+*
+* By default these tools have no `execute` function — when the AI model calls
+* them, the tool call is sent back to the client for execution.
+*
+* When `options.execute` is provided, each tool is built WITH an `execute` that
+* delegates to it. This is used by the RPC path (e.g. a parent agent driving a
+* Think sub-agent) so the model's client-tool call is resolved inline within
+* the same turn.
+*
+* @param clientTools - Array of tool schemas from the client
+* @param options - Optional `execute` delegate to run the tools inline
+* @returns Record of AI SDK tools that can be spread into your tools object
+*/
+function createToolsFromClientSchemas(clientTools, options) {
+	if (!clientTools || clientTools.length === 0) return {};
+	const seenNames = /* @__PURE__ */ new Set();
+	for (const t of clientTools) {
+		if (seenNames.has(t.name)) console.warn(`[createToolsFromClientSchemas] Duplicate tool name "${t.name}" found. Later definitions will override earlier ones.`);
+		seenNames.add(t.name);
+	}
+	const execute = options?.execute;
+	const createTool = tool;
+	return Object.fromEntries(clientTools.map((t) => [t.name, createTool({
+		description: typeof t.description === "function" ? "" : t.description ?? "",
+		inputSchema: jsonSchema(t.parameters ?? { type: "object" }),
+		...execute ? { execute: (input, executeOptions) => execute({
+			toolName: t.name,
+			input,
+			toolCallId: executeOptions?.toolCallId ?? ""
+		}) } : {}
+	})]));
+}
+//#endregion
+//#region src/chat/parse-protocol.ts
+/**
+* Protocol Message Parser — typed parsing of cf_agent_chat_* WebSocket messages.
+*
+* Parses raw WebSocket messages into a discriminated union of protocol events.
+* Both AIChatAgent and Think can use this instead of manual JSON.parse + type checking.
+*/
+/**
+* Parse a raw WebSocket message string into a typed protocol event.
+*
+* Returns `null` if the message is not valid JSON or not a recognized
+* protocol message type. Callers should fall through to the user's
+* `onMessage` handler when `null` is returned.
+*
+* @example
+* ```typescript
+* const event = parseProtocolMessage(rawMessage);
+* if (!event) return userOnMessage(connection, rawMessage);
+*
+* switch (event.type) {
+*   case "chat-request": { ... }
+*   case "clear": { ... }
+*   case "tool-result": { ... }
+* }
+* ```
+*/
+function parseProtocolMessage(raw) {
+	let data;
+	try {
+		data = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	const wireType = data.type;
+	if (!wireType) return null;
+	switch (wireType) {
+		case CHAT_MESSAGE_TYPES.USE_CHAT_REQUEST: return {
+			type: "chat-request",
+			id: data.id,
+			init: data.init ?? {}
+		};
+		case CHAT_MESSAGE_TYPES.CHAT_CLEAR: return { type: "clear" };
+		case CHAT_MESSAGE_TYPES.CHAT_REQUEST_CANCEL: return {
+			type: "cancel",
+			id: data.id
+		};
+		case CHAT_MESSAGE_TYPES.TOOL_RESULT: return {
+			type: "tool-result",
+			toolCallId: data.toolCallId,
+			toolName: data.toolName ?? "",
+			output: data.output,
+			state: data.state,
+			errorText: data.errorText,
+			autoContinue: data.autoContinue,
+			clientTools: data.clientTools
+		};
+		case CHAT_MESSAGE_TYPES.TOOL_APPROVAL: return {
+			type: "tool-approval",
+			toolCallId: data.toolCallId,
+			approved: data.approved,
+			autoContinue: data.autoContinue
+		};
+		case CHAT_MESSAGE_TYPES.STREAM_RESUME_REQUEST: return {
+			type: "stream-resume-request",
+			...typeof data.probeId === "string" ? { probeId: data.probeId } : {}
+		};
+		case CHAT_MESSAGE_TYPES.STREAM_RESUME_ACK: return {
+			type: "stream-resume-ack",
+			id: data.id
+		};
+		case CHAT_MESSAGE_TYPES.CHAT_MESSAGES: return {
+			type: "messages",
+			messages: data.messages ?? []
+		};
+		default: return null;
+	}
+}
+//#endregion
+//#region src/chat/stall-watchdog.ts
+/**
+* Shared inactivity watchdog for UI-message streams.
+*
+* A model/transport stream can park indefinitely without ever throwing (a hung
+* provider, a wedged transport). Left unguarded, the consumer read-loop waits
+* forever. {@link iterateWithStallWatchdog} wraps such a stream so that a gap of
+* `timeoutMs` between chunks aborts the upstream and throws
+* {@link ChatStreamStalledError}, letting the consumer route the stall into
+* bounded recovery (#1626) — a transient hang is retried within the existing
+* recovery budget — while genuine in-band errors stay terminal.
+*
+* @internal Sibling-package support for `@cloudflare/ai-chat` and
+* `@cloudflare/think`, not a public API. See
+* `design/rfc-chat-recovery-foundation.md`.
+*/
+/**
+* Thrown by {@link iterateWithStallWatchdog} when the inactivity watchdog fires
+* (a model/transport stream that parks without ever throwing). Distinct from
+* in-band model/stream errors so the read-loop catch can route a stall into
+* bounded recovery (#1626) — a transient hang is retried within the existing
+* recovery budget — while genuine errors stay terminal.
+*/
+var ChatStreamStalledError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.isChatStreamStall = true;
+		this.name = "ChatStreamStalledError";
+	}
+};
+/**
+* Wrap a UI-message stream with an inactivity watchdog. If no chunk arrives
+* within `timeoutMs`, `onStall` runs (aborting the upstream model stream) and
+* the iterator throws, so the consumer loop exits with a terminal error
+* instead of parking forever on a hung provider/transport. `timeoutMs <= 0`
+* passes the source through untouched.
+*/
+async function* iterateWithStallWatchdog(source, timeoutMs, onStall) {
+	if (!(timeoutMs > 0)) {
+		yield* source;
+		return;
+	}
+	const iterator = source[Symbol.asyncIterator]();
+	let selfAborted = false;
+	try {
+		while (true) {
+			let timer;
+			let stalled = false;
+			const stall = new Promise((_, reject) => {
+				timer = setTimeout(() => {
+					stalled = true;
+					reject(new ChatStreamStalledError(`Chat stream stalled: no activity for ${timeoutMs}ms; the turn was aborted by the stall watchdog.`));
+				}, timeoutMs);
+			});
+			const nextPromise = iterator.next();
+			nextPromise.catch(() => {});
+			let next;
+			try {
+				next = await Promise.race([nextPromise, stall]);
+			} catch (err) {
+				if (stalled) {
+					selfAborted = true;
+					onStall();
+				}
+				throw err;
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+			}
+			if (next.done) return;
+			yield next.value;
+		}
+	} finally {
+		if (!selfAborted) await iterator.return?.(void 0).catch(() => {});
+	}
+}
+//#endregion
+export { createToolsFromClientSchemas as i, iterateWithStallWatchdog as n, parseProtocolMessage as r, ChatStreamStalledError as t };
+
+//# sourceMappingURL=stall-watchdog-BpRF2uwG.js.map

package/dist/stall-watchdog-BpRF2uwG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall-watchdog-BpRF2uwG.js","names":[],"sources":["../src/chat/client-tools.ts","../src/chat/parse-protocol.ts","../src/chat/stall-watchdog.ts"],"sourcesContent":["/**\n * Client tool schema handling for the cf_agent_chat protocol.\n *\n * Converts client-provided tool schemas (JSON wire format) into AI SDK\n * tool definitions. By default these tools have no `execute` function —\n * when the model calls them, the tool call is sent back to the client.\n *\n * When an `execute` delegate is supplied (e.g. a parent agent that drives a\n * Think sub-agent over RPC and can run the client tools itself), the tools are\n * built WITH an `execute` so the model's call is resolved inline within the\n * same turn instead of being surfaced as a dangling tool call.\n *\n * Used by both @cloudflare/ai-chat and @cloudflare/think.\n */\n\nimport type { JSONSchema7, Tool, ToolSet } from \"ai\";\nimport { tool, jsonSchema } from \"ai\";\n\n/**\n * Wire-format tool schema sent from the client.\n * Uses `parameters` (JSONSchema7) rather than AI SDK's `inputSchema`\n * because Zod schemas cannot be serialized over the wire.\n */\nexport type ClientToolSchema = {\n  /** Unique name for the tool */\n  name: string;\n  /** Human-readable description of what the tool does */\n  description?: Tool[\"description\"];\n  /** JSON Schema defining the tool's input parameters */\n  parameters?: JSONSchema7;\n};\n\n/**\n * Executes a client-defined tool and returns its output.\n *\n * Used for the RPC path (e.g. a parent agent delegating to a Think sub-agent)\n * where the caller can run the client tools itself, rather than the\n * browser/WebSocket path where results are sent back asynchronously.\n */\nexport type ClientToolExecutor = (call: {\n  /** The name of the client tool the model called. */\n  toolName: string;\n  /** The model-generated input for the tool call. */\n  input: unknown;\n  /** The AI SDK tool-call id for the invocation. */\n  toolCallId: string;\n}) => unknown | Promise<unknown>;\n\n/**\n * Converts client tool schemas to AI SDK tool format.\n *\n * By default these tools have no `execute` function — when the AI model calls\n * them, the tool call is sent back to the client for execution.\n *\n * When `options.execute` is provided, each tool is built WITH an `execute` that\n * delegates to it. This is used by the RPC path (e.g. a parent agent driving a\n * Think sub-agent) so the model's client-tool call is resolved inline within\n * the same turn.\n *\n * @param clientTools - Array of tool schemas from the client\n * @param options - Optional `execute` delegate to run the tools inline\n * @returns Record of AI SDK tools that can be spread into your tools object\n */\nexport function createToolsFromClientSchemas(\n  clientTools?: ClientToolSchema[],\n  options?: { execute?: ClientToolExecutor }\n): ToolSet {\n  if (!clientTools || clientTools.length === 0) {\n    return {};\n  }\n\n  const seenNames = new Set<string>();\n  for (const t of clientTools) {\n    if (seenNames.has(t.name)) {\n      console.warn(\n        `[createToolsFromClientSchemas] Duplicate tool name \"${t.name}\" found. Later definitions will override earlier ones.`\n      );\n    }\n    seenNames.add(t.name);\n  }\n\n  const execute = options?.execute;\n  // The AI SDK's `tool()` overloads infer the input type as `never` when an\n  // `execute` is combined with a runtime `jsonSchema(...)`. Cast to a\n  // permissive signature (same approach as `agentTool()`), since the wire\n  // schema is untyped JSON.\n  const createTool = tool as unknown as (config: {\n    description: string | ((options: unknown) => string);\n    inputSchema: ReturnType<typeof jsonSchema>;\n    execute?: (\n      input: unknown,\n      executeOptions?: { toolCallId?: string }\n    ) => unknown | Promise<unknown>;\n  }) => Tool;\n\n  return Object.fromEntries(\n    clientTools.map((t) => [\n      t.name,\n      createTool({\n        description:\n          typeof t.description === \"function\" ? \"\" : (t.description ?? \"\"),\n        inputSchema: jsonSchema(t.parameters ?? { type: \"object\" }),\n        ...(execute\n          ? {\n              execute: (\n                input: unknown,\n                executeOptions?: { toolCallId?: string }\n              ) =>\n                execute({\n                  toolName: t.name,\n                  input,\n                  toolCallId: executeOptions?.toolCallId ?? \"\"\n                })\n            }\n          : {})\n      })\n    ])\n  );\n}\n","/**\n * Protocol Message Parser — typed parsing of cf_agent_chat_* WebSocket messages.\n *\n * Parses raw WebSocket messages into a discriminated union of protocol events.\n * Both AIChatAgent and Think can use this instead of manual JSON.parse + type checking.\n */\n\nimport { CHAT_MESSAGE_TYPES } from \"./protocol\";\n\n/**\n * Discriminated union of all incoming chat protocol events.\n *\n * Each agent handles the events it cares about and ignores the rest.\n * Returns `null` for non-JSON messages or unrecognized types.\n */\nexport type ChatProtocolEvent =\n  | {\n      type: \"chat-request\";\n      id: string;\n      init: { method?: string; body?: string; [key: string]: unknown };\n    }\n  | { type: \"clear\" }\n  | { type: \"cancel\"; id: string }\n  | {\n      type: \"tool-result\";\n      toolCallId: string;\n      toolName: string;\n      output: unknown;\n      state?: string;\n      errorText?: string;\n      autoContinue?: boolean;\n      clientTools?: Array<{\n        name: string;\n        description?: string;\n        parameters?: unknown;\n      }>;\n    }\n  | {\n      type: \"tool-approval\";\n      toolCallId: string;\n      approved: boolean;\n      autoContinue?: boolean;\n    }\n  | { type: \"stream-resume-request\"; probeId?: string }\n  | { type: \"stream-resume-ack\"; id: string }\n  | { type: \"messages\"; messages: unknown[] };\n\n/**\n * Parse a raw WebSocket message string into a typed protocol event.\n *\n * Returns `null` if the message is not valid JSON or not a recognized\n * protocol message type. Callers should fall through to the user's\n * `onMessage` handler when `null` is returned.\n *\n * @example\n * ```typescript\n * const event = parseProtocolMessage(rawMessage);\n * if (!event) return userOnMessage(connection, rawMessage);\n *\n * switch (event.type) {\n *   case \"chat-request\": { ... }\n *   case \"clear\": { ... }\n *   case \"tool-result\": { ... }\n * }\n * ```\n */\nexport function parseProtocolMessage(raw: string): ChatProtocolEvent | null {\n  let data: Record<string, unknown>;\n  try {\n    data = JSON.parse(raw) as Record<string, unknown>;\n  } catch {\n    return null;\n  }\n\n  const wireType = data.type as string | undefined;\n  if (!wireType) return null;\n\n  switch (wireType) {\n    case CHAT_MESSAGE_TYPES.USE_CHAT_REQUEST:\n      return {\n        type: \"chat-request\",\n        id: data.id as string,\n        init: (data.init as { method?: string; body?: string }) ?? {}\n      };\n\n    case CHAT_MESSAGE_TYPES.CHAT_CLEAR:\n      return { type: \"clear\" };\n\n    case CHAT_MESSAGE_TYPES.CHAT_REQUEST_CANCEL:\n      return { type: \"cancel\", id: data.id as string };\n\n    case CHAT_MESSAGE_TYPES.TOOL_RESULT:\n      return {\n        type: \"tool-result\",\n        toolCallId: data.toolCallId as string,\n        toolName: (data.toolName as string) ?? \"\",\n        output: data.output,\n        state: data.state as string | undefined,\n        errorText: data.errorText as string | undefined,\n        autoContinue: data.autoContinue as boolean | undefined,\n        clientTools: data.clientTools as\n          | Array<{\n              name: string;\n              description?: string;\n              parameters?: unknown;\n            }>\n          | undefined\n      };\n\n    case CHAT_MESSAGE_TYPES.TOOL_APPROVAL:\n      return {\n        type: \"tool-approval\",\n        toolCallId: data.toolCallId as string,\n        approved: data.approved as boolean,\n        autoContinue: data.autoContinue as boolean | undefined\n      };\n\n    case CHAT_MESSAGE_TYPES.STREAM_RESUME_REQUEST:\n      return {\n        type: \"stream-resume-request\",\n        ...(typeof data.probeId === \"string\" ? { probeId: data.probeId } : {})\n      };\n\n    case CHAT_MESSAGE_TYPES.STREAM_RESUME_ACK:\n      return {\n        type: \"stream-resume-ack\",\n        id: data.id as string\n      };\n\n    case CHAT_MESSAGE_TYPES.CHAT_MESSAGES:\n      return {\n        type: \"messages\",\n        messages: (data.messages as unknown[]) ?? []\n      };\n\n    default:\n      return null;\n  }\n}\n","/**\n * Shared inactivity watchdog for UI-message streams.\n *\n * A model/transport stream can park indefinitely without ever throwing (a hung\n * provider, a wedged transport). Left unguarded, the consumer read-loop waits\n * forever. {@link iterateWithStallWatchdog} wraps such a stream so that a gap of\n * `timeoutMs` between chunks aborts the upstream and throws\n * {@link ChatStreamStalledError}, letting the consumer route the stall into\n * bounded recovery (#1626) — a transient hang is retried within the existing\n * recovery budget — while genuine in-band errors stay terminal.\n *\n * @internal Sibling-package support for `@cloudflare/ai-chat` and\n * `@cloudflare/think`, not a public API. See\n * `design/rfc-chat-recovery-foundation.md`.\n */\n\n/**\n * Thrown by {@link iterateWithStallWatchdog} when the inactivity watchdog fires\n * (a model/transport stream that parks without ever throwing). Distinct from\n * in-band model/stream errors so the read-loop catch can route a stall into\n * bounded recovery (#1626) — a transient hang is retried within the existing\n * recovery budget — while genuine errors stay terminal.\n */\nexport class ChatStreamStalledError extends Error {\n  readonly isChatStreamStall = true;\n  constructor(message: string) {\n    super(message);\n    this.name = \"ChatStreamStalledError\";\n  }\n}\n\n/**\n * Wrap a UI-message stream with an inactivity watchdog. If no chunk arrives\n * within `timeoutMs`, `onStall` runs (aborting the upstream model stream) and\n * the iterator throws, so the consumer loop exits with a terminal error\n * instead of parking forever on a hung provider/transport. `timeoutMs <= 0`\n * passes the source through untouched.\n */\nexport async function* iterateWithStallWatchdog<T>(\n  source: AsyncIterable<T>,\n  timeoutMs: number,\n  onStall: () => void\n): AsyncGenerator<T> {\n  if (!(timeoutMs > 0)) {\n    yield* source;\n    return;\n  }\n  const iterator = source[Symbol.asyncIterator]();\n  // Tracks whether the watchdog itself aborted the upstream. In that case we\n  // must NOT also `iterator.return()` it: cancelling the readable after the\n  // abort makes the AI SDK pipeline write to an already-cancelled readable\n  // (\"readable side is no longer readable\"). Letting the abort error the\n  // stream is the clean path.\n  let selfAborted = false;\n  try {\n    while (true) {\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      let stalled = false;\n      const stall = new Promise<never>((_, reject) => {\n        timer = setTimeout(() => {\n          stalled = true;\n          reject(\n            new ChatStreamStalledError(\n              `Chat stream stalled: no activity for ${timeoutMs}ms; the turn was aborted by the stall watchdog.`\n            )\n          );\n        }, timeoutMs);\n      });\n      const nextPromise = iterator.next();\n      // If the watchdog wins the race we abandon this read; aborting the\n      // upstream stream makes it reject later, so pre-attach a no-op catch to\n      // keep that abandoned rejection from surfacing as an unhandled rejection.\n      nextPromise.catch(() => {});\n      let next: IteratorResult<T>;\n      try {\n        next = await Promise.race([nextPromise, stall]);\n      } catch (err) {\n        if (stalled) {\n          selfAborted = true;\n          onStall();\n        }\n        throw err;\n      } finally {\n        if (timer !== undefined) clearTimeout(timer);\n      }\n      if (next.done) return;\n      yield next.value;\n    }\n  } finally {\n    // Forward early termination (consumer `break`/`throw`, e.g. an in-band\n    // stream error where the abort signal is NOT set) to the source so its\n    // reader is cancelled — otherwise the wrapped source would leak when the\n    // consumer stops reading mid-stream. Skipped after a watchdog stall, which\n    // already aborted the upstream (see `selfAborted` above).\n    if (!selfAborted) {\n      await iterator.return?.(undefined as never).catch(() => {});\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/state/index.d.ts

@@ -2,5 +2,5 @@ import {
   n as StateChangeSource,
   r as StateOptions,
   t as State
-} from "../index-BreL0YrQ.js";
+} from "../index-BEL3ZV-s.js";
 export { State, StateChangeSource, StateOptions };

package/dist/state/index.js

@@ -1,6 +1,6 @@
 import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _assertClassBrand, t as _classPrivateFieldGet2 } from "../classPrivateFieldGet2-DZBYAB34.js";
 import { t as _classPrivateMethodInitSpec } from "../classPrivateMethodInitSpec-qMjJ6sHQ.js";
-import { t as LifecycleCapability } from "../capability-B4WbF81e.js";
+import { t as LifecycleCapability } from "../capability-DBAKc6UZ.js";
 //#region src/state/index.ts
 /**
 * Namespaced KV key holding this capability's schema version. Kept separate
@@ -33,8 +33,6 @@ var _State_brand = /* @__PURE__ */ new WeakSet();
 * validated persistence. Install the instance with `Lifecycle.use()`. State
 * validation and the post-change notification hook stay on the host, which
 * injects both callbacks. This capability never touches connections.
-*
-* @experimental The API surface may change before stabilizing.
 */
 var State = class extends LifecycleCapability {
 	/**

package/dist/state/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/state/index.ts"],"sourcesContent":["import { LifecycleCapability } from \"../lifecycle/capability\";\nimport type { Connection } from \"../lifecycle/durable-object-lifecycle\";\n\n/**\n * Source of a state change: `\"server\"` for host code (e.g. `setState()`), or\n * the {@link Connection} the change arrived from. Hosts use it to exclude the\n * originating connection from a broadcast.\n */\nexport type StateChangeSource = Connection | \"server\";\n\n/**\n * Options for a {@link State} capability. Validation and the post-change hook\n * stay on the host, which passes them in; the capability owns storage and\n * change ordering.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport interface StateOptions<T = unknown> {\n  /** Seeded on first access when nothing is stored. `undefined` seeds nothing. */\n  readonly initialState?: T;\n\n  /** Called after a change is validated and persisted. May be async. */\n  readonly onChanged?: (\n    state: T,\n    source: StateChangeSource\n  ) => void | Promise<void>;\n\n  /**\n   * Synchronous gating hook run before a change is persisted. Throw to reject\n   * the change; the throw propagates to the caller of {@link State.set}.\n   */\n  readonly validateStateChange?: (\n    nextState: T,\n    source: StateChangeSource\n  ) => void;\n}\n\n/**\n * Namespaced KV key holding this capability's schema version. Kept separate\n * from the host's global schema version so State owns its own migrations\n * without gating the host's DDL.\n */\nconst STATE_SCHEMA_VERSION_KEY = \"cf_agents:state_schema_version\";\nconst CURRENT_STATE_SCHEMA_VERSION = 1;\n\n/** Row id under which the single state value is stored in `cf_agents_state`. */\nconst STATE_ROW_ID = \"cf_state_row_id\";\n\n/**\n * Legacy row written by SDKs that predate the single-row state optimization.\n * Never written now; the v1 migration deletes it.\n */\nconst LEGACY_WAS_CHANGED_ROW_ID = \"cf_state_was_changed\";\n\n/**\n * Sentinel distinguishing \"state not yet loaded / never set\" from a stored\n * value. A distinct object reference means falsy states (null, 0, false, \"\")\n * still read back as set.\n */\nconst DEFAULT_STATE = {} as unknown;\n\n/**\n * Durable state storage for a Lifecycle Object.\n *\n * Owns the `cf_agents_state` state row, lazy load with an in-memory cache, and\n * validated persistence. Install the instance with `Lifecycle.use()`. State\n * validation and the post-change notification hook stay on the host, which\n * injects both callbacks. This capability never touches connections.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport class State<T = unknown> extends LifecycleCapability {\n  #state = DEFAULT_STATE as T;\n  #tableEnsured = false;\n  readonly #options: StateOptions<T>;\n\n  /**\n   * Create a durable state capability.\n   *\n   * @param options - Optional initial state and a synchronous validation hook\n   * injected by the host.\n   */\n  constructor(options: StateOptions<T> = {}) {\n    super(\"state\");\n    this.#options = options;\n  }\n\n  // ── Lifecycle capability hooks ─────────────────────────────────────────────\n\n  /** Initialize state storage during Lifecycle startup. */\n  async onStart(): Promise<void> {\n    const version =\n      (await this.lifecycle.storage.get<number>(STATE_SCHEMA_VERSION_KEY)) ?? 0;\n    if (version >= CURRENT_STATE_SCHEMA_VERSION) {\n      this.#tableEnsured = true;\n      return;\n    }\n\n    // v1: own the table and clear the legacy wasChanged row left behind by\n    // pre-optimization SDKs (state itself lives in STATE_ROW_ID).\n    this.#ensureTable();\n    this.lifecycle.storage.sql.exec(\n      \"DELETE FROM cf_agents_state WHERE id = ?\",\n      LEGACY_WAS_CHANGED_ROW_ID\n    );\n    await this.lifecycle.storage.put(\n      STATE_SCHEMA_VERSION_KEY,\n      CURRENT_STATE_SCHEMA_VERSION\n    );\n  }\n\n  #ensureTable(): void {\n    if (this.#tableEnsured) return;\n    this.lifecycle.storage.sql.exec(`\n      CREATE TABLE IF NOT EXISTS cf_agents_state (\n        id TEXT PRIMARY KEY NOT NULL,\n        state TEXT\n      )\n    `);\n    this.#tableEnsured = true;\n  }\n\n  // ── State access ───────────────────────────────────────────────────────────\n\n  /**\n   * Current state.\n   *\n   * Loads lazily from storage on first access and caches in memory. Row\n   * existence in `cf_agents_state` is the signal that state was previously\n   * set, so falsy values persist correctly. On a corrupt row, falls back to\n   * the initial state (re-persisting it) or clears the row.\n   */\n  get(): T | undefined {\n    if (this.#state !== DEFAULT_STATE) {\n      // state was previously set, and populated internal state\n      return this.#state;\n    }\n    // looks like this is the first time the state is being accessed\n    // check if the state was set in a previous life\n    this.#ensureTable();\n    const result = this.lifecycle.storage.sql\n      .exec(\"SELECT state FROM cf_agents_state WHERE id = ?\", STATE_ROW_ID)\n      .toArray() as { state: string | null }[];\n\n    // Row existence is the signal that state was previously set.\n    // This handles all values including falsy ones (null, 0, false, \"\").\n    if (result.length > 0) {\n      const state = result[0].state as string;\n\n      try {\n        this.#state = JSON.parse(state);\n      } catch (e) {\n        console.error(\n          \"Failed to parse stored state, falling back to initialState:\",\n          e\n        );\n        const initial = this.#options.initialState;\n        if (initial !== undefined) {\n          this.#state = initial;\n          // Persist the fixed state to prevent future parse errors\n          this.set(initial, \"server\");\n        } else {\n          // No initialState defined - clear corrupted data to prevent infinite retry loop\n          this.lifecycle.storage.sql.exec(\n            \"DELETE FROM cf_agents_state WHERE id = ?\",\n            STATE_ROW_ID\n          );\n          return undefined;\n        }\n      }\n      return this.#state;\n    }\n\n    // ok, this is the first time the state is being accessed\n    // and the state was not set in a previous life\n    // so we need to set the initial state (if provided)\n    const initial = this.#options.initialState;\n    if (initial === undefined) {\n      // no initial state provided, so we return undefined\n      return undefined;\n    }\n    // initial state provided, so we set the state,\n    // update db and return the initial state\n    this.set(initial, \"server\");\n    return initial;\n  }\n\n  /**\n   * Validate and persist a state change, then call the change hook.\n   *\n   * @param nextState - The new state to persist.\n   * @param source - `\"server\"` for host-originated changes, or the originating\n   * connection for client-originated changes.\n   * @throws Whatever the injected `validateStateChange` throws.\n   */\n  set(nextState: T, source: StateChangeSource = \"server\"): void {\n    // Validation/gating hook (sync only)\n    this.#options.validateStateChange?.(nextState, source);\n    this.#ensureTable();\n\n    // Persist first, cache second: a value that fails to serialize or to\n    // write must not be served by later get() calls. Row existence in\n    // cf_agents_state is the signal that state was set.\n    const serialized = JSON.stringify(nextState);\n    this.lifecycle.storage.sql.exec(\n      \"INSERT OR REPLACE INTO cf_agents_state (id, state) VALUES (?, ?)\",\n      STATE_ROW_ID,\n      serialized\n    );\n    this.#state = nextState;\n\n    let pending: void | Promise<void>;\n    try {\n      pending = this.#options.onChanged?.(nextState, source);\n    } catch (error) {\n      console.error(\"State onChanged hook failed:\", error);\n      return;\n    }\n\n    if (pending) {\n      // Durable Objects remain active for pending I/O without waitUntil. Keep\n      // set() synchronous while ensuring asynchronous failures are observed.\n      // Promise.resolve normalizes thenables from other realms or libraries.\n      void Promise.resolve(pending).catch((error) => {\n        console.error(\"State onChanged hook failed:\", error);\n      });\n    }\n  }\n}\n"],"mappings":";;;;;;;;;AA0CA,MAAM,2BAA2B;AACjC,MAAM,+BAA+B;;AAGrC,MAAM,eAAe;;;;;AAMrB,MAAM,4BAA4B;;;;;;AAOlC,MAAM,gBAAgB,CAAC;;;;;;;;;;;;;;;AAYvB,IAAa,QAAb,cAAwC,oBAAoB;;;;;;;CAW1D,YAAY,UAA2B,CAAC,GAAG;EACzC,MAAM,OAAO;;2CAXN,aAAA;kDACO,KAAA;;EAWd,uBAAA,UAAA,MAAgB,OAAA;CAClB;;CAKA,MAAM,UAAyB;EAG7B,KADG,MAAM,KAAK,UAAU,QAAQ,IAAY,wBAAwB,KAAM,MAC3D,8BAA8B;GAC3C,uBAAA,eAAA,MAAqB,IAAA;GACrB;EACF;EAIA,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAClB,KAAK,UAAU,QAAQ,IAAI,KACzB,4CACA,yBACF;EACA,MAAM,KAAK,UAAU,QAAQ,IAC3B,0BACA,4BACF;CACF;;;;;;;;;CAuBA,MAAqB;EACnB,IAAA,uBAAA,QAAI,IAAA,MAAgB,eAElB,OAAA,uBAAA,QAAO,IAAA;EAIT,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAClB,MAAM,SAAS,KAAK,UAAU,QAAQ,IACnC,KAAK,kDAAkD,YAAY,CAAC,CACpE,QAAQ;EAIX,IAAI,OAAO,SAAS,GAAG;GACrB,MAAM,QAAQ,OAAO,EAAE,CAAC;GAExB,IAAI;IACF,uBAAA,QAAA,MAAc,KAAK,MAAM,KAAK,CAAA;GAChC,SAAS,GAAG;IACV,QAAQ,MACN,+DACA,CACF;IACA,MAAM,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc;IAC9B,IAAI,YAAY,KAAA,GAAW;KACzB,uBAAA,QAAA,MAAc,OAAA;KAEd,KAAK,IAAI,SAAS,QAAQ;IAC5B,OAAO;KAEL,KAAK,UAAU,QAAQ,IAAI,KACzB,4CACA,YACF;KACA;IACF;GACF;GACA,OAAA,uBAAA,QAAO,IAAA;EACT;EAKA,MAAM,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc;EAC9B,IAAI,YAAY,KAAA,GAEd;EAIF,KAAK,IAAI,SAAS,QAAQ;EAC1B,OAAO;CACT;;;;;;;;;CAUA,IAAI,WAAc,SAA4B,UAAgB;EAE5D,uBAAA,UAAA,IAAA,CAAA,CAAc,sBAAsB,WAAW,MAAM;EACrD,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAKlB,MAAM,aAAa,KAAK,UAAU,SAAS;EAC3C,KAAK,UAAU,QAAQ,IAAI,KACzB,oEACA,cACA,UACF;EACA,uBAAA,QAAA,MAAc,SAAA;EAEd,IAAI;EACJ,IAAI;GACF,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc,YAAY,WAAW,MAAM;EACvD,SAAS,OAAO;GACd,QAAQ,MAAM,gCAAgC,KAAK;GACnD;EACF;EAEA,IAAI,SAIF,QAAa,QAAQ,OAAO,CAAC,CAAC,OAAO,UAAU;GAC7C,QAAQ,MAAM,gCAAgC,KAAK;EACrD,CAAC;CAEL;AACF;AArHE,SAAA,eAAqB;CACnB,IAAA,uBAAA,eAAI,IAAA,GAAoB;CACxB,KAAK,UAAU,QAAQ,IAAI,KAAK;;;;;KAK/B;CACD,uBAAA,eAAA,MAAqB,IAAA;AACvB"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/state/index.ts"],"sourcesContent":["import { LifecycleCapability } from \"../lifecycle/capability\";\nimport type { Connection } from \"../lifecycle/durable-object-lifecycle\";\n\n/**\n * Source of a state change: `\"server\"` for host code (e.g. `setState()`), or\n * the {@link Connection} the change arrived from. Hosts use it to exclude the\n * originating connection from a broadcast.\n */\nexport type StateChangeSource = Connection | \"server\";\n\n/**\n * Options for a {@link State} capability. Validation and the post-change hook\n * stay on the host, which passes them in; the capability owns storage and\n * change ordering.\n */\nexport interface StateOptions<T = unknown> {\n  /** Seeded on first access when nothing is stored. `undefined` seeds nothing. */\n  readonly initialState?: T;\n\n  /** Called after a change is validated and persisted. May be async. */\n  readonly onChanged?: (\n    state: T,\n    source: StateChangeSource\n  ) => void | Promise<void>;\n\n  /**\n   * Synchronous gating hook run before a change is persisted. Throw to reject\n   * the change; the throw propagates to the caller of {@link State.set}.\n   */\n  readonly validateStateChange?: (\n    nextState: T,\n    source: StateChangeSource\n  ) => void;\n}\n\n/**\n * Namespaced KV key holding this capability's schema version. Kept separate\n * from the host's global schema version so State owns its own migrations\n * without gating the host's DDL.\n */\nconst STATE_SCHEMA_VERSION_KEY = \"cf_agents:state_schema_version\";\nconst CURRENT_STATE_SCHEMA_VERSION = 1;\n\n/** Row id under which the single state value is stored in `cf_agents_state`. */\nconst STATE_ROW_ID = \"cf_state_row_id\";\n\n/**\n * Legacy row written by SDKs that predate the single-row state optimization.\n * Never written now; the v1 migration deletes it.\n */\nconst LEGACY_WAS_CHANGED_ROW_ID = \"cf_state_was_changed\";\n\n/**\n * Sentinel distinguishing \"state not yet loaded / never set\" from a stored\n * value. A distinct object reference means falsy states (null, 0, false, \"\")\n * still read back as set.\n */\nconst DEFAULT_STATE = {} as unknown;\n\n/**\n * Durable state storage for a Lifecycle Object.\n *\n * Owns the `cf_agents_state` state row, lazy load with an in-memory cache, and\n * validated persistence. Install the instance with `Lifecycle.use()`. State\n * validation and the post-change notification hook stay on the host, which\n * injects both callbacks. This capability never touches connections.\n */\nexport class State<T = unknown> extends LifecycleCapability {\n  #state = DEFAULT_STATE as T;\n  #tableEnsured = false;\n  readonly #options: StateOptions<T>;\n\n  /**\n   * Create a durable state capability.\n   *\n   * @param options - Optional initial state and a synchronous validation hook\n   * injected by the host.\n   */\n  constructor(options: StateOptions<T> = {}) {\n    super(\"state\");\n    this.#options = options;\n  }\n\n  // ── Lifecycle capability hooks ─────────────────────────────────────────────\n\n  /** Initialize state storage during Lifecycle startup. */\n  async onStart(): Promise<void> {\n    const version =\n      (await this.lifecycle.storage.get<number>(STATE_SCHEMA_VERSION_KEY)) ?? 0;\n    if (version >= CURRENT_STATE_SCHEMA_VERSION) {\n      this.#tableEnsured = true;\n      return;\n    }\n\n    // v1: own the table and clear the legacy wasChanged row left behind by\n    // pre-optimization SDKs (state itself lives in STATE_ROW_ID).\n    this.#ensureTable();\n    this.lifecycle.storage.sql.exec(\n      \"DELETE FROM cf_agents_state WHERE id = ?\",\n      LEGACY_WAS_CHANGED_ROW_ID\n    );\n    await this.lifecycle.storage.put(\n      STATE_SCHEMA_VERSION_KEY,\n      CURRENT_STATE_SCHEMA_VERSION\n    );\n  }\n\n  #ensureTable(): void {\n    if (this.#tableEnsured) return;\n    this.lifecycle.storage.sql.exec(`\n      CREATE TABLE IF NOT EXISTS cf_agents_state (\n        id TEXT PRIMARY KEY NOT NULL,\n        state TEXT\n      )\n    `);\n    this.#tableEnsured = true;\n  }\n\n  // ── State access ───────────────────────────────────────────────────────────\n\n  /**\n   * Current state.\n   *\n   * Loads lazily from storage on first access and caches in memory. Row\n   * existence in `cf_agents_state` is the signal that state was previously\n   * set, so falsy values persist correctly. On a corrupt row, falls back to\n   * the initial state (re-persisting it) or clears the row.\n   */\n  get(): T | undefined {\n    if (this.#state !== DEFAULT_STATE) {\n      // state was previously set, and populated internal state\n      return this.#state;\n    }\n    // looks like this is the first time the state is being accessed\n    // check if the state was set in a previous life\n    this.#ensureTable();\n    const result = this.lifecycle.storage.sql\n      .exec(\"SELECT state FROM cf_agents_state WHERE id = ?\", STATE_ROW_ID)\n      .toArray() as { state: string | null }[];\n\n    // Row existence is the signal that state was previously set.\n    // This handles all values including falsy ones (null, 0, false, \"\").\n    if (result.length > 0) {\n      const state = result[0].state as string;\n\n      try {\n        this.#state = JSON.parse(state);\n      } catch (e) {\n        console.error(\n          \"Failed to parse stored state, falling back to initialState:\",\n          e\n        );\n        const initial = this.#options.initialState;\n        if (initial !== undefined) {\n          this.#state = initial;\n          // Persist the fixed state to prevent future parse errors\n          this.set(initial, \"server\");\n        } else {\n          // No initialState defined - clear corrupted data to prevent infinite retry loop\n          this.lifecycle.storage.sql.exec(\n            \"DELETE FROM cf_agents_state WHERE id = ?\",\n            STATE_ROW_ID\n          );\n          return undefined;\n        }\n      }\n      return this.#state;\n    }\n\n    // ok, this is the first time the state is being accessed\n    // and the state was not set in a previous life\n    // so we need to set the initial state (if provided)\n    const initial = this.#options.initialState;\n    if (initial === undefined) {\n      // no initial state provided, so we return undefined\n      return undefined;\n    }\n    // initial state provided, so we set the state,\n    // update db and return the initial state\n    this.set(initial, \"server\");\n    return initial;\n  }\n\n  /**\n   * Validate and persist a state change, then call the change hook.\n   *\n   * @param nextState - The new state to persist.\n   * @param source - `\"server\"` for host-originated changes, or the originating\n   * connection for client-originated changes.\n   * @throws Whatever the injected `validateStateChange` throws.\n   */\n  set(nextState: T, source: StateChangeSource = \"server\"): void {\n    // Validation/gating hook (sync only)\n    this.#options.validateStateChange?.(nextState, source);\n    this.#ensureTable();\n\n    // Persist first, cache second: a value that fails to serialize or to\n    // write must not be served by later get() calls. Row existence in\n    // cf_agents_state is the signal that state was set.\n    const serialized = JSON.stringify(nextState);\n    this.lifecycle.storage.sql.exec(\n      \"INSERT OR REPLACE INTO cf_agents_state (id, state) VALUES (?, ?)\",\n      STATE_ROW_ID,\n      serialized\n    );\n    this.#state = nextState;\n\n    let pending: void | Promise<void>;\n    try {\n      pending = this.#options.onChanged?.(nextState, source);\n    } catch (error) {\n      console.error(\"State onChanged hook failed:\", error);\n      return;\n    }\n\n    if (pending) {\n      // Durable Objects remain active for pending I/O without waitUntil. Keep\n      // set() synchronous while ensuring asynchronous failures are observed.\n      // Promise.resolve normalizes thenables from other realms or libraries.\n      void Promise.resolve(pending).catch((error) => {\n        console.error(\"State onChanged hook failed:\", error);\n      });\n    }\n  }\n}\n"],"mappings":";;;;;;;;;AAwCA,MAAM,2BAA2B;AACjC,MAAM,+BAA+B;;AAGrC,MAAM,eAAe;;;;;AAMrB,MAAM,4BAA4B;;;;;;AAOlC,MAAM,gBAAgB,CAAC;;;;;;;;;;;;;AAUvB,IAAa,QAAb,cAAwC,oBAAoB;;;;;;;CAW1D,YAAY,UAA2B,CAAC,GAAG;EACzC,MAAM,OAAO;;2CAXN,aAAA;kDACO,KAAA;;EAWd,uBAAA,UAAA,MAAgB,OAAA;CAClB;;CAKA,MAAM,UAAyB;EAG7B,KADG,MAAM,KAAK,UAAU,QAAQ,IAAY,wBAAwB,KAAM,MAC3D,8BAA8B;GAC3C,uBAAA,eAAA,MAAqB,IAAA;GACrB;EACF;EAIA,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAClB,KAAK,UAAU,QAAQ,IAAI,KACzB,4CACA,yBACF;EACA,MAAM,KAAK,UAAU,QAAQ,IAC3B,0BACA,4BACF;CACF;;;;;;;;;CAuBA,MAAqB;EACnB,IAAA,uBAAA,QAAI,IAAA,MAAgB,eAElB,OAAA,uBAAA,QAAO,IAAA;EAIT,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAClB,MAAM,SAAS,KAAK,UAAU,QAAQ,IACnC,KAAK,kDAAkD,YAAY,CAAC,CACpE,QAAQ;EAIX,IAAI,OAAO,SAAS,GAAG;GACrB,MAAM,QAAQ,OAAO,EAAE,CAAC;GAExB,IAAI;IACF,uBAAA,QAAA,MAAc,KAAK,MAAM,KAAK,CAAA;GAChC,SAAS,GAAG;IACV,QAAQ,MACN,+DACA,CACF;IACA,MAAM,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc;IAC9B,IAAI,YAAY,KAAA,GAAW;KACzB,uBAAA,QAAA,MAAc,OAAA;KAEd,KAAK,IAAI,SAAS,QAAQ;IAC5B,OAAO;KAEL,KAAK,UAAU,QAAQ,IAAI,KACzB,4CACA,YACF;KACA;IACF;GACF;GACA,OAAA,uBAAA,QAAO,IAAA;EACT;EAKA,MAAM,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc;EAC9B,IAAI,YAAY,KAAA,GAEd;EAIF,KAAK,IAAI,SAAS,QAAQ;EAC1B,OAAO;CACT;;;;;;;;;CAUA,IAAI,WAAc,SAA4B,UAAgB;EAE5D,uBAAA,UAAA,IAAA,CAAA,CAAc,sBAAsB,WAAW,MAAM;EACrD,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAKlB,MAAM,aAAa,KAAK,UAAU,SAAS;EAC3C,KAAK,UAAU,QAAQ,IAAI,KACzB,oEACA,cACA,UACF;EACA,uBAAA,QAAA,MAAc,SAAA;EAEd,IAAI;EACJ,IAAI;GACF,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc,YAAY,WAAW,MAAM;EACvD,SAAS,OAAO;GACd,QAAQ,MAAM,gCAAgC,KAAK;GACnD;EACF;EAEA,IAAI,SAIF,QAAa,QAAQ,OAAO,CAAC,CAAC,OAAO,UAAU;GAC7C,QAAQ,MAAM,gCAAgC,KAAK;EACrD,CAAC;CAEL;AACF;AArHE,SAAA,eAAqB;CACnB,IAAA,uBAAA,eAAI,IAAA,GAAoB;CACxB,KAAK,UAAU,QAAQ,IAAI,KAAK;;;;;KAK/B;CACD,uBAAA,eAAA,MAAqB,IAAA;AACvB"}

package/dist/store-BKM4Xm9M.d.ts

@@ -0,0 +1,332 @@
+//#region src/harness/store/store.d.ts
+/**
+ * A session store for harnesses, on a Durable Object's SQLite database.
+ *
+ * Any harness that runs its agent somewhere other than the object (a
+ * container, a sandbox, a remote process) needs the same few things kept
+ * durably next to it: which sessions exist, which operations were submitted
+ * and how each one ended, and the session's history in whatever format the
+ * harness speaks. This store keeps those and nothing more. It knows no
+ * message format, no event vocabulary and no runtime: inputs, results,
+ * session state and log entries are opaque JSON that the harness parses.
+ *
+ * Three record kinds:
+ *
+ * - **Sessions**: an id, an optional parent (a fork), and one JSON state
+ *   value the harness owns (model, cursors, resume handles).
+ * - **Operations**: one row per submitted operation, keyed by an
+ *   idempotency id within its session, moving `queued` → `running` →
+ *   `done` | `unanswered`. Transitions are guarded in SQL, so a duplicate or
+ *   late transition is a no-op rather than a regression.
+ * - **Logs**: named, append-ordered streams of JSON entries per session
+ *   (`"messages"`, `"engine"`, …). An entry may carry an id, and an entry
+ *   written again under the same id replaces the old one in place. Entries
+ *   larger than one SQLite row are split across continuation rows.
+ *
+ * The store is synchronous, like the SQL API under it, so a harness can
+ * group several writes in `transaction()` without awaiting.
+ *
+ * @experimental The API may change before it stabilizes.
+ */
+/** A JSON value, as the store keeps it. */
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | {
+      readonly [key: string]: JsonValue;
+    };
+/** Where an operation is in its life. */
+type OperationStatus = "queued" | "running" | "done" | "unanswered";
+/** A session, as stored. */
+type SessionRecord = {
+  readonly id: string /** The session this one was forked from. */;
+  readonly parent:
+    | string
+    | undefined /** Harness-owned state. `null` until the harness writes some. */;
+  readonly state: JsonValue;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+};
+/** One operation, as stored. */
+type OperationRecord = {
+  readonly session: string /** The idempotency key, unique within the session. */;
+  readonly id: string /** Submission order within the whole store. */;
+  readonly seq: number;
+  readonly status: OperationStatus /** What was submitted, in the harness's format. */;
+  readonly input: JsonValue /** Harness-owned submission options and bookkeeping. */;
+  readonly meta: JsonValue /** The harness's result for a `done` operation, else `null`. */;
+  readonly result: JsonValue /** Why an `unanswered` operation ended. */;
+  readonly reason: string | undefined;
+  readonly createdAt: number;
+  readonly settledAt: number | undefined;
+};
+/** One log entry, as stored. */
+type LogEntry = {
+  /** Position in the log. Stable when the entry is replaced by id. */ readonly seq: number;
+  readonly id: string | undefined;
+  readonly data: JsonValue;
+  readonly createdAt: number;
+};
+/** One entry to append. */
+type LogAppend = {
+  /** Replace an existing entry with this id in place, instead of appending. */ readonly id?: string;
+  readonly data: JsonValue;
+};
+/** How an operation ended. */
+type OperationOutcome =
+  | {
+      readonly status: "done";
+      readonly result: JsonValue;
+    }
+  | {
+      readonly status: "unanswered";
+      readonly reason: string;
+    };
+/** `openHarnessStore`'s options. */
+type HarnessStoreOptions = {
+  /**
+   * Prefix for the store's tables. Two harnesses in one object use two
+   * prefixes. Must not start with `_cf_`, which Durable Objects reserve.
+   * Default `harness_`.
+   */
+  readonly prefix?: string;
+};
+/**
+ * Open the store over this object's SQLite database, creating its tables on
+ * first use. Cheap: call it once per isolate and keep the result.
+ *
+ * @param storage - The Durable Object's storage.
+ * @param options - Table prefix.
+ * @returns The store.
+ */
+declare function openHarnessStore(
+  storage: DurableObjectStorage,
+  options?: HarnessStoreOptions
+): HarnessStore;
+/**
+ * The store. Construct it with `openHarnessStore`.
+ *
+ * @experimental The API may change before it stabilizes.
+ */
+declare class HarnessStore {
+  #private;
+  /**
+   * @param storage - The Durable Object's storage.
+   * @param options - Table prefix.
+   */
+  constructor(storage: DurableObjectStorage, options: HarnessStoreOptions);
+  /**
+   * Run `fn` in one storage transaction. Writes inside it commit together or
+   * not at all.
+   *
+   * @template T - What `fn` returns.
+   * @param fn - Synchronous work against this store.
+   * @returns What `fn` returned.
+   */
+  transaction<T>(fn: () => T): T;
+  /**
+   * Create a session, or return the existing one with this id unchanged.
+   *
+   * @param input - The id, an optional parent, and the initial state.
+   *   `createdAt` keeps the creation time of a session imported from
+   *   elsewhere, so the session list stays in creation order; default now.
+   * @returns The stored session.
+   */
+  createSession(input: {
+    readonly id: string;
+    readonly parent?: string;
+    readonly state?: JsonValue;
+    readonly createdAt?: number;
+  }): SessionRecord;
+  /**
+   * Read one session.
+   *
+   * @param id - The session id.
+   * @returns The session, or `undefined` when there is none.
+   */
+  session(id: string): SessionRecord | undefined;
+  /**
+   * Every session, oldest first.
+   *
+   * @returns The sessions.
+   */
+  sessions(): SessionRecord[];
+  /**
+   * Replace a session's harness-owned state.
+   *
+   * @param id - The session id.
+   * @param state - The new state.
+   * @returns False when there is no such session.
+   */
+  setSessionState(id: string, state: JsonValue): boolean;
+  /**
+   * Delete a session with its operations and logs.
+   *
+   * @param id - The session id.
+   * @returns False when there was no such session.
+   */
+  deleteSession(id: string): boolean;
+  /**
+   * Durably queue an operation. Idempotent on `(session, id)`: a second
+   * enqueue with the same id stores nothing and returns the first record.
+   *
+   * @param input - The session, the idempotency id, the input and options.
+   * @returns The stored record, and whether this call created it.
+   */
+  enqueue(input: {
+    readonly session: string;
+    readonly id: string;
+    readonly input: JsonValue;
+    readonly meta?: JsonValue;
+  }): {
+    readonly record: OperationRecord;
+    readonly accepted: boolean;
+  };
+  /**
+   * Read one operation.
+   *
+   * @param session - The session id.
+   * @param id - The operation id.
+   * @returns The operation, or `undefined` when there is none.
+   */
+  operation(session: string, id: string): OperationRecord | undefined;
+  /**
+   * Operations in submission order, optionally narrowed to one session and
+   * to some statuses.
+   *
+   * @param filter - The session and statuses to keep. Default: all.
+   * @returns The matching operations, oldest first.
+   */
+  operations(filter?: {
+    readonly session?: string;
+    readonly status?: readonly OperationStatus[];
+  }): OperationRecord[];
+  /**
+   * Move a queued operation to `running`.
+   *
+   * @param session - The session id.
+   * @param id - The operation id.
+   * @returns False when it was not queued.
+   */
+  start(session: string, id: string): boolean;
+  /**
+   * Move a running operation back to `queued`, to run it again.
+   *
+   * @param session - The session id.
+   * @param id - The operation id.
+   * @returns False when it was not running.
+   */
+  requeue(session: string, id: string): boolean;
+  /**
+   * Settle a queued or running operation.
+   *
+   * @param session - The session id.
+   * @param id - The operation id.
+   * @param outcome - How it ended.
+   * @returns False when it had already settled or does not exist.
+   */
+  settle(session: string, id: string, outcome: OperationOutcome): boolean;
+  /**
+   * Delete one operation, whatever its status. Its id may be enqueued
+   * again. For replacing a record imported from elsewhere; a harness that
+   * deletes an open operation must stop running it itself.
+   *
+   * @param session - The session id.
+   * @param id - The operation id.
+   * @returns False when there was no such operation.
+   */
+  deleteOperation(session: string, id: string): boolean;
+  /**
+   * Forget a session's settled operations, as when the session starts
+   * over. Open operations are kept. A forgotten operation's id may be
+   * enqueued again.
+   *
+   * @param session - The session id.
+   * @returns How many operations were deleted.
+   */
+  deleteSettled(session: string): number;
+  /**
+   * Replace an operation's harness-owned bookkeeping.
+   *
+   * @param session - The session id.
+   * @param id - The operation id.
+   * @param meta - The new value.
+   * @returns False when there is no such operation.
+   */
+  setOperationMeta(session: string, id: string, meta: JsonValue): boolean;
+  /**
+   * Append entries to a session's log. An entry with an id that is already
+   * in the log replaces that entry in place, keeping its position.
+   *
+   * @param session - The session id.
+   * @param log - The log's name, such as `"messages"`.
+   * @param entries - The entries, in order.
+   * @returns The position of the last entry written, or of the log's end.
+   */
+  append(session: string, log: string, entries: readonly LogAppend[]): number;
+  /**
+   * Read a session's log in order.
+   *
+   * @param session - The session id.
+   * @param log - The log's name.
+   * @param range - Entries after position `after` (exclusive), at most `limit`.
+   * @returns The entries.
+   */
+  read(
+    session: string,
+    log: string,
+    range?: {
+      readonly after?: number;
+      readonly limit?: number;
+    }
+  ): LogEntry[];
+  /**
+   * One entry by id.
+   *
+   * @param session - The session id.
+   * @param log - The log's name.
+   * @param id - The entry id.
+   * @returns The entry, or `undefined`.
+   */
+  entry(session: string, log: string, id: string): LogEntry | undefined;
+  /**
+   * The position of a log's last entry.
+   *
+   * @param session - The session id.
+   * @param log - The log's name.
+   * @returns The position, or 0 for an empty log.
+   */
+  end(session: string, log: string): number;
+  /**
+   * Empty a session's log.
+   *
+   * @param session - The session id.
+   * @param log - The log's name.
+   */
+  clear(session: string, log: string): void;
+  /**
+   * Copy one session's log onto the end of another's, keeping entry ids.
+   *
+   * @param from - The source session.
+   * @param to - The target session.
+   * @param log - The log's name.
+   */
+  copy(from: string, to: string, log: string): void;
+}
+//#endregion
+export {
+  LogEntry as a,
+  OperationStatus as c,
+  LogAppend as i,
+  SessionRecord as l,
+  HarnessStoreOptions as n,
+  OperationOutcome as o,
+  JsonValue as r,
+  OperationRecord as s,
+  HarnessStore as t,
+  openHarnessStore as u
+};
+//# sourceMappingURL=store-BKM4Xm9M.d.ts.map