@haikit/core 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,34 @@
+# @haikit/core
+
+The contract layer. Isomorphic, zero runtime dependencies — imported by the
+server runtime, the browser client, every adapter, and both halves of your app.
+
+```ts
+import { defineSurface, resolve, query } from "@haikit/core";
+
+export const picker = defineSurface({
+  name: "flight_table",
+  version: 1,
+  props: z.object({ flights: z.array(Flight) }),
+  actions: { select: resolve(z.string()) },
+  queries: { filter: query(FilterArgs) },
+});
+```
+
+Schemas are accepted **structurally** — anything with a `.parse()` method works,
+so zod is your choice rather than this package's dependency.
+
+## The four guarantees
+
+Enforced in the type system, and asserted by `test/types/guarantees.ts`:
+
+| | |
+|---|---|
+| a surface cannot exist without a `digest` | `digest` is a required field |
+| a query's result can only be produced by `cap()` | `Capped` has no other constructor |
+| `mode: "elicit"` needs a `resolve` action | otherwise the call does not typecheck |
+| an undeclared action does not exist | the contract *is* the allowlist |
+
+`npm run typetest` at the repo root compiles those tests twice — once with their
+`@ts-expect-error` directives (must be clean) and once stripped (every marked
+line must error). A guarantee that silently stops working fails CI.

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * hai-core — the contract layer.
+ *
+ * Isomorphic. Imported by the server runtime, by adapters, and (as types only)
+ * by app code on both sides of the wire. Zero runtime dependencies: schemas are
+ * accepted structurally, so zod works but is not required.
+ *
+ * Four guarantees are enforced here, in the type system:
+ *   1. a surface cannot exist without a `digest`
+ *   2. a query's return value can only be produced by `cap()`
+ *   3. `mode: "elicit"` only accepts a surface declaring a `resolve` action
+ *   4. declaring an action is the only way to make it round-trip
+ */
+/** Structural match for zod, valibot, or a hand-rolled validator. */
+export interface Schema<T> {
+    parse(value: unknown): T;
+}
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+/** JSON Schema for the model-facing tool definition. */
+export type JsonSchema = Record<string, unknown>;
+declare const CAPPED: unique symbol;
+/**
+ * The return type of a query. There is no runtime value for CAPPED, so no
+ * object literal can satisfy this — `cap()` is the only constructor.
+ *
+ * This is what stops a filter that matches all 47 rows from returning all 47.
+ */
+export interface Capped {
+    readonly [CAPPED]: true;
+    text: string;
+    shown: number;
+    total: number;
+}
+export interface CapOptions {
+    /** Secondary bound. Default 8. */
+    maxRows?: number;
+    /** Primary bound — a token proxy. Whichever binds first wins. Default 1800. */
+    maxChars?: number;
+}
+export type Cap = <T>(rows: T[], fmt: (row: T) => string, opts?: CapOptions) => Capped;
+/**
+ * Bound a result set and — just as important — say that you bounded it.
+ * Silent truncation turns a cost problem into a correctness problem: the model
+ * reports "there are 8" when there are 30, and it has no way to know better.
+ */
+export declare function makeCap(total: number): Cap;
+export type ActionKind = "resolve" | "inform";
+export interface ActionSpec<K extends ActionKind = ActionKind, V = unknown> {
+    kind: K;
+    input: Schema<V>;
+}
+export interface QuerySpec<A = unknown> {
+    input: Schema<A>;
+    description?: string;
+}
+export type ActionMap = Record<string, ActionSpec<ActionKind, any>>;
+export type QueryMap = Record<string, QuerySpec<any>>;
+/** Resolves a parked `elicit` turn. The click becomes the tool_result. */
+export declare const resolve: <V>(input: Schema<V>) => ActionSpec<"resolve", V>;
+/** Adds context to the conversation without having blocked it. */
+export declare const inform: <V>(input: Schema<V>) => ActionSpec<"inform", V>;
+/** A named accessor over the stored payload. There is no raw dereference. */
+export declare const query: <A>(input: Schema<A>, description?: string) => QuerySpec<A>;
+export interface DigestCtx {
+    handle: string;
+}
+export interface ActionCtx<P> {
+    props: P;
+    handle: string;
+}
+export interface QueryCtx<P> {
+    props: P;
+    cap: Cap;
+}
+export interface SurfaceImplDef<P, A extends ActionMap, Q extends QueryMap> {
+    /**
+     * GUARANTEE 1 — required.
+     *
+     * A count and a price range is a lazy digest; it invites the model to narrate
+     * facts about rows it never received. Precompute whatever the next turn or two
+     * will plausibly need.
+     */
+    digest: (props: P, ctx: DigestCtx) => string;
+    actions: {
+        [K in keyof A]: (value: Infer<A[K]["input"]>, ctx: ActionCtx<P>) => string;
+    };
+    /** GUARANTEE 2 — must return `Capped`, i.e. must call `ctx.cap`. */
+    queries: {
+        [K in keyof Q]: (args: Infer<Q[K]["input"]>, ctx: QueryCtx<P>) => Capped;
+    };
+}
+export interface Surface<P, A extends ActionMap, Q extends QueryMap> {
+    readonly name: string;
+    readonly version: number;
+    readonly props: Schema<P>;
+    readonly actions: A;
+    readonly queries: Q;
+    implement(impl: SurfaceImplDef<P, A, Q>): SurfaceImpl<P, A, Q>;
+}
+export interface SurfaceImpl<P, A extends ActionMap, Q extends QueryMap> {
+    readonly surface: Surface<P, A, Q>;
+    readonly impl: SurfaceImplDef<P, A, Q>;
+}
+export type AnySurfaceImpl = SurfaceImpl<any, ActionMap, QueryMap>;
+/**
+ * Declare a surface contract. Import this module from BOTH halves: the server
+ * calls `.implement()`, the client renders against the same prop type.
+ *
+ * GUARANTEE 4: `actions` is the complete list of interactions that may reach the
+ * server. Anything a component does that is not declared here is local by
+ * construction — there is no channel for it.
+ */
+export declare function defineSurface<P, A extends ActionMap = {}, Q extends QueryMap = {}>(def: {
+    name: string;
+    version: number;
+    props: Schema<P>;
+    actions?: A;
+    queries?: Q;
+}): Surface<P, A, Q>;
+type ResolveKeys<A extends ActionMap> = {
+    [K in keyof A]: A[K]["kind"] extends "resolve" ? K : never;
+}[keyof A];
+export type HasResolve<A extends ActionMap> = [ResolveKeys<A>] extends [never] ? false : true;
+/**
+ * Passing a surface with no `resolve` action makes this an object type carrying
+ * an unsatisfiable required property, so the error names the actual problem
+ * instead of "not assignable to never".
+ */
+export type ElicitOptions<A extends ActionMap> = HasResolve<A> extends true ? {
+    mode: "elicit";
+} : {
+    mode: "elicit";
+    "⚠ this surface declares no resolve action — an elicit turn could never be unparked": never;
+};
+export interface ToolReturn {
+    /** Goes into `tool_result`. The model channel. */
+    model: string;
+    /** Set when the tool rendered a surface. */
+    handle?: string;
+}
+export interface ToolCtx {
+    readonly conversationId: string;
+    /** A tool with no UI. */
+    text(model: string): ToolReturn;
+    /** Render a surface as a blocking question. Requires a `resolve` action. */
+    render<P, A extends ActionMap, Q extends QueryMap>(surface: SurfaceImpl<P, A, Q>, props: P, options: ElicitOptions<A>): Promise<ToolReturn>;
+    /** Render a surface as a side-artifact. Resolves immediately. */
+    render<P, A extends ActionMap, Q extends QueryMap>(surface: SurfaceImpl<P, A, Q>, props: P, options?: {
+        mode?: "display";
+    }): Promise<ToolReturn>;
+}
+export interface Tool<I = any> {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Schema<I>;
+    readonly inputJsonSchema: JsonSchema;
+    readonly strict: boolean;
+    run(input: I, ctx: ToolCtx): Promise<ToolReturn> | ToolReturn;
+}
+export declare function defineTool<I>(def: {
+    name: string;
+    description: string;
+    input: Schema<I>;
+    /** JSON Schema sent to the model. Derive it with zod-to-json-schema if you like. */
+    inputJsonSchema: JsonSchema;
+    strict?: boolean;
+    run(input: I, ctx: ToolCtx): Promise<ToolReturn> | ToolReturn;
+}): Tool<I>;
+export type ConversationStatus = "idle" | "streaming" | "awaiting";
+/** Anthropic-shaped message. Kept loose so adapters can map as needed. */
+export interface Message {
+    role: "user" | "assistant";
+    content: unknown;
+}
+export interface Pending {
+    toolUseId: string;
+    handle: string;
+    /** An elicit tool never received a tool_result, so its digest has not reached
+     *  the model yet. It ships with the resolution. */
+    digest: string;
+    /** Sibling results from the same turn. The API is all-or-nothing per batch. */
+    results: unknown[];
+}
+export interface Conversation {
+    id: string;
+    status: ConversationStatus;
+    messages: Message[];
+    handles: string[];
+    pending: Pending | null;
+    /** Turn lease. A dead process leaves this in the past. */
+    leaseUntil: number | null;
+}
+export interface PayloadRecord {
+    handle: string;
+    conversationId: string;
+    component: string;
+    version: number;
+    props: unknown;
+    mode: "display" | "elicit";
+    state: "live" | "frozen";
+    createdAt: number;
+}
+export type Block = {
+    kind: "user";
+    id: string;
+    text: string;
+} | {
+    kind: "assistant";
+    id: string;
+    text: string;
+} | {
+    kind: "tool";
+    id: string;
+    name: string;
+    input: unknown;
+    status: string;
+    ms?: number;
+    result?: string;
+} | {
+    kind: "interaction";
+    id: string;
+    handle: string;
+    label: string;
+};
+export type WireEvent = {
+    type: "hello";
+    conversationId: string;
+    model: string;
+} | {
+    type: "block_start";
+    block: Block;
+} | {
+    type: "text_delta";
+    id: string;
+    text: string;
+} | {
+    type: "block_update";
+    id: string;
+    status: string;
+    ms: number;
+    result: string;
+} | {
+    type: "ui_open";
+    handle: string;
+    toolId: string;
+    component: string;
+    version: number;
+    mode: string;
+} | {
+    type: "ui_props";
+    handle: string;
+    props: unknown;
+} | {
+    type: "ui_state";
+    handle: string;
+    state: "frozen";
+    selection?: unknown;
+} | {
+    type: "status";
+    status: ConversationStatus;
+} | {
+    type: "context";
+    messages: Message[];
+    modelTokens: number;
+    uiTokens: number;
+} | {
+    type: "error";
+    message: string;
+};
+export type Emit = (event: WireEvent) => void;
+export interface ModelRequest {
+    system: string;
+    tools: {
+        name: string;
+        description: string;
+        input_schema: JsonSchema;
+        strict?: boolean;
+    }[];
+    messages: Message[];
+    onTextDelta: (text: string) => void;
+}
+export interface ModelResponse {
+    content: any[];
+    stop_reason: string;
+}
+export interface ModelAdapter {
+    readonly id: string;
+    generate(request: ModelRequest): Promise<ModelResponse>;
+}
+export interface StoreAdapter {
+    loadConversation(id: string | undefined): Promise<Conversation>;
+    saveConversation(conversation: Conversation): Promise<void>;
+    putPayload(record: Omit<PayloadRecord, "handle" | "createdAt">): Promise<string>;
+    getPayload(handle: string, conversationId: string): Promise<PayloadRecord | null>;
+    freezePayload(handle: string): Promise<void>;
+}
+/** Rough token estimate. Only used to surface the economics in the UI. */
+export declare const estTokens: (value: unknown) => number;
+export {};
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * hai-core — the contract layer.
+ *
+ * Isomorphic. Imported by the server runtime, by adapters, and (as types only)
+ * by app code on both sides of the wire. Zero runtime dependencies: schemas are
+ * accepted structurally, so zod works but is not required.
+ *
+ * Four guarantees are enforced here, in the type system:
+ *   1. a surface cannot exist without a `digest`
+ *   2. a query's return value can only be produced by `cap()`
+ *   3. `mode: "elicit"` only accepts a surface declaring a `resolve` action
+ *   4. declaring an action is the only way to make it round-trip
+ */
+/**
+ * Bound a result set and — just as important — say that you bounded it.
+ * Silent truncation turns a cost problem into a correctness problem: the model
+ * reports "there are 8" when there are 30, and it has no way to know better.
+ */
+export function makeCap(total) {
+    return function cap(rows, fmt, opts = {}) {
+        const maxRows = opts.maxRows ?? 8;
+        const maxChars = opts.maxChars ?? 1800;
+        const lines = [];
+        let chars = 0;
+        for (const row of rows.slice(0, maxRows)) {
+            const line = fmt(row);
+            if (chars + line.length > maxChars)
+                break;
+            lines.push(line);
+            chars += line.length + 1;
+        }
+        const omitted = rows.length - lines.length;
+        const head = rows.length === 0
+            ? `0 of ${total} match.`
+            : `${rows.length} of ${total} match. ${lines.length} shown` +
+                (omitted > 0 ? `, ${omitted} omitted` : "") +
+                ":";
+        return {
+            text: lines.length ? `${head}\n${lines.join("\n")}` : head,
+            shown: lines.length,
+            total,
+        };
+    };
+}
+/** Resolves a parked `elicit` turn. The click becomes the tool_result. */
+export const resolve = (input) => ({ kind: "resolve", input });
+/** Adds context to the conversation without having blocked it. */
+export const inform = (input) => ({ kind: "inform", input });
+/** A named accessor over the stored payload. There is no raw dereference. */
+export const query = (input, description) => ({ input, description });
+/**
+ * Declare a surface contract. Import this module from BOTH halves: the server
+ * calls `.implement()`, the client renders against the same prop type.
+ *
+ * GUARANTEE 4: `actions` is the complete list of interactions that may reach the
+ * server. Anything a component does that is not declared here is local by
+ * construction — there is no channel for it.
+ */
+export function defineSurface(def) {
+    const surface = {
+        name: def.name,
+        version: def.version,
+        props: def.props,
+        actions: (def.actions ?? {}),
+        queries: (def.queries ?? {}),
+        implement(impl) {
+            return { surface, impl };
+        },
+    };
+    return surface;
+}
+export function defineTool(def) {
+    return { strict: true, ...def };
+}
+/** Rough token estimate. Only used to surface the economics in the UI. */
+export const estTokens = (value) => Math.ceil((typeof value === "string" ? value : JSON.stringify(value ?? "")).length / 4);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@haikit/core",
+  "version": "0.1.0",
+  "description": "The haikit contract layer: declare a UI surface once, implement it on the server and in the browser. Isomorphic, zero runtime dependencies.",
+  "keywords": [
+    "haikit",
+    "llm",
+    "agent",
+    "agentic-ui",
+    "generative-ui",
+    "tool-use",
+    "tool-calling",
+    "ai",
+    "chat"
+  ],
+  "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"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/wfoxd/haikit/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/wfoxd/haikit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wfoxd/haikit.git",
+    "directory": "packages/core"
+  }
+}

package/src/index.ts

@@ -0,0 +1,351 @@
+/**
+ * hai-core — the contract layer.
+ *
+ * Isomorphic. Imported by the server runtime, by adapters, and (as types only)
+ * by app code on both sides of the wire. Zero runtime dependencies: schemas are
+ * accepted structurally, so zod works but is not required.
+ *
+ * Four guarantees are enforced here, in the type system:
+ *   1. a surface cannot exist without a `digest`
+ *   2. a query's return value can only be produced by `cap()`
+ *   3. `mode: "elicit"` only accepts a surface declaring a `resolve` action
+ *   4. declaring an action is the only way to make it round-trip
+ */
+
+// ───────────────────────────────────────────────────────── schemas
+
+/** Structural match for zod, valibot, or a hand-rolled validator. */
+export interface Schema<T> {
+  parse(value: unknown): T;
+}
+
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+
+/** JSON Schema for the model-facing tool definition. */
+export type JsonSchema = Record<string, unknown>;
+
+// ───────────────────────────────────────────── GUARANTEE 2: Capped
+
+declare const CAPPED: unique symbol;
+
+/**
+ * The return type of a query. There is no runtime value for CAPPED, so no
+ * object literal can satisfy this — `cap()` is the only constructor.
+ *
+ * This is what stops a filter that matches all 47 rows from returning all 47.
+ */
+export interface Capped {
+  readonly [CAPPED]: true;
+  text: string;
+  shown: number;
+  total: number;
+}
+
+export interface CapOptions {
+  /** Secondary bound. Default 8. */
+  maxRows?: number;
+  /** Primary bound — a token proxy. Whichever binds first wins. Default 1800. */
+  maxChars?: number;
+}
+
+export type Cap = <T>(rows: T[], fmt: (row: T) => string, opts?: CapOptions) => Capped;
+
+/**
+ * Bound a result set and — just as important — say that you bounded it.
+ * Silent truncation turns a cost problem into a correctness problem: the model
+ * reports "there are 8" when there are 30, and it has no way to know better.
+ */
+export function makeCap(total: number): Cap {
+  return function cap<T>(rows: T[], fmt: (row: T) => string, opts: CapOptions = {}): Capped {
+    const maxRows = opts.maxRows ?? 8;
+    const maxChars = opts.maxChars ?? 1800;
+
+    const lines: string[] = [];
+    let chars = 0;
+    for (const row of rows.slice(0, maxRows)) {
+      const line = fmt(row);
+      if (chars + line.length > maxChars) break;
+      lines.push(line);
+      chars += line.length + 1;
+    }
+
+    const omitted = rows.length - lines.length;
+    const head =
+      rows.length === 0
+        ? `0 of ${total} match.`
+        : `${rows.length} of ${total} match. ${lines.length} shown` +
+          (omitted > 0 ? `, ${omitted} omitted` : "") +
+          ":";
+
+    return {
+      text: lines.length ? `${head}\n${lines.join("\n")}` : head,
+      shown: lines.length,
+      total,
+    } as Capped;
+  };
+}
+
+// ────────────────────────────────────────────── actions and queries
+
+export type ActionKind = "resolve" | "inform";
+
+export interface ActionSpec<K extends ActionKind = ActionKind, V = unknown> {
+  kind: K;
+  input: Schema<V>;
+}
+
+export interface QuerySpec<A = unknown> {
+  input: Schema<A>;
+  description?: string;
+}
+
+export type ActionMap = Record<string, ActionSpec<ActionKind, any>>;
+export type QueryMap = Record<string, QuerySpec<any>>;
+
+/** Resolves a parked `elicit` turn. The click becomes the tool_result. */
+export const resolve = <V>(input: Schema<V>): ActionSpec<"resolve", V> => ({ kind: "resolve", input });
+
+/** Adds context to the conversation without having blocked it. */
+export const inform = <V>(input: Schema<V>): ActionSpec<"inform", V> => ({ kind: "inform", input });
+
+/** A named accessor over the stored payload. There is no raw dereference. */
+export const query = <A>(input: Schema<A>, description?: string): QuerySpec<A> => ({ input, description });
+
+// ──────────────────────────────────────────────────────── surfaces
+
+export interface DigestCtx {
+  handle: string;
+}
+export interface ActionCtx<P> {
+  props: P;
+  handle: string;
+}
+export interface QueryCtx<P> {
+  props: P;
+  cap: Cap;
+}
+
+export interface SurfaceImplDef<P, A extends ActionMap, Q extends QueryMap> {
+  /**
+   * GUARANTEE 1 — required.
+   *
+   * A count and a price range is a lazy digest; it invites the model to narrate
+   * facts about rows it never received. Precompute whatever the next turn or two
+   * will plausibly need.
+   */
+  digest: (props: P, ctx: DigestCtx) => string;
+
+  actions: { [K in keyof A]: (value: Infer<A[K]["input"]>, ctx: ActionCtx<P>) => string };
+
+  /** GUARANTEE 2 — must return `Capped`, i.e. must call `ctx.cap`. */
+  queries: { [K in keyof Q]: (args: Infer<Q[K]["input"]>, ctx: QueryCtx<P>) => Capped };
+}
+
+export interface Surface<P, A extends ActionMap, Q extends QueryMap> {
+  readonly name: string;
+  readonly version: number;
+  readonly props: Schema<P>;
+  readonly actions: A;
+  readonly queries: Q;
+  implement(impl: SurfaceImplDef<P, A, Q>): SurfaceImpl<P, A, Q>;
+}
+
+export interface SurfaceImpl<P, A extends ActionMap, Q extends QueryMap> {
+  readonly surface: Surface<P, A, Q>;
+  readonly impl: SurfaceImplDef<P, A, Q>;
+}
+
+export type AnySurfaceImpl = SurfaceImpl<any, ActionMap, QueryMap>;
+
+/**
+ * Declare a surface contract. Import this module from BOTH halves: the server
+ * calls `.implement()`, the client renders against the same prop type.
+ *
+ * GUARANTEE 4: `actions` is the complete list of interactions that may reach the
+ * server. Anything a component does that is not declared here is local by
+ * construction — there is no channel for it.
+ */
+export function defineSurface<P, A extends ActionMap = {}, Q extends QueryMap = {}>(def: {
+  name: string;
+  version: number;
+  props: Schema<P>;
+  actions?: A;
+  queries?: Q;
+}): Surface<P, A, Q> {
+  const surface: Surface<P, A, Q> = {
+    name: def.name,
+    version: def.version,
+    props: def.props,
+    actions: (def.actions ?? {}) as A,
+    queries: (def.queries ?? {}) as Q,
+    implement(impl) {
+      return { surface, impl };
+    },
+  };
+  return surface;
+}
+
+// ─────────────────────────────────────── GUARANTEE 3: elicit safety
+
+type ResolveKeys<A extends ActionMap> = {
+  [K in keyof A]: A[K]["kind"] extends "resolve" ? K : never;
+}[keyof A];
+
+export type HasResolve<A extends ActionMap> = [ResolveKeys<A>] extends [never] ? false : true;
+
+/**
+ * Passing a surface with no `resolve` action makes this an object type carrying
+ * an unsatisfiable required property, so the error names the actual problem
+ * instead of "not assignable to never".
+ */
+export type ElicitOptions<A extends ActionMap> = HasResolve<A> extends true
+  ? { mode: "elicit" }
+  : {
+      mode: "elicit";
+      "⚠ this surface declares no resolve action — an elicit turn could never be unparked": never;
+    };
+
+// ─────────────────────────────────────────────────────────── tools
+
+export interface ToolReturn {
+  /** Goes into `tool_result`. The model channel. */
+  model: string;
+  /** Set when the tool rendered a surface. */
+  handle?: string;
+}
+
+export interface ToolCtx {
+  readonly conversationId: string;
+
+  /** A tool with no UI. */
+  text(model: string): ToolReturn;
+
+  /** Render a surface as a blocking question. Requires a `resolve` action. */
+  render<P, A extends ActionMap, Q extends QueryMap>(
+    surface: SurfaceImpl<P, A, Q>,
+    props: P,
+    options: ElicitOptions<A>,
+  ): Promise<ToolReturn>;
+
+  /** Render a surface as a side-artifact. Resolves immediately. */
+  render<P, A extends ActionMap, Q extends QueryMap>(
+    surface: SurfaceImpl<P, A, Q>,
+    props: P,
+    options?: { mode?: "display" },
+  ): Promise<ToolReturn>;
+}
+
+export interface Tool<I = any> {
+  readonly name: string;
+  readonly description: string;
+  readonly input: Schema<I>;
+  readonly inputJsonSchema: JsonSchema;
+  readonly strict: boolean;
+  run(input: I, ctx: ToolCtx): Promise<ToolReturn> | ToolReturn;
+}
+
+export function defineTool<I>(def: {
+  name: string;
+  description: string;
+  input: Schema<I>;
+  /** JSON Schema sent to the model. Derive it with zod-to-json-schema if you like. */
+  inputJsonSchema: JsonSchema;
+  strict?: boolean;
+  run(input: I, ctx: ToolCtx): Promise<ToolReturn> | ToolReturn;
+}): Tool<I> {
+  return { strict: true, ...def };
+}
+
+// ───────────────────────────────────────────────────── conversation
+
+export type ConversationStatus = "idle" | "streaming" | "awaiting";
+
+/** Anthropic-shaped message. Kept loose so adapters can map as needed. */
+export interface Message {
+  role: "user" | "assistant";
+  content: unknown;
+}
+
+export interface Pending {
+  toolUseId: string;
+  handle: string;
+  /** An elicit tool never received a tool_result, so its digest has not reached
+   *  the model yet. It ships with the resolution. */
+  digest: string;
+  /** Sibling results from the same turn. The API is all-or-nothing per batch. */
+  results: unknown[];
+}
+
+export interface Conversation {
+  id: string;
+  status: ConversationStatus;
+  messages: Message[];
+  handles: string[];
+  pending: Pending | null;
+  /** Turn lease. A dead process leaves this in the past. */
+  leaseUntil: number | null;
+}
+
+export interface PayloadRecord {
+  handle: string;
+  conversationId: string;
+  component: string;
+  version: number;
+  props: unknown;
+  mode: "display" | "elicit";
+  state: "live" | "frozen";
+  createdAt: number;
+}
+
+// ─────────────────────────────────────────────────── wire protocol
+
+export type Block =
+  | { kind: "user"; id: string; text: string }
+  | { kind: "assistant"; id: string; text: string }
+  | { kind: "tool"; id: string; name: string; input: unknown; status: string; ms?: number; result?: string }
+  | { kind: "interaction"; id: string; handle: string; label: string };
+
+export type WireEvent =
+  | { type: "hello"; conversationId: string; model: string }
+  | { type: "block_start"; block: Block }
+  | { type: "text_delta"; id: string; text: string }
+  | { type: "block_update"; id: string; status: string; ms: number; result: string }
+  | { type: "ui_open"; handle: string; toolId: string; component: string; version: number; mode: string }
+  | { type: "ui_props"; handle: string; props: unknown }
+  | { type: "ui_state"; handle: string; state: "frozen"; selection?: unknown }
+  | { type: "status"; status: ConversationStatus }
+  | { type: "context"; messages: Message[]; modelTokens: number; uiTokens: number }
+  | { type: "error"; message: string };
+
+export type Emit = (event: WireEvent) => void;
+
+// ───────────────────────────────────────────────────────── adapters
+
+export interface ModelRequest {
+  system: string;
+  tools: { name: string; description: string; input_schema: JsonSchema; strict?: boolean }[];
+  messages: Message[];
+  onTextDelta: (text: string) => void;
+}
+
+export interface ModelResponse {
+  content: any[];
+  stop_reason: string;
+}
+
+export interface ModelAdapter {
+  readonly id: string;
+  generate(request: ModelRequest): Promise<ModelResponse>;
+}
+
+export interface StoreAdapter {
+  loadConversation(id: string | undefined): Promise<Conversation>;
+  saveConversation(conversation: Conversation): Promise<void>;
+  putPayload(record: Omit<PayloadRecord, "handle" | "createdAt">): Promise<string>;
+  getPayload(handle: string, conversationId: string): Promise<PayloadRecord | null>;
+  freezePayload(handle: string): Promise<void>;
+}
+
+/** Rough token estimate. Only used to surface the economics in the UI. */
+export const estTokens = (value: unknown): number =>
+  Math.ceil((typeof value === "string" ? value : JSON.stringify(value ?? "")).length / 4);