purra-interaction 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lybrands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# purra-interaction · TypeScript
+
+English | [简体中文](README.zh-CN.md)
+
+Persist structured questions, wait for user input, and continue execution.
+Requires Node.js 22.13+.
+
+| API | Use |
+| --- | --- |
+| `SqliteClarification` | Suspend and resume the same Run using `purra-sqlite` checkpoints |
+| `ClarificationStore` + `ClarificationWorkflow` | Collect input before execution, then create a Run through an application callback |
+
+## Install
+
+Follow [source installation](../../README.md#source-installation). Build and
+install `purra-sqlite` before `integrations/interaction/typescript` when using
+`SqliteClarification`.
+
+## Configure a Run
+
+Given a model gateway `model`:
+
+```ts
+import { Agent } from "purra";
+import { SqliteAgentAdapters } from "purra-sqlite";
+import { SqliteClarification } from "purra-interaction";
+
+const storage = new SqliteAgentAdapters("agent.db", { scope: "user-1/project-1" });
+const interaction = new SqliteClarification(storage);
+const agent = new Agent({
+  model,
+  preset: { id: "assistant", revision: "1" },
+  tools: [interaction.tool],
+  checkpointHandler: interaction.checkpointHandler,
+  runRepository: storage.runs,
+  outputPublisher: storage.publisher,
+});
+```
+
+Submit through `agent.submit(request, { budgets: { maxRunGenerationTokens: 8192 } })`.
+When the Agent asks a question, the handle's `result` rejects with
+`UserInputRequired` from `purra`. Use `error.requestId` with
+`await interaction.get(error.requestId)` to obtain public question data.
+
+The Run remains waiting without keeping a worker or model call alive. After the
+user answers, provide the question revision, a stable command key, and answers
+keyed by question ID:
+
+```ts
+async function answerAndResume(
+  requestId: string,
+  revision: number,
+  answerKey: string,
+  answers: Record<string, string>,
+) {
+  const ready = await interaction.answer(requestId, {
+    revision, key: answerKey, answers,
+  });
+  return interaction.resume(agent, ready.id);
+}
+```
+
+The returned handle continues the same Run with its spent budget and deadline.
+It may request input again. Answers provide task data and do not grant tool permissions.
+
+## Reload and cancel
+
+Recreate the same storage, Agent preset, gateway, and interaction objects after
+restart. `listPending()` includes waiting and answered requests; resume those
+in `ready` state. Use `cancel(requestId)` while waiting, or the Run handle after
+execution resumes.
+
+For Agent trees, bind the same Run-tree repository and answer all pending questions
+under a Root before resuming. Auto, Reactive, and Planned execution are supported.
+Pauses occur at completed tool-round boundaries. Reconcile uncertain external
+writes and wait for active execution to settle before closing storage.
+
+## Pre-execution input
+
+`ClarificationStore.ask(...)` saves questions and an application checkpoint.
+Expose `ClarificationStore.publicView(saved)` to the UI, then call `store.answer(...)`.
+`ClarificationWorkflow.resume(id, { revision, submit })` invokes
+`submit(snapshot, continuationKey)` to create a new Run and return its ID.
+
+Persist the continuation key on that Run. If submission is interrupted, reconcile
+against the existing Run before retrying. The application restores credentials,
+permissions, and remaining task budgets. Close the store on shutdown.

package/README.zh-CN.md

@@ -0,0 +1,81 @@
+# purra-interaction · TypeScript
+
+[English](README.md) | 简体中文
+
+持久化结构化问题，等待用户输入后继续执行。要求 Node.js 22.13+。
+
+| API | 用途 |
+| --- | --- |
+| `SqliteClarification` | 通过 `purra-sqlite` 检查点暂停并恢复同一 Run |
+| `ClarificationStore` + `ClarificationWorkflow` | 在执行前收集输入，再通过应用回调创建 Run |
+
+## 安装
+
+按照[源码安装说明](../../README.zh-CN.md#从源码安装)操作。
+使用 `SqliteClarification` 时，先构建并安装 `purra-sqlite`，再处理
+`integrations/interaction/typescript`。
+
+## 配置 Run
+
+已有模型网关 `model` 时：
+
+```ts
+import { Agent } from "purra";
+import { SqliteAgentAdapters } from "purra-sqlite";
+import { SqliteClarification } from "purra-interaction";
+
+const storage = new SqliteAgentAdapters("agent.db", { scope: "user-1/project-1" });
+const interaction = new SqliteClarification(storage);
+const agent = new Agent({
+  model,
+  preset: { id: "assistant", revision: "1" },
+  tools: [interaction.tool],
+  checkpointHandler: interaction.checkpointHandler,
+  runRepository: storage.runs,
+  outputPublisher: storage.publisher,
+});
+```
+
+通过 `agent.submit(request, { budgets: { maxRunGenerationTokens: 8192 } })` 提交。
+Agent 提问后，句柄的 `result` 会以 `purra` 导出的 `UserInputRequired` 拒绝。
+使用异常中的 `error.requestId` 调用 `await interaction.get(error.requestId)`，获取可展示的问题数据。
+
+Run 保持等待状态，不占用持续运行的执行任务或模型调用。收到用户回答后，传入问题修订号、
+稳定的命令键，以及按问题 ID 组织的回答：
+
+```ts
+async function answerAndResume(
+  requestId: string,
+  revision: number,
+  answerKey: string,
+  answers: Record<string, string>,
+) {
+  const ready = await interaction.answer(requestId, {
+    revision, key: answerKey, answers,
+  });
+  return interaction.resume(agent, ready.id);
+}
+```
+
+返回的句柄继续执行原 Run，保留已消耗预算和截止时间，也可能再次请求输入。
+回答只提供任务数据，不授予工具权限。
+
+## 重新加载与取消
+
+进程重启后，还原相同的存储、Agent preset、网关和交互对象。
+`listPending()` 包含等待中和已回答的请求，可恢复其中处于 `ready` 状态的记录。
+等待期间使用 `cancel(requestId)`；恢复执行后使用 Run 句柄取消。
+
+使用 Agent 树时，绑定同一 Run 树仓储，回答 Root 下的全部待答问题后再恢复。
+支持 Auto、Reactive 和 Planned。暂停发生在完整工具轮次结束后。
+结果不确定的外部写入需要先确认；等待活动执行结束后再关闭存储。
+
+## 执行前收集输入
+
+`ClarificationStore.ask(...)` 保存问题和应用检查点。
+向界面提供 `ClarificationStore.publicView(saved)`，再通过 `store.answer(...)` 保存回答。
+`ClarificationWorkflow.resume(id, { revision, submit })` 调用
+`submit(snapshot, continuationKey)` 创建新 Run 并返回其 ID。
+
+将续接键保存在对应 Run 上。提交中断时，先根据已有 Run 确认结果再重试。
+应用负责还原凭据、权限和任务剩余预算，并在关闭时关闭 store。

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { type Agent, type AgentExecutionCheckpoint, type RunRequest, type RunLeaseClaim, type ToolDefinition, type RunHandle } from "purra";
+import type { SqliteAgentAdapters } from "purra-sqlite";
+import type { JsonValue, TaskAdmissionDecision } from "purra";
+export interface InputQuestion {
+    readonly id: string;
+    readonly prompt: string;
+    readonly choices?: readonly string[];
+    readonly allowFreeform?: boolean;
+}
+export interface ClarificationInput {
+    readonly key: string;
+    readonly questions: readonly InputQuestion[];
+    readonly checkpoint: JsonValue;
+    readonly sourceRunId?: string | null;
+    readonly expiresAtMs?: number | null;
+}
+export interface ClarificationSnapshot {
+    readonly id: string;
+    readonly questions: readonly Required<InputQuestion>[];
+    readonly checkpoint: JsonValue;
+    readonly sourceRunId: string | null;
+    readonly expiresAtMs: number | null;
+    readonly state: "waiting" | "ready" | "resuming" | "resumed" | "canceled";
+    readonly revision: number;
+    readonly answers: Readonly<Record<string, string>> | null;
+    readonly runId: string | null;
+    readonly resumeToken: string | null;
+}
+/** SQLite clarification storage. It does not replace the canonical Core Run journal. */
+export declare class ClarificationStore {
+    #private;
+    constructor(path: string, options: {
+        scope: string;
+    });
+    ask(input: ClarificationInput): ClarificationSnapshot;
+    get(id: string): ClarificationSnapshot;
+    answer(id: string, options: {
+        revision: number;
+        key: string;
+        answers: Readonly<Record<string, string>>;
+    }): ClarificationSnapshot;
+    claim(id: string, options: {
+        revision: number;
+    }): {
+        token: string;
+        snapshot: ClarificationSnapshot;
+    };
+    reconcile(id: string, options: {
+        token: string;
+        runId?: string;
+        notSubmitted?: boolean;
+    }): ClarificationSnapshot;
+    cancel(id: string, options: {
+        revision: number;
+    }): ClarificationSnapshot;
+    static publicView(saved: ClarificationSnapshot): Omit<ClarificationSnapshot, "checkpoint" | "resumeToken">;
+    close(): void;
+}
+export declare class ClarificationWorkflow {
+    readonly store: ClarificationStore;
+    constructor(store: ClarificationStore);
+    admission(input: ClarificationInput): TaskAdmissionDecision;
+    resume(id: string, options: {
+        revision: number;
+        submit: (snapshot: ClarificationSnapshot, continuationKey: string) => Promise<string>;
+    }): Promise<ClarificationSnapshot>;
+}
+/** Compose with SqliteAgentAdapters and Agent.checkpointHandler. */
+export declare class SqliteClarification {
+    #private;
+    readonly storage: SqliteAgentAdapters;
+    readonly tool: ToolDefinition;
+    constructor(storage: SqliteAgentAdapters);
+    readonly checkpointHandler: (checkpoint: AgentExecutionCheckpoint, request: RunRequest, claim?: RunLeaseClaim) => Promise<AgentExecutionCheckpoint>;
+    checkpoint(checkpoint: AgentExecutionCheckpoint, request: RunRequest, claim?: RunLeaseClaim): Promise<AgentExecutionCheckpoint>;
+    get(id: string): Promise<{
+        id: string;
+        runId: string;
+        rootRunId: string;
+        questions: JsonValue;
+        revision: number;
+        state: string;
+        answers: Readonly<Record<string, string>> | null;
+    }>;
+    listPending(): Promise<{
+        id: string;
+        runId: string;
+        rootRunId: string;
+        questions: JsonValue;
+        revision: number;
+        state: string;
+        answers: Readonly<Record<string, string>> | null;
+    }[]>;
+    listWaiting(): Promise<{
+        id: string;
+        runId: string;
+        rootRunId: string;
+        questions: JsonValue;
+        state: "ready" | "waiting";
+        revision: number;
+    }[]>;
+    answer(id: string, options: {
+        revision: number;
+        key: string;
+        answers: Readonly<Record<string, string>>;
+    }): Promise<{
+        id: string;
+        runId: string;
+        rootRunId: string;
+        questions: JsonValue;
+        revision: number;
+        state: string;
+        answers: Readonly<Record<string, string>> | null;
+    }>;
+    resume(agent: Agent, id: string): Promise<RunHandle>;
+    cancel(id: string): Promise<boolean>;
+}

package/dist/index.js

@@ -0,0 +1,371 @@
+import { createHash } from "node:crypto";
+import { UserInputRequired } from "purra";
+import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+function text(value, limit = 512) {
+    if (typeof value !== "string" || !value.trim() || [...value].length > limit)
+        throw new TypeError("Expected bounded non-empty text");
+    return value;
+}
+function encode(value) {
+    const active = new Set();
+    function copy(v) {
+        if (v === null || typeof v === "string" || typeof v === "boolean")
+            return v;
+        if (typeof v === "number" && Number.isFinite(v) && Math.abs(v) <= Number.MAX_SAFE_INTEGER)
+            return v;
+        if (!v || typeof v !== "object" || active.has(v))
+            throw new TypeError("Checkpoint must be finite JSON data");
+        active.add(v);
+        try {
+            if (Array.isArray(v))
+                return v.map(copy);
+            if (Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null)
+                throw new TypeError("Checkpoint must be plain JSON data");
+            return Object.fromEntries(Object.keys(v).sort().map(k => [k, copy(v[k])]));
+        }
+        finally {
+            active.delete(v);
+        }
+    }
+    const result = JSON.stringify(copy(value));
+    if (Buffer.byteLength(result) > 131072)
+        throw new TypeError("Clarification exceeds 128 KiB");
+    return result;
+}
+function questions(values) {
+    if (!Array.isArray(values) || values.length < 1 || values.length > 3)
+        throw new TypeError("Clarification requires 1 to 3 questions");
+    const result = values.map(q => {
+        if (!q || typeof q !== "object" || Object.keys(q).some(k => !["id", "prompt", "choices", "allowFreeform"].includes(k)))
+            throw new TypeError("Invalid question");
+        const choices = q.choices ?? [];
+        if (!Array.isArray(choices) || choices.length > 8 || new Set(choices).size !== choices.length)
+            throw new TypeError("Invalid choices");
+        const allowFreeform = q.allowFreeform ?? true;
+        if (typeof allowFreeform !== "boolean" || (!allowFreeform && !choices.length))
+            throw new TypeError("Invalid answer mode");
+        return { id: text(q.id, 128), prompt: text(q.prompt, 8000), choices: choices.map(c => text(c, 128)), allowFreeform };
+    });
+    if (new Set(result.map(q => q.id)).size !== result.length)
+        throw new TypeError("Question ids must be unique");
+    return result;
+}
+/** SQLite clarification storage. It does not replace the canonical Core Run journal. */
+export class ClarificationStore {
+    #db;
+    #scope;
+    constructor(path, options) {
+        this.#scope = text(options.scope);
+        this.#db = new DatabaseSync(path);
+        this.#db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA busy_timeout=5000;
+      CREATE TABLE IF NOT EXISTS purra_clarifications (
+        scope TEXT NOT NULL, id TEXT NOT NULL, request_key TEXT NOT NULL,
+        request_json TEXT NOT NULL, state TEXT NOT NULL, revision INTEGER NOT NULL,
+        answer_key TEXT, answers_json TEXT, resume_token TEXT, run_id TEXT,
+        PRIMARY KEY(scope, id), UNIQUE(scope, request_key));`);
+    }
+    #transaction(action) {
+        this.#db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = action();
+            this.#db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.#db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    ask(input) {
+        text(input.key);
+        if (input.sourceRunId != null)
+            text(input.sourceRunId);
+        if (input.expiresAtMs != null && (!Number.isSafeInteger(input.expiresAtMs) || input.expiresAtMs <= 0))
+            throw new TypeError("Expiry must be a positive integer");
+        const body = encode({ questions: questions(input.questions), checkpoint: input.checkpoint,
+            sourceRunId: input.sourceRunId ?? null, expiresAtMs: input.expiresAtMs ?? null });
+        const id = this.#transaction(() => {
+            const existing = this.#db.prepare("SELECT id,request_json FROM purra_clarifications WHERE scope=? AND request_key=?").get(this.#scope, input.key);
+            if (existing) {
+                if (encode(JSON.parse(existing.request_json)) !== body)
+                    throw new Error("clarification_idempotency_conflict");
+                return existing.id;
+            }
+            const identifier = randomUUID().replaceAll("-", "");
+            this.#db.prepare("INSERT INTO purra_clarifications(scope,id,request_key,request_json,state,revision) VALUES(?,?,?,?,'waiting',1)").run(this.#scope, identifier, input.key, body);
+            return identifier;
+        });
+        return this.get(id);
+    }
+    get(id) {
+        const row = this.#db.prepare("SELECT request_json,state,revision,answers_json,run_id,resume_token FROM purra_clarifications WHERE scope=? AND id=?").get(this.#scope, text(id));
+        if (!row)
+            throw new Error("clarification_not_found");
+        return { id, ...JSON.parse(row.request_json), state: row.state, revision: row.revision,
+            answers: row.answers_json === null ? null : JSON.parse(row.answers_json), runId: row.run_id, resumeToken: row.resume_token };
+    }
+    answer(id, options) {
+        text(options.key);
+        const encoded = encode(options.answers);
+        this.#transaction(() => {
+            const saved = this.get(id);
+            const previous = this.#db.prepare("SELECT answer_key,answers_json FROM purra_clarifications WHERE scope=? AND id=?").get(this.#scope, id);
+            if (previous.answer_key === options.key) {
+                if (encode(JSON.parse(previous.answers_json)) !== encoded)
+                    throw new Error("clarification_idempotency_conflict");
+                return;
+            }
+            this.#require(saved, "waiting", options.revision);
+            if (!options.answers || typeof options.answers !== "object" || Array.isArray(options.answers)
+                || Object.keys(options.answers).length !== saved.questions.length || saved.questions.some(q => !Object.hasOwn(options.answers, q.id)))
+                throw new TypeError("Answers must cover exactly the requested questions");
+            for (const q of saved.questions) {
+                const answer = text(options.answers[q.id], 8000);
+                if (!q.allowFreeform && !q.choices.includes(answer))
+                    throw new TypeError("Answer is not one of the offered choices");
+            }
+            this.#db.prepare("UPDATE purra_clarifications SET state='ready',revision=revision+1,answer_key=?,answers_json=? WHERE scope=? AND id=?").run(options.key, encoded, this.#scope, id);
+        });
+        return this.get(id);
+    }
+    claim(id, options) {
+        const token = this.#transaction(() => {
+            this.#require(this.get(id), "ready", options.revision);
+            const value = randomUUID().replaceAll("-", "");
+            this.#db.prepare("UPDATE purra_clarifications SET state='resuming',revision=revision+1,resume_token=? WHERE scope=? AND id=?").run(value, this.#scope, id);
+            return value;
+        });
+        return { token, snapshot: this.get(id) };
+    }
+    reconcile(id, options) {
+        if (options.notSubmitted !== undefined && typeof options.notSubmitted !== "boolean")
+            throw new TypeError("notSubmitted must be boolean");
+        if ((options.runId === undefined) === (options.notSubmitted !== true))
+            throw new TypeError("Provide an existing Run id or notSubmitted=true");
+        if (options.runId !== undefined)
+            text(options.runId);
+        this.#transaction(() => {
+            const row = this.#db.prepare("SELECT state,resume_token,run_id FROM purra_clarifications WHERE scope=? AND id=?").get(this.#scope, id);
+            if (!row || row.resume_token !== options.token)
+                throw new Error("clarification_claim_conflict");
+            if (row.state === "resumed" && row.run_id === options.runId)
+                return;
+            if (row.state !== "resuming")
+                throw new Error("clarification_state_conflict");
+            this.#db.prepare("UPDATE purra_clarifications SET state=?,revision=revision+1,run_id=? WHERE scope=? AND id=?").run(options.notSubmitted ? "ready" : "resumed", options.runId ?? null, this.#scope, id);
+        });
+        return this.get(id);
+    }
+    cancel(id, options) {
+        this.#transaction(() => {
+            const saved = this.get(id);
+            if (saved.revision !== options.revision || !["waiting", "ready"].includes(saved.state))
+                throw new Error("clarification_state_conflict");
+            this.#db.prepare("UPDATE purra_clarifications SET state='canceled',revision=revision+1 WHERE scope=? AND id=?").run(this.#scope, id);
+        });
+        return this.get(id);
+    }
+    static publicView(saved) {
+        const { checkpoint: _, resumeToken: __, ...view } = saved;
+        return view;
+    }
+    #require(saved, state, revision) {
+        if (!Number.isSafeInteger(revision) || saved.state !== state || saved.revision !== revision)
+            throw new Error("clarification_state_conflict");
+        if (saved.expiresAtMs !== null && saved.expiresAtMs <= Date.now())
+            throw new Error("clarification_expired");
+    }
+    close() { this.#db.close(); }
+}
+export class ClarificationWorkflow {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    admission(input) {
+        const saved = this.store.ask(input);
+        return { mode: "clarify", reasonCode: "user_input_required", message: saved.questions.map(q => q.prompt).join("\n"), metadata: { inputRequestId: saved.id } };
+    }
+    async resume(id, options) {
+        const { token, snapshot } = this.store.claim(id, options);
+        const runId = await options.submit(snapshot, "clarification:" + id);
+        return this.store.reconcile(id, { token, runId });
+    }
+}
+/** Compose with SqliteAgentAdapters and Agent.checkpointHandler. */
+export class SqliteClarification {
+    storage;
+    tool = {
+        name: "request_user_input", description: "Ask the user for missing task information. Execution waits for the answer.",
+        inputSchema: { type: "object", properties: { questions: { type: "array", minItems: 1, maxItems: 3,
+                    items: { type: "object", properties: { id: { type: "string" }, prompt: { type: "string" },
+                            choices: { type: "array", items: { type: "string" }, maxItems: 8 }, allowFreeform: { type: "boolean" } },
+                        required: ["id", "prompt"], additionalProperties: false } } }, required: ["questions"], additionalProperties: false },
+        policy: { mode: "read", title: "Ask the user" },
+        run: (input) => ({ content: { purraInputRequest: questions(input.questions) }, effectState: "not_started" }),
+    };
+    constructor(storage) {
+        this.storage = storage;
+    }
+    checkpointHandler = (checkpoint, request, claim = {}) => this.checkpoint(checkpoint, request, claim);
+    async checkpoint(checkpoint, request, claim = {}) {
+        const calls = new Set(checkpoint.messages.flatMap(m => m.toolCalls ?? []).filter(c => c.name === "request_user_input").map(c => c.id));
+        const waiting = await this.storage.transaction(async (all, extra) => {
+            let tree;
+            try {
+                tree = await all.runTree.getRun(checkpoint.runId);
+            }
+            catch (error) {
+                if (error.code !== "child_run_not_found")
+                    throw error;
+            }
+            const rootRunId = tree?.rootRunId ?? checkpoint.runId;
+            const rows = extra.clarifications ??= Object.create(null);
+            for (const message of checkpoint.messages) {
+                if (message.role !== "tool" || !calls.has(message.toolCallId ?? ""))
+                    continue;
+                let value = message.content;
+                if (typeof value === "string") {
+                    try {
+                        value = JSON.parse(value);
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                if (!value?.purraInputRequest)
+                    continue;
+                const id = createHash("sha256").update(checkpoint.runId + "\0" + message.toolCallId).digest("hex");
+                if (!rows[id]) {
+                    const row = { id, runId: checkpoint.runId, rootRunId, questions: questions(value.purraInputRequest), state: "waiting", revision: 1, answers: null, answerKey: null, request };
+                    rows[id] = row;
+                    await all.runs.appendEvent(row.runId, { sourceKey: `input:${id}:required`, kind: "input.required", channel: "lifecycle", visibility: "public", payload: this.#public(row) }, claim);
+                }
+            }
+            const descendants = new Set(tree ? (await all.runTree.listDescendants(checkpoint.runId)).map(run => run.runId) : []);
+            descendants.add(checkpoint.runId);
+            for (const row of Object.values(rows)) {
+                if (descendants.has(row.runId) && row.state === "waiting" && (await all.runs.get(row.runId)).status === "running")
+                    return row;
+            }
+            return undefined;
+        });
+        if (waiting)
+            throw new UserInputRequired(checkpoint.runId, waiting.id);
+        return checkpoint;
+    }
+    #public(row) { return { id: row.id, runId: row.runId, rootRunId: row.rootRunId, questions: row.questions, state: row.state, revision: row.revision }; }
+    async get(id) {
+        return this.storage.transaction(async (all, extra) => {
+            const row = extra.clarifications?.[id];
+            if (!row)
+                throw new Error("clarification_not_found");
+            const run = await all.runs.get(row.runId);
+            const lease = extra.leases[row.runId];
+            const state = run.status !== "running" ? run.status : row.state === "ready" && lease?.owner && lease.expires > Date.now() ? "running" : row.state;
+            return { ...this.#public(row), state, answers: row.answers };
+        });
+    }
+    async listPending() {
+        const ids = await this.storage.transaction(async (all, extra) => {
+            const result = [];
+            for (const row of Object.values((extra.clarifications ?? {}))) {
+                if ((await all.runs.get(row.runId)).status === "running")
+                    result.push(row.id);
+            }
+            return result;
+        });
+        return Promise.all(ids.map(id => this.get(id)));
+    }
+    async listWaiting() {
+        return this.storage.transaction(async (all, extra) => {
+            const result = [];
+            for (const row of Object.values((extra.clarifications ?? {}))) {
+                if (row.state === "waiting" && (await all.runs.get(row.runId)).status === "running")
+                    result.push(this.#public(row));
+            }
+            return result;
+        });
+    }
+    async answer(id, options) {
+        text(options.key);
+        encode(options.answers);
+        await this.storage.transaction(async (all, extra) => {
+            const row = extra.clarifications[id];
+            if (row.answerKey === options.key) {
+                if (encode(row.answers) !== encode(options.answers))
+                    throw new Error("clarification_idempotency_conflict");
+                return;
+            }
+            if (row.state !== "waiting" || row.revision !== options.revision)
+                throw new Error("clarification_revision_conflict");
+            if (!options.answers || Array.isArray(options.answers) || Object.keys(options.answers).length !== row.questions.length)
+                throw new Error("answers must cover the questions");
+            for (const q of row.questions) {
+                const value = text(options.answers[q.id], 8000);
+                if (!q.allowFreeform && !q.choices.includes(value))
+                    throw new Error("invalid answer choice");
+            }
+            const snapshot = await all.runs.get(row.runId);
+            if (snapshot.status !== "running")
+                throw new Error("clarification_run_terminal");
+            if (snapshot.deadlineAt !== null && Date.parse(snapshot.deadlineAt) <= Date.now())
+                throw new Error("clarification_expired");
+            const checkpoint = snapshot.executionCheckpoint;
+            if (!checkpoint)
+                throw new Error("clarification_checkpoint_missing");
+            await all.runs.saveExecutionCheckpoint(row.runId, { ...checkpoint, inputRevision: (checkpoint.inputRevision ?? 0) + 1, messages: [...checkpoint.messages,
+                    { role: "user", content: "Answers to requested task information:\n" + encode(options.answers), attributes: { inputRequestId: id } }] });
+            row.answers = options.answers;
+            row.answerKey = options.key;
+            row.state = "ready";
+            row.revision += 1;
+            await all.runs.appendEvent(row.runId, { sourceKey: `input:${id}:answered`, kind: "input.answered", channel: "lifecycle", visibility: "public", payload: this.#public(row) });
+        });
+        return this.get(id);
+    }
+    async resume(agent, id) {
+        const row = await this.storage.transaction(async (all, extra) => {
+            const saved = extra.clarifications[id];
+            if (saved.state !== "ready")
+                throw new Error("clarification_not_ready");
+            for (const r of Object.values(extra.clarifications)) {
+                if (r.rootRunId === saved.rootRunId && r.state === "waiting" && (await all.runs.get(r.runId)).status === "running")
+                    throw new Error("clarification_answers_incomplete");
+            }
+            return saved;
+        });
+        return agent.resume(row.rootRunId, row.request);
+    }
+    async cancel(id) {
+        return this.storage.transaction(async (all, extra) => {
+            const row = extra.clarifications[id];
+            let tree;
+            try {
+                tree = await all.runTree.getRun(row.rootRunId);
+            }
+            catch (error) {
+                if (error.code !== "child_run_not_found")
+                    throw error;
+            }
+            const ids = [row.rootRunId, ...(tree ? (await all.runTree.listDescendants(row.rootRunId)).map(run => run.runId) : [])];
+            if (ids.some(rid => extra.leases[rid]?.owner))
+                throw new Error("cancel the active Run through its handle");
+            const accepted = (await all.runs.cancel(row.rootRunId)).accepted;
+            if (tree) {
+                for (const rid of ids.slice(1)) {
+                    try {
+                        await all.runs.cancel(rid);
+                    }
+                    catch (error) {
+                        if (error.code !== "run_not_found")
+                            throw error;
+                    }
+                }
+                await all.runTree.cancelSubtree(row.rootRunId);
+            }
+            return accepted;
+        });
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "purra-interaction",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Durable pre-execution user clarification for PurrA",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "purra": "0.5.0",
+    "purra-sqlite": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "purra": "file:../../../typescript",
+    "typescript": "7.0.2",
+    "purra-sqlite": "file:../../sqlite/typescript"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "check": "npm run build && npm test",
+    "prepack": "npm run build"
+  },
+  "peerDependenciesMeta": {
+    "purra-sqlite": {
+      "optional": true
+    }
+  }
+}