@haikit/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hai contributors
+
+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,21 @@
+# @haikit/server
+
+The runtime: agent loop, elicit state machine, the interaction security
+boundary, and a derived `query_ui`.
+
+```ts
+import { createHai, memoryStore, nodeHandler } from "@haikit/server";
+
+const hai = createHai({ model, store: memoryStore(), tools, surfaces, system });
+const handle = nodeHandler(hai, "/hai");
+```
+
+Two routes: `POST /hai/chat` and `POST /hai/interact`, both streaming SSE.
+
+**`/hai/interact` accepts `{handle, action, value}` and nothing else.** What an
+action *means* is resolved server-side from the surface's declared contract. If
+the client could name a tool, a prompt injection inside any tool result would
+become a button wired to it.
+
+`memoryStore()` is for development. A parked elicit turn is durable state —
+lose `pending` and that conversation can never be sent again.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Hai, type HaiConfig } from "./runtime.js";
+export { memoryStore } from "./store.js";
+export { nodeHandler } from "./routes.js";
+import { Hai, type HaiConfig } from "./runtime.js";
+export declare const createHai: (config: HaiConfig) => Hai;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,GAAG,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACnD,eAAO,MAAM,SAAS,GAAI,QAAQ,SAAS,QAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Hai } from "./runtime.js";
+export { memoryStore } from "./store.js";
+export { nodeHandler } from "./routes.js";
+import { Hai } from "./runtime.js";
+export const createHai = (config) => new Hai(config);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAkB,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,GAAG,EAAkB,MAAM,cAAc,CAAC;AACnD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAiB,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC"}

package/dist/routes.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Hai } from "./runtime.js";
+/**
+ * Node http handler for the two routes. Returns true if it handled the request.
+ *
+ * Both routes stream SSE, because both can resume the agent loop. Note what the
+ * interact route accepts: {handle, action, value} and nothing else. The client
+ * cannot name a tool, a handler, or an action target.
+ */
+export declare function nodeHandler(hai: Hai, basePath?: string): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,SAAS,IACxB,KAAK,eAAe,EAAE,KAAK,cAAc,KAAG,OAAO,CAAC,OAAO,CAAC,CAiC1F"}

package/dist/routes.js

@@ -0,0 +1,54 @@
+/**
+ * Node http handler for the two routes. Returns true if it handled the request.
+ *
+ * Both routes stream SSE, because both can resume the agent loop. Note what the
+ * interact route accepts: {handle, action, value} and nothing else. The client
+ * cannot name a tool, a handler, or an action target.
+ */
+export function nodeHandler(hai, basePath = "/hai") {
+    return async function handle(req, res) {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (req.method !== "POST" || !url.pathname.startsWith(basePath))
+            return false;
+        const route = url.pathname.slice(basePath.length);
+        if (route !== "/chat" && route !== "/interact")
+            return false;
+        const body = await readJson(req);
+        const conversation = await hai.config.store.loadConversation(body.conversationId);
+        const emit = openSSE(res);
+        if (route === "/chat") {
+            emit({ type: "hello", conversationId: conversation.id, model: hai.config.model.id });
+        }
+        try {
+            if (route === "/chat") {
+                await hai.send(conversation, String(body.message ?? ""), emit);
+            }
+            else {
+                await hai.interact(conversation, { handle: body.handle, action: body.action, value: body.value }, emit);
+            }
+        }
+        catch (err) {
+            emit({ type: "error", message: err.message });
+        }
+        await hai.config.store.saveConversation(conversation);
+        res.end();
+        return true;
+    };
+}
+function openSSE(res) {
+    res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+    });
+    return (event) => {
+        res.write(`data: ${JSON.stringify(event)}\n\n`);
+    };
+}
+async function readJson(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return JSON.parse(Buffer.concat(chunks).toString() || "{}");
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAQ,EAAE,QAAQ,GAAG,MAAM;IACrD,OAAO,KAAK,UAAU,MAAM,CAAC,GAAoB,EAAE,GAAmB;QACpE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACxD,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAE9E,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC;QAE7D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAElF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACvF,CAAC;QAED,IAAI,CAAC;YACH,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;gBACtB,MAAM,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YACjE,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,CAAC,QAAQ,CAChB,YAAY,EACZ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,EAC/D,IAAI,CACL,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3D,CAAC;QAED,MAAM,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC;QACtD,GAAG,CAAC,GAAG,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,GAAmB;IAClC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;QACjB,cAAc,EAAE,mBAAmB;QACnC,eAAe,EAAE,UAAU;QAC3B,UAAU,EAAE,YAAY;KACzB,CAAC,CAAC;IACH,OAAO,CAAC,KAAgB,EAAE,EAAE;QAC1B,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,GAAoB;IAC1C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG;QAAE,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC,CAAC;AAC9D,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,31 @@
+import { type AnySurfaceImpl, type Conversation, type Emit, type ModelAdapter, type StoreAdapter, type Tool } from "@haikit/core";
+export interface HaiConfig {
+    model: ModelAdapter;
+    store: StoreAdapter;
+    system: string;
+    tools: Tool[];
+    surfaces: AnySurfaceImpl[];
+    /** Guard against runaway tool loops. */
+    maxHops?: number;
+    /** Turn lease duration; a dead process releases after this. */
+    leaseMs?: number;
+}
+export declare class Hai {
+    readonly config: HaiConfig;
+    private readonly surfaces;
+    private readonly tools;
+    private seq;
+    constructor(config: HaiConfig);
+    private nid;
+    private buildQueryUiTool;
+    send(conversation: Conversation, text: string, emit: Emit): Promise<void>;
+    interact(conversation: Conversation, input: {
+        handle: string;
+        action: string;
+        value: unknown;
+    }, emit: Emit): Promise<void>;
+    private runTurn;
+    private invokeTool;
+    private emitContext;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,IAAI,EACT,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,IAAI,EAGV,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,qBAAa,GAAG;IACd,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,GAAG,CAAK;gBAEJ,MAAM,EAAE,SAAS;IAU7B,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,gBAAgB;IAuDlB,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BzE,QAAQ,CACZ,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EACzD,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC;YAsDF,OAAO;YA0EP,UAAU;YA+DV,WAAW;CAa1B"}

package/dist/runtime.js

@@ -0,0 +1,288 @@
+import { estTokens, makeCap, } from "@haikit/core";
+const LEASE_MS = 120_000;
+export class Hai {
+    config;
+    surfaces = new Map();
+    tools = new Map();
+    seq = 0;
+    constructor(config) {
+        this.config = config;
+        for (const s of config.surfaces)
+            this.surfaces.set(s.surface.name, s);
+        for (const t of config.tools)
+            this.tools.set(t.name, t);
+        // query_ui is DERIVED, never authored. It cannot drift from the surfaces
+        // that actually exist, and it always exists.
+        const queryUi = this.buildQueryUiTool();
+        this.tools.set(queryUi.name, queryUi);
+    }
+    nid(prefix) {
+        return `${prefix}_${++this.seq}`;
+    }
+    // ───────────────────────────────────────────────── derived tool
+    buildQueryUiTool() {
+        const catalogue = [...this.surfaces.values()]
+            .map((s) => {
+            const names = Object.keys(s.surface.queries);
+            return names.length ? `${s.surface.name}: ${names.join(", ")}` : null;
+        })
+            .filter(Boolean)
+            .join(" · ");
+        const self = this;
+        return {
+            name: "query_ui",
+            description: "Dereference a rendered component's full dataset. The digest in your context holds only " +
+                "highlights; use this for anything beyond it. Never guess about rows you have not seen. " +
+                (catalogue ? `Available queries — ${catalogue}.` : ""),
+            input: { parse: (v) => v },
+            inputJsonSchema: {
+                type: "object",
+                properties: {
+                    handle: { type: "string", description: "e.g. ui_01" },
+                    query: { type: "string" },
+                    args: { type: "object" },
+                },
+                required: ["handle", "query"],
+            },
+            strict: false,
+            async run(input, ctx) {
+                const record = await self.config.store.getPayload(input.handle, ctx.conversationId);
+                if (!record)
+                    return ctx.text(`No such handle: ${input.handle}`);
+                const impl = self.surfaces.get(record.component);
+                const handler = impl?.impl.queries?.[input.query];
+                if (!impl || !handler) {
+                    const available = impl ? Object.keys(impl.surface.queries).join(", ") : "none";
+                    return ctx.text(`Unsupported query "${input.query}". Available: ${available || "none"}.`);
+                }
+                const spec = impl.surface.queries[input.query];
+                let args;
+                try {
+                    args = spec.input.parse(input.args ?? {});
+                }
+                catch (err) {
+                    return ctx.text(`Invalid args for "${input.query}": ${err.message}`);
+                }
+                const rows = record.props?.[primaryCollection(record.props)] ?? [];
+                const capped = handler(args, { props: record.props, cap: makeCap(rows.length) });
+                return ctx.text(capped.text);
+            },
+        };
+    }
+    // ─────────────────────────────────────────────────── public API
+    async send(conversation, text, emit) {
+        // The user typed while a tool was parked. Every tool_use in a turn must
+        // receive a tool_result, so close the pending one out honestly first.
+        if (conversation.status === "awaiting" && conversation.pending) {
+            const { toolUseId, handle, results, digest } = conversation.pending;
+            await this.config.store.freezePayload(handle);
+            emit({ type: "ui_state", handle, state: "frozen" });
+            conversation.messages.push({
+                role: "user",
+                content: [
+                    ...results,
+                    {
+                        type: "tool_result",
+                        tool_use_id: toolUseId,
+                        content: `${digest}\nUser did not select; they said: "${text}"`,
+                    },
+                ],
+            });
+            conversation.pending = null;
+        }
+        emit({ type: "block_start", block: { kind: "user", id: this.nid("b"), text } });
+        conversation.messages.push({ role: "user", content: text });
+        await this.runTurn(conversation, emit);
+    }
+    async interact(conversation, input, emit) {
+        const record = await this.config.store.getPayload(input.handle, conversation.id);
+        if (!record)
+            throw new Error("unknown handle");
+        if (record.state === "frozen")
+            throw new Error("component is frozen");
+        const impl = this.surfaces.get(record.component);
+        if (!impl)
+            throw new Error(`unknown component: ${record.component}`);
+        // GUARANTEE 4 in force at runtime: the client sent {handle, action, value}.
+        // What that action MEANS is decided here, from the declared contract.
+        const spec = impl.surface.actions[input.action];
+        const handler = impl.impl.actions?.[input.action];
+        if (!spec || !handler)
+            throw new Error("unbound action");
+        let value;
+        try {
+            value = spec.input.parse(input.value);
+        }
+        catch (err) {
+            throw new Error(`invalid action payload: ${err.message}`);
+        }
+        const label = handler(value, { props: record.props, handle: record.handle });
+        if (spec.kind === "resolve") {
+            if (conversation.pending?.handle !== input.handle)
+                throw new Error("nothing awaiting this handle");
+            await this.config.store.freezePayload(input.handle);
+            emit({ type: "ui_state", handle: input.handle, state: "frozen", selection: value });
+            emit({ type: "block_start", block: { kind: "interaction", id: this.nid("b"), handle: input.handle, label } });
+            conversation.messages.push({
+                role: "user",
+                content: [
+                    ...conversation.pending.results,
+                    {
+                        type: "tool_result",
+                        tool_use_id: conversation.pending.toolUseId,
+                        // The digest rides along: this elicit tool never got a tool_result,
+                        // so nothing about the search has reached the model yet.
+                        content: `${conversation.pending.digest}\n${label}`,
+                    },
+                ],
+            });
+            conversation.pending = null;
+            return this.runTurn(conversation, emit);
+        }
+        // inform: enriches the conversation without having blocked it
+        emit({ type: "block_start", block: { kind: "interaction", id: this.nid("b"), handle: input.handle, label } });
+        conversation.messages.push({ role: "user", content: `[UI interaction] ${label}` });
+        return this.runTurn(conversation, emit);
+    }
+    // ──────────────────────────────────────────────── the agent loop
+    async runTurn(conversation, emit) {
+        conversation.status = "streaming";
+        conversation.leaseUntil = Date.now() + (this.config.leaseMs ?? LEASE_MS);
+        emit({ type: "status", status: "streaming" });
+        const toolDefs = [...this.tools.values()].map((t) => ({
+            name: t.name,
+            description: t.description,
+            input_schema: t.inputJsonSchema,
+            strict: t.strict,
+        }));
+        for (let hop = 0; hop < (this.config.maxHops ?? 8); hop++) {
+            const blockId = this.nid("b");
+            let opened = false;
+            const final = await this.config.model.generate({
+                system: this.config.system,
+                tools: toolDefs,
+                messages: conversation.messages,
+                onTextDelta: (text) => {
+                    if (!opened) {
+                        opened = true;
+                        emit({ type: "block_start", block: { kind: "assistant", id: blockId, text: "" } });
+                    }
+                    emit({ type: "text_delta", id: blockId, text });
+                },
+            });
+            conversation.messages.push({ role: "assistant", content: final.content });
+            if (final.stop_reason !== "tool_use")
+                break;
+            const results = [];
+            let parked = null;
+            for (const call of final.content.filter((b) => b?.type === "tool_use")) {
+                const toolBlockId = this.nid("b");
+                emit({
+                    type: "block_start",
+                    block: { kind: "tool", id: toolBlockId, name: call.name, input: call.input, status: "running" },
+                });
+                const started = Date.now();
+                const { ret, mode } = await this.invokeTool(conversation, call, emit, toolBlockId);
+                const ms = Date.now() - started;
+                if (mode === "elicit" && ret.handle) {
+                    emit({ type: "block_update", id: toolBlockId, status: "awaiting", ms, result: ret.model });
+                    parked = { toolUseId: call.id, handle: ret.handle, digest: ret.model };
+                }
+                else {
+                    emit({ type: "block_update", id: toolBlockId, status: "ok", ms, result: ret.model });
+                    results.push({ type: "tool_result", tool_use_id: call.id, content: ret.model });
+                }
+            }
+            if (parked) {
+                // Hold the resolved siblings too — the API is all-or-nothing per batch.
+                conversation.status = "awaiting";
+                conversation.pending = { ...parked, results };
+                conversation.leaseUntil = null;
+                emit({ type: "status", status: "awaiting" });
+                await this.emitContext(conversation, emit);
+                return;
+            }
+            conversation.messages.push({ role: "user", content: results });
+        }
+        conversation.status = "idle";
+        conversation.leaseUntil = null;
+        emit({ type: "status", status: "idle" });
+        await this.emitContext(conversation, emit);
+    }
+    async invokeTool(conversation, call, emit, toolBlockId) {
+        const tool = this.tools.get(call.name);
+        if (!tool)
+            return { ret: { model: `Unknown tool: ${call.name}` }, mode: null };
+        let mode = null;
+        const ctx = {
+            conversationId: conversation.id,
+            text: (model) => ({ model }),
+            render: (async (impl, props, options) => {
+                const surfaceMode = options?.mode ?? "display";
+                mode = surfaceMode;
+                // Validate before storing: props may originate outside this process.
+                const parsed = impl.surface.props.parse(props);
+                const handle = await this.config.store.putPayload({
+                    conversationId: conversation.id,
+                    component: impl.surface.name,
+                    version: impl.surface.version,
+                    props: parsed,
+                    mode: surfaceMode,
+                    state: "live",
+                });
+                conversation.handles.push(handle);
+                // The split, in two lines. Digest -> model. Payload -> browser.
+                const digest = impl.impl.digest(parsed, { handle });
+                emit({
+                    type: "ui_open",
+                    handle,
+                    toolId: toolBlockId,
+                    component: impl.surface.name,
+                    version: impl.surface.version,
+                    mode: surfaceMode,
+                });
+                emit({ type: "ui_props", handle, props: parsed });
+                return { model: digest, handle };
+            }),
+        };
+        let input;
+        try {
+            input = tool.input.parse(call.input);
+        }
+        catch (err) {
+            return { ret: { model: `Invalid input for ${call.name}: ${err.message}` }, mode: null };
+        }
+        try {
+            const ret = await tool.run(input, ctx);
+            return { ret, mode };
+        }
+        catch (err) {
+            return { ret: { model: `${call.name} failed: ${err.message}` }, mode: null };
+        }
+    }
+    async emitContext(conversation, emit) {
+        let uiTokens = 0;
+        for (const handle of conversation.handles) {
+            const record = await this.config.store.getPayload(handle, conversation.id);
+            if (record)
+                uiTokens += estTokens(record.props);
+        }
+        emit({
+            type: "context",
+            messages: conversation.messages,
+            modelTokens: estTokens(conversation.messages),
+            uiTokens,
+        });
+    }
+}
+/** Find the array prop a surface's queries operate over (for cap totals). */
+function primaryCollection(props) {
+    if (props && typeof props === "object") {
+        for (const [key, value] of Object.entries(props)) {
+            if (Array.isArray(value))
+                return key;
+        }
+    }
+    return "";
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,OAAO,GASR,MAAM,cAAc,CAAC;AActB,MAAM,QAAQ,GAAG,OAAO,CAAC;AAEzB,MAAM,OAAO,GAAG;IACL,MAAM,CAAY;IACV,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC7C,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IACzC,GAAG,GAAG,CAAC,CAAC;IAEhB,YAAY,MAAiB;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACxD,yEAAyE;QACzE,6CAA6C;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAEO,GAAG,CAAC,MAAc;QACxB,OAAO,GAAG,MAAM,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IACnC,CAAC;IAED,iEAAiE;IAEzD,gBAAgB;QACtB,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;aAC1C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC7C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACxE,CAAC,CAAC;aACD,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,KAAK,CAAC,CAAC;QAEf,MAAM,IAAI,GAAG,IAAI,CAAC;QAClB,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,WAAW,EACT,yFAAyF;gBACzF,yFAAyF;gBACzF,CAAC,SAAS,CAAC,CAAC,CAAC,uBAAuB,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAQ,EAAE;YACjC,eAAe,EAAE;gBACf,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE;oBACrD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iBACzB;gBACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC;aAC9B;YACD,MAAM,EAAE,KAAK;YACb,KAAK,CAAC,GAAG,CAAC,KAAwD,EAAE,GAAG;gBACrE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;gBACpF,IAAI,CAAC,MAAM;oBAAE,OAAO,GAAG,CAAC,IAAI,CAAC,mBAAmB,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;gBAEhE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACjD,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAClD,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBACtB,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;oBAC/E,OAAO,GAAG,CAAC,IAAI,CAAC,sBAAsB,KAAK,CAAC,KAAK,iBAAiB,SAAS,IAAI,MAAM,GAAG,CAAC,CAAC;gBAC5F,CAAC;gBAED,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC/C,IAAI,IAAa,CAAC;gBAClB,IAAI,CAAC;oBACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;gBAC5C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,GAAG,CAAC,IAAI,CAAC,qBAAqB,KAAK,CAAC,KAAK,MAAO,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;gBAClF,CAAC;gBAED,MAAM,IAAI,GAAI,MAAM,CAAC,KAAa,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACjF,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;SACF,CAAC;IACJ,CAAC;IAED,iEAAiE;IAEjE,KAAK,CAAC,IAAI,CAAC,YAA0B,EAAE,IAAY,EAAE,IAAU;QAC7D,wEAAwE;QACxE,sEAAsE;QACtE,IAAI,YAAY,CAAC,MAAM,KAAK,UAAU,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;YAC/D,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC;YACpE,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;YACpD,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACzB,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,GAAG,OAAO;oBACV;wBACE,IAAI,EAAE,aAAa;wBACnB,WAAW,EAAE,SAAS;wBACtB,OAAO,EAAE,GAAG,MAAM,sCAAsC,IAAI,GAAG;qBAChE;iBACF;aACF,CAAC,CAAC;YACH,YAAY,CAAC,OAAO,GAAG,IAAI,CAAC;QAC9B,CAAC;QAED,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QAChF,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,YAA0B,EAC1B,KAAyD,EACzD,IAAU;QAEV,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC/C,IAAI,MAAM,CAAC,KAAK,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;QAEtE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAErE,4EAA4E;QAC5E,sEAAsE;QACtE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAChD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAEzD,IAAI,KAAc,CAAC;QACnB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,2BAA4B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAE7E,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,YAAY,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;YACnG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACpD,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YACpF,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YAE9G,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACzB,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO;oBAC/B;wBACE,IAAI,EAAE,aAAa;wBACnB,WAAW,EAAE,YAAY,CAAC,OAAO,CAAC,SAAS;wBAC3C,oEAAoE;wBACpE,yDAAyD;wBACzD,OAAO,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE;qBACpD;iBACF;aACF,CAAC,CAAC;YACH,YAAY,CAAC,OAAO,GAAG,IAAI,CAAC;YAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC;QAED,8DAA8D;QAC9D,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC9G,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,KAAK,EAAE,EAAE,CAAC,CAAC;QACnF,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,kEAAkE;IAE1D,KAAK,CAAC,OAAO,CAAC,YAA0B,EAAE,IAAU;QAC1D,YAAY,CAAC,MAAM,GAAG,WAAW,CAAC;QAClC,YAAY,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,CAAC;QACzE,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QAE9C,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpD,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,YAAY,EAAE,CAAC,CAAC,eAAe;YAC/B,MAAM,EAAE,CAAC,CAAC,MAAM;SACjB,CAAC,CAAC,CAAC;QAEJ,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;YAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,MAAM,GAAG,KAAK,CAAC;YAEnB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC;gBAC7C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;gBAC1B,KAAK,EAAE,QAAQ;gBACf,QAAQ,EAAE,YAAY,CAAC,QAAQ;gBAC/B,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE;oBACpB,IAAI,CAAC,MAAM,EAAE,CAAC;wBACZ,MAAM,GAAG,IAAI,CAAC;wBACd,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;oBACrF,CAAC;oBACD,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;gBAClD,CAAC;aACF,CAAC,CAAC;YAEH,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,IAAI,KAAK,CAAC,WAAW,KAAK,UAAU;gBAAE,MAAM;YAE5C,MAAM,OAAO,GAAc,EAAE,CAAC;YAC9B,IAAI,MAAM,GAAiE,IAAI,CAAC;YAEhF,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,KAAK,UAAU,CAAC,EAAE,CAAC;gBAC5E,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClC,IAAI,CAAC;oBACH,IAAI,EAAE,aAAa;oBACnB,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE;iBAChG,CAAC,CAAC;gBAEH,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC3B,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;gBACnF,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;gBAEhC,IAAI,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;oBACpC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;oBAC3F,MAAM,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;gBACzE,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;oBACrF,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;gBAClF,CAAC;YACH,CAAC;YAED,IAAI,MAAM,EAAE,CAAC;gBACX,wEAAwE;gBACxE,YAAY,CAAC,MAAM,GAAG,UAAU,CAAC;gBACjC,YAAY,CAAC,OAAO,GAAG,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC;gBAC9C,YAAY,CAAC,UAAU,GAAG,IAAI,CAAC;gBAC/B,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC7C,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;gBAC3C,OAAO;YACT,CAAC;YAED,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,YAAY,CAAC,MAAM,GAAG,MAAM,CAAC;QAC7B,YAAY,CAAC,UAAU,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAEO,KAAK,CAAC,UAAU,CACtB,YAA0B,EAC1B,IAAS,EACT,IAAU,EACV,WAAmB;QAEnB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,iBAAiB,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAE/E,IAAI,IAAI,GAAgC,IAAI,CAAC;QAE7C,MAAM,GAAG,GAAY;YACnB,cAAc,EAAE,YAAY,CAAC,EAAE;YAC/B,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YAC5B,MAAM,EAAE,CAAC,KAAK,EAAE,IAAoB,EAAE,KAAc,EAAE,OAAyC,EAAE,EAAE;gBACjG,MAAM,WAAW,GAAG,OAAO,EAAE,IAAI,IAAI,SAAS,CAAC;gBAC/C,IAAI,GAAG,WAAW,CAAC;gBAEnB,qEAAqE;gBACrE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAE/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;oBAChD,cAAc,EAAE,YAAY,CAAC,EAAE;oBAC/B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;oBAC5B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;oBAC7B,KAAK,EAAE,MAAM;oBACb,IAAI,EAAE,WAAW;oBACjB,KAAK,EAAE,MAAM;iBACd,CAAC,CAAC;gBAEH,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAElC,gEAAgE;gBAChE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;gBACpD,IAAI,CAAC;oBACH,IAAI,EAAE,SAAS;oBACf,MAAM;oBACN,MAAM,EAAE,WAAW;oBACnB,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;oBAC5B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;oBAC7B,IAAI,EAAE,WAAW;iBAClB,CAAC,CAAC;gBACH,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;gBAElD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YACnC,CAAC,CAAsB;SACxB,CAAC;QAEF,IAAI,KAAc,CAAC;QACnB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,qBAAqB,IAAI,CAAC,IAAI,KAAM,GAAa,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACrG,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACvC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QACvB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,IAAI,YAAa,GAAa,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC1F,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,YAA0B,EAAE,IAAU;QAC9D,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,MAAM,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;YAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;YAC3E,IAAI,MAAM;gBAAE,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,CAAC;YACH,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,YAAY,CAAC,QAAQ;YAC/B,WAAW,EAAE,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC;YAC7C,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;CACF;AAED,6EAA6E;AAC7E,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC5E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAO,GAAG,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,10 @@
+import type { StoreAdapter } from "@haikit/core";
+/**
+ * In-memory store. Implements the same interface a Postgres store would.
+ *
+ * Swapping this for a durable store is the single highest-value change for
+ * production: a parked `elicit` turn is durable state, and losing `pending`
+ * makes a conversation permanently unsendable.
+ */
+export declare function memoryStore(): StoreAdapter;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA+B,YAAY,EAAE,MAAM,cAAc,CAAC;AAE9E;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,YAAY,CA2C1C"}

package/dist/store.js

@@ -0,0 +1,50 @@
+/**
+ * In-memory store. Implements the same interface a Postgres store would.
+ *
+ * Swapping this for a durable store is the single highest-value change for
+ * production: a parked `elicit` turn is durable state, and losing `pending`
+ * makes a conversation permanently unsendable.
+ */
+export function memoryStore() {
+    const conversations = new Map();
+    const payloads = new Map();
+    let convSeq = 0;
+    let handleSeq = 0;
+    return {
+        async loadConversation(id) {
+            if (id && conversations.has(id))
+                return conversations.get(id);
+            const conversation = {
+                id: `conv_${++convSeq}`,
+                status: "idle",
+                messages: [],
+                handles: [],
+                pending: null,
+                leaseUntil: null,
+            };
+            conversations.set(conversation.id, conversation);
+            return conversation;
+        },
+        async saveConversation(conversation) {
+            conversations.set(conversation.id, conversation);
+        },
+        async putPayload(record) {
+            const handle = `ui_${String(++handleSeq).padStart(2, "0")}`;
+            payloads.set(handle, { ...record, handle, createdAt: Date.now() });
+            return handle;
+        },
+        /** Scoped: a handle from another conversation must not resolve. */
+        async getPayload(handle, conversationId) {
+            const record = payloads.get(handle);
+            if (!record || record.conversationId !== conversationId)
+                return null;
+            return record;
+        },
+        async freezePayload(handle) {
+            const record = payloads.get(handle);
+            if (record)
+                record.state = "frozen";
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,aAAa,GAAG,IAAI,GAAG,EAAwB,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyB,CAAC;IAClD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,OAAO;QACL,KAAK,CAAC,gBAAgB,CAAC,EAAE;YACvB,IAAI,EAAE,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,OAAO,aAAa,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;YAC/D,MAAM,YAAY,GAAiB;gBACjC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE;gBACvB,MAAM,EAAE,MAAM;gBACd,QAAQ,EAAE,EAAE;gBACZ,OAAO,EAAE,EAAE;gBACX,OAAO,EAAE,IAAI;gBACb,UAAU,EAAE,IAAI;aACjB,CAAC;YACF,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;YACjD,OAAO,YAAY,CAAC;QACtB,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,YAAY;YACjC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;QACnD,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,MAAM;YACrB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YAC5D,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACnE,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,mEAAmE;QACnE,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,cAAc;YACrC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,cAAc,KAAK,cAAc;gBAAE,OAAO,IAAI,CAAC;YACrE,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,aAAa,CAAC,MAAM;YACxB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,MAAM;gBAAE,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@haikit/server",
+  "version": "0.1.0",
+  "description": "The haikit server runtime: agent loop, elicit state machine, derived query_ui, and the interaction security boundary.",
+  "keywords": [
+    "haikit",
+    "llm",
+    "agent",
+    "agentic-ui",
+    "generative-ui",
+    "tool-use",
+    "tool-calling",
+    "elicitation",
+    "sse",
+    "ai"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "prepack": "npm --prefix ../.. run build"
+  },
+  "dependencies": {
+    "@haikit/core": "0.1.0",
+    "@types/node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/wfoxd/haikit/tree/main/packages/server#readme",
+  "bugs": {
+    "url": "https://github.com/wfoxd/haikit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wfoxd/haikit.git",
+    "directory": "packages/server"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { Hai, type HaiConfig } from "./runtime.js";
+export { memoryStore } from "./store.js";
+export { nodeHandler } from "./routes.js";
+
+import { Hai, type HaiConfig } from "./runtime.js";
+export const createHai = (config: HaiConfig) => new Hai(config);

package/src/routes.ts

@@ -0,0 +1,63 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Emit, WireEvent } from "@haikit/core";
+import type { Hai } from "./runtime.js";
+
+/**
+ * Node http handler for the two routes. Returns true if it handled the request.
+ *
+ * Both routes stream SSE, because both can resume the agent loop. Note what the
+ * interact route accepts: {handle, action, value} and nothing else. The client
+ * cannot name a tool, a handler, or an action target.
+ */
+export function nodeHandler(hai: Hai, basePath = "/hai") {
+  return async function handle(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (req.method !== "POST" || !url.pathname.startsWith(basePath)) return false;
+
+    const route = url.pathname.slice(basePath.length);
+    if (route !== "/chat" && route !== "/interact") return false;
+
+    const body = await readJson(req);
+    const conversation = await hai.config.store.loadConversation(body.conversationId);
+
+    const emit = openSSE(res);
+    if (route === "/chat") {
+      emit({ type: "hello", conversationId: conversation.id, model: hai.config.model.id });
+    }
+
+    try {
+      if (route === "/chat") {
+        await hai.send(conversation, String(body.message ?? ""), emit);
+      } else {
+        await hai.interact(
+          conversation,
+          { handle: body.handle, action: body.action, value: body.value },
+          emit,
+        );
+      }
+    } catch (err) {
+      emit({ type: "error", message: (err as Error).message });
+    }
+
+    await hai.config.store.saveConversation(conversation);
+    res.end();
+    return true;
+  };
+}
+
+function openSSE(res: ServerResponse): Emit {
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    connection: "keep-alive",
+  });
+  return (event: WireEvent) => {
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+  };
+}
+
+async function readJson(req: IncomingMessage): Promise<any> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  return JSON.parse(Buffer.concat(chunks).toString() || "{}");
+}

package/src/runtime.ts

@@ -0,0 +1,349 @@
+import {
+  estTokens,
+  makeCap,
+  type AnySurfaceImpl,
+  type Conversation,
+  type Emit,
+  type ModelAdapter,
+  type StoreAdapter,
+  type Tool,
+  type ToolCtx,
+  type ToolReturn,
+} from "@haikit/core";
+
+export interface HaiConfig {
+  model: ModelAdapter;
+  store: StoreAdapter;
+  system: string;
+  tools: Tool[];
+  surfaces: AnySurfaceImpl[];
+  /** Guard against runaway tool loops. */
+  maxHops?: number;
+  /** Turn lease duration; a dead process releases after this. */
+  leaseMs?: number;
+}
+
+const LEASE_MS = 120_000;
+
+export class Hai {
+  readonly config: HaiConfig;
+  private readonly surfaces = new Map<string, AnySurfaceImpl>();
+  private readonly tools = new Map<string, Tool>();
+  private seq = 0;
+
+  constructor(config: HaiConfig) {
+    this.config = config;
+    for (const s of config.surfaces) this.surfaces.set(s.surface.name, s);
+    for (const t of config.tools) this.tools.set(t.name, t);
+    // query_ui is DERIVED, never authored. It cannot drift from the surfaces
+    // that actually exist, and it always exists.
+    const queryUi = this.buildQueryUiTool();
+    this.tools.set(queryUi.name, queryUi);
+  }
+
+  private nid(prefix: string) {
+    return `${prefix}_${++this.seq}`;
+  }
+
+  // ───────────────────────────────────────────────── derived tool
+
+  private buildQueryUiTool(): Tool<any> {
+    const catalogue = [...this.surfaces.values()]
+      .map((s) => {
+        const names = Object.keys(s.surface.queries);
+        return names.length ? `${s.surface.name}: ${names.join(", ")}` : null;
+      })
+      .filter(Boolean)
+      .join(" · ");
+
+    const self = this;
+    return {
+      name: "query_ui",
+      description:
+        "Dereference a rendered component's full dataset. The digest in your context holds only " +
+        "highlights; use this for anything beyond it. Never guess about rows you have not seen. " +
+        (catalogue ? `Available queries — ${catalogue}.` : ""),
+      input: { parse: (v) => v as any },
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          handle: { type: "string", description: "e.g. ui_01" },
+          query: { type: "string" },
+          args: { type: "object" },
+        },
+        required: ["handle", "query"],
+      },
+      strict: false,
+      async run(input: { handle: string; query: string; args?: unknown }, ctx) {
+        const record = await self.config.store.getPayload(input.handle, ctx.conversationId);
+        if (!record) return ctx.text(`No such handle: ${input.handle}`);
+
+        const impl = self.surfaces.get(record.component);
+        const handler = impl?.impl.queries?.[input.query];
+        if (!impl || !handler) {
+          const available = impl ? Object.keys(impl.surface.queries).join(", ") : "none";
+          return ctx.text(`Unsupported query "${input.query}". Available: ${available || "none"}.`);
+        }
+
+        const spec = impl.surface.queries[input.query];
+        let args: unknown;
+        try {
+          args = spec.input.parse(input.args ?? {});
+        } catch (err) {
+          return ctx.text(`Invalid args for "${input.query}": ${(err as Error).message}`);
+        }
+
+        const rows = (record.props as any)?.[primaryCollection(record.props)] ?? [];
+        const capped = handler(args, { props: record.props, cap: makeCap(rows.length) });
+        return ctx.text(capped.text);
+      },
+    };
+  }
+
+  // ─────────────────────────────────────────────────── public API
+
+  async send(conversation: Conversation, text: string, emit: Emit): Promise<void> {
+    // The user typed while a tool was parked. Every tool_use in a turn must
+    // receive a tool_result, so close the pending one out honestly first.
+    if (conversation.status === "awaiting" && conversation.pending) {
+      const { toolUseId, handle, results, digest } = conversation.pending;
+      await this.config.store.freezePayload(handle);
+      emit({ type: "ui_state", handle, state: "frozen" });
+      conversation.messages.push({
+        role: "user",
+        content: [
+          ...results,
+          {
+            type: "tool_result",
+            tool_use_id: toolUseId,
+            content: `${digest}\nUser did not select; they said: "${text}"`,
+          },
+        ],
+      });
+      conversation.pending = null;
+    }
+
+    emit({ type: "block_start", block: { kind: "user", id: this.nid("b"), text } });
+    conversation.messages.push({ role: "user", content: text });
+    await this.runTurn(conversation, emit);
+  }
+
+  async interact(
+    conversation: Conversation,
+    input: { handle: string; action: string; value: unknown },
+    emit: Emit,
+  ): Promise<void> {
+    const record = await this.config.store.getPayload(input.handle, conversation.id);
+    if (!record) throw new Error("unknown handle");
+    if (record.state === "frozen") throw new Error("component is frozen");
+
+    const impl = this.surfaces.get(record.component);
+    if (!impl) throw new Error(`unknown component: ${record.component}`);
+
+    // GUARANTEE 4 in force at runtime: the client sent {handle, action, value}.
+    // What that action MEANS is decided here, from the declared contract.
+    const spec = impl.surface.actions[input.action];
+    const handler = impl.impl.actions?.[input.action];
+    if (!spec || !handler) throw new Error("unbound action");
+
+    let value: unknown;
+    try {
+      value = spec.input.parse(input.value);
+    } catch (err) {
+      throw new Error(`invalid action payload: ${(err as Error).message}`);
+    }
+
+    const label = handler(value, { props: record.props, handle: record.handle });
+
+    if (spec.kind === "resolve") {
+      if (conversation.pending?.handle !== input.handle) throw new Error("nothing awaiting this handle");
+      await this.config.store.freezePayload(input.handle);
+      emit({ type: "ui_state", handle: input.handle, state: "frozen", selection: value });
+      emit({ type: "block_start", block: { kind: "interaction", id: this.nid("b"), handle: input.handle, label } });
+
+      conversation.messages.push({
+        role: "user",
+        content: [
+          ...conversation.pending.results,
+          {
+            type: "tool_result",
+            tool_use_id: conversation.pending.toolUseId,
+            // The digest rides along: this elicit tool never got a tool_result,
+            // so nothing about the search has reached the model yet.
+            content: `${conversation.pending.digest}\n${label}`,
+          },
+        ],
+      });
+      conversation.pending = null;
+      return this.runTurn(conversation, emit);
+    }
+
+    // inform: enriches the conversation without having blocked it
+    emit({ type: "block_start", block: { kind: "interaction", id: this.nid("b"), handle: input.handle, label } });
+    conversation.messages.push({ role: "user", content: `[UI interaction] ${label}` });
+    return this.runTurn(conversation, emit);
+  }
+
+  // ──────────────────────────────────────────────── the agent loop
+
+  private async runTurn(conversation: Conversation, emit: Emit): Promise<void> {
+    conversation.status = "streaming";
+    conversation.leaseUntil = Date.now() + (this.config.leaseMs ?? LEASE_MS);
+    emit({ type: "status", status: "streaming" });
+
+    const toolDefs = [...this.tools.values()].map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.inputJsonSchema,
+      strict: t.strict,
+    }));
+
+    for (let hop = 0; hop < (this.config.maxHops ?? 8); hop++) {
+      const blockId = this.nid("b");
+      let opened = false;
+
+      const final = await this.config.model.generate({
+        system: this.config.system,
+        tools: toolDefs,
+        messages: conversation.messages,
+        onTextDelta: (text) => {
+          if (!opened) {
+            opened = true;
+            emit({ type: "block_start", block: { kind: "assistant", id: blockId, text: "" } });
+          }
+          emit({ type: "text_delta", id: blockId, text });
+        },
+      });
+
+      conversation.messages.push({ role: "assistant", content: final.content });
+      if (final.stop_reason !== "tool_use") break;
+
+      const results: unknown[] = [];
+      let parked: { toolUseId: string; handle: string; digest: string } | null = null;
+
+      for (const call of final.content.filter((b: any) => b?.type === "tool_use")) {
+        const toolBlockId = this.nid("b");
+        emit({
+          type: "block_start",
+          block: { kind: "tool", id: toolBlockId, name: call.name, input: call.input, status: "running" },
+        });
+
+        const started = Date.now();
+        const { ret, mode } = await this.invokeTool(conversation, call, emit, toolBlockId);
+        const ms = Date.now() - started;
+
+        if (mode === "elicit" && ret.handle) {
+          emit({ type: "block_update", id: toolBlockId, status: "awaiting", ms, result: ret.model });
+          parked = { toolUseId: call.id, handle: ret.handle, digest: ret.model };
+        } else {
+          emit({ type: "block_update", id: toolBlockId, status: "ok", ms, result: ret.model });
+          results.push({ type: "tool_result", tool_use_id: call.id, content: ret.model });
+        }
+      }
+
+      if (parked) {
+        // Hold the resolved siblings too — the API is all-or-nothing per batch.
+        conversation.status = "awaiting";
+        conversation.pending = { ...parked, results };
+        conversation.leaseUntil = null;
+        emit({ type: "status", status: "awaiting" });
+        await this.emitContext(conversation, emit);
+        return;
+      }
+
+      conversation.messages.push({ role: "user", content: results });
+    }
+
+    conversation.status = "idle";
+    conversation.leaseUntil = null;
+    emit({ type: "status", status: "idle" });
+    await this.emitContext(conversation, emit);
+  }
+
+  private async invokeTool(
+    conversation: Conversation,
+    call: any,
+    emit: Emit,
+    toolBlockId: string,
+  ): Promise<{ ret: ToolReturn; mode: "display" | "elicit" | null }> {
+    const tool = this.tools.get(call.name);
+    if (!tool) return { ret: { model: `Unknown tool: ${call.name}` }, mode: null };
+
+    let mode: "display" | "elicit" | null = null;
+
+    const ctx: ToolCtx = {
+      conversationId: conversation.id,
+      text: (model) => ({ model }),
+      render: (async (impl: AnySurfaceImpl, props: unknown, options?: { mode?: "display" | "elicit" }) => {
+        const surfaceMode = options?.mode ?? "display";
+        mode = surfaceMode;
+
+        // Validate before storing: props may originate outside this process.
+        const parsed = impl.surface.props.parse(props);
+
+        const handle = await this.config.store.putPayload({
+          conversationId: conversation.id,
+          component: impl.surface.name,
+          version: impl.surface.version,
+          props: parsed,
+          mode: surfaceMode,
+          state: "live",
+        });
+
+        conversation.handles.push(handle);
+
+        // The split, in two lines. Digest -> model. Payload -> browser.
+        const digest = impl.impl.digest(parsed, { handle });
+        emit({
+          type: "ui_open",
+          handle,
+          toolId: toolBlockId,
+          component: impl.surface.name,
+          version: impl.surface.version,
+          mode: surfaceMode,
+        });
+        emit({ type: "ui_props", handle, props: parsed });
+
+        return { model: digest, handle };
+      }) as ToolCtx["render"],
+    };
+
+    let input: unknown;
+    try {
+      input = tool.input.parse(call.input);
+    } catch (err) {
+      return { ret: { model: `Invalid input for ${call.name}: ${(err as Error).message}` }, mode: null };
+    }
+
+    try {
+      const ret = await tool.run(input, ctx);
+      return { ret, mode };
+    } catch (err) {
+      return { ret: { model: `${call.name} failed: ${(err as Error).message}` }, mode: null };
+    }
+  }
+
+  private async emitContext(conversation: Conversation, emit: Emit) {
+    let uiTokens = 0;
+    for (const handle of conversation.handles) {
+      const record = await this.config.store.getPayload(handle, conversation.id);
+      if (record) uiTokens += estTokens(record.props);
+    }
+    emit({
+      type: "context",
+      messages: conversation.messages,
+      modelTokens: estTokens(conversation.messages),
+      uiTokens,
+    });
+  }
+}
+
+/** Find the array prop a surface's queries operate over (for cap totals). */
+function primaryCollection(props: unknown): string {
+  if (props && typeof props === "object") {
+    for (const [key, value] of Object.entries(props as Record<string, unknown>)) {
+      if (Array.isArray(value)) return key;
+    }
+  }
+  return "";
+}

package/src/store.ts

@@ -0,0 +1,53 @@
+import type { Conversation, PayloadRecord, StoreAdapter } from "@haikit/core";
+
+/**
+ * In-memory store. Implements the same interface a Postgres store would.
+ *
+ * Swapping this for a durable store is the single highest-value change for
+ * production: a parked `elicit` turn is durable state, and losing `pending`
+ * makes a conversation permanently unsendable.
+ */
+export function memoryStore(): StoreAdapter {
+  const conversations = new Map<string, Conversation>();
+  const payloads = new Map<string, PayloadRecord>();
+  let convSeq = 0;
+  let handleSeq = 0;
+
+  return {
+    async loadConversation(id) {
+      if (id && conversations.has(id)) return conversations.get(id)!;
+      const conversation: Conversation = {
+        id: `conv_${++convSeq}`,
+        status: "idle",
+        messages: [],
+        handles: [],
+        pending: null,
+        leaseUntil: null,
+      };
+      conversations.set(conversation.id, conversation);
+      return conversation;
+    },
+
+    async saveConversation(conversation) {
+      conversations.set(conversation.id, conversation);
+    },
+
+    async putPayload(record) {
+      const handle = `ui_${String(++handleSeq).padStart(2, "0")}`;
+      payloads.set(handle, { ...record, handle, createdAt: Date.now() });
+      return handle;
+    },
+
+    /** Scoped: a handle from another conversation must not resolve. */
+    async getPayload(handle, conversationId) {
+      const record = payloads.get(handle);
+      if (!record || record.conversationId !== conversationId) return null;
+      return record;
+    },
+
+    async freezePayload(handle) {
+      const record = payloads.get(handle);
+      if (record) record.state = "frozen";
+    },
+  };
+}