@kitn.ai/ui 0.25.2 → 0.27.0

package/src/schemas/tool-defs.ts

@@ -27,9 +27,14 @@
 // `format: "uri"` (link/embed/artifact), `minimum` (tasks/embed/artifact),
 // `maxItems` (confirm/artifact), `pattern` (embed), `if`/`then` (embed), `oneOf`
 // (artifact), a free-form object (form) and untyped `payload`/`allowOther` members
-// (confirm/choice). Non-strict is therefore not merely the default, it is currently
-// the only working mode, and it is also the mode the five-configuration conformance
-// spike actually proved cards in.
+// (confirm/choice). Non-strict is therefore the default and the mode the
+// five-configuration conformance spike actually proved cards in — but since F-20 it
+// is no longer a raw pass-through either: a root combinator (`anyOf` on artifact,
+// `allOf` on embed) gets HTTP 400 from OpenAI and Anthropic even non-strict, so the
+// non-strict projection relaxes those root combinators LOUDLY (constraint restated in
+// the description, console.warn names the relaxation, registry.validate still
+// enforces at render time). The jsonschema projection stays byte-faithful to the
+// authored schema.
 //
 // The alternative was to silently drop the offending keywords. That is rejected for
 // the reason the plan gives: a dropped `maxItems: 4` means the model emits six
@@ -126,6 +131,52 @@ export interface CardToolOptions<P extends ToolProvider = ToolProvider> {
    * When it throws it names the card, the path and the keyword.
    */
   readonly strict?: boolean;
+  /**
+   * Narrow the DERIVED tool schema per card type, after projection.
+   *
+   * A card's authored schema is deliberately permissive — `files` is optional on an
+   * artifact, its items need only a `path` — because the card CONTRACT must accept
+   * what a host may legitimately render. A model filling the tool in, though, is
+   * often better served by a tighter tool: requiring `code` on every file, or at
+   * least one file at all, moves a class of failures from render time (a card the
+   * registry rejects) to generation time (the model literally cannot emit one).
+   *
+   * This narrows the WIRE projection only — the authored schema and
+   * `registry.validate()` are untouched, so a hand-built envelope still validates.
+   * Applied for every provider, `jsonschema` included, and merged loudly: an
+   * unknown path or a required name the node has no property for is a TypeError
+   * naming the card, the path and the field, because a tool that can never be
+   * satisfied must not ship quietly.
+   *
+   * IT CANNOT REACH A FORM CARD'S FIELDS, and that is a known limitation rather
+   * than an oversight. The form
+   * card's payload IS a JSON Schema, so `form.schema.json` describes `properties`
+   * as a map of field definitions and there is no node at `properties.ticketId`
+   * for a rule to land on — `require: { form: [{ path: 'properties.ticketId' }] }`
+   * raises the TypeError above, correctly. So an app cannot pin
+   * `x-kai-format: 'custom'` onto one field of a form the model authors. The
+   * enum on that hint is what makes a small model pick a valid token; an app that
+   * needs a guarantee checks the envelope when it arrives.
+   */
+  readonly require?: Readonly<Record<string, readonly CardRequireRule[]>>;
+}
+
+/**
+ * One narrowing instruction for one node of one card's projected schema.
+ *
+ * `path` is a dot-path from the envelope-data root through `properties` keys
+ * (`''` names the root node itself). On an ARRAY node, `required` narrows
+ * `items.required` and `minItems` lands on the array; on an object node,
+ * `required` lands on the node's own `required`. Existing requirements merge,
+ * never replace.
+ */
+export interface CardRequireRule {
+  /** Dot-path from the envelope-data root to a schema node, e.g. 'files'. */
+  readonly path: string;
+  /** Property names to require. On an ARRAY node this narrows `items.required`; on an object node, the node's own `required`. */
+  readonly required?: readonly string[];
+  /** Sets `minItems` (array nodes only). */
+  readonly minItems?: number;
 }
 
 /**
@@ -225,7 +276,7 @@ function formatUnsupported(subset: ProviderSubset, cards: readonly UnsupportedCa
   lines.push('');
   lines.push(`  subset source: ${subset.source} (read ${subset.checkedOn})`);
   lines.push(
-    '  Fix: drop `strict: true`. Non-strict is the default and is the mode the kit\'s cards are proven in; both providers accept a loose schema there and ignore what they do not compile. Rewriting a built-in card schema to fit a strict subset would change what a valid card IS, which is a card-contract change, not a projection setting.',
+    '  Fix: drop `strict: true`. Non-strict mode projects a provider-valid schema (root combinators are relaxed with the constraint restated in the description and still enforced by card validation). Rewriting a built-in card schema to fit a strict subset would change what a valid card IS, which is a card-contract change, not a projection setting.',
   );
   return lines.join('\n');
 }
@@ -237,6 +288,227 @@ function formatUnsupported(subset: ProviderSubset, cards: readonly UnsupportedCa
 const isRecord = (v: unknown): v is Record<string, unknown> =>
   typeof v === 'object' && v !== null && !Array.isArray(v);
 
+/**
+ * Root combinators the two largest providers refuse on a tool schema's root node
+ * (measured: OpenAI and Anthropic 400 before the model runs — findings F-20;
+ * DeepSeek's OpenAI-compatible route requires the same workaround). The AUTHORED
+ * schemas keep them — card validation keeps every constraint. Only the WIRE
+ * projection relaxes, loudly: the constraint is restated in the description the
+ * model reads, a console.warn names the relaxation, and a violating envelope
+ * still fails registry.validate() at render time with a hard diagnostic.
+ */
+const ROOT_RELAXATIONS: Readonly<Record<string, string>> = {
+  artifact:
+    'Provide `src` (a preview URL) or `files` — at least one. An envelope with neither is rejected.',
+  embed:
+    "For provider 'generic', include `url`. For 'youtube'/'vimeo', include `id` or `url`.",
+};
+
+/** Strip a banned combinator key from the projected ROOT node only (nested
+ *  combinators are accepted by every provider measured and stay). Returns the
+ *  relaxation note to restate in the TOOL description the model reads. Two
+ *  distinct no-note return paths: `undefined` when NOTHING was banned (the wire
+ *  projection is faithful, nothing was widened), and GENERIC_NOTE when something
+ *  WAS banned but no curated copy exists (a custom card) — that path still
+ *  restates the relaxation, because deleting a combinator without telling the
+ *  model would be a silent widening. */
+const GENERIC_RELAXATION_NOTE =
+  'The root constraint of this schema was relaxed for this provider; consult the card registry for what a valid payload is.';
+
+const BANNED_ROOT_KEYS = ['anyOf', 'allOf', 'oneOf', 'not', 'enum', 'const'] as const;
+
+/**
+ * The object shape a literal `enum` / `const` VALUE implies.
+ *
+ * `const: { op: 'ping' }` is a whole-instance constraint, which a provider refuses
+ * at the root exactly like a combinator. The instance it admits is an object, so
+ * the shape survives the relaxation as `properties: { op: { const: 'ping' } }` with
+ * `op` required — nothing widened that the branch did not already allow.
+ */
+function branchFromLiteral(value: unknown): Record<string, unknown> | null {
+  if (!isRecord(value)) return null;
+  const properties: Record<string, unknown> = {};
+  for (const [key, member] of Object.entries(value)) properties[key] = { const: member };
+  return { type: 'object', properties, required: Object.keys(value) };
+}
+
+/** The branch schemas one banned root keyword contributes, or `[]` for one that has none. */
+function branchesOfRootKeyword(keyword: string, value: unknown): Record<string, unknown>[] {
+  if (keyword === 'anyOf' || keyword === 'oneOf' || keyword === 'allOf') {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+  }
+  if (keyword === 'const') return [branchFromLiteral(value)].filter((b): b is Record<string, unknown> => b !== null);
+  if (keyword === 'enum') {
+    return Array.isArray(value)
+      ? value.map(branchFromLiteral).filter((b): b is Record<string, unknown> => b !== null)
+      : [];
+  }
+  // `not` is a NEGATIVE constraint: nothing it says is a property the instance may
+  // carry, so there is nothing sound to merge back. It is dropped and restated in
+  // the description like every other relaxation.
+  return [];
+}
+
+/**
+ * Fold a root combinator's branches back into the object root that replaces it.
+ *
+ * The two built-ins showed the shape of the rule and this generalises it rather
+ * than special-casing them. `artifact`'s root `anyOf` is `[{required:['src']},
+ * {required:['files']}]`: a DISJUNCTION guarantees only what EVERY branch
+ * guarantees, so the intersection is empty and `required` stays absent — which is
+ * exactly what the artifact projection already did. `embed`'s root `allOf` is two
+ * `if`/`then` pairs: a CONJUNCTION guarantees every branch's own top-level
+ * `required`, and an `if`/`then` branch declares none, so again nothing is added.
+ * A consumer card whose branches carry real `properties` is the case neither
+ * built-in reaches, and the one this exists for.
+ *
+ * Properties are UNIONed (each branch's shape must remain expressible — dropping
+ * one is the silent narrowing the whole F-20 fix exists to avoid); a name already
+ * on the root keeps the root's definition. `required` is the intersection for
+ * `anyOf`/`oneOf`/`enum`/`const` and the union for `allOf`, unioned in turn with
+ * whatever the root already required, and filtered to names the merged
+ * `properties` actually carries so the tool can never be unsatisfiable.
+ */
+function mergeBranchesIntoRoot(parameters: Record<string, unknown>, banned: readonly string[]): void {
+  const properties: Record<string, unknown> = isRecord(parameters.properties)
+    ? { ...parameters.properties }
+    : {};
+  const guaranteed = new Set<string>(
+    Array.isArray(parameters.required) ? parameters.required.map(String) : [],
+  );
+
+  for (const keyword of banned) {
+    const branches = branchesOfRootKeyword(keyword, parameters[keyword]);
+    if (branches.length === 0) continue;
+
+    for (const branch of branches) {
+      if (!isRecord(branch.properties)) continue;
+      for (const [name, sub] of Object.entries(branch.properties)) {
+        if (!(name in properties)) properties[name] = sub;
+      }
+    }
+
+    const perBranch = branches.map(
+      (branch) => new Set(Array.isArray(branch.required) ? branch.required.map(String) : []),
+    );
+    if (keyword === 'allOf') {
+      for (const set of perBranch) for (const name of set) guaranteed.add(name);
+    } else {
+      // Disjunction: keep only what every branch requires.
+      const [first, ...rest] = perBranch;
+      for (const name of first) {
+        if (rest.every((set) => set.has(name))) guaranteed.add(name);
+      }
+    }
+  }
+
+  if (Object.keys(properties).length > 0) parameters.properties = properties;
+  const required = [...guaranteed].filter((name) => name in properties);
+  if (required.length > 0) parameters.required = required;
+}
+
+/**
+ * Make the projected ROOT the object shape every provider demands.
+ *
+ * Deleting a root combinator is only half of F-20. A schema whose root was NOTHING
+ * BUT the combinator projects to `{"title":…,"description":…}` once it is gone —
+ * accepted by no provider (measured: OpenAI 400, "schema must be a JSON Schema of
+ * type \"object\"") and unfillable by any model. Every built-in declares
+ * `type: "object"` at its root, so nothing in the suite reached this until a
+ * consumer card did.
+ *
+ * A root that declares a NON-object type cannot be a tool schema at all, and
+ * asserting `type: "object"` over it would be a lie about the card. That refuses,
+ * naming the card.
+ */
+function ensureObjectRoot(parameters: Record<string, unknown>, cardType: string): void {
+  const declared = parameters.type;
+  if (declared !== undefined && declared !== 'object') {
+    throw new TypeError(
+      `cardTools: the '${cardType}' card schema declares root type '${String(declared)}', but a provider tool ` +
+        `schema root must be an object (OpenAI and Anthropic reject anything else with HTTP 400). ` +
+        `Wrap the payload in an object, or project this card with provider 'jsonschema'.`,
+    );
+  }
+  parameters.type = 'object';
+}
+
+function relaxRootCombinators(parameters: Record<string, unknown>, cardType: string): string | undefined {
+  const note = ROOT_RELAXATIONS[cardType];
+  const banned = BANNED_ROOT_KEYS.filter((k) => k in parameters);
+  // The object-root guarantee holds for EVERY provider projection, banned keys or
+  // not: it is what the provider requires, not what the relaxation broke.
+  ensureObjectRoot(parameters, cardType);
+  if (banned.length === 0) return undefined;
+  mergeBranchesIntoRoot(parameters, banned);
+  for (const k of banned) delete parameters[k];
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[kai-card-tools] relaxed root ${banned.join('/')} on the projected '${toolNameForCardType(cardType)}' tool schema ` +
+      `for this provider (it would be refused with HTTP 400); the constraint now lives in the ` +
+      `description and is still enforced by card validation.`,
+  );
+  return note ?? GENERIC_RELAXATION_NOTE;
+}
+
+/**
+ * Apply one card's `require` rules to its PROJECTED parameters.
+ *
+ * Runs after `project()` and `relaxRootCombinators()`, on the copy the projection
+ * built — never on the authored schema, which `registry.validate()` keeps reading.
+ * Merges into whatever `required` already exists rather than replacing it, so a
+ * rule can only ever NARROW what the model may emit, never widen it.
+ */
+function applyRequire(
+  parameters: Record<string, unknown>,
+  cardType: string,
+  rules: readonly CardRequireRule[],
+): void {
+  for (const rule of rules) {
+    // Resolve the dot-path through `properties` keys. `''` names the root node;
+    // every other segment must name a property of the node reached so far.
+    let node: Record<string, unknown> = parameters;
+    if (rule.path !== '') {
+      for (const segment of rule.path.split('.')) {
+        const props = isRecord(node.properties) ? node.properties : undefined;
+        const next = props?.[segment];
+        if (!isRecord(next)) {
+          throw new TypeError(
+            `cardTools: require on '${cardType}': path '${rule.path}' does not resolve in the schema`,
+          );
+        }
+        node = next;
+      }
+    }
+
+    const isArrayNode = node.type === 'array' || (node.type === undefined && 'items' in node);
+    if (isArrayNode && rule.minItems !== undefined) node.minItems = rule.minItems;
+    if (!isArrayNode && rule.minItems !== undefined) {
+      throw new TypeError(
+        `cardTools: minItems at require path '${rule.path}' applies to array nodes only, ` +
+          `but '${rule.path}' in the '${cardType}' schema is not one`,
+      );
+    }
+
+    if (rule.required !== undefined) {
+      // On an array node the requirement lives on the ITEMS (each element must carry
+      // the field), not on the array itself.
+      const target = isArrayNode && isRecord(node.items) ? node.items : node;
+      const props = isRecord(target.properties) ? target.properties : undefined;
+      for (const field of rule.required) {
+        if (!props || !(field in props)) {
+          throw new TypeError(
+            `cardTools: require on '${cardType}' at path '${rule.path}': '${field}' is not a property of that node — ` +
+              `a required name with no property would make the tool unsatisfiable`,
+          );
+        }
+      }
+      const existing = Array.isArray(target.required) ? target.required.map(String) : [];
+      target.required = [...new Set([...existing, ...rule.required])];
+    }
+  }
+}
+
 /**
  * Keywords stripped from every projection, strict or not.
  *
@@ -430,11 +702,40 @@ export function cardTools(a: CardToolInput | CardToolOptions, b?: CardToolOption
   const defs: ToolDef[] = [];
   const failures: UnsupportedCardTool[] = [];
 
+  // A `require` key naming a card the call does not carry is a typo, and a typo here
+  // would otherwise narrow NOTHING while looking like it narrowed something — the
+  // same decide-loudly class as an unknown dot-path below.
+  if (opts.require !== undefined) {
+    for (const key of Object.keys(opts.require)) {
+      if (!(key in schemas)) {
+        throw new TypeError(
+          `cardTools: require names card type '${key}', which this call does not carry ` +
+            `(carries: ${Object.keys(schemas).join(', ') || 'none'})`,
+        );
+      }
+    }
+  }
+
   for (const [cardType, schema] of Object.entries(schemas)) {
     const name = toolNameForCardType(cardType);
     const description = describe(cardType, schema, descriptions);
     const parameters = project(schema, projectOptions) as ToolParameters;
 
+    // F-20: non-strict only. Strict mode already refuses these cards with the full
+    // subset check, so the relaxation must never mask it. The note is restated in the
+    // TOOL description — the envelope field the model reads when choosing the tool.
+    const relaxedNote =
+      subset === null && opts.provider !== 'jsonschema'
+        ? relaxRootCombinators(parameters as Record<string, unknown>, cardType)
+        : undefined;
+    const wireDescription = relaxedNote ? `${description} ${relaxedNote}` : description;
+
+    // F-23: every provider, jsonschema included — a consumer handing the bare schema
+    // to the Vercel AI SDK narrows their tool the same way. Runs BEFORE the strict
+    // subset check so that check judges the schema that actually ships.
+    const requireRules = opts.require?.[cardType];
+    if (requireRules !== undefined) applyRequire(parameters as Record<string, unknown>, cardType, requireRules);
+
     if (subset) {
       const violations = checkProviderSubset(parameters, subset);
       if (violations.length > 0) {
@@ -444,9 +745,9 @@ export function cardTools(a: CardToolInput | CardToolOptions, b?: CardToolOption
     }
 
     if (opts.provider === 'openai') {
-      defs.push({ type: 'function', function: { name, description, parameters, ...(strict ? { strict: true as const } : {}) } });
+      defs.push({ type: 'function', function: { name, description: wireDescription, parameters, ...(strict ? { strict: true as const } : {}) } });
     } else if (opts.provider === 'anthropic') {
-      defs.push({ name, description, input_schema: parameters, ...(strict ? { strict: true as const } : {}) });
+      defs.push({ name, description: wireDescription, input_schema: parameters, ...(strict ? { strict: true as const } : {}) });
     } else {
       defs.push({ name, description, schema: parameters });
     }

package/src/solid.ts

@@ -53,8 +53,18 @@ export { Input } from './ui/input';
 export type { InputProps } from './ui/input';
 export { Kbd } from './ui/kbd';
 export type { KbdProps, KbdPlatform } from './ui/kbd';
+export { Checkbox } from './ui/checkbox';
+export type { CheckboxProps } from './ui/checkbox';
+export { Radio, RadioGroup } from './ui/radio';
+export type { RadioProps, RadioGroupProps, RadioOption } from './ui/radio';
+export { CheckboxGroup } from './ui/checkbox-group';
+export type { CheckboxGroupProps, CheckboxOption } from './ui/checkbox-group';
 export { Switch } from './ui/switch';
 export type { SwitchProps } from './ui/switch';
+export { Slider } from './ui/slider';
+export type { SliderProps } from './ui/slider';
+export { Select } from './ui/select';
+export type { SelectProps, SelectOption } from './ui/select';
 export { Tabs } from './ui/tabs';
 export type { TabsProps, TabsVariant, KaiTabItem } from './ui/tabs';
 export { Segmented } from './ui/segmented';
@@ -69,6 +79,8 @@ export { EditableLabel } from './ui/editable-label';
 export type { EditableLabelProps } from './ui/editable-label';
 export { Dialog } from './ui/dialog';
 export type { DialogProps, DialogController } from './ui/dialog';
+export { Dock, DockLauncherGlyph, DockCloseGlyph } from './ui/dock';
+export type { DockProps, DockController, DockPosition, DockFocusOnOpen } from './ui/dock';
 export { Popover } from './ui/popover';
 export type { PopoverProps, PopoverController } from './ui/popover';
 export { Nav } from './ui/nav';
@@ -148,3 +160,6 @@ export type {
   AudioVisualizerProps, VisualizerVariant, ShaderSpec, ShaderVariantProps,
 } from './components/audio-visualizer';
 export type { VisualizerSize } from './components/audio-visualizer/sizes';
+export { WorkspaceShell, type WorkspaceShellProps, type WorkspaceShellController, type WorkspaceAsideSide, type WorkspaceAsideToggleDetail, type WorkspaceAsideResizeDetail } from './components/workspace-shell';
+export { createConversationItemsController, readConversationItemId } from './components/conversation-list';
+export type { ConversationItemsController, ConversationItemsControllerOptions } from './components/conversation-list';

package/src/state/index.ts

@@ -7,11 +7,23 @@ export type { SetMessages, AssistantStream } from './stream';
 export { appendTextPart, appendReasoningPart, upsertToolPart, upsertCardPart, fingerprint } from './parts';
 export type { ReasoningOpts } from './parts';
 
+// Multi-thread mechanics (the workspace recast, spec §3b): the id-bound
+// SetMessages fold + the in-flight-turn bookkeeping. The consumer's record
+// shape and every persistence/retention decision stay outside — see ./threads.
+export { updateThreadMessages, bindThreadMessages, createThreadSessions } from './threads';
+export type { ThreadLike, SetThreads, BindThreadOptions, ThreadSessions } from './threads';
+
+// The persistence SEAM, not persistence: the stored-thread validator (F-18,
+// variant list derived from the MessagePart union) and the debounce/flush
+// shape. No storage backend, no default delay — policy is the consumer's.
+export { parseStoredThread, createSaveScheduler } from './persistence';
+export type { ParsedThread, DroppedStored, SaveScheduler, SaveSchedulerOptions } from './persistence';
+
 // The zero-config mock. Produces SSE frames rather than folding parts directly,
 // so the no-backend preview runs through the SAME parser a real provider does —
 // and is deliberately impossible to mistake for one. See ./mock.
 export { createMockResponder, DEFAULT_MOCK_REPLIES, MOCK_BANNER, MOCK_MARKER, MOCK_MARKER_KEY, MOCK_MODEL_ID } from './mock';
-export type { MockResponder, MockResponderOptions } from './mock';
+export type { MockReply, MockResponder, MockResponderOptions, MockToolCall, MockTurn } from './mock';
 
 // The content-model types every signature above mentions. Without these a
 // consumer importing only from '@kitn.ai/ui/state' cannot annotate the very

package/src/state/mock.ts

@@ -96,9 +96,42 @@ export const DEFAULT_MOCK_REPLIES: readonly string[] = [
   'Mock again. Every frame I send is tagged `_kai_mock` and my usage reports zero tokens, so nothing here can be mistaken for a real turn.',
 ];
 
+/** One scripted tool call for a mock turn. Framed exactly the way the OpenAI
+ *  chat-completions wire frames a real one — an announce fragment carrying
+ *  `id`/`function.name`, then the argument JSON streamed in fragments — so the
+ *  kit's own reader (`readOpenAIStream`) reassembles it through the same path a
+ *  real provider's call takes. */
+export interface MockToolCall {
+  /** The tool name, e.g. `'get_weather'` or a card tool like `'kai_confirm'`. */
+  name: string;
+  /** The call's arguments. Serialized with `JSON.stringify` and streamed as
+   *  fragments, like a real provider. Defaults to `{}`. */
+  arguments?: unknown;
+  /** Explicit tool-call id. Defaults to `call_kai-mock-<turn>-<n>`, which keeps
+   *  the mock's naming tell (see tell 3): no provider issues ids in that shape. */
+  id?: string;
+}
+
+/** A scripted mock turn: optional text, then optional tool calls. A turn with
+ *  tool calls finishes `finish_reason: 'tool_calls'`, exactly as a real
+ *  tool-calling turn does; a turn without them finishes `'stop'`. */
+export interface MockTurn {
+  /** Text streamed (token by token) before the tool calls. */
+  text?: string;
+  /** Tool calls announced this turn, in order. */
+  toolCalls?: readonly MockToolCall[];
+}
+
+/** A canned reply: plain text, or a scripted turn. A string is exactly
+ *  `{ text }` — the pre-tool-call API unchanged. */
+export type MockReply = string | MockTurn;
+
 export interface MockResponderOptions {
-  /** Canned replies, cycled one per turn. Defaults to `DEFAULT_MOCK_REPLIES`. */
-  replies?: readonly string[];
+  /** Canned replies, cycled one per turn. Plain strings stream as text; a
+   *  `MockTurn` can also script tool calls (`{ text, toolCalls }`), which is
+   *  what lets the zero-config mock exercise the kit's tool/card path without
+   *  hand-rolled SSE framing. Defaults to `DEFAULT_MOCK_REPLIES`. */
+  replies?: readonly MockReply[];
   /** Delay between chunks, in ms. Defaults to 24 — fast enough to feel alive,
    *  slow enough that the streaming is visible. `0` streams as fast as the
    *  event loop allows, which is what tests want. */
@@ -144,6 +177,27 @@ function frame(id: string, body: Record<string, unknown>): string {
 const delay = (ms: number): Promise<void> =>
   ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
 
+/** Normalize a canned reply: a plain string is exactly `{ text }`. */
+const asTurn = (reply: MockReply): MockTurn => (typeof reply === 'string' ? { text: reply } : reply);
+
+/** How many characters of argument JSON ride in each tool-call fragment. Small
+ *  enough that any realistic argument object spans several frames, so the
+ *  reader's fragment-reassembly path — the one a real provider exercises — is
+ *  exercised here too, rather than a single-frame shortcut it would never see
+ *  in production. */
+const TOOL_ARG_FRAGMENT_CHARS = 16;
+
+/** Split argument JSON into the fragments a provider streams. Never empty: an
+ *  empty-object call still sends its `'{}'` so the reader has arguments to
+ *  parse. */
+function argumentFragments(json: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < json.length; i += TOOL_ARG_FRAGMENT_CHARS) {
+    out.push(json.slice(i, i + TOOL_ARG_FRAGMENT_CHARS));
+  }
+  return out.length > 0 ? out : [''];
+}
+
 /**
  * Build a mock responder.
  *
@@ -170,8 +224,9 @@ export function createMockResponder(options: MockResponderOptions = {}): MockRes
   let announced = false;
 
   return function respond(_prompt?: string): AsyncIterable<string> {
-    const reply = pool[turn % pool.length];
+    const scripted = asTurn(pool[turn % pool.length]);
     const id = `kai-mock-${turn + 1}`;
+    const turnNumber = turn + 1;
     turn += 1;
 
     return {
@@ -193,15 +248,46 @@ export function createMockResponder(options: MockResponderOptions = {}): MockRes
         // exercises the reader's empty-delta path.
         yield frame(id, { choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] });
 
-        for (const token of tokenize(reply, chunkSize)) {
+        for (const token of tokenize(scripted.text ?? '', chunkSize)) {
           await delay(delayMs);
           yield frame(id, { choices: [{ index: 0, delta: { content: token }, finish_reason: null }] });
         }
 
+        // Scripted tool calls, framed the way the OpenAI wire frames real ones:
+        // one announce fragment per call (`index`/`id`/`function.name` + empty
+        // arguments), then the argument JSON in fragments. The kit's reader
+        // reassembles them through the exact path a real provider's call takes.
+        const toolCalls = scripted.toolCalls ?? [];
+        for (let index = 0; index < toolCalls.length; index += 1) {
+          const call = toolCalls[index];
+          // Tell 3's shape, extended to call ids: no provider issues these.
+          const callId = call.id ?? `call_${MOCK_MODEL_ID}-${turnNumber}-${index + 1}`;
+          await delay(delayMs);
+          yield frame(id, {
+            choices: [{
+              index: 0,
+              delta: { tool_calls: [{ index, id: callId, function: { name: call.name, arguments: '' } }] },
+              finish_reason: null,
+            }],
+          });
+          for (const fragment of argumentFragments(JSON.stringify(call.arguments ?? {}))) {
+            await delay(delayMs);
+            yield frame(id, {
+              choices: [{
+                index: 0,
+                delta: { tool_calls: [{ index, function: { arguments: fragment } }] },
+                finish_reason: null,
+              }],
+            });
+          }
+        }
+
         // Tell 4: zero usage. A real turn that produced this much text cannot
-        // report zero completion tokens.
+        // report zero completion tokens. A turn that announced tool calls ends
+        // `tool_calls`, exactly as a real one does, so the consumer's tool loop
+        // branches the same way it would against a provider.
         yield frame(id, {
-          choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+          choices: [{ index: 0, delta: {}, finish_reason: toolCalls.length > 0 ? 'tool_calls' : 'stop' }],
           usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
         });
         yield 'data: [DONE]\n\n';