wizards 0.1.9

package/apps/runtime/dist/engenty/document-scanner/schemas/receipt.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { documentTypeDescription, documentTypeSchema, lineItemSchema, taxTypeSchema, } from "./shared.js";
+/**
+ * Receipt extraction schema.
+ * Uses Zod `.describe()` annotations as LLM instructions (midday pattern).
+ * Designed for multi-modal OCR extraction via Mistral/Gemini.
+ */
+export const receiptSchema = z.object({
+    document_type: documentTypeSchema.describe(documentTypeDescription),
+    date: z
+        .string()
+        .nullable()
+        .describe("Date of receipt in ISO 8601 format (YYYY-MM-DD)"),
+    total_amount: z
+        .number()
+        .nullable()
+        .describe("Total amount including tax in EUR. Null if document_type is 'other'."),
+    subtotal_amount: z.number().nullable().describe("Subtotal amount before tax"),
+    tax_amount: z
+        .number()
+        .nullable()
+        .describe("Tax amount. Null if document_type is 'other'."),
+    tax_rate: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Tax rate as a percentage value (e.g., 20 for 20%)"),
+    tax_type: taxTypeSchema
+        .nullable()
+        .describe("The type of tax applied: VAT, Sales Tax, GST, Withholding Tax, Service Tax, Excise Tax, Reverse Charge, or Custom Tax. Infer from country/context if not specified."),
+    vendor_name: z
+        .string()
+        .nullable()
+        .describe("Name of the store/merchant/vendor"),
+    vendor_address: z
+        .string()
+        .nullable()
+        .describe("Complete address of the vendor"),
+    vendor_website: z
+        .string()
+        .nullable()
+        .describe("Vendor website URL — look directly on the receipt, or infer from email/store name."),
+    vendor_email: z
+        .string()
+        .nullable()
+        .describe("Email of the vendor/store if present"),
+    vendor_vat_id: z
+        .string()
+        .nullable()
+        .describe("VAT ID of the vendor (e.g., ATU12345678, DE123456789). Look for UID, USt-IdNr., or similar."),
+    payment_method: z
+        .string()
+        .nullable()
+        .describe("Method of payment (e.g., cash, credit card, debit card)"),
+    items: z
+        .array(lineItemSchema)
+        .describe("Array of items purchased on the receipt"),
+    notes: z.string().nullable().describe("Additional notes or comments"),
+    language: z
+        .string()
+        .nullable()
+        .describe("The language of the document (e.g., 'english', 'german', 'french')"),
+});

package/apps/runtime/dist/engenty/document-scanner/schemas/shared.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+/**
+ * Tax type enum — covers major international tax systems.
+ * Modeled after midday's taxTypeSchema.
+ */
+export const taxTypeSchema = z.enum([
+    "vat",
+    "sales_tax",
+    "gst",
+    "withholding_tax",
+    "service_tax",
+    "excise_tax",
+    "reverse_charge",
+    "custom_tax",
+]);
+/** Document type classifier */
+export const documentTypeSchema = z.enum(["invoice", "receipt", "other"]);
+const documentTypeDescription = `Classify this document type FIRST before extracting data:
+- 'invoice': A bill requesting payment with amounts due, from vendor to customer
+- 'receipt': Proof of completed purchase showing items and payment made
+- 'other': Any non-financial document (contracts, agreements, newsletters, shipping notifications, confirmations without amounts, terms of service, correspondence)
+If 'other', financial fields (amount, currency, etc.) may be left as null.`;
+/** Shared line item schema */
+export const lineItemSchema = z.object({
+    description: z.string().nullable().describe("Description of the item"),
+    quantity: z.number().nullable().describe("Quantity of items"),
+    unit_price: z.number().nullable().describe("Price per unit"),
+    total_price: z.number().nullable().describe("Total price for this line item"),
+    tax_rate: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Tax rate percentage for this item (e.g., 20 for 20%)"),
+    discount: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Discount amount applied to this item if any"),
+});
+export { documentTypeDescription };

package/apps/runtime/dist/engenty/search-index/chunks.js

@@ -0,0 +1,164 @@
+// Chunking helpers shared by all providers.
+//
+// `mode: "fixed"` slices on character boundaries (cheap, predictable).
+// `mode: "paragraph"` accumulates `\n\n`-separated paragraphs up to
+// `max_chunk_length` with optional word-overlap between consecutive chunks
+// (matches KB's historical chunkText so we can drop the bespoke copy).
+const CHUNK_ID_SEPARATOR = "::chunk::";
+export function createSearchChunkId(docId, chunkIndex) {
+    if (!docId.trim()) {
+        throw new Error("docId is required");
+    }
+    if (!Number.isInteger(chunkIndex) || chunkIndex < 0) {
+        throw new Error("chunkIndex must be a non-negative integer");
+    }
+    return `${docId}${CHUNK_ID_SEPARATOR}${chunkIndex}`;
+}
+export function parseSearchChunkId(chunkId) {
+    const separatorIndex = chunkId.lastIndexOf(CHUNK_ID_SEPARATOR);
+    if (separatorIndex <= 0) {
+        return null;
+    }
+    const docId = chunkId.slice(0, separatorIndex);
+    const rawIndex = chunkId.slice(separatorIndex + CHUNK_ID_SEPARATOR.length);
+    const chunkIndex = Number.parseInt(rawIndex, 10);
+    if (!Number.isInteger(chunkIndex) || chunkIndex < 0) {
+        return null;
+    }
+    return {
+        chunk_index: chunkIndex,
+        doc_id: docId,
+    };
+}
+export function compactSearchText(parts, separator = "\n\n") {
+    return parts
+        .map((part) => part?.trim() ?? "")
+        .filter(Boolean)
+        .join(separator)
+        .trim();
+}
+export function createSearchChunks(params) {
+    const mode = params.mode ?? "fixed";
+    if (mode === "paragraph") {
+        return createParagraphChunks(params);
+    }
+    return createFixedChunks(params);
+}
+function createFixedChunks(params) {
+    const maxChunkLength = Math.max(params.max_chunk_length ?? 4000, 1);
+    const chunks = [];
+    let index = 0;
+    for (let start = 0; start < params.text.length; start += maxChunkLength) {
+        const end = Math.min(start + maxChunkLength, params.text.length);
+        const slice = params.text.slice(start, end);
+        const trimmed = slice.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const sourceOffset = { end, start };
+        chunks.push(buildChunk(params, trimmed, sourceOffset, index));
+        index += 1;
+    }
+    return chunks;
+}
+function createParagraphChunks(params) {
+    const maxChunkLength = Math.max(params.max_chunk_length ?? 1000, 1);
+    const overlap = Math.max(params.overlap ?? 0, 0);
+    if (!params.text.trim()) {
+        return [];
+    }
+    const paragraphs = splitParagraphsWithOffsets(params.text);
+    const chunks = [];
+    let buffer = "";
+    let bufferStart = null;
+    let bufferEnd = 0;
+    let index = 0;
+    const flush = () => {
+        if (!buffer.trim() || bufferStart === null) {
+            return;
+        }
+        const sourceOffset = { end: bufferEnd, start: bufferStart };
+        chunks.push(buildChunk(params, buffer.trim(), sourceOffset, index));
+        index += 1;
+    };
+    for (const para of paragraphs) {
+        const tentativeLength = buffer.length + para.text.length + (buffer.length > 0 ? 2 : 0);
+        if (tentativeLength > maxChunkLength && buffer.length > 0) {
+            flush();
+            const overlapText = overlap > 0 ? takeWordsFromEnd(buffer, overlap) : "";
+            buffer = overlapText ? `${overlapText}\n\n${para.text}` : para.text;
+            bufferStart = para.start;
+            bufferEnd = para.end;
+        }
+        else {
+            if (buffer.length === 0) {
+                bufferStart = para.start;
+            }
+            buffer += (buffer ? "\n\n" : "") + para.text;
+            bufferEnd = para.end;
+        }
+    }
+    flush();
+    return chunks;
+}
+function splitParagraphsWithOffsets(text) {
+    const spans = [];
+    const re = /\n{2,}/g;
+    let lastIndex = 0;
+    for (let m = re.exec(text); m !== null; m = re.exec(text)) {
+        pushSpan(spans, text, lastIndex, m.index);
+        lastIndex = m.index + m[0].length;
+    }
+    pushSpan(spans, text, lastIndex, text.length);
+    return spans;
+}
+function pushSpan(spans, text, rawStart, rawEnd) {
+    if (rawEnd <= rawStart) {
+        return;
+    }
+    const slice = text.slice(rawStart, rawEnd);
+    const leading = slice.match(/^\s*/)?.[0].length ?? 0;
+    const trailing = slice.match(/\s*$/)?.[0].length ?? 0;
+    const start = rawStart + leading;
+    const end = rawEnd - trailing;
+    if (end <= start) {
+        return;
+    }
+    spans.push({ end, start, text: text.slice(start, end) });
+}
+function takeWordsFromEnd(text, approxChars) {
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+        return "";
+    }
+    const wordCount = Math.max(1, Math.ceil(approxChars / 6));
+    return words.slice(-wordCount).join(" ");
+}
+function buildChunk(params, text, sourceOffset, index) {
+    const chunk = {
+        chunk_id: createSearchChunkId(params.doc_id, index),
+        chunk_index: index,
+        doc_id: params.doc_id,
+        ...(params.metadata ? { metadata: params.metadata } : {}),
+        source_offset: sourceOffset,
+        text,
+    };
+    if (params.track_lines) {
+        chunk.source_lines = computeSourceLines(params.text, sourceOffset);
+    }
+    return chunk;
+}
+function computeSourceLines(text, offset) {
+    const start = countLines(text, 0, offset.start) + 1;
+    const end = countLines(text, 0, Math.max(offset.end - 1, offset.start)) + 1;
+    return { end: Math.max(end, start), start };
+}
+function countLines(text, from, to) {
+    let count = 0;
+    for (let i = from; i < to; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            count += 1;
+        }
+    }
+    return count;
+}

package/apps/runtime/dist/engenty/search-index/contracts.js

@@ -0,0 +1,9 @@
+// Core search-index contracts.
+//
+// `SearchDocument` is the wire shape every provider stores; `SearchIndexProvider`
+// is the contract every search backend implements (chat-search, kb, contacts,
+// api-catalog). Providers carry a stable `id` so the host can route auto-tools,
+// declarative re-index events, and operator status/backfill by name.
+// Sentinel for tenant-less / system-scope providers (e.g. core api-catalog).
+// Documents use a real tenant id when scoped per tenant; otherwise this value.
+export const SEARCH_INDEX_SYSTEM_TENANT_ID = "__system__";

package/apps/runtime/dist/engenty/shims/connections-sdk.js

@@ -0,0 +1,39 @@
+/**
+ * Stand-in for `@engenty/connections-sdk`: the contracts, OAuth2 and registry are engenty's own
+ * files; what engenty binds to its database and plugin host is provided here.
+ */
+import { seal, unseal } from "../../secrets/crypto.js";
+import { filesCapabilityActions } from "../connections-sdk/files-capability.js";
+import { storageCapabilityActions } from "../connections-sdk/storage-capability.js";
+export * from "../connections-sdk/oauth2.js";
+export * from "../connections-sdk/registry.js";
+export * from "../connections-sdk/types.js";
+/** Secrets of imported connectors (OAuth client id and secret) at rest. */
+export function encryptToken(plain) {
+    return seal(plain);
+}
+export function decryptToken(value) {
+    const plain = unseal(value);
+    if (plain === null) {
+        throw new Error("stored connector secret cannot be read");
+    }
+    return plain;
+}
+/**
+ * Finalises a connector definition as engenty's runtime does: a `files` capability becomes the
+ * read actions `files_list` / `files_read` / `files_stat` / `files_search`, a `storage`
+ * capability the write actions `files_write` / `files_delete` / `files_move`.
+ */
+export function defineConnector(def) {
+    if (!(def.files || def.storage)) {
+        return def;
+    }
+    return {
+        ...def,
+        actions: [
+            ...def.actions,
+            ...(def.files ? filesCapabilityActions(def.files, def.filesProviderScopes) : []),
+            ...(def.storage ? storageCapabilityActions(def.storage, def.storageProviderScopes) : []),
+        ],
+    };
+}

package/apps/runtime/dist/engenty/shims/plugin-sdk.js

@@ -0,0 +1 @@
+export {};

package/apps/runtime/dist/engenty/shims/web-ingest.js

@@ -0,0 +1,3 @@
+/** Stand-in for `@engenty/web-ingest`: its host guard, and this product's HTML to Markdown. */
+export { htmlToMarkdown } from "../../render/convert.js";
+export { assertPublicHttpHost, isBlockedIp } from "../web-ingest/ssrf.js";

package/apps/runtime/dist/engenty/web-ingest/ssrf.js

@@ -0,0 +1,277 @@
+/**
+ * SSRF protection for server-side URL fetching.
+ *
+ * `assertPublicHttpHost` is the ONE guard — it resolves the hostname via DNS and
+ * validates every returned address with `isBlockedIp`. The literal-hostname
+ * check is its internal fast path, deliberately NOT exported: a string-only
+ * check passes any name that resolves to a private address, so exporting it
+ * invites call sites that look guarded and aren't (it was the sole guard on two
+ * fetch paths until 2026-08-04 — see TRK-01).
+ *
+ * Residual risk: DNS rebinding / TOCTOU window between resolution here and the
+ * actual TCP connect.  The proper mitigation is to hook into the HTTP client's
+ * connect phase (e.g. undici `connect.lookup`). That is tracked as a follow-up.
+ */
+// No top-level node:* imports: this module reaches browser bundles through the
+// `@engenty/web-ingest` barrel (document-sources adapters → module UI plugins),
+// so IP classification is implemented in pure JS instead of `node:net.isIP`.
+const IPV4_PATTERN = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+function isValidIpv6(ip) {
+    const halves = ip.split("::");
+    if (halves.length > 2) {
+        return false;
+    }
+    const hasDoubleColon = halves.length === 2;
+    const head = halves[0] === "" ? [] : halves[0].split(":");
+    const tail = hasDoubleColon && halves[1] !== "" ? halves[1].split(":") : [];
+    const groups = [...head, ...tail];
+    let wordCount = 0;
+    for (let i = 0; i < groups.length; i++) {
+        const group = groups[i];
+        // Embedded IPv4 (e.g. ::ffff:192.168.1.1) is only valid as the last group.
+        if (i === groups.length - 1 && group.includes(".")) {
+            if (!IPV4_PATTERN.test(group)) {
+                return false;
+            }
+            wordCount += 2;
+            continue;
+        }
+        if (!/^[0-9a-fA-F]{1,4}$/.test(group)) {
+            return false;
+        }
+        wordCount += 1;
+    }
+    return hasDoubleColon ? wordCount < 8 : wordCount === 8;
+}
+/** Pure equivalent of `node:net.isIP`: 4, 6, or 0 when not a valid IP literal. */
+function isIP(ip) {
+    if (IPV4_PATTERN.test(ip)) {
+        return 4;
+    }
+    return isValidIpv6(ip) ? 6 : 0;
+}
+// ---------------------------------------------------------------------------
+// Literal-hostname fast path — internal to assertPublicHttpHost, never exported
+// ---------------------------------------------------------------------------
+/** Block obvious SSRF targets by name, before any DNS work. */
+function isBlockedHostname(hostname) {
+    const h = hostname.toLowerCase();
+    if (h === "localhost" || h.endsWith(".localhost")) {
+        return true;
+    }
+    if (h === "metadata" || h === "metadata.google.internal") {
+        return true;
+    }
+    if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h)) {
+        return true;
+    }
+    if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h)) {
+        return true;
+    }
+    if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(h)) {
+        return true;
+    }
+    if (/^172\.(1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}$/.test(h)) {
+        return true;
+    }
+    if (/^169\.254\.\d{1,3}\.\d{1,3}$/.test(h)) {
+        return true;
+    }
+    if (h === "[::1]" || h === "::1") {
+        return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// IP-level range check
+// ---------------------------------------------------------------------------
+function ipv4ToNumber(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4) {
+        return null;
+    }
+    let n = 0;
+    for (const part of parts) {
+        const octet = Number(part);
+        if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
+            return null;
+        }
+        n = n * 256 + octet;
+    }
+    return n;
+}
+function inCidr(ip, base, prefixLen) {
+    const a = ipv4ToNumber(ip);
+    const b = ipv4ToNumber(base);
+    if (a === null || b === null) {
+        return false;
+    }
+    // biome-ignore lint/suspicious/noBitwiseOperators: intentional — CIDR mask arithmetic requires bitwise ops
+    const mask = prefixLen === 0 ? 0 : (~0 << (32 - prefixLen)) >>> 0;
+    // biome-ignore lint/suspicious/noBitwiseOperators: intentional — CIDR mask arithmetic requires bitwise ops
+    return (a & mask) >>> 0 === (b & mask) >>> 0;
+}
+/**
+ * Returns true if the given IP address (v4 or v6) falls within a range that
+ * must not be reached from a server-side fetch.
+ */
+export function isBlockedIp(ip) {
+    const kind = isIP(ip);
+    if (kind === 4) {
+        // 0.0.0.0/8
+        if (inCidr(ip, "0.0.0.0", 8)) {
+            return true;
+        }
+        // 10.0.0.0/8
+        if (inCidr(ip, "10.0.0.0", 8)) {
+            return true;
+        }
+        // 100.64.0.0/10 (carrier-grade NAT)
+        if (inCidr(ip, "100.64.0.0", 10)) {
+            return true;
+        }
+        // 127.0.0.0/8 (loopback)
+        if (inCidr(ip, "127.0.0.0", 8)) {
+            return true;
+        }
+        // 169.254.0.0/16 (link-local / cloud metadata)
+        if (inCidr(ip, "169.254.0.0", 16)) {
+            return true;
+        }
+        // 172.16.0.0/12
+        if (inCidr(ip, "172.16.0.0", 12)) {
+            return true;
+        }
+        // 192.168.0.0/16
+        if (inCidr(ip, "192.168.0.0", 16)) {
+            return true;
+        }
+        // 198.18.0.0/15 (benchmark / testing)
+        if (inCidr(ip, "198.18.0.0", 15)) {
+            return true;
+        }
+        // 224.0.0.0/3 (multicast + reserved: 224–255.x.x.x)
+        if (inCidr(ip, "224.0.0.0", 3)) {
+            return true;
+        }
+        return false;
+    }
+    if (kind === 6) {
+        const lower = ip.toLowerCase();
+        // ::1 (loopback)
+        if (lower === "::1") {
+            return true;
+        }
+        // :: (unspecified)
+        if (lower === "::") {
+            return true;
+        }
+        // fc00::/7 (unique-local: fc00:: – fdff::)
+        // First 7 bits are 1111110x — covers fc00:: and fd00:: prefixes
+        if (lower.startsWith("fc") || lower.startsWith("fd")) {
+            return true;
+        }
+        // fe80::/10 (link-local)
+        if (lower.startsWith("fe8") ||
+            lower.startsWith("fe9") ||
+            lower.startsWith("fea") ||
+            lower.startsWith("feb")) {
+            return true;
+        }
+        // ::ffff:0:0/96 — IPv4-mapped; extract and re-check the embedded v4 address
+        if (lower.startsWith("::ffff:")) {
+            const v4Part = lower.slice("::ffff:".length);
+            // Could be dotted-quad (::ffff:192.168.1.1) or hex word pair (::ffff:c0a8:0101)
+            if (v4Part.includes(".")) {
+                if (isBlockedIp(v4Part)) {
+                    return true;
+                }
+            }
+            else {
+                // Parse two hex words into dotted-quad
+                const words = v4Part.split(":");
+                if (words.length === 2) {
+                    const hi = Number.parseInt(words[0], 16);
+                    const lo = Number.parseInt(words[1], 16);
+                    if (!(Number.isNaN(hi) || Number.isNaN(lo))) {
+                        // biome-ignore lint/suspicious/noBitwiseOperators: intentional — extracting octets from 16-bit words
+                        const dotted = [hi >>> 8, hi & 0xff, lo >>> 8, lo & 0xff].join(".");
+                        if (isBlockedIp(dotted)) {
+                            return true;
+                        }
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    // Not a valid IP — treat as blocked to be safe
+    return true;
+}
+/**
+ * Validates `urlString` is a safe public HTTP(S) target:
+ *  - Must be http: or https:
+ *  - Hostname must pass `isBlockedHostname` (fast-path, no DNS)
+ *  - If hostname is an IP literal, `isBlockedIp` is called directly
+ *  - Otherwise DNS is resolved and *every* returned address is checked with `isBlockedIp`
+ *
+ * Returns the parsed URL and the list of resolved addresses on success.
+ * Throws a descriptive Error on any violation.
+ *
+ * `lookupImpl` can be injected for testing; defaults to `dns/promises` lookup.
+ */
+export async function assertPublicHttpHost(urlString, lookupImpl) {
+    let url;
+    try {
+        url = new URL(urlString);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${urlString}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("Only http and https URLs are allowed");
+    }
+    const hostname = url.hostname;
+    // Strip IPv6 brackets that URL parsing leaves in
+    const hostForCheck = hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+    // Fast-path: blocked hostnames by name
+    if (isBlockedHostname(hostname)) {
+        throw new Error(`URL host is not allowed for fetch: ${hostname}`);
+    }
+    // If the hostname is an IP literal, skip DNS and check it directly
+    if (isIP(hostForCheck) !== 0) {
+        if (isBlockedIp(hostForCheck)) {
+            throw new Error(`URL host is not allowed for fetch: ${hostname}`);
+        }
+        return { url, addresses: [hostForCheck] };
+    }
+    // Resolve via DNS and check every returned address
+    let lookup;
+    if (lookupImpl) {
+        lookup = lookupImpl;
+    }
+    else {
+        const dns = await import("node:dns/promises");
+        lookup = dns.lookup;
+    }
+    let entries;
+    try {
+        entries = await lookup(hostname, { all: true, verbatim: true });
+    }
+    catch (e) {
+        throw new Error(`DNS resolution failed for ${hostname}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (entries.length === 0) {
+        throw new Error(`No DNS records found for ${hostname}`);
+    }
+    const addresses = [];
+    for (const entry of entries) {
+        if (isBlockedIp(entry.address)) {
+            throw new Error(`URL host resolves to a blocked IP (${entry.address}): ${hostname}`);
+        }
+        addresses.push(entry.address);
+    }
+    return { url, addresses };
+}

package/apps/runtime/dist/engine/asks.js

@@ -0,0 +1,60 @@
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { db, schema } from "../db/client.js";
+import { signalChanged } from "./events.js";
+/** How long a step waits for the person before it goes on without them. */
+const ASK_TIMEOUT_MS = 15 * 60_000;
+/** Runs nobody watches (an MCP client drives them): a question there would wait for no one. */
+export const unattended = new Set();
+const waiting = new Map();
+async function setAsk(runId, ask) {
+    await db.update(schema.run).set({ ask, updatedAt: new Date() }).where(eq(schema.run.id, runId));
+    signalChanged(runId);
+}
+/**
+ * Puts a question to the person and waits. The run stays "running": the step is in the middle
+ * of its work and goes on with the answer. One question per run at a time.
+ */
+export async function askPerson(runId, ask, signal) {
+    if (waiting.has(runId)) {
+        throw new Error("The wizard is already waiting for the person.");
+    }
+    const full = { ...ask, id: nanoid(10), at: new Date().toISOString() };
+    const result = new Promise((resolve) => {
+        const finish = (r) => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            resolve(r);
+        };
+        const onAbort = () => finish({ type: "skip" });
+        const timer = setTimeout(() => finish({ type: "timeout" }), ASK_TIMEOUT_MS);
+        signal.addEventListener("abort", onAbort, { once: true });
+        waiting.set(runId, { ask: full, settle: finish });
+    });
+    await setAsk(runId, full);
+    try {
+        return await result;
+    }
+    finally {
+        waiting.delete(runId);
+        await setAsk(runId, null).catch(() => undefined);
+    }
+}
+/** The question a run is waiting on, if any. */
+export function pendingAsk(runId) {
+    return waiting.get(runId)?.ask ?? null;
+}
+export function answerAsk(runId, askId, answer) {
+    const entry = waiting.get(runId);
+    if (!entry || entry.ask.id !== askId) {
+        return false;
+    }
+    entry.settle(answer);
+    return true;
+}
+/** A question left in the row by a server that stopped: nobody is waiting for it any more. */
+export async function clearStaleAsk(runId) {
+    if (!waiting.has(runId)) {
+        await db.update(schema.run).set({ ask: null }).where(eq(schema.run.id, runId));
+    }
+}