From 383c282e04bc5d2a890fd5ec759be2ae0bceac55 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Fri, 31 Jul 2026 15:53:41 -0500
Subject: [PATCH 01/19] feat(agent): OpenUI library model, fragment builder,
 and plugin helper (DEV-773)

The SDK half of the OpenUI backport from Noetic (DEV-765). Adds
packages/agent/src/lib/openui/: defineComponent/createLibrary (Zod props
with normative declaration order), the typed fragment() builder with
uiRef/uiState/uiBuiltin, OpenUI Lang expression serialization, and the
openui(library) helper producing the wire-shaped plugin preference
(Zod -> JSON Schema).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/agent/src/index.ts               |  29 +++
 packages/agent/src/lib/openui/document.ts |  84 +++++++
 packages/agent/src/lib/openui/fragment.ts | 143 ++++++++++++
 packages/agent/src/lib/openui/index.ts    |  36 +++
 packages/agent/src/lib/openui/library.ts  |  93 ++++++++
 packages/agent/src/lib/openui/plugin.ts   |  63 ++++++
 packages/agent/tests/unit/openui.test.ts  | 259 ++++++++++++++++++++++
 7 files changed, 707 insertions(+)
 create mode 100644 packages/agent/src/lib/openui/document.ts
 create mode 100644 packages/agent/src/lib/openui/fragment.ts
 create mode 100644 packages/agent/src/lib/openui/index.ts
 create mode 100644 packages/agent/src/lib/openui/library.ts
 create mode 100644 packages/agent/src/lib/openui/plugin.ts
 create mode 100644 packages/agent/tests/unit/openui.test.ts

diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts
index 6f791d22..ebfc6615 100644
--- a/packages/agent/src/index.ts
+++ b/packages/agent/src/index.ts
@@ -182,6 +182,35 @@ export {
   buildNextTurnParamsContext,
   executeNextTurnParamsFunctions,
 } from './lib/next-turn-params.js';
+export type {
+  ComponentDefinition,
+  CreateLibraryOptions,
+  FragmentArg,
+  FragmentBuilder,
+  FragmentNode,
+  OpenUiPlugin,
+  OpenUiWireComponent,
+  PropSignature,
+  UiExpr,
+  UiFragment,
+  UiLibrary,
+  UiLiteralValue,
+} from './lib/openui/index.js';
+// OpenUI (generative UI) bindings: library model, fragment builder, plugin helper
+export {
+  componentProps,
+  createLibrary,
+  defineComponent,
+  fragment,
+  OPENUI_BUILTIN_COMPONENTS,
+  OPENUI_LANG_DIALECT,
+  OPENUI_ROOT_REF,
+  openui,
+  serializeExpr,
+  uiBuiltin,
+  uiRef,
+  uiState,
+} from './lib/openui/index.js';
 // Stop condition helpers
 export {
   finishReasonIs,
diff --git a/packages/agent/src/lib/openui/document.ts b/packages/agent/src/lib/openui/document.ts
new file mode 100644
index 00000000..7efb8aeb
--- /dev/null
+++ b/packages/agent/src/lib/openui/document.ts
@@ -0,0 +1,84 @@
+/**
+ * OpenUI Lang expression model + serialization.
+ *
+ * OpenUI Lang is a line-oriented assignment language: one statement per line,
+ * `name = expression`. The SDK only *authors* OpenUI Lang (tool-authored
+ * fragments, wire-format libraries) — parsing, validation, and prompt
+ * injection are API-side responsibilities. This module is therefore the
+ * minimal expression tree and serializer shared by the fragment builder.
+ */
+
+/** The OpenUI Lang dialect this package emits. */
+export const OPENUI_LANG_DIALECT = 'openui-lang/0.5';
+
+/** The reserved assignment ref that designates the document root. */
+export const OPENUI_ROOT_REF = 'root';
+
+export type UiLiteralValue = string | number | boolean | null;
+
+/** Expression tree for one assignment's right-hand side. */
+export type UiExpr =
+  | {
+      kind: 'literal';
+      value: UiLiteralValue;
+    }
+  | {
+      kind: 'ref';
+      name: string;
+    }
+  | {
+      kind: 'state-ref';
+      name: string;
+    }
+  | {
+      kind: 'member';
+      base: UiExpr;
+      path: string[];
+    }
+  | {
+      kind: 'array';
+      items: UiExpr[];
+    }
+  | {
+      kind: 'object';
+      entries: Array<{
+        key: string;
+        value: UiExpr;
+      }>;
+    }
+  | {
+      kind: 'call';
+      fn: string;
+      builtin: boolean;
+      args: UiExpr[];
+    };
+
+/**
+ * A renderable piece of UI: the dialect it's expressed in plus its serialized
+ * OpenUI Lang source. This is the shape carried on `tool.ui_fragment` stream
+ * events and (for server tools) `response.openui.fragment` wire events.
+ */
+export interface UiFragment {
+  dialect: string;
+  source: string;
+}
+
+/** Serialize an expression to OpenUI Lang source. */
+export function serializeExpr(expr: UiExpr): string {
+  switch (expr.kind) {
+    case 'literal':
+      return typeof expr.value === 'string' ? JSON.stringify(expr.value) : String(expr.value);
+    case 'ref':
+      return expr.name;
+    case 'state-ref':
+      return `$${expr.name}`;
+    case 'member':
+      return `${serializeExpr(expr.base)}.${expr.path.join('.')}`;
+    case 'array':
+      return `[${expr.items.map(serializeExpr).join(', ')}]`;
+    case 'object':
+      return `{${expr.entries.map((e) => `${e.key}: ${serializeExpr(e.value)}`).join(', ')}}`;
+    case 'call':
+      return `${expr.builtin ? '@' : ''}${expr.fn}(${expr.args.map(serializeExpr).join(', ')})`;
+  }
+}
diff --git a/packages/agent/src/lib/openui/fragment.ts b/packages/agent/src/lib/openui/fragment.ts
new file mode 100644
index 00000000..3e86185a
--- /dev/null
+++ b/packages/agent/src/lib/openui/fragment.ts
@@ -0,0 +1,143 @@
+/**
+ * Typed fragment builder for tool-authored UI.
+ *
+ * `fragment(library)` compiles a constructor per registered component from the
+ * library's own Zod prop schemas, so tool render functions build fragments in
+ * plain TypeScript and get validation at construction time — a typo'd
+ * component name fails typecheck, a bad literal prop fails before the client
+ * renderer ever sees it. Constructors return a `FragmentNode` (dialect +
+ * serialized source) that also composes as a child of other constructors.
+ */
+import * as z4 from 'zod/v4';
+import type { UiExpr, UiFragment, UiLiteralValue } from './document.js';
+import { OPENUI_LANG_DIALECT, OPENUI_ROOT_REF, serializeExpr } from './document.js';
+import type { UiLibrary } from './library.js';
+import { componentProps } from './library.js';
+
+const FRAGMENT_EXPR: unique symbol = Symbol.for('openrouter.openui.fragment-expr');
+
+/** A composable fragment node: a {@link UiFragment} that also nests as a child argument. */
+export interface FragmentNode extends UiFragment {
+  [FRAGMENT_EXPR]: UiExpr;
+}
+
+/** Any value accepted as a fragment constructor argument. */
+export type FragmentArg =
+  | UiLiteralValue
+  | FragmentNode
+  | FragmentArg[]
+  | {
+      [key: string]: FragmentArg;
+    };
+
+function isFragmentNode(value: unknown): value is FragmentNode {
+  return typeof value === 'object' && value !== null && FRAGMENT_EXPR in value;
+}
+
+function toExpr(arg: FragmentArg): UiExpr {
+  if (isFragmentNode(arg)) {
+    return arg[FRAGMENT_EXPR];
+  }
+  if (Array.isArray(arg)) {
+    return {
+      kind: 'array',
+      items: arg.map(toExpr),
+    };
+  }
+  if (typeof arg === 'object' && arg !== null) {
+    return {
+      kind: 'object',
+      entries: Object.entries(arg).map(([key, value]) => ({
+        key,
+        value: toExpr(value),
+      })),
+    };
+  }
+  return {
+    kind: 'literal',
+    value: arg,
+  };
+}
+
+function makeNode(dialect: string, expr: UiExpr): FragmentNode {
+  return {
+    dialect,
+    source: `${OPENUI_ROOT_REF} = ${serializeExpr(expr)}`,
+    [FRAGMENT_EXPR]: expr,
+  };
+}
+
+/** Reference another statement by ref (`uiRef('chart')` → `chart`). */
+export function uiRef(name: string, dialect?: string): FragmentNode {
+  return makeNode(dialect ?? OPENUI_LANG_DIALECT, {
+    kind: 'ref',
+    name,
+  });
+}
+
+/** Reference a reactive state variable (`uiState('tab')` → `$tab`). */
+export function uiState(name: string, dialect?: string): FragmentNode {
+  return makeNode(dialect ?? OPENUI_LANG_DIALECT, {
+    kind: 'state-ref',
+    name,
+  });
+}
+
+/** A built-in function step (`uiBuiltin('Run', uiRef('save'))` → `@Run(save)`). */
+export function uiBuiltin(fn: string, ...args: FragmentArg[]): FragmentNode {
+  return makeNode(OPENUI_LANG_DIALECT, {
+    kind: 'call',
+    fn,
+    builtin: true,
+    args: args.map(toExpr),
+  });
+}
+
+/** One constructor per component: builds a validated fragment node. */
+export type FragmentBuilder<N extends string> = Record<N, (...args: FragmentArg[]) => FragmentNode>;
+
+/**
+ * Compile a typed fragment builder from a library.
+ *
+ * @example
+ * ```typescript
+ * const ui = fragment(library);
+ * const card = ui.Card('Usage', [ui.Text('$12.30 across 42 requests')]);
+ * // card.source === 'root = Card("Usage", [Text("$12.30 across 42 requests")])'
+ * ```
+ */
+export function fragment<N extends string>(library: UiLibrary<N>): FragmentBuilder<N> {
+  const builder: Record<string, (...args: FragmentArg[]) => FragmentNode> = {};
+  for (const def of library.components.values()) {
+    const props = componentProps(def);
+    builder[def.name] = (...args: FragmentArg[]) => {
+      if (args.length > props.length) {
+        throw new Error(
+          `${def.name}() takes at most ${props.length} argument(s) (${props.map((p) => p.name).join(', ')}), got ${args.length}`,
+        );
+      }
+      const exprs = args.map((arg, i) => {
+        const expr = toExpr(arg);
+        const prop = props[i];
+        if (prop && expr.kind === 'literal') {
+          const parsed = z4.safeParse(prop.schema, expr.value);
+          if (!parsed.success) {
+            throw new Error(
+              `${def.name}() prop '${prop.name}' rejects ${JSON.stringify(expr.value)}: ${parsed.error.issues[0]?.message ?? 'invalid'}`,
+            );
+          }
+        }
+        return expr;
+      });
+      return makeNode(library.dialect, {
+        kind: 'call',
+        fn: def.name,
+        builtin: false,
+        args: exprs,
+      });
+    };
+  }
+  // Keys are exactly the library's component names; TS can't see that through
+  // the Map iteration, so cast at the boundary.
+  return builder as FragmentBuilder<N>;
+}
diff --git a/packages/agent/src/lib/openui/index.ts b/packages/agent/src/lib/openui/index.ts
new file mode 100644
index 00000000..bc5df714
--- /dev/null
+++ b/packages/agent/src/lib/openui/index.ts
@@ -0,0 +1,36 @@
+/**
+ * OpenUI (generative UI) bindings for the Agent SDK.
+ *
+ * The API owns the heavy lifting — prompt injection, streaming OpenUI Lang
+ * parsing, and library validation (see DEV-765). This module ships the thin
+ * client half: the component-library model, the typed fragment builder for
+ * tool-authored UI, and the `openui()` plugin helper for `callModel()`.
+ */
+export {
+  OPENUI_LANG_DIALECT,
+  OPENUI_ROOT_REF,
+  serializeExpr,
+  type UiExpr,
+  type UiFragment,
+  type UiLiteralValue,
+} from './document.js';
+export {
+  type FragmentArg,
+  type FragmentBuilder,
+  type FragmentNode,
+  fragment,
+  uiBuiltin,
+  uiRef,
+  uiState,
+} from './fragment.js';
+export {
+  type ComponentDefinition,
+  type CreateLibraryOptions,
+  componentProps,
+  createLibrary,
+  defineComponent,
+  OPENUI_BUILTIN_COMPONENTS,
+  type PropSignature,
+  type UiLibrary,
+} from './library.js';
+export { type OpenUiPlugin, type OpenUiWireComponent, openui } from './plugin.js';
diff --git a/packages/agent/src/lib/openui/library.ts b/packages/agent/src/lib/openui/library.ts
new file mode 100644
index 00000000..67188739
--- /dev/null
+++ b/packages/agent/src/lib/openui/library.ts
@@ -0,0 +1,93 @@
+/**
+ * Component library model: `defineComponent` / `createLibrary`.
+ *
+ * A library is the vocabulary an agent may render — component names plus
+ * Zod prop schemas whose *declaration order is normative* (positional args in
+ * OpenUI Lang map to props by declared order). The SDK ships the library to
+ * the API via the `openui` plugin (see `plugin.ts`); prompt generation and
+ * document validation happen API-side.
+ */
+
+import type { ZodObject, ZodRawShape } from 'zod/v4';
+import * as z4 from 'zod/v4';
+import type { $ZodType } from 'zod/v4/core';
+import { OPENUI_LANG_DIALECT } from './document.js';
+
+/** One registered component: its name, docs, and ordered prop schemas. */
+export interface ComponentDefinition<N extends string = string> {
+  name: N;
+  description?: string;
+  /**
+   * Prop schemas. Positional arguments in OpenUI Lang map to props by key
+   * declaration order (Zod preserves shape insertion order).
+   */
+  props?: ZodObject<ZodRawShape>;
+}
+
+/** Declare a component the model (or a tool) may render. */
+export function defineComponent<const N extends string>(
+  def: ComponentDefinition<N>,
+): ComponentDefinition<N> {
+  return def;
+}
+
+/**
+ * Components every library accepts implicitly: data bindings, action blocks,
+ * and the slot that mounts a tool-owned region into a model-authored layout.
+ */
+export const OPENUI_BUILTIN_COMPONENTS = [
+  'Action',
+  'Query',
+  'Mutation',
+  'ToolView',
+] as const;
+
+/** A registered component library — the vocabulary a surface renders. */
+export interface UiLibrary<N extends string = string> {
+  dialect: string;
+  components: ReadonlyMap<string, ComponentDefinition>;
+  componentNames: readonly N[];
+}
+
+/** Options for {@link createLibrary}. */
+export interface CreateLibraryOptions {
+  dialect?: string;
+}
+
+/** Build a library from component definitions. */
+export function createLibrary<const D extends readonly ComponentDefinition[]>(
+  definitions: D,
+  options?: CreateLibraryOptions,
+): UiLibrary<D[number]['name']> {
+  const components = new Map<string, ComponentDefinition>();
+  for (const def of definitions) {
+    if (components.has(def.name)) {
+      throw new Error(`duplicate component name '${def.name}' in library`);
+    }
+    components.set(def.name, def);
+  }
+  return {
+    dialect: options?.dialect ?? OPENUI_LANG_DIALECT,
+    components,
+    componentNames: definitions.map((d) => d.name),
+  };
+}
+
+/** An ordered prop signature for a component (declaration order). */
+export interface PropSignature {
+  name: string;
+  optional: boolean;
+  schema: $ZodType;
+}
+
+/** Ordered prop signatures for a component (declaration order). */
+export function componentProps(def: ComponentDefinition): PropSignature[] {
+  if (!def.props) {
+    return [];
+  }
+  return Object.entries(def.props.shape).map(([name, schema]) => ({
+    name,
+    optional: z4.safeParse(schema as $ZodType, undefined).success,
+    schema: schema as $ZodType,
+  }));
+}
diff --git a/packages/agent/src/lib/openui/plugin.ts b/packages/agent/src/lib/openui/plugin.ts
new file mode 100644
index 00000000..204dcf9d
--- /dev/null
+++ b/packages/agent/src/lib/openui/plugin.ts
@@ -0,0 +1,63 @@
+/**
+ * The `openui()` request helper: turn a component library into the `openui`
+ * plugin preference carried on a Responses request. Zod prop schemas are
+ * converted to JSON Schema at this boundary — the API owns prompt generation
+ * and validation, so the wire shape is renderer- and SDK-agnostic.
+ *
+ * Note: until `@openrouter/sdk` regenerates with the `openui` plugin member
+ * (DEV-772), the SDK's closed `plugins` union will not accept this shape —
+ * gate usage on that release.
+ */
+import { convertZodToJsonSchema } from '../tool-executor.js';
+import type { UiLibrary } from './library.js';
+
+/** Wire shape of one component definition inside the plugin preference. */
+export interface OpenUiWireComponent {
+  name: string;
+  description?: string;
+  /**
+   * JSON Schema for the component's props. Property declaration order is
+   * normative: positional arguments in OpenUI Lang map to props in order.
+   */
+  props?: Record<string, unknown>;
+}
+
+/** Wire shape of the `openui` plugin preference. */
+export interface OpenUiPlugin {
+  id: 'openui';
+  library: OpenUiWireComponent[];
+  dialect?: string;
+}
+
+/**
+ * Build the `openui` plugin preference from a component library.
+ *
+ * @example
+ * ```typescript
+ * const result = callModel(client, {
+ *   model: 'anthropic/claude-sonnet-5',
+ *   input: 'Show me a dashboard',
+ *   plugins: [openui(library)],
+ * });
+ * ```
+ */
+export function openui(library: UiLibrary): OpenUiPlugin {
+  return {
+    id: 'openui',
+    library: [
+      ...library.components.values(),
+    ].map((def) => {
+      const component: OpenUiWireComponent = {
+        name: def.name,
+      };
+      if (def.description !== undefined) {
+        component.description = def.description;
+      }
+      if (def.props !== undefined) {
+        component.props = convertZodToJsonSchema(def.props);
+      }
+      return component;
+    }),
+    dialect: library.dialect,
+  };
+}
diff --git a/packages/agent/tests/unit/openui.test.ts b/packages/agent/tests/unit/openui.test.ts
new file mode 100644
index 00000000..74758d84
--- /dev/null
+++ b/packages/agent/tests/unit/openui.test.ts
@@ -0,0 +1,259 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod/v4';
+import type { UiExpr } from '../../src/lib/openui/document.js';
+import { OPENUI_LANG_DIALECT, serializeExpr } from '../../src/lib/openui/document.js';
+import { fragment, uiBuiltin, uiRef, uiState } from '../../src/lib/openui/fragment.js';
+import { componentProps, createLibrary, defineComponent } from '../../src/lib/openui/library.js';
+import { openui } from '../../src/lib/openui/plugin.js';
+
+const library = createLibrary([
+  defineComponent({
+    name: 'Card',
+    description: 'Container with a title',
+    props: z.object({
+      title: z.string(),
+      children: z.array(z.unknown()).optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Text',
+    props: z.object({
+      value: z.string(),
+    }),
+  }),
+  defineComponent({
+    name: 'Divider',
+  }),
+]);
+
+describe('serializeExpr', () => {
+  it('serializes literals with JSON string quoting', () => {
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: 'a "quoted" string',
+      }),
+    ).toBe('"a \\"quoted\\" string"');
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: 42,
+      }),
+    ).toBe('42');
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: true,
+      }),
+    ).toBe('true');
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: null,
+      }),
+    ).toBe('null');
+  });
+
+  it('serializes refs, state refs, and member access', () => {
+    expect(
+      serializeExpr({
+        kind: 'ref',
+        name: 'chart',
+      }),
+    ).toBe('chart');
+    expect(
+      serializeExpr({
+        kind: 'state-ref',
+        name: 'tab',
+      }),
+    ).toBe('$tab');
+    expect(
+      serializeExpr({
+        kind: 'member',
+        base: {
+          kind: 'ref',
+          name: 'data',
+        },
+        path: [
+          'rows',
+          'title',
+        ],
+      }),
+    ).toBe('data.rows.title');
+  });
+
+  it('serializes arrays, objects, and calls (builtin vs component)', () => {
+    const expr: UiExpr = {
+      kind: 'call',
+      fn: 'Action',
+      builtin: false,
+      args: [
+        {
+          kind: 'array',
+          items: [
+            {
+              kind: 'call',
+              fn: 'Run',
+              builtin: true,
+              args: [
+                {
+                  kind: 'ref',
+                  name: 'save',
+                },
+              ],
+            },
+          ],
+        },
+        {
+          kind: 'object',
+          entries: [
+            {
+              key: 'once',
+              value: {
+                kind: 'literal',
+                value: true,
+              },
+            },
+          ],
+        },
+      ],
+    };
+    expect(serializeExpr(expr)).toBe('Action([@Run(save)], {once: true})');
+  });
+});
+
+describe('createLibrary / componentProps', () => {
+  it('preserves component order and rejects duplicates', () => {
+    expect(library.componentNames).toEqual([
+      'Card',
+      'Text',
+      'Divider',
+    ]);
+    expect(library.dialect).toBe(OPENUI_LANG_DIALECT);
+    expect(() =>
+      createLibrary([
+        defineComponent({
+          name: 'A',
+        }),
+        defineComponent({
+          name: 'A',
+        }),
+      ]),
+    ).toThrow(/duplicate component name 'A'/);
+  });
+
+  it('reports prop signatures in declaration order with optionality', () => {
+    const card = library.components.get('Card');
+    expect(card).toBeDefined();
+    const props = componentProps(card!);
+    expect(props.map((p) => p.name)).toEqual([
+      'title',
+      'children',
+    ]);
+    expect(props.map((p) => p.optional)).toEqual([
+      false,
+      true,
+    ]);
+  });
+
+  it('supports a custom dialect', () => {
+    const custom = createLibrary(
+      [
+        defineComponent({
+          name: 'X',
+        }),
+      ],
+      {
+        dialect: 'openui-lang/0.6',
+      },
+    );
+    expect(custom.dialect).toBe('openui-lang/0.6');
+  });
+});
+
+describe('fragment builder', () => {
+  const ui = fragment(library);
+
+  it('builds a serialized fragment rooted at `root`', () => {
+    const node = ui.Card('Usage', [
+      ui.Text('hello'),
+    ]);
+    expect(node.dialect).toBe(OPENUI_LANG_DIALECT);
+    expect(node.source).toBe('root = Card("Usage", [Text("hello")])');
+  });
+
+  it('composes refs, state, and builtins', () => {
+    const node = ui.Card('Tabs', [
+      uiState('tab'),
+      uiBuiltin('Run', uiRef('load')),
+    ]);
+    expect(node.source).toBe('root = Card("Tabs", [$tab, @Run(load)])');
+  });
+
+  it('accepts plain objects and arrays as args', () => {
+    const node = ui.Text('ok');
+    const wrapped = ui.Card('W', [
+      node,
+      {
+        nested: [
+          1,
+          true,
+          null,
+        ],
+      } as never,
+    ]);
+    expect(wrapped.source).toBe('root = Card("W", [Text("ok"), {nested: [1, true, null]}])');
+  });
+
+  it('validates literal props at construction time', () => {
+    expect(() => ui.Text(42)).toThrow(/Text\(\) prop 'value' rejects 42/);
+  });
+
+  it('rejects arity overflow', () => {
+    expect(() => ui.Divider('extra')).toThrow(/Divider\(\) takes at most 0 argument\(s\)/);
+  });
+
+  it('skips validation for dynamic args (refs resolve at render time)', () => {
+    expect(() => ui.Text(uiRef('someRef'))).not.toThrow();
+    expect(ui.Text(uiState('value')).source).toBe('root = Text($value)');
+  });
+});
+
+describe('openui() plugin helper', () => {
+  it('produces the wire-shaped plugin preference with JSON Schema props', () => {
+    const plugin = openui(library);
+    expect(plugin.id).toBe('openui');
+    expect(plugin.dialect).toBe(OPENUI_LANG_DIALECT);
+    expect(plugin.library.map((c) => c.name)).toEqual([
+      'Card',
+      'Text',
+      'Divider',
+    ]);
+
+    const card = plugin.library[0];
+    expect(card?.description).toBe('Container with a title');
+    expect(card?.props).toMatchObject({
+      type: 'object',
+      required: [
+        'title',
+      ],
+    });
+    // Property declaration order is normative for positional-arg mapping.
+    expect(
+      Object.keys(
+        (
+          card?.props as {
+            properties: object;
+          }
+        ).properties,
+      ),
+    ).toEqual([
+      'title',
+      'children',
+    ]);
+
+    const divider = plugin.library[2];
+    expect(divider?.props).toBeUndefined();
+    expect(divider?.description).toBeUndefined();
+  });
+});

From a3347b5e2182f77bd483403da418a5735242b819 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Fri, 31 Jul 2026 16:05:08 -0500
Subject: [PATCH 02/19] feat(agent): toUIOutput on tool(), tool.ui_fragment
 events, and getUiStream() (DEV-773)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tools can now author OpenUI render fragments: an optional toUIOutput
sibling of toModelOutput on every executable tool shape. Fragments are
broadcast as tool.ui_fragment stream events after successful execution
(render-only, never sent to the model; a throwing toUIOutput degrades to
no-fragment).

getUiStream() on ModelResult surfaces UI events across all turns:
tool-authored fragments plus the API's response.openui.* wire events
(statement/fragment/document) from the openui plugin. Wire events not
yet in the SDK's stream-event union arrive via its forward-compat
Unknown catch-all, so translation reads the raw payload — the stream
works both before and after the SDK regen (DEV-772).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/agent/src/index.ts                   |   9 +
 packages/agent/src/lib/model-result.ts        | 100 ++++
 packages/agent/src/lib/openui/index.ts        |   8 +
 packages/agent/src/lib/openui/ui-stream.ts    | 194 +++++++
 packages/agent/src/lib/tool-types.ts          |  44 ++
 packages/agent/src/lib/tool.ts                |  23 +
 .../agent/tests/unit/openui-stream.test.ts    | 489 ++++++++++++++++++
 7 files changed, 867 insertions(+)
 create mode 100644 packages/agent/src/lib/openui/ui-stream.ts
 create mode 100644 packages/agent/tests/unit/openui-stream.test.ts

diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts
index ebfc6615..fc094e20 100644
--- a/packages/agent/src/index.ts
+++ b/packages/agent/src/index.ts
@@ -191,10 +191,14 @@ export type {
   OpenUiPlugin,
   OpenUiWireComponent,
   PropSignature,
+  UiDocumentEvent,
   UiExpr,
   UiFragment,
+  UiFragmentEvent,
   UiLibrary,
   UiLiteralValue,
+  UiStatementEvent,
+  UiStreamEvent,
 } from './lib/openui/index.js';
 // OpenUI (generative UI) bindings: library model, fragment builder, plugin helper
 export {
@@ -205,8 +209,10 @@ export {
   OPENUI_BUILTIN_COMPONENTS,
   OPENUI_LANG_DIALECT,
   OPENUI_ROOT_REF,
+  OPENUI_WIRE_EVENT,
   openui,
   serializeExpr,
+  translateUiEvent,
   uiBuiltin,
   uiRef,
   uiState,
@@ -277,8 +283,10 @@ export type {
   ToolResultEvent,
   ToolResultItem,
   ToolStreamEvent,
+  ToolUiFragmentEvent,
   ToolWithExecute,
   ToolWithGenerator,
+  ToUIOutputFunction,
   TurnContext,
   TurnEndEvent,
   TurnStartEvent,
@@ -301,6 +309,7 @@ export {
   isToolCallOutputEvent,
   isToolPreliminaryResultEvent,
   isToolResultEvent,
+  isToolUiFragmentEvent,
   isTurnEndEvent,
   isTurnStartEvent,
   ToolType,
diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index acab9dce..8940f7d5 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -31,6 +31,8 @@ import {
   applyNextTurnParamsToRequest,
   executeNextTurnParamsFunctions,
 } from './next-turn-params.js';
+import type { UiStreamEvent } from './openui/ui-stream.js';
+import { translateUiEvent } from './openui/ui-stream.js';
 import { ReusableReadableStream } from './reusable-stream.js';
 import { isStopConditionMet } from './stop-conditions.js';
 import type { ItemInProgress, StreamableOutputItem } from './stream-transformers.js';
@@ -78,6 +80,7 @@ import type {
   ToolContextMapWithShared,
   ToolResultItem,
   ToolStreamEvent,
+  ToolUiFragmentEvent,
   TurnContext,
   TurnEndEvent,
   TurnStartEvent,
@@ -2670,6 +2673,8 @@ export class ModelResult<
         output: executedOutput,
         timestamp: Date.now(),
       } satisfies ToolCallOutputEvent);
+
+      await this.broadcastUiFragment(value);
     }
 
     return {
@@ -2678,6 +2683,54 @@ export class ModelResult<
     };
   }
 
+  /**
+   * Compute and broadcast a tool-authored OpenUI fragment for a successful
+   * execution. Render-only: the fragment never reaches the model, so a
+   * throwing `toUIOutput` degrades to "no fragment" instead of failing the
+   * round — the model-facing output has already been pushed.
+   */
+  private async broadcastUiFragment(value: {
+    toolCall: ParsedToolCall<Tool>;
+    tool: Tool;
+    result: {
+      result: unknown;
+      error?: Error;
+    };
+  }): Promise<void> {
+    if (
+      value.result.error ||
+      !isAutoResolvableTool(value.tool) ||
+      !value.tool.function.toUIOutput
+    ) {
+      return;
+    }
+    const rawArgs: unknown = value.toolCall.arguments;
+    if (!isRecord(rawArgs)) {
+      return;
+    }
+    try {
+      const fragment = await value.tool.function.toUIOutput({
+        output: value.result.result,
+        input: rawArgs,
+      });
+      if (!fragment) {
+        return;
+      }
+      this.turnBroadcaster?.push({
+        type: 'tool.ui_fragment' as const,
+        toolCallId: value.toolCall.id,
+        toolName: value.toolCall.name,
+        fragment: {
+          dialect: fragment.dialect,
+          source: fragment.source,
+        },
+        timestamp: Date.now(),
+      } satisfies ToolUiFragmentEvent);
+    } catch {
+      // Fragment construction failed — drop it; rendering is best-effort.
+    }
+  }
+
   /**
    * Resolve async functions for the current turn.
    * Updates the resolved request with turn-specific parameter values.
@@ -4592,6 +4645,53 @@ export class ModelResult<
     }.call(this);
   }
 
+  /**
+   * Stream OpenUI events from all turns: completed OpenUI Lang statements
+   * authored by the model (`response.openui.*` wire events from the `openui`
+   * plugin) and tool-authored fragments (`tool.ui_fragment` events produced
+   * by tools declaring `toUIOutput`).
+   *
+   * Wire events not yet in the SDK's stream-event union arrive through its
+   * forward-compat catch-all; translation reads the raw payload, so this
+   * stream works both before and after the SDK regen picks them up.
+   */
+  getUiStream(): AsyncIterableIterator<UiStreamEvent> {
+    return async function* (this: ModelResult<TTools, TShared>) {
+      await this.initStreamGuarded();
+
+      if (!this.options.tools?.length) {
+        let streamFailed = false;
+        try {
+          if (this.reusableStream) {
+            for await (const event of this.reusableStream.createConsumer()) {
+              const uiEvent = translateUiEvent(event);
+              if (uiEvent) {
+                yield uiEvent;
+              }
+            }
+          }
+        } catch (error) {
+          streamFailed = true;
+          throw error;
+        } finally {
+          await this.finishHooksSessionForStream(streamFailed ? 'error' : 'complete');
+        }
+        return;
+      }
+
+      const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+
+      for await (const event of consumer) {
+        const uiEvent = translateUiEvent(event);
+        if (uiEvent) {
+          yield uiEvent;
+        }
+      }
+
+      await executionPromise;
+    }.call(this);
+  }
+
   /**
    * Stream tool call argument deltas and preliminary results from all turns.
    * Preliminary results are streamed in REAL-TIME as generator tools yield.
diff --git a/packages/agent/src/lib/openui/index.ts b/packages/agent/src/lib/openui/index.ts
index bc5df714..78cf91f1 100644
--- a/packages/agent/src/lib/openui/index.ts
+++ b/packages/agent/src/lib/openui/index.ts
@@ -34,3 +34,11 @@ export {
   type UiLibrary,
 } from './library.js';
 export { type OpenUiPlugin, type OpenUiWireComponent, openui } from './plugin.js';
+export {
+  OPENUI_WIRE_EVENT,
+  translateUiEvent,
+  type UiDocumentEvent,
+  type UiFragmentEvent,
+  type UiStatementEvent,
+  type UiStreamEvent,
+} from './ui-stream.js';
diff --git a/packages/agent/src/lib/openui/ui-stream.ts b/packages/agent/src/lib/openui/ui-stream.ts
new file mode 100644
index 00000000..6414fe12
--- /dev/null
+++ b/packages/agent/src/lib/openui/ui-stream.ts
@@ -0,0 +1,194 @@
+/**
+ * UI stream event model: the events `getUiStream()` yields, plus the
+ * translation from raw response-stream events.
+ *
+ * Two sources feed the UI stream:
+ * - `tool.ui_fragment` — SDK-synthetic events broadcast when a local tool's
+ *   `toUIOutput` produces a fragment.
+ * - `response.openui.*` — API wire events emitted by the `openui` plugin.
+ *   Until `@openrouter/sdk` regenerates with these union members (DEV-772),
+ *   they arrive through the SDK's forward-compat catch-all as
+ *   `{ type: 'UNKNOWN', raw: {...}, isUnknown: true }` — so translation reads
+ *   the raw payload, never the outer discriminant.
+ */
+
+/** One completed OpenUI Lang statement authored by the model. */
+export interface UiStatementEvent {
+  type: 'statement';
+  /** Assignment target ref (state refs keep their `$` prefix). */
+  ref: string;
+  /** Statement classification: component | state | query | mutation | value. */
+  kind: string;
+  /** OpenUI Lang source of the single completed statement. */
+  source: string;
+}
+
+/** A tool-authored fragment (local `toUIOutput` or API `response.openui.fragment`). */
+export interface UiFragmentEvent {
+  type: 'fragment';
+  /** The tool call this fragment belongs to, when tool-authored. */
+  toolCallId?: string;
+  /** The tool that authored the fragment, when known (local tools only). */
+  toolName?: string;
+  dialect: string;
+  source: string;
+}
+
+/** Turn-end document summary from the API (root ref + diagnostics). */
+export interface UiDocumentEvent {
+  type: 'document';
+  root: string | null;
+  dialect: string;
+  diagnostics: Array<{
+    line?: number;
+    message: string;
+    source?: string;
+  }>;
+}
+
+/** Every event {@link ModelResult.getUiStream} yields. */
+export type UiStreamEvent = UiStatementEvent | UiFragmentEvent | UiDocumentEvent;
+
+/** Wire event types the `openui` plugin emits on the Responses stream. */
+export const OPENUI_WIRE_EVENT = {
+  Statement: 'response.openui.statement',
+  Fragment: 'response.openui.fragment',
+  Document: 'response.openui.document',
+} as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Unwrap the SDK's forward-compat catch-all: unrecognized SSE event types
+ * parse to `{ type: 'UNKNOWN', raw: <original>, isUnknown: true }`. Returns
+ * the payload carrying the real `type` either way.
+ */
+function unwrapEvent(event: unknown): Record<string, unknown> | null {
+  if (!isRecord(event)) {
+    return null;
+  }
+  if (event['isUnknown'] === true && isRecord(event['raw'])) {
+    return event['raw'];
+  }
+  return event;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Translate one response-stream event into a UI stream event, or null when
+ * the event carries nothing the UI renders. Handles both the SDK-synthetic
+ * `tool.ui_fragment` and the API's `response.openui.*` wire events (including
+ * their pre-regen `Unknown` encoding).
+ */
+export function translateUiEvent(event: unknown): UiStreamEvent | null {
+  const payload = unwrapEvent(event);
+  if (!payload) {
+    return null;
+  }
+
+  switch (payload['type']) {
+    case 'tool.ui_fragment': {
+      const fragment = payload['fragment'];
+      if (!isRecord(fragment)) {
+        return null;
+      }
+      const dialect = str(fragment['dialect']);
+      const source = str(fragment['source']);
+      if (dialect === undefined || source === undefined) {
+        return null;
+      }
+      const result: UiFragmentEvent = {
+        type: 'fragment',
+        dialect,
+        source,
+      };
+      const toolCallId = str(payload['toolCallId']);
+      if (toolCallId !== undefined) {
+        result.toolCallId = toolCallId;
+      }
+      const toolName = str(payload['toolName']);
+      if (toolName !== undefined) {
+        result.toolName = toolName;
+      }
+      return result;
+    }
+
+    case OPENUI_WIRE_EVENT.Statement: {
+      const ref = str(payload['ref']);
+      const kind = str(payload['kind']);
+      const source = str(payload['source']);
+      if (ref === undefined || kind === undefined || source === undefined) {
+        return null;
+      }
+      return {
+        type: 'statement',
+        ref,
+        kind,
+        source,
+      };
+    }
+
+    case OPENUI_WIRE_EVENT.Fragment: {
+      const dialect = str(payload['dialect']);
+      const source = str(payload['source']);
+      if (dialect === undefined || source === undefined) {
+        return null;
+      }
+      const result: UiFragmentEvent = {
+        type: 'fragment',
+        dialect,
+        source,
+      };
+      // Wire field is snake_case; tolerate camelCase for forward compat.
+      const callId = str(payload['call_id']) ?? str(payload['callId']);
+      if (callId !== undefined) {
+        result.toolCallId = callId;
+      }
+      return result;
+    }
+
+    case OPENUI_WIRE_EVENT.Document: {
+      const dialect = str(payload['dialect']);
+      if (dialect === undefined) {
+        return null;
+      }
+      const root = str(payload['root']) ?? null;
+      const rawDiagnostics = payload['diagnostics'];
+      const diagnostics: UiDocumentEvent['diagnostics'] = Array.isArray(rawDiagnostics)
+        ? rawDiagnostics.filter(isRecord).flatMap((d) => {
+            const message = str(d['message']);
+            if (message === undefined) {
+              return [];
+            }
+            const diagnostic: UiDocumentEvent['diagnostics'][number] = {
+              message,
+            };
+            if (typeof d['line'] === 'number') {
+              diagnostic.line = d['line'];
+            }
+            const source = str(d['source']);
+            if (source !== undefined) {
+              diagnostic.source = source;
+            }
+            return [
+              diagnostic,
+            ];
+          })
+        : [];
+      return {
+        type: 'document',
+        root,
+        dialect,
+        diagnostics,
+      };
+    }
+
+    default:
+      return null;
+  }
+}
diff --git a/packages/agent/src/lib/tool-types.ts b/packages/agent/src/lib/tool-types.ts
index 6656c7c3..5c8e798e 100644
--- a/packages/agent/src/lib/tool-types.ts
+++ b/packages/agent/src/lib/tool-types.ts
@@ -2,6 +2,7 @@ import type * as models from '@openrouter/sdk/models';
 import type { StreamEvents } from '@openrouter/sdk/models';
 import type { $ZodObject, $ZodShape, $ZodType, infer as zodInfer } from 'zod/v4/core';
 import type { DoomLoopSerializedState } from './doom-loop.js';
+import type { UiFragment } from './openui/document.js';
 
 /**
  * Tool type enum for enhanced tools
@@ -265,6 +266,22 @@ export type ToModelOutputFunction<TInput, TOutput> = {
   }): ToModelOutputResult | Promise<ToModelOutputResult>;
 }['bivarianceHack'];
 
+/**
+ * Function to convert tool execution output to a renderable UI fragment
+ * (OpenUI). Runs after a successful execution alongside `toModelOutput`; the
+ * fragment is broadcast as a `tool.ui_fragment` stream event and never sent
+ * to the model. Returning `null`/`undefined` emits nothing for this call.
+ * @template TInput - The tool's input type
+ * @template TOutput - The tool's output type
+ */
+// Object-with-method form for bivariant param checking — see ToModelOutputFunction.
+export type ToUIOutputFunction<TInput, TOutput> = {
+  bivarianceHack(params: {
+    output: TOutput;
+    input: TInput;
+  }): UiFragment | null | undefined | Promise<UiFragment | null | undefined>;
+}['bivarianceHack'];
+
 /**
  * Base tool function interface with inputSchema
  * @template TInput - Zod schema for tool input
@@ -319,6 +336,8 @@ export interface ToolFunctionWithExecute<
   ): Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 }
 
 /**
@@ -360,6 +379,8 @@ export interface ToolFunctionWithGenerator<
   ): AsyncGenerator<zodInfer<TEvent> | zodInfer<TOutput>, zodInfer<TOutput> | undefined>;
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 }
 
 /**
@@ -409,6 +430,8 @@ export interface HITLToolFunction<
     context?: ToolExecuteContext<TName, TContext>,
   ): Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 }
 
 /**
@@ -964,6 +987,19 @@ export type ToolCallOutputEvent = {
   timestamp: number;
 };
 
+/**
+ * Tool UI fragment event carrying a tool-authored OpenUI fragment.
+ * Broadcast by executeToolRound after a successful execution when the tool
+ * declares `toUIOutput`. Client-render only — never sent to the model.
+ */
+export type ToolUiFragmentEvent = {
+  type: 'tool.ui_fragment';
+  toolCallId: string;
+  toolName: string;
+  fragment: UiFragment;
+  timestamp: number;
+};
+
 /**
  * Turn start event emitted at the beginning of each API turn
  * Turn 0 is the initial request, subsequent turns follow tool execution
@@ -995,6 +1031,7 @@ export type ResponseStreamEvent<TEvent = unknown, TResult = unknown> =
   | ToolPreliminaryResultEvent<TEvent>
   | ToolResultEvent<TResult, TEvent>
   | ToolCallOutputEvent
+  | ToolUiFragmentEvent
   | TurnStartEvent
   | TurnEndEvent;
 
@@ -1023,6 +1060,13 @@ export function isToolCallOutputEvent(event: ResponseStreamEvent): event is Tool
   return event.type === 'tool.call_output';
 }
 
+/**
+ * Type guard to check if an event is a tool UI fragment event
+ */
+export function isToolUiFragmentEvent(event: ResponseStreamEvent): event is ToolUiFragmentEvent {
+  return event.type === 'tool.ui_fragment';
+}
+
 /**
  * Type guard to check if an event is a turn start event
  */
diff --git a/packages/agent/src/lib/tool.ts b/packages/agent/src/lib/tool.ts
index 911667e9..72a76cf9 100644
--- a/packages/agent/src/lib/tool.ts
+++ b/packages/agent/src/lib/tool.ts
@@ -15,6 +15,7 @@ import type {
   ToolLoopKey,
   ToolWithExecute,
   ToolWithGenerator,
+  ToUIOutputFunction,
 } from './tool-types.js';
 import { isClientTool, SHARED_CONTEXT_KEY, ToolType } from './tool-types.js';
 
@@ -48,6 +49,8 @@ type RegularToolConfigWithOutput<
   ) => Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 };
 
 /**
@@ -76,6 +79,8 @@ type RegularToolConfigWithoutOutput<
   ) => Promise<TReturn> | TReturn;
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, TReturn>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, TReturn>;
 };
 
 /**
@@ -105,6 +110,8 @@ type GeneratorToolConfig<
   ) => AsyncGenerator<zodInfer<TEvent> | zodInfer<TOutput>>;
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 };
 
 /**
@@ -171,6 +178,8 @@ type HITLToolConfig<
   ) => Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 };
 
 /**
@@ -203,6 +212,8 @@ type ToolConfigWithSharedContext<
     | false;
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<Record<string, unknown>, unknown>;
+  /** Convert tool execution output to a renderable OpenUI fragment */
+  toUIOutput?: ToUIOutputFunction<Record<string, unknown>, unknown>;
 };
 
 //#endregion
@@ -379,6 +390,10 @@ export function tool(
       fn.toModelOutput = config.toModelOutput;
     }
 
+    if (config.toUIOutput !== undefined) {
+      fn.toUIOutput = config.toUIOutput;
+    }
+
     return {
       type: ToolType.Function,
       function: fn,
@@ -464,6 +479,10 @@ export function tool(
       fn.toModelOutput = config.toModelOutput;
     }
 
+    if ('toUIOutput' in config && config.toUIOutput !== undefined) {
+      fn.toUIOutput = config.toUIOutput;
+    }
+
     return {
       type: ToolType.Function,
       function: fn,
@@ -497,6 +516,10 @@ export function tool(
       config.toModelOutput !== undefined && {
         toModelOutput: config.toModelOutput,
       }),
+    ...('toUIOutput' in config &&
+      config.toUIOutput !== undefined && {
+        toUIOutput: config.toUIOutput,
+      }),
   };
 
   return {
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
new file mode 100644
index 00000000..a13ea237
--- /dev/null
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -0,0 +1,489 @@
+/**
+ * Tests for the OpenUI streaming half: toUIOutput plumbing through tool(),
+ * the tool.ui_fragment broadcast, translateUiEvent (including the SDK's
+ * forward-compat Unknown encoding of response.openui.* wire events), and
+ * getUiStream()'s no-tools fast path.
+ */
+import type { OpenRouterCore } from '@openrouter/sdk/core';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod/v4';
+import { ModelResult } from '../../src/lib/model-result.js';
+import { fragment } from '../../src/lib/openui/fragment.js';
+import { createLibrary, defineComponent } from '../../src/lib/openui/library.js';
+import { translateUiEvent } from '../../src/lib/openui/ui-stream.js';
+import { ReusableReadableStream } from '../../src/lib/reusable-stream.js';
+import { tool } from '../../src/lib/tool.js';
+import type { ParsedToolCall, Tool } from '../../src/lib/tool-types.js';
+import { isToolUiFragmentEvent } from '../../src/lib/tool-types.js';
+
+const library = createLibrary([
+  defineComponent({
+    name: 'Card',
+    props: z.object({
+      title: z.string(),
+    }),
+  }),
+  defineComponent({
+    name: 'Text',
+    props: z.object({
+      value: z.string(),
+    }),
+  }),
+]);
+const ui = fragment(library);
+
+describe('tool() carries toUIOutput', () => {
+  it('regular tool', () => {
+    const t = tool({
+      name: 'usage',
+      inputSchema: z.object({
+        days: z.number(),
+      }),
+      execute: async () => ({
+        total: 12,
+      }),
+      toUIOutput: ({ output }) => ui.Card(`$${output.total}`),
+    });
+    expect(t.function.toUIOutput).toBeTypeOf('function');
+  });
+
+  it('generator tool', () => {
+    const t = tool({
+      name: 'gen',
+      inputSchema: z.object({}),
+      eventSchema: z.object({
+        status: z.string(),
+      }),
+      outputSchema: z.object({
+        done: z.boolean(),
+      }),
+      execute: async function* () {
+        yield {
+          done: true,
+        };
+      },
+      toUIOutput: () => ui.Text('done'),
+    });
+    expect(t.function.toUIOutput).toBeTypeOf('function');
+  });
+
+  it('HITL tool', () => {
+    const t = tool({
+      name: 'hitl',
+      inputSchema: z.object({}),
+      outputSchema: z.object({
+        ok: z.boolean(),
+      }),
+      onToolCalled: () => null,
+      toUIOutput: () => ui.Text('pending'),
+    });
+    expect(t.function.toUIOutput).toBeTypeOf('function');
+  });
+
+  it('omitted stays absent', () => {
+    const t = tool({
+      name: 'plain',
+      inputSchema: z.object({}),
+      execute: async () => 'ok',
+    });
+    expect('toUIOutput' in t.function && t.function.toUIOutput !== undefined).toBe(false);
+  });
+});
+
+describe('translateUiEvent', () => {
+  it('translates tool.ui_fragment synthetic events', () => {
+    const event = translateUiEvent({
+      type: 'tool.ui_fragment',
+      toolCallId: 'c1',
+      toolName: 'usage',
+      fragment: {
+        dialect: 'openui-lang/0.5',
+        source: 'root = Card("hi")',
+      },
+      timestamp: 1,
+    });
+    expect(event).toEqual({
+      type: 'fragment',
+      toolCallId: 'c1',
+      toolName: 'usage',
+      dialect: 'openui-lang/0.5',
+      source: 'root = Card("hi")',
+    });
+  });
+
+  it('translates response.openui.statement wire events', () => {
+    const event = translateUiEvent({
+      type: 'response.openui.statement',
+      ref: 'root',
+      kind: 'component',
+      source: 'root = Card("Usage")',
+    });
+    expect(event).toEqual({
+      type: 'statement',
+      ref: 'root',
+      kind: 'component',
+      source: 'root = Card("Usage")',
+    });
+  });
+
+  it("unwraps the SDK's Unknown forward-compat encoding", () => {
+    const event = translateUiEvent({
+      type: 'UNKNOWN',
+      isUnknown: true,
+      raw: {
+        type: 'response.openui.statement',
+        ref: '$tab',
+        kind: 'state',
+        source: '$tab = "overview"',
+      },
+    });
+    expect(event).toEqual({
+      type: 'statement',
+      ref: '$tab',
+      kind: 'state',
+      source: '$tab = "overview"',
+    });
+  });
+
+  it('translates response.openui.fragment with snake_case call_id', () => {
+    const event = translateUiEvent({
+      type: 'response.openui.fragment',
+      call_id: 'srv_1',
+      dialect: 'openui-lang/0.5',
+      source: 'root = Text("x")',
+    });
+    expect(event).toEqual({
+      type: 'fragment',
+      toolCallId: 'srv_1',
+      dialect: 'openui-lang/0.5',
+      source: 'root = Text("x")',
+    });
+  });
+
+  it('translates response.openui.document with diagnostics', () => {
+    const event = translateUiEvent({
+      type: 'response.openui.document',
+      root: 'root',
+      dialect: 'openui-lang/0.5',
+      diagnostics: [
+        {
+          line: 3,
+          message: 'prose line',
+          source: 'Here is your UI:',
+        },
+        {
+          message: 'no line',
+        },
+        'garbage',
+      ],
+    });
+    expect(event).toEqual({
+      type: 'document',
+      root: 'root',
+      dialect: 'openui-lang/0.5',
+      diagnostics: [
+        {
+          line: 3,
+          message: 'prose line',
+          source: 'Here is your UI:',
+        },
+        {
+          message: 'no line',
+        },
+      ],
+    });
+  });
+
+  it('returns null for everything else', () => {
+    expect(
+      translateUiEvent({
+        type: 'response.output_text.delta',
+        delta: 'hi',
+      }),
+    ).toBeNull();
+    expect(
+      translateUiEvent({
+        type: 'turn.start',
+        turnNumber: 0,
+        timestamp: 1,
+      }),
+    ).toBeNull();
+    expect(translateUiEvent(null)).toBeNull();
+    expect(translateUiEvent('text')).toBeNull();
+    // Malformed payloads degrade to null, never throw.
+    expect(
+      translateUiEvent({
+        type: 'response.openui.statement',
+        ref: 'r',
+      }),
+    ).toBeNull();
+    expect(
+      translateUiEvent({
+        type: 'tool.ui_fragment',
+        fragment: 'not-an-object',
+      }),
+    ).toBeNull();
+  });
+});
+
+describe('getUiStream (no-tools fast path)', () => {
+  function makeModelResult(events: unknown[]): ModelResult<readonly Tool[]> {
+    const modelResult = new ModelResult<readonly Tool[]>({
+      request: {
+        model: 'test-model',
+        input: 'test',
+      },
+      client: {} as OpenRouterCore,
+    });
+    const readable = new ReadableStream({
+      start(controller) {
+        for (const event of events) {
+          controller.enqueue(event);
+        }
+        controller.close();
+      },
+    });
+    const internal = modelResult as unknown as Record<string, unknown>;
+    internal['reusableStream'] = new ReusableReadableStream(readable);
+    internal['initPromise'] = Promise.resolve();
+    return modelResult;
+  }
+
+  it('yields only UI events, in order, from a mixed stream', async () => {
+    const modelResult = makeModelResult([
+      {
+        type: 'response.output_text.delta',
+        delta: 'Here ',
+      },
+      {
+        type: 'UNKNOWN',
+        isUnknown: true,
+        raw: {
+          type: 'response.openui.statement',
+          ref: 'a',
+          kind: 'component',
+          source: 'a = Text("1")',
+        },
+      },
+      {
+        type: 'response.output_text.delta',
+        delta: 'you go',
+      },
+      {
+        type: 'UNKNOWN',
+        isUnknown: true,
+        raw: {
+          type: 'response.openui.document',
+          root: 'a',
+          dialect: 'openui-lang/0.5',
+          diagnostics: [],
+        },
+      },
+      {
+        type: 'response.completed',
+        response: {
+          id: 'r1',
+        },
+      },
+    ]);
+
+    const events = [];
+    for await (const event of modelResult.getUiStream()) {
+      events.push(event);
+    }
+    expect(events).toEqual([
+      {
+        type: 'statement',
+        ref: 'a',
+        kind: 'component',
+        source: 'a = Text("1")',
+      },
+      {
+        type: 'document',
+        root: 'a',
+        dialect: 'openui-lang/0.5',
+        diagnostics: [],
+      },
+    ]);
+  });
+
+  it('yields nothing for a stream with no UI events', async () => {
+    const modelResult = makeModelResult([
+      {
+        type: 'response.output_text.delta',
+        delta: 'plain text',
+      },
+      {
+        type: 'response.completed',
+        response: {
+          id: 'r1',
+        },
+      },
+    ]);
+    const events = [];
+    for await (const event of modelResult.getUiStream()) {
+      events.push(event);
+    }
+    expect(events).toEqual([]);
+  });
+});
+
+describe('broadcastUiFragment', () => {
+  type Internal = {
+    turnBroadcaster: {
+      push: (event: unknown) => void;
+    } | null;
+    broadcastUiFragment: (value: {
+      toolCall: ParsedToolCall<Tool>;
+      tool: Tool;
+      result: {
+        result: unknown;
+        error?: Error;
+      };
+    }) => Promise<void>;
+  };
+
+  function makeHarness() {
+    const pushed: unknown[] = [];
+    const modelResult = new ModelResult<readonly Tool[]>({
+      request: {
+        model: 'test-model',
+        input: 'test',
+      },
+      client: {} as OpenRouterCore,
+    });
+    const internal = modelResult as unknown as Internal;
+    internal.turnBroadcaster = {
+      push: (event: unknown) => {
+        pushed.push(event);
+      },
+    };
+    return {
+      internal,
+      pushed,
+    };
+  }
+
+  function makeCall(
+    t: Tool,
+    result: {
+      result: unknown;
+      error?: Error;
+    },
+  ) {
+    return {
+      toolCall: {
+        id: 'c1',
+        name: t.type === 'function' ? t.function.name : 'server',
+        arguments: {
+          days: 7,
+        },
+      } as unknown as ParsedToolCall<Tool>,
+      tool: t,
+      result,
+    };
+  }
+
+  it('pushes a tool.ui_fragment event for a successful execution', async () => {
+    const { internal, pushed } = makeHarness();
+    const t = tool({
+      name: 'usage',
+      inputSchema: z.object({
+        days: z.number(),
+      }),
+      execute: async () => ({
+        total: 12,
+      }),
+      toUIOutput: ({ output, input }) => ui.Card(`$${output.total} over ${input.days}d`),
+    });
+
+    await internal.broadcastUiFragment(
+      makeCall(t, {
+        result: {
+          total: 12,
+        },
+      }),
+    );
+
+    expect(pushed).toHaveLength(1);
+    const event = pushed[0];
+    expect(isToolUiFragmentEvent(event as never)).toBe(true);
+    expect(event).toMatchObject({
+      type: 'tool.ui_fragment',
+      toolCallId: 'c1',
+      toolName: 'usage',
+      fragment: {
+        dialect: 'openui-lang/0.5',
+        source: 'root = Card("$12 over 7d")',
+      },
+    });
+  });
+
+  it('skips tools without toUIOutput and errored executions', async () => {
+    const { internal, pushed } = makeHarness();
+    const plain = tool({
+      name: 'plain',
+      inputSchema: z.object({
+        days: z.number(),
+      }),
+      execute: async () => 'ok',
+    });
+    await internal.broadcastUiFragment(
+      makeCall(plain, {
+        result: 'ok',
+      }),
+    );
+
+    const withUi = tool({
+      name: 'ui_tool',
+      inputSchema: z.object({
+        days: z.number(),
+      }),
+      execute: async () => 'ok',
+      toUIOutput: () => ui.Text('never'),
+    });
+    await internal.broadcastUiFragment(
+      makeCall(withUi, {
+        result: undefined,
+        error: new Error('boom'),
+      }),
+    );
+
+    expect(pushed).toEqual([]);
+  });
+
+  it('drops the fragment when toUIOutput returns null or throws', async () => {
+    const { internal, pushed } = makeHarness();
+    const nullTool = tool({
+      name: 'null_ui',
+      inputSchema: z.object({
+        days: z.number(),
+      }),
+      execute: async () => 'ok',
+      toUIOutput: () => null,
+    });
+    await internal.broadcastUiFragment(
+      makeCall(nullTool, {
+        result: 'ok',
+      }),
+    );
+
+    const throwingTool = tool({
+      name: 'throwing_ui',
+      inputSchema: z.object({
+        days: z.number(),
+      }),
+      execute: async () => 'ok',
+      toUIOutput: () => {
+        throw new Error('render bug');
+      },
+    });
+    await internal.broadcastUiFragment(
+      makeCall(throwingTool, {
+        result: 'ok',
+      }),
+    );
+
+    expect(pushed).toEqual([]);
+  });
+});

From 978cab95f497ed369daae9d6a5691c535c0ac508 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Fri, 31 Jul 2026 16:23:50 -0500
Subject: [PATCH 03/19] feat(playground): OpenUI test/bench/eval webapp
 (DEV-773)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New private package @openrouter/openui-playground: a local webapp for
testing, benching, and evaluating OpenUI generative-UI support.

- Progressive renderer over the demo component library (Stack/Card/
  Heading/Text/Stat/Badge/Table/Input/Select/Button/Progress) — UI
  materializes statement-by-statement mid-stream
- Two modes with identical event shapes: emulate (local library prompt +
  reference streaming parser over the text stream — works today) and
  native (openui() plugin + getUiStream() — flips on when DEV-771/772
  land), so the paths can be A/B'd from the history table
- Bench stats per run: TTFB, first-statement latency, total time,
  statement/diagnostic counts, token usage, cost; session history for
  comparing models and prompts
- Reference incremental OpenUI Lang parser (the same logic DEV-770
  ports into openrouter-web) with 11 conformance tests
- Plain node:http + static client; no build step

Verified end-to-end against live models: single-card and 12-statement
dashboard prompts parse clean (0 diagnostics) and render progressively.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/openui-playground/README.md          |  46 ++
 packages/openui-playground/package.json       |  26 +
 packages/openui-playground/public/app.js      | 576 ++++++++++++++++++
 packages/openui-playground/public/index.html  | 149 +++++
 .../openui-playground/src/demo-library.ts     | 124 ++++
 packages/openui-playground/src/generate.ts    | 278 +++++++++
 packages/openui-playground/src/lang/parser.ts | 551 +++++++++++++++++
 packages/openui-playground/src/lang/prompt.ts |  69 +++
 packages/openui-playground/src/server.ts      | 192 ++++++
 .../openui-playground/tests/parser.test.ts    | 170 ++++++
 packages/openui-playground/tsconfig.json      |   9 +
 packages/openui-playground/vitest.config.ts   |   7 +
 pnpm-lock.yaml                                | 318 +++++++++-
 13 files changed, 2507 insertions(+), 8 deletions(-)
 create mode 100644 packages/openui-playground/README.md
 create mode 100644 packages/openui-playground/package.json
 create mode 100644 packages/openui-playground/public/app.js
 create mode 100644 packages/openui-playground/public/index.html
 create mode 100644 packages/openui-playground/src/demo-library.ts
 create mode 100644 packages/openui-playground/src/generate.ts
 create mode 100644 packages/openui-playground/src/lang/parser.ts
 create mode 100644 packages/openui-playground/src/lang/prompt.ts
 create mode 100644 packages/openui-playground/src/server.ts
 create mode 100644 packages/openui-playground/tests/parser.test.ts
 create mode 100644 packages/openui-playground/tsconfig.json
 create mode 100644 packages/openui-playground/vitest.config.ts

diff --git a/packages/openui-playground/README.md b/packages/openui-playground/README.md
new file mode 100644
index 00000000..c96d651d
--- /dev/null
+++ b/packages/openui-playground/README.md
@@ -0,0 +1,46 @@
+# @openrouter/openui-playground
+
+Local webapp to **test, bench, and eval** OpenUI generative-UI support in the
+Agent SDK (DEV-773 / DEV-765).
+
+```bash
+OPENROUTER_API_KEY=sk-... pnpm --filter @openrouter/openui-playground dev
+# → http://localhost:5170
+```
+
+## What it does
+
+- Sends your prompt to a model via `callModel()` with the demo component
+  library (Stack/Card/Heading/Text/Stat/Badge/Table/Input/Select/Button/Progress).
+- **Progressively renders** the generated UI as OpenUI Lang statements complete
+  — statement by statement, mid-stream.
+- Shows the raw model text, the parsed OpenUI Lang stream, parse/validation
+  diagnostics, and per-run bench stats (TTFB, first-statement latency, total
+  time, statement count, token usage, cost) with a session history table for
+  comparing models and prompts.
+
+## Modes
+
+| Mode | What happens | Status |
+|---|---|---|
+| `emulate` (default) | The playground injects the library prompt locally and runs the reference streaming parser over the model's text stream — emulating what the API's `openui` plugin will do server-side (DEV-771). | Works today |
+| `native` | Sends the `openui(library)` plugin preference and consumes `ModelResult.getUiStream()`. | Blocked on DEV-771/DEV-772; the API rejects the unknown plugin id until then |
+
+The two modes emit the same event shapes, so once native lands you can A/B the
+paths in the history table with zero client changes.
+
+## Env
+
+- `OPENROUTER_API_KEY` (required)
+- `PORT` (default `5170`)
+- `OPENUI_PLAYGROUND_MODEL` (default `anthropic/claude-sonnet-5`)
+
+## Layout
+
+- `src/lang/parser.ts` — reference incremental OpenUI Lang parser (the same
+  logic DEV-770 ports into openrouter-web; conformance tests in `tests/`)
+- `src/lang/prompt.ts` — library → system prompt (mirror of the API's injection)
+- `src/demo-library.ts` — the component vocabulary (keep `public/app.js` renderer in sync)
+- `src/generate.ts` — one generation run → normalized SSE event stream + stats
+- `src/server.ts` — plain `node:http` server; no build step
+- `public/` — static client: progressive renderer, Lang stream, bench panels
diff --git a/packages/openui-playground/package.json b/packages/openui-playground/package.json
new file mode 100644
index 00000000..5df05291
--- /dev/null
+++ b/packages/openui-playground/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@openrouter/openui-playground",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Local playground to test, bench, and eval OpenUI generative-UI support in the Agent SDK (DEV-773/DEV-765).",
+  "type": "module",
+  "scripts": {
+    "lint": "biome check src tests public",
+    "lint:fix": "biome check --write src tests public",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "dev": "tsx watch src/server.ts",
+    "start": "tsx src/server.ts"
+  },
+  "dependencies": {
+    "@openrouter/agent": "workspace:*",
+    "@openrouter/sdk": "^0.13.7",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "~5.8.3",
+    "vitest": "^4.1.5"
+  }
+}
diff --git a/packages/openui-playground/public/app.js b/packages/openui-playground/public/app.js
new file mode 100644
index 00000000..c76d3496
--- /dev/null
+++ b/packages/openui-playground/public/app.js
@@ -0,0 +1,576 @@
+/**
+ * OpenUI playground client: posts a prompt to /api/generate, consumes the SSE
+ * stream, and progressively renders the generated document.
+ *
+ * The renderer implements the demo library (see src/demo-library.ts — keep in
+ * sync). Statements arrive with their parsed expression tree attached, so the
+ * client resolves refs/state and materializes DOM without its own parser.
+ */
+
+const $ = (id) => document.getElementById(id);
+
+const PRESETS = [
+  [
+    'Dashboard',
+    'Show a dashboard for this month: $128.40 spend (+12%), 41,203 requests, 9 models. Table of top 3 models by spend, budget progress at 64%.',
+  ],
+  [
+    'Form',
+    'Build a support-ticket form: severity select (low/medium/high), a title input, and a submit button.',
+  ],
+  [
+    'Status page',
+    'A status page: API operational (success badge), Dashboard degraded (warning badge), a table of the last 3 incidents with dates.',
+  ],
+  [
+    'Re-render',
+    'Show a counter card with value 1. Then update the same card to value 2, then 3, by re-assigning the same refs.',
+  ],
+  [
+    'Adversarial',
+    'Explain what OpenUI is in prose, and ALSO show a card titled "OpenUI" with a one-line description. (The prose should become diagnostics, not break rendering.)',
+  ],
+];
+
+// ---------------------------------------------------------------------------
+// Document state: ordered refs → assignment (mirrors UiDocument semantics)
+// ---------------------------------------------------------------------------
+
+const doc = {
+  order: [],
+  assignments: new Map(),
+  stateVars: new Map(),
+};
+
+function resetDoc() {
+  doc.order.length = 0;
+  doc.assignments.clear();
+  doc.stateVars.clear();
+}
+
+function applyStatement(stmt) {
+  if (stmt.ref.startsWith('$')) {
+    doc.stateVars.set(stmt.ref.slice(1), stmt.expr ? literalOf(stmt.expr) : null);
+  }
+  if (doc.assignments.has(stmt.ref)) {
+    doc.order.splice(doc.order.indexOf(stmt.ref), 1);
+  }
+  doc.assignments.set(stmt.ref, stmt);
+  doc.order.push(stmt.ref);
+}
+
+function literalOf(expr) {
+  return expr && expr.kind === 'literal' ? expr.value : null;
+}
+
+// ---------------------------------------------------------------------------
+// Expression → value / DOM
+// ---------------------------------------------------------------------------
+
+function evalExpr(expr, depth = 0) {
+  if (!expr || depth > 32) {
+    return null;
+  }
+  switch (expr.kind) {
+    case 'literal':
+      return expr.value;
+    case 'array':
+      return expr.items.map((e) => evalExpr(e, depth + 1));
+    case 'object': {
+      const out = {};
+      for (const { key, value } of expr.entries) {
+        out[key] = evalExpr(value, depth + 1);
+      }
+      return out;
+    }
+    case 'state-ref':
+      return doc.stateVars.get(expr.name) ?? null;
+    case 'ref': {
+      const target = doc.assignments.get(expr.name);
+      return target ? evalExpr(target.expr, depth + 1) : null;
+    }
+    case 'member': {
+      let base = evalExpr(expr.base, depth + 1);
+      for (const key of expr.path) {
+        base = base !== null ? base[key] : null;
+      }
+      return base;
+    }
+    case 'call':
+      return expr; // calls materialize as DOM, not values
+    default:
+      return null;
+  }
+}
+
+function renderExpr(expr, depth = 0) {
+  if (!expr || depth > 32) {
+    return null;
+  }
+  if (expr.kind === 'ref') {
+    const target = doc.assignments.get(expr.name);
+    return target ? renderExpr(target.expr, depth + 1) : textNode(`⟨${expr.name}?⟩`, 'ui-unknown');
+  }
+  if (expr.kind === 'state-ref') {
+    return textNode(String(doc.stateVars.get(expr.name) ?? ''), 'ui-text');
+  }
+  if (expr.kind === 'array') {
+    const frag = document.createDocumentFragment();
+    for (const item of expr.items) {
+      const node = renderExpr(item, depth + 1);
+      if (node) {
+        frag.appendChild(node);
+      }
+    }
+    return frag;
+  }
+  if (expr.kind === 'literal') {
+    return textNode(String(expr.value ?? ''), 'ui-text');
+  }
+  if (expr.kind === 'call') {
+    return renderCall(expr, depth);
+  }
+  return null;
+}
+
+function textNode(text, cls) {
+  const el = document.createElement('div');
+  el.className = cls;
+  el.textContent = text;
+  return el;
+}
+
+function el(tag, cls, children) {
+  const node = document.createElement(tag);
+  if (cls) {
+    node.className = cls;
+  }
+  for (const child of children ?? []) {
+    if (child) {
+      node.appendChild(child);
+    }
+  }
+  return node;
+}
+
+/** Positional args → named props using the component's signature. */
+const SIGNATURES = {
+  Stack: [
+    'children',
+    'direction',
+    'gap',
+  ],
+  Card: [
+    'title',
+    'children',
+  ],
+  Heading: [
+    'text',
+    'level',
+  ],
+  Text: [
+    'value',
+    'muted',
+  ],
+  Stat: [
+    'label',
+    'value',
+    'delta',
+  ],
+  Badge: [
+    'text',
+    'tone',
+  ],
+  Table: [
+    'columns',
+    'rows',
+  ],
+  Input: [
+    'name',
+    'value',
+    'placeholder',
+  ],
+  Select: [
+    'name',
+    'options',
+    'value',
+  ],
+  Button: [
+    'label',
+    'action',
+    'variant',
+  ],
+  Progress: [
+    'value',
+    'label',
+  ],
+};
+
+function propsOf(call) {
+  const names = SIGNATURES[call.fn] ?? [];
+  const props = {};
+  call.args.forEach((arg, i) => {
+    const name = names[i] ?? `arg${i}`;
+    props[name] = arg;
+  });
+  return props;
+}
+
+function renderCall(call, depth) {
+  if (call.builtin) {
+    return null; // @Run/@Set/... are action steps, not DOM
+  }
+  const p = propsOf(call);
+  const val = (name, fallback) => {
+    const v = p[name] !== undefined ? evalExpr(p[name], depth + 1) : undefined;
+    return v === undefined || v === null || (v && v.kind === 'call') ? fallback : v;
+  };
+  const children = (name) => (p[name] ? renderExpr(p[name], depth + 1) : null);
+
+  switch (call.fn) {
+    case 'Stack': {
+      const node = el('div', `ui-stack${val('direction', 'column') === 'row' ? ' row' : ''}`, [
+        children('children'),
+      ]);
+      const gap = val('gap', null);
+      if (typeof gap === 'number') {
+        node.style.gap = `${gap}px`;
+      }
+      return node;
+    }
+    case 'Card': {
+      const kids = [];
+      const title = val('title', null);
+      const titleIsText = typeof title === 'string';
+      if (titleIsText) {
+        kids.push(textNode(title, 'title'));
+      }
+      // Card("x", [...]) puts children second; Card([...]) puts them first.
+      const body = titleIsText ? children('children') : (children('title') ?? children('children'));
+      if (body) {
+        kids.push(body);
+      }
+      return el('div', 'ui-card', kids);
+    }
+    case 'Heading': {
+      const level = Math.min(3, Math.max(1, val('level', 2)));
+      return textNode(String(val('text', '')), `ui-heading${level}`);
+    }
+    case 'Text':
+      return textNode(String(val('value', '')), `ui-text${val('muted', false) ? ' muted' : ''}`);
+    case 'Stat': {
+      const kids = [
+        textNode(String(val('value', '')), 'v'),
+        textNode(String(val('label', '')), 'l'),
+      ];
+      const delta = val('delta', null);
+      if (delta) {
+        kids.push(textNode(String(delta), 'd'));
+      }
+      return el('div', 'ui-stat', kids);
+    }
+    case 'Badge':
+      return textNode(String(val('text', '')), `ui-badge ${val('tone', 'neutral')}`);
+    case 'Table': {
+      const columns = val('columns', []);
+      const rows = val('rows', []);
+      const table = document.createElement('table');
+      table.className = 'ui-table';
+      if (Array.isArray(columns)) {
+        const tr = document.createElement('tr');
+        for (const c of columns) {
+          tr.appendChild(
+            el('th', null, [
+              document.createTextNode(String(c)),
+            ]),
+          );
+        }
+        table.appendChild(tr);
+      }
+      if (Array.isArray(rows)) {
+        for (const row of rows) {
+          const tr = document.createElement('tr');
+          for (const cell of Array.isArray(row)
+            ? row
+            : [
+                row,
+              ]) {
+            tr.appendChild(
+              el('td', null, [
+                document.createTextNode(String(cell)),
+              ]),
+            );
+          }
+          table.appendChild(tr);
+        }
+      }
+      return table;
+    }
+    case 'Input': {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.className = 'ui-input';
+      input.placeholder = String(val('placeholder', ''));
+      const v = val('value', '');
+      if (v) {
+        input.value = String(v);
+      }
+      return input;
+    }
+    case 'Select': {
+      const select = document.createElement('select');
+      select.className = 'ui-select';
+      for (const opt of val('options', [])) {
+        const o = document.createElement('option');
+        o.textContent = String(opt);
+        select.appendChild(o);
+      }
+      return select;
+    }
+    case 'Button': {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = `ui-button ${val('variant', 'secondary')}`;
+      btn.textContent = String(val('label', 'Button'));
+      btn.addEventListener('click', () =>
+        setStatus('action fired (client event ingestion is Phase 3 — DEV-774)'),
+      );
+      return btn;
+    }
+    case 'Progress': {
+      const value = Math.min(100, Math.max(0, Number(val('value', 0))));
+      const bar = el('div', 'ui-progress', [
+        el('div'),
+      ]);
+      bar.firstChild.style.width = `${value}%`;
+      const label = val('label', null);
+      return label
+        ? el('div', null, [
+            textNode(String(label), 'ui-text muted'),
+            bar,
+          ])
+        : bar;
+    }
+    case 'Query':
+    case 'Mutation':
+    case 'Action':
+    case 'ToolView':
+      return null; // data/action bindings — no direct DOM in the playground yet
+    default:
+      return textNode(`⟨unknown component ${call.fn}⟩`, 'ui-unknown');
+  }
+}
+
+function renderSurface() {
+  const surface = $('surface');
+  surface.replaceChildren();
+  const rootStmt = doc.assignments.get('root');
+  if (!rootStmt) {
+    // No root yet: render every component statement in order (progressive view).
+    const stack = el('div', 'ui-stack');
+    for (const ref of doc.order) {
+      const stmt = doc.assignments.get(ref);
+      if (stmt && stmt.kind === 'component') {
+        const node = renderExpr(stmt.expr);
+        if (node) {
+          stack.appendChild(node);
+        }
+      }
+    }
+    surface.appendChild(
+      stack.childNodes.length
+        ? stack
+        : el('div', 'placeholder', [
+            document.createTextNode('Waiting for statements…'),
+          ]),
+    );
+    return;
+  }
+  const node = renderExpr(rootStmt.expr);
+  surface.appendChild(
+    node ??
+      el('div', 'placeholder', [
+        document.createTextNode('Root did not render.'),
+      ]),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Stats + history
+// ---------------------------------------------------------------------------
+
+const history = [];
+
+function statTile(label, value) {
+  return `<div class="stat-tile"><div class="v">${value}</div><div class="l">${label}</div></div>`;
+}
+
+function renderStats(s) {
+  const fmt = (v, suffix = '') => (v === null || v === undefined ? '—' : `${v}${suffix}`);
+  $('stats').innerHTML = [
+    statTile('TTFB', fmt(s.ttfbMs, 'ms')),
+    statTile('1st stmt', fmt(s.firstStatementMs, 'ms')),
+    statTile('total', fmt(s.totalMs, 'ms')),
+    statTile('statements', fmt(s.statements)),
+    statTile('diagnostics', fmt(s.diagnostics)),
+    statTile('out tokens', fmt(s.outputTokens)),
+  ].join('');
+}
+
+function renderHistory() {
+  if (!history.length) {
+    return;
+  }
+  const rows = history
+    .map(
+      (h) =>
+        `<tr><td>${h.model} · ${h.mode}</td><td>${h.ttfbMs ?? '—'}</td><td>${h.firstStatementMs ?? '—'}</td><td>${h.totalMs}</td><td>${h.statements}</td><td>${h.diagnostics}</td><td>${h.outputTokens ?? '—'}</td><td>${h.cost !== null ? `$${h.cost.toFixed(5)}` : '—'}</td></tr>`,
+    )
+    .join('');
+  $('history').innerHTML =
+    `<table><tr><th>run</th><th>ttfb</th><th>1st</th><th>total</th><th>stmts</th><th>diag</th><th>tok</th><th>cost</th></tr>${rows}</table>`;
+}
+
+function setStatus(text, isError = false) {
+  const status = $('status');
+  status.textContent = text;
+  status.className = isError ? 'dialect err' : 'dialect';
+}
+
+// ---------------------------------------------------------------------------
+// Wiring
+// ---------------------------------------------------------------------------
+
+async function boot() {
+  const meta = await (await fetch('/api/library')).json();
+  $('dialect').textContent = `${meta.dialect} · ${meta.components.length} components`;
+  $('libprompt').textContent = meta.prompt;
+  $('model').value = meta.defaultModel;
+  for (const [name, prompt] of PRESETS) {
+    const b = document.createElement('button');
+    b.type = 'button';
+    b.textContent = name;
+    b.addEventListener('click', () => {
+      $('prompt').value = prompt;
+    });
+    $('presets').appendChild(b);
+  }
+}
+
+async function run() {
+  const runBtn = $('run');
+  runBtn.disabled = true;
+  resetDoc();
+  $('lang').replaceChildren();
+  $('events').textContent = '';
+  $('diagnostics').innerHTML = '<span style="color:var(--muted)">—</span>';
+  $('stats').innerHTML = '';
+  renderSurface();
+  setStatus('generating…');
+
+  const mode = document.querySelector('input[name=mode]:checked').value;
+  const body = {
+    prompt: $('prompt').value,
+    model: $('model').value,
+    mode,
+  };
+
+  try {
+    const res = await fetch('/api/generate', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok || !res.body) {
+      const err = await res.json().catch(() => ({
+        error: res.statusText,
+      }));
+      throw new Error(err.error ?? 'request failed');
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, {
+        stream: true,
+      });
+      let idx = buffer.indexOf('\n\n');
+      while (idx >= 0) {
+        const frame = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        idx = buffer.indexOf('\n\n');
+        if (!frame.startsWith('data: ')) {
+          continue;
+        }
+        const payload = frame.slice(6);
+        if (payload === '[DONE]') {
+          continue;
+        }
+        handleEvent(JSON.parse(payload));
+      }
+    }
+    setStatus('done');
+  } catch (error) {
+    setStatus(String(error.message ?? error), true);
+  } finally {
+    runBtn.disabled = false;
+  }
+}
+
+function handleEvent(event) {
+  switch (event.type) {
+    case 'text':
+      $('events').textContent += event.delta;
+      break;
+    case 'statement': {
+      applyStatement(event);
+      renderSurface();
+      const line = document.createElement('div');
+      line.className = 'stmt';
+      line.textContent = `[${String(event.at).padStart(5)}ms] ${event.source}`;
+      $('lang').appendChild(line);
+      $('lang').scrollTop = $('lang').scrollHeight;
+      break;
+    }
+    case 'fragment': {
+      const line = document.createElement('div');
+      line.className = 'stmt';
+      line.textContent = `[fragment${event.toolCallId ? ` ${event.toolCallId}` : ''}] ${event.source}`;
+      $('lang').appendChild(line);
+      break;
+    }
+    case 'document': {
+      if (event.diagnostics.length) {
+        $('diagnostics').innerHTML = event.diagnostics
+          .map((d) => `<div class="diag">L${d.line}: ${d.message} — ${escapeHtml(d.source)}</div>`)
+          .join('');
+      } else {
+        $('diagnostics').innerHTML =
+          '<span style="color:var(--success)">clean parse — no diagnostics</span>';
+      }
+      break;
+    }
+    case 'stats':
+      renderStats(event);
+      history.unshift(event);
+      renderHistory();
+      break;
+    case 'error':
+      setStatus(event.message, true);
+      break;
+  }
+}
+
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+
+$('run').addEventListener('click', run);
+boot().catch((error) => setStatus(String(error), true));
diff --git a/packages/openui-playground/public/index.html b/packages/openui-playground/public/index.html
new file mode 100644
index 00000000..c05757fe
--- /dev/null
+++ b/packages/openui-playground/public/index.html
@@ -0,0 +1,149 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>OpenUI Playground</title>
+<style>
+  :root {
+    --bg: #0d1117; --panel: #161b22; --border: #30363d; --text: #e6edf3;
+    --muted: #8b949e; --accent: #58a6ff; --success: #3fb950; --warning: #d29922;
+    --danger: #f85149; --mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--text);
+    font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  }
+  header {
+    display: flex; align-items: center; gap: 12px; padding: 10px 16px;
+    border-bottom: 1px solid var(--border); background: var(--panel);
+  }
+  header h1 { font-size: 15px; margin: 0; font-weight: 600; }
+  header .dialect { color: var(--muted); font-family: var(--mono); font-size: 12px; }
+  main { display: grid; grid-template-columns: 340px 1fr 380px; gap: 0; height: calc(100vh - 45px); }
+  .col { overflow-y: auto; padding: 14px; }
+  .col + .col { border-left: 1px solid var(--border); }
+  label { display: block; color: var(--muted); font-size: 12px; margin: 10px 0 4px; }
+  textarea, input[type=text], select {
+    width: 100%; background: var(--bg); color: var(--text); border: 1px solid var(--border);
+    border-radius: 6px; padding: 8px; font: inherit;
+  }
+  textarea { min-height: 90px; resize: vertical; }
+  button.run {
+    margin-top: 12px; width: 100%; padding: 9px; border: 0; border-radius: 6px;
+    background: var(--accent); color: #0d1117; font-weight: 600; cursor: pointer; font-size: 14px;
+  }
+  button.run:disabled { opacity: .5; cursor: wait; }
+  .presets { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 6px; }
+  .presets button {
+    background: var(--bg); border: 1px solid var(--border); color: var(--muted);
+    border-radius: 12px; padding: 3px 10px; font-size: 12px; cursor: pointer;
+  }
+  .presets button:hover { color: var(--text); border-color: var(--accent); }
+  .modes { display: flex; gap: 10px; margin-top: 4px; color: var(--muted); font-size: 13px; }
+
+  /* Rendered surface */
+  #surface { min-height: 200px; }
+  .placeholder { color: var(--muted); text-align: center; margin-top: 80px; }
+  .ui-stack { display: flex; flex-direction: column; gap: 10px; }
+  .ui-stack.row { flex-direction: row; flex-wrap: wrap; align-items: flex-start; }
+  .ui-card { border: 1px solid var(--border); border-radius: 8px; padding: 12px; background: var(--panel); }
+  .ui-card > .title { font-weight: 600; margin-bottom: 8px; }
+  .ui-heading1 { font-size: 22px; font-weight: 700; margin: 4px 0; }
+  .ui-heading2 { font-size: 18px; font-weight: 600; margin: 3px 0; }
+  .ui-heading3 { font-size: 15px; font-weight: 600; margin: 2px 0; }
+  .ui-text { margin: 2px 0; }
+  .ui-text.muted { color: var(--muted); }
+  .ui-stat { display: inline-flex; flex-direction: column; padding: 10px 14px; border: 1px solid var(--border); border-radius: 8px; min-width: 110px; }
+  .ui-stat .v { font-size: 20px; font-weight: 700; }
+  .ui-stat .l { color: var(--muted); font-size: 12px; }
+  .ui-stat .d { font-size: 12px; color: var(--success); }
+  .ui-badge { display: inline-block; padding: 1px 9px; border-radius: 10px; font-size: 12px; border: 1px solid var(--border); }
+  .ui-badge.success { color: var(--success); border-color: var(--success); }
+  .ui-badge.warning { color: var(--warning); border-color: var(--warning); }
+  .ui-badge.danger { color: var(--danger); border-color: var(--danger); }
+  table.ui-table { border-collapse: collapse; width: 100%; }
+  table.ui-table th, table.ui-table td { border: 1px solid var(--border); padding: 5px 9px; text-align: left; font-size: 13px; }
+  table.ui-table th { color: var(--muted); font-weight: 600; }
+  .ui-button { padding: 6px 14px; border-radius: 6px; border: 1px solid var(--border); background: var(--panel); color: var(--text); cursor: pointer; }
+  .ui-button.primary { background: var(--accent); color: #0d1117; border: 0; font-weight: 600; }
+  .ui-button.danger { background: var(--danger); color: #fff; border: 0; }
+  .ui-progress { background: var(--border); border-radius: 6px; height: 10px; overflow: hidden; }
+  .ui-progress > div { background: var(--accent); height: 100%; }
+  .ui-input, .ui-select { width: auto; min-width: 180px; }
+  .ui-unknown { color: var(--danger); font-family: var(--mono); font-size: 12px; }
+
+  /* Right column */
+  h2.pane { font-size: 12px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin: 14px 0 6px; }
+  #lang, #events {
+    font-family: var(--mono); font-size: 12px; white-space: pre-wrap; word-break: break-word;
+    background: var(--bg); border: 1px solid var(--border); border-radius: 6px; padding: 8px;
+    max-height: 220px; overflow-y: auto;
+  }
+  #lang .stmt { color: var(--text); }
+  #lang .prose { color: var(--muted); font-style: italic; }
+  .stats { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 8px; }
+  .stat-tile { border: 1px solid var(--border); border-radius: 6px; padding: 7px 9px; }
+  .stat-tile .v { font-size: 16px; font-weight: 700; font-family: var(--mono); }
+  .stat-tile .l { color: var(--muted); font-size: 11px; }
+  #history { font-size: 12px; }
+  #history table { border-collapse: collapse; width: 100%; }
+  #history td, #history th { border-bottom: 1px solid var(--border); padding: 4px 6px; text-align: right; font-family: var(--mono); }
+  #history th { color: var(--muted); font-weight: 500; }
+  #history td:first-child, #history th:first-child { text-align: left; font-family: inherit; }
+  .diag { color: var(--warning); font-family: var(--mono); font-size: 12px; margin: 2px 0; }
+  .err { color: var(--danger); }
+</style>
+</head>
+<body>
+<header>
+  <h1>OpenUI Playground</h1>
+  <span class="dialect" id="dialect"></span>
+  <span class="dialect" style="margin-left:auto" id="status"></span>
+</header>
+<main>
+  <div class="col">
+    <label for="prompt">Prompt</label>
+    <textarea id="prompt">Show me a dashboard summarizing this month's API usage: total spend $128.40 (up 12%), 41,203 requests, 9 models used. Include a table of the top 3 models by spend and a progress bar showing 64% of the monthly budget used.</textarea>
+    <div class="presets" id="presets"></div>
+    <label for="model">Model</label>
+    <input type="text" id="model" list="model-options" />
+    <datalist id="model-options">
+      <option value="anthropic/claude-sonnet-5"></option>
+      <option value="anthropic/claude-haiku-4.5"></option>
+      <option value="openai/gpt-5.2"></option>
+      <option value="google/gemini-3-flash"></option>
+      <option value="deepseek/deepseek-v4"></option>
+    </datalist>
+    <label>Mode</label>
+    <div class="modes">
+      <label><input type="radio" name="mode" value="emulate" checked /> emulate (local parse)</label>
+      <label><input type="radio" name="mode" value="native" /> native (API plugin)</label>
+    </div>
+    <button type="button" class="run" id="run">Generate UI</button>
+    <h2 class="pane">Library prompt sent to the model</h2>
+    <div id="libprompt" style="font-family:var(--mono);font-size:11px;color:var(--muted);white-space:pre-wrap;"></div>
+  </div>
+
+  <div class="col">
+    <h2 class="pane">Rendered surface</h2>
+    <div id="surface"><div class="placeholder">Run a prompt to render generated UI here.</div></div>
+    <h2 class="pane">Diagnostics</h2>
+    <div id="diagnostics"><span style="color:var(--muted)">—</span></div>
+  </div>
+
+  <div class="col">
+    <h2 class="pane">Run stats</h2>
+    <div class="stats" id="stats"></div>
+    <h2 class="pane">OpenUI Lang stream</h2>
+    <div id="lang"></div>
+    <h2 class="pane">Raw model text</h2>
+    <div id="events"></div>
+    <h2 class="pane">Run history (this session)</h2>
+    <div id="history"></div>
+  </div>
+</main>
+<script type="module" src="/app.js"></script>
+</body>
+</html>
diff --git a/packages/openui-playground/src/demo-library.ts b/packages/openui-playground/src/demo-library.ts
new file mode 100644
index 00000000..e900a2af
--- /dev/null
+++ b/packages/openui-playground/src/demo-library.ts
@@ -0,0 +1,124 @@
+/**
+ * The playground's demo component library — a small but representative
+ * vocabulary (layout, text, data display, inputs, actions) that exercises
+ * positional props, optional props, enums, arrays, and nesting. The client
+ * renderer in public/app.js implements exactly these components; keep the
+ * two in sync.
+ */
+import { createLibrary, defineComponent } from '@openrouter/agent';
+import { z } from 'zod/v4';
+
+export const demoLibrary = createLibrary([
+  defineComponent({
+    name: 'Stack',
+    description: 'Layout container. direction defaults to "column".',
+    props: z.object({
+      children: z.array(z.unknown()),
+      direction: z
+        .enum([
+          'row',
+          'column',
+        ])
+        .optional(),
+      gap: z.number().optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Card',
+    description: 'Bordered container with an optional title.',
+    props: z.object({
+      title: z.string().optional(),
+      children: z.array(z.unknown()).optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Heading',
+    description: 'Section heading. level 1-3, defaults to 2.',
+    props: z.object({
+      text: z.string(),
+      level: z.number().optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Text',
+    description: 'A paragraph of body text.',
+    props: z.object({
+      value: z.string(),
+      muted: z.boolean().optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Stat',
+    description: 'A labeled metric (big value, small label, optional delta like "+12%").',
+    props: z.object({
+      label: z.string(),
+      value: z.string(),
+      delta: z.string().optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Badge',
+    description: 'Small status pill.',
+    props: z.object({
+      text: z.string(),
+      tone: z
+        .enum([
+          'neutral',
+          'success',
+          'warning',
+          'danger',
+        ])
+        .optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Table',
+    description:
+      'Data table. columns is an array of header strings; rows is an array of arrays of cell strings.',
+    props: z.object({
+      columns: z.array(z.string()),
+      rows: z.array(z.array(z.string())),
+    }),
+  }),
+  defineComponent({
+    name: 'Input',
+    description: 'Single-line text input. Pass a $state ref as value to two-way bind.',
+    props: z.object({
+      name: z.string(),
+      value: z.unknown().optional(),
+      placeholder: z.string().optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Select',
+    description: 'Dropdown. Pass a $state ref as value to two-way bind.',
+    props: z.object({
+      name: z.string(),
+      options: z.array(z.string()),
+      value: z.unknown().optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Button',
+    description: 'Action button. action is an Action(...) block.',
+    props: z.object({
+      label: z.string(),
+      action: z.unknown().optional(),
+      variant: z
+        .enum([
+          'primary',
+          'secondary',
+          'danger',
+        ])
+        .optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Progress',
+    description: 'Progress bar, value 0-100.',
+    props: z.object({
+      value: z.number(),
+      label: z.string().optional(),
+    }),
+  }),
+]);
diff --git a/packages/openui-playground/src/generate.ts b/packages/openui-playground/src/generate.ts
new file mode 100644
index 00000000..9fcfab81
--- /dev/null
+++ b/packages/openui-playground/src/generate.ts
@@ -0,0 +1,278 @@
+/**
+ * The playground's generation core: run one OpenUI turn against a model and
+ * emit a normalized event stream the client renders progressively.
+ *
+ * Two modes:
+ * - `emulate` (default) — works today. Injects the library prompt locally and
+ *   runs the streaming parser over the model's text stream, emitting the same
+ *   statement/document events the API's `openui` plugin will emit natively.
+ * - `native` — sends the `openui(library)` plugin preference and consumes
+ *   `getUiStream()`. Useful the moment DEV-771/DEV-772 land; until then the
+ *   API rejects the unknown plugin id.
+ *
+ * Every run also emits bench stats (TTFB, first-statement latency, statement
+ * count, token usage, cost) so the playground doubles as an eval harness.
+ */
+
+import type { UiLibrary } from '@openrouter/agent';
+import { callModel, openui, serializeExpr } from '@openrouter/agent';
+import type { OpenRouterCore } from '@openrouter/sdk/core';
+import type { UiAssignment, UiDocument } from './lang/parser.js';
+import { OpenUiLangParser } from './lang/parser.js';
+import { libraryPrompt } from './lang/prompt.js';
+
+export type GenerateMode = 'emulate' | 'native';
+
+export interface GenerateRequest {
+  prompt: string;
+  model: string;
+  mode?: GenerateMode;
+  /** Optional extra system prompt prepended before the library prompt. */
+  system?: string;
+}
+
+/** Normalized playground stream events (superset of the wire protocol shapes). */
+export type PlaygroundEvent =
+  | {
+      type: 'statement';
+      ref: string;
+      kind: string;
+      source: string;
+      /**
+       * Parsed expression tree (playground extra, not on the wire protocol) —
+       * lets the client render without carrying its own parser. Absent in
+       * native mode until the wire protocol grows one.
+       */
+      expr?: unknown;
+      at: number;
+    }
+  | {
+      type: 'fragment';
+      toolCallId?: string;
+      dialect: string;
+      source: string;
+      at: number;
+    }
+  | {
+      type: 'text';
+      delta: string;
+    }
+  | {
+      type: 'document';
+      root: string | null;
+      dialect: string;
+      statements: number;
+      diagnostics: Array<{
+        line: number;
+        message: string;
+        source: string;
+      }>;
+    }
+  | {
+      type: 'stats';
+      mode: GenerateMode;
+      model: string;
+      ttfbMs: number | null;
+      firstStatementMs: number | null;
+      totalMs: number;
+      statements: number;
+      diagnostics: number;
+      chars: number;
+      inputTokens: number | null;
+      outputTokens: number | null;
+      cost: number | null;
+    }
+  | {
+      type: 'error';
+      message: string;
+    };
+
+interface UsageSummary {
+  inputTokens: number | null;
+  outputTokens: number | null;
+  cost: number | null;
+}
+
+function extractUsage(response: unknown): UsageSummary {
+  const usage =
+    typeof response === 'object' && response !== null
+      ? (
+          response as {
+            usage?: Record<string, unknown>;
+          }
+        ).usage
+      : undefined;
+  const num = (v: unknown): number | null => (typeof v === 'number' ? v : null);
+  return {
+    inputTokens: num(usage?.['inputTokens']),
+    outputTokens: num(usage?.['outputTokens']),
+    cost: num(usage?.['cost']),
+  };
+}
+
+/**
+ * Run one generation and yield playground events as they materialize.
+ */
+export async function* generate(
+  client: OpenRouterCore,
+  library: UiLibrary,
+  request: GenerateRequest,
+): AsyncGenerator<PlaygroundEvent> {
+  const mode: GenerateMode = request.mode ?? 'emulate';
+  const start = Date.now();
+  let ttfbMs: number | null = null;
+  let firstStatementMs: number | null = null;
+  let statements = 0;
+  let chars = 0;
+
+  if (mode === 'native') {
+    // Native path: the API owns prompting + parsing; we consume getUiStream().
+    const result = callModel(client, {
+      model: request.model,
+      input: request.prompt,
+      ...(request.system !== undefined && {
+        instructions: request.system,
+      }),
+      plugins: [
+        openui(library) as never,
+      ],
+    });
+
+    for await (const event of result.getUiStream()) {
+      if (ttfbMs === null) {
+        ttfbMs = Date.now() - start;
+      }
+      if (event.type === 'statement') {
+        if (firstStatementMs === null) {
+          firstStatementMs = Date.now() - start;
+        }
+        statements += 1;
+        chars += event.source.length;
+        yield {
+          ...event,
+          at: Date.now() - start,
+        };
+      } else if (event.type === 'fragment') {
+        yield {
+          ...event,
+          at: Date.now() - start,
+        };
+      } else {
+        yield {
+          type: 'document',
+          root: event.root,
+          dialect: event.dialect,
+          statements,
+          diagnostics: event.diagnostics.map((d) => ({
+            line: d.line ?? 0,
+            message: d.message,
+            source: d.source ?? '',
+          })),
+        };
+      }
+    }
+
+    const usage = extractUsage(await result.getResponse());
+    yield {
+      type: 'stats',
+      mode,
+      model: request.model,
+      ttfbMs,
+      firstStatementMs,
+      totalMs: Date.now() - start,
+      statements,
+      diagnostics: 0,
+      chars,
+      ...usage,
+    };
+    return;
+  }
+
+  // Emulate path: inject the library prompt locally, parse the text stream.
+  const instructions = [
+    request.system,
+    libraryPrompt(library),
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+  const result = callModel(client, {
+    model: request.model,
+    input: request.prompt,
+    instructions,
+  });
+
+  const parser = new OpenUiLangParser(library.dialect);
+  let lastEmittedLine = 0;
+  for await (const delta of result.getTextStream()) {
+    if (ttfbMs === null) {
+      ttfbMs = Date.now() - start;
+    }
+    chars += delta.length;
+    yield {
+      type: 'text',
+      delta,
+    };
+    for (const assignment of parser.push(delta)) {
+      if (firstStatementMs === null) {
+        firstStatementMs = Date.now() - start;
+      }
+      statements += 1;
+      lastEmittedLine = assignment.line;
+      yield {
+        type: 'statement',
+        ref: assignment.ref,
+        kind: assignment.kind,
+        source: serializeStatement(assignment.ref, assignment),
+        expr: assignment.expr,
+        at: Date.now() - start,
+      };
+    }
+  }
+
+  const doc: UiDocument = parser.end();
+  // end() may flush one trailing statement that arrived without a final
+  // newline — emit any assignment parsed past the last line we streamed.
+  for (const ref of doc.order) {
+    const assignment = doc.assignments[ref];
+    if (assignment && assignment.line > lastEmittedLine) {
+      if (firstStatementMs === null) {
+        firstStatementMs = Date.now() - start;
+      }
+      statements += 1;
+      yield {
+        type: 'statement',
+        ref: assignment.ref,
+        kind: assignment.kind,
+        source: serializeStatement(assignment.ref, assignment),
+        expr: assignment.expr,
+        at: Date.now() - start,
+      };
+    }
+  }
+
+  yield {
+    type: 'document',
+    root: doc.root,
+    dialect: doc.dialect,
+    statements: doc.order.length,
+    diagnostics: doc.diagnostics,
+  };
+
+  const usage = extractUsage(await result.getResponse());
+  yield {
+    type: 'stats',
+    mode,
+    model: request.model,
+    ttfbMs,
+    firstStatementMs,
+    totalMs: Date.now() - start,
+    statements,
+    diagnostics: doc.diagnostics.length,
+    chars,
+    ...usage,
+  };
+}
+
+function serializeStatement(ref: string, assignment: UiAssignment): string {
+  return `${ref} = ${serializeExpr(assignment.expr)}`;
+}
diff --git a/packages/openui-playground/src/lang/parser.ts b/packages/openui-playground/src/lang/parser.ts
new file mode 100644
index 00000000..4eb5f1ba
--- /dev/null
+++ b/packages/openui-playground/src/lang/parser.ts
@@ -0,0 +1,551 @@
+/**
+ * Incremental OpenUI Lang parser — playground emulation layer.
+ *
+ * This is the reference streaming parser the API will own once DEV-770/771
+ * land in openrouter-web. The playground carries its own copy so it can
+ * emulate the `openui` plugin end-to-end today: inject the library prompt,
+ * parse the model's text stream, and emit `response.openui.*`-shaped events
+ * — which is exactly what lets us bench/eval renderer behavior and model
+ * output quality before the API path exists.
+ *
+ * The language is line-oriented — one assignment statement per line — so the
+ * parser is a line assembler (bracket- and string-aware, so a statement whose
+ * brackets span lines still parses) feeding a per-statement recursive-descent
+ * expression parser. It is tolerant by design: prose, fences, and unparseable
+ * lines become diagnostics, never throws.
+ */
+import type { UiExpr } from '@openrouter/agent';
+import { OPENUI_LANG_DIALECT, OPENUI_ROOT_REF } from '@openrouter/agent';
+
+/** Classification of one assignment statement. */
+export type UiStatementKind = 'component' | 'query' | 'mutation' | 'state' | 'value';
+
+/** One parsed assignment statement. */
+export interface UiAssignment {
+  /** Assignment target. State declarations keep their `$` prefix (`'$tab'`). */
+  ref: string;
+  kind: UiStatementKind;
+  expr: UiExpr;
+  /** 1-indexed statement line within the turn's output. */
+  line: number;
+}
+
+/** A non-fatal parse problem (unparseable or prose line). */
+export interface UiDiagnostic {
+  line: number;
+  message: string;
+  source: string;
+}
+
+/** The materialized document — the mounted tree plus state and data bindings. */
+export interface UiDocument {
+  dialect: string;
+  /** `'root'` when the document assigned the reserved root ref, else null. */
+  root: string | null;
+  /** Assignments keyed by ref (state refs keyed with their `$` prefix). */
+  assignments: Record<string, UiAssignment>;
+  /** Refs in statement order. Re-assignment moves a ref to the end. */
+  order: string[];
+  diagnostics: UiDiagnostic[];
+}
+
+export function emptyDocument(dialect: string = OPENUI_LANG_DIALECT): UiDocument {
+  return {
+    dialect,
+    root: null,
+    assignments: {},
+    order: [],
+    diagnostics: [],
+  };
+}
+
+//#region Statement scanner (line assembler)
+
+const FENCE_PREFIX = '```';
+const COMMENT_PREFIXES = [
+  '#',
+  '//',
+];
+
+interface ScannerState {
+  buffer: string;
+  depth: number;
+  inString: boolean;
+  escaped: boolean;
+  line: number;
+}
+
+function freshScannerState(): ScannerState {
+  return {
+    buffer: '',
+    depth: 0,
+    inString: false,
+    escaped: false,
+    line: 0,
+  };
+}
+
+interface ScannedStatement {
+  source: string;
+  line: number;
+}
+
+/**
+ * Consume raw text, returning each completed top-level statement line.
+ * Newlines inside brackets or strings do not terminate a statement.
+ */
+function scanStatements(state: ScannerState, text: string): ScannedStatement[] {
+  const completed: ScannedStatement[] = [];
+  for (const ch of text) {
+    if (ch === '\n' && state.depth <= 0 && !state.inString) {
+      flushStatement(state, completed);
+      continue;
+    }
+    state.buffer += ch;
+    if (state.inString) {
+      if (state.escaped) {
+        state.escaped = false;
+      } else if (ch === '\\') {
+        state.escaped = true;
+      } else if (ch === '"') {
+        state.inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      state.inString = true;
+      continue;
+    }
+    if (ch === '(' || ch === '[' || ch === '{') {
+      state.depth += 1;
+      continue;
+    }
+    if (ch === ')' || ch === ']' || ch === '}') {
+      state.depth -= 1;
+    }
+  }
+  return completed;
+}
+
+function flushStatement(state: ScannerState, out: ScannedStatement[]): void {
+  state.line += 1;
+  const source = state.buffer.trim();
+  state.buffer = '';
+  state.depth = 0;
+  state.inString = false;
+  state.escaped = false;
+  if (source.length === 0) {
+    return;
+  }
+  out.push({
+    source,
+    line: state.line,
+  });
+}
+
+//#endregion
+
+//#region Expression parser
+
+class ParseFailure extends Error {}
+
+function isDigit(ch: string): boolean {
+  return ch >= '0' && ch <= '9';
+}
+
+function isIdentStart(ch: string): boolean {
+  return /[A-Za-z_]/.test(ch);
+}
+
+class ExprParser {
+  private pos = 0;
+
+  constructor(private readonly src: string) {}
+
+  parseExpr(): UiExpr {
+    this.skipWs();
+    const ch = this.peek();
+    if (ch === undefined) {
+      throw new ParseFailure('unexpected end of expression');
+    }
+    if (ch === '"') {
+      return {
+        kind: 'literal',
+        value: this.parseString(),
+      };
+    }
+    if (ch === '[') {
+      return this.parseArray();
+    }
+    if (ch === '{') {
+      return this.parseObject();
+    }
+    if (ch === '-' || isDigit(ch)) {
+      return {
+        kind: 'literal',
+        value: this.parseNumber(),
+      };
+    }
+    if (ch === '$') {
+      this.pos += 1;
+      const name = this.parseIdent();
+      return this.maybeMember({
+        kind: 'state-ref',
+        name,
+      });
+    }
+    if (ch === '@') {
+      this.pos += 1;
+      const fn = this.parseIdent();
+      return this.maybeMember({
+        kind: 'call',
+        fn,
+        builtin: true,
+        args: this.parseArgs(),
+      });
+    }
+    if (isIdentStart(ch)) {
+      const name = this.parseIdent();
+      if (name === 'true') {
+        return {
+          kind: 'literal',
+          value: true,
+        };
+      }
+      if (name === 'false') {
+        return {
+          kind: 'literal',
+          value: false,
+        };
+      }
+      if (name === 'null') {
+        return {
+          kind: 'literal',
+          value: null,
+        };
+      }
+      this.skipWs();
+      if (this.peek() === '(') {
+        return this.maybeMember({
+          kind: 'call',
+          fn: name,
+          builtin: false,
+          args: this.parseArgs(),
+        });
+      }
+      return this.maybeMember({
+        kind: 'ref',
+        name,
+      });
+    }
+    throw new ParseFailure(`unexpected character '${ch}'`);
+  }
+
+  /** Fails unless the whole source was consumed. */
+  parseComplete(): UiExpr {
+    const expr = this.parseExpr();
+    this.skipWs();
+    if (this.pos < this.src.length) {
+      throw new ParseFailure(`trailing content after expression: '${this.src.slice(this.pos)}'`);
+    }
+    return expr;
+  }
+
+  private maybeMember(base: UiExpr): UiExpr {
+    this.skipWs();
+    if (this.peek() !== '.') {
+      return base;
+    }
+    const path: string[] = [];
+    while (this.peek() === '.') {
+      this.pos += 1;
+      path.push(this.parseIdent());
+    }
+    return {
+      kind: 'member',
+      base,
+      path,
+    };
+  }
+
+  private parseArgs(): UiExpr[] {
+    this.expect('(');
+    const args: UiExpr[] = [];
+    this.skipWs();
+    if (this.peek() === ')') {
+      this.pos += 1;
+      return args;
+    }
+    for (;;) {
+      args.push(this.parseExpr());
+      this.skipWs();
+      const ch = this.peek();
+      if (ch === ',') {
+        this.pos += 1;
+        continue;
+      }
+      if (ch === ')') {
+        this.pos += 1;
+        return args;
+      }
+      throw new ParseFailure(`expected ',' or ')' in arguments, got '${ch ?? 'end'}'`);
+    }
+  }
+
+  private parseArray(): UiExpr {
+    this.expect('[');
+    const items: UiExpr[] = [];
+    this.skipWs();
+    if (this.peek() === ']') {
+      this.pos += 1;
+      return {
+        kind: 'array',
+        items,
+      };
+    }
+    for (;;) {
+      items.push(this.parseExpr());
+      this.skipWs();
+      const ch = this.peek();
+      if (ch === ',') {
+        this.pos += 1;
+        continue;
+      }
+      if (ch === ']') {
+        this.pos += 1;
+        return {
+          kind: 'array',
+          items,
+        };
+      }
+      throw new ParseFailure(`expected ',' or ']' in array, got '${ch ?? 'end'}'`);
+    }
+  }
+
+  private parseObject(): UiExpr {
+    this.expect('{');
+    const entries: Array<{
+      key: string;
+      value: UiExpr;
+    }> = [];
+    this.skipWs();
+    if (this.peek() === '}') {
+      this.pos += 1;
+      return {
+        kind: 'object',
+        entries,
+      };
+    }
+    for (;;) {
+      this.skipWs();
+      const key = this.peek() === '"' ? this.parseString() : this.parseIdent();
+      this.skipWs();
+      this.expect(':');
+      entries.push({
+        key,
+        value: this.parseExpr(),
+      });
+      this.skipWs();
+      const ch = this.peek();
+      if (ch === ',') {
+        this.pos += 1;
+        continue;
+      }
+      if (ch === '}') {
+        this.pos += 1;
+        return {
+          kind: 'object',
+          entries,
+        };
+      }
+      throw new ParseFailure(`expected ',' or '}' in object, got '${ch ?? 'end'}'`);
+    }
+  }
+
+  private parseString(): string {
+    this.expect('"');
+    let out = '';
+    for (;;) {
+      const ch = this.src[this.pos];
+      if (ch === undefined) {
+        throw new ParseFailure('unterminated string');
+      }
+      this.pos += 1;
+      if (ch === '"') {
+        return out;
+      }
+      if (ch !== '\\') {
+        out += ch;
+        continue;
+      }
+      const esc = this.src[this.pos];
+      if (esc === undefined) {
+        throw new ParseFailure('unterminated escape');
+      }
+      this.pos += 1;
+      if (esc === 'n') {
+        out += '\n';
+      } else if (esc === 't') {
+        out += '\t';
+      } else {
+        out += esc;
+      }
+    }
+  }
+
+  private parseNumber(): number {
+    const match = /^-?\d+(\.\d+)?([eE][+-]?\d+)?/.exec(this.src.slice(this.pos));
+    if (!match) {
+      throw new ParseFailure('invalid number');
+    }
+    this.pos += match[0].length;
+    return Number(match[0]);
+  }
+
+  private parseIdent(): string {
+    const match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.src.slice(this.pos));
+    if (!match) {
+      throw new ParseFailure(`expected identifier at '${this.src.slice(this.pos, this.pos + 8)}'`);
+    }
+    this.pos += match[0].length;
+    return match[0];
+  }
+
+  private expect(ch: string): void {
+    this.skipWs();
+    if (this.src[this.pos] !== ch) {
+      throw new ParseFailure(`expected '${ch}', got '${this.src[this.pos] ?? 'end'}'`);
+    }
+    this.pos += 1;
+  }
+
+  private peek(): string | undefined {
+    return this.src[this.pos];
+  }
+
+  private skipWs(): void {
+    while (this.pos < this.src.length && /\s/.test(this.src[this.pos] ?? '')) {
+      this.pos += 1;
+    }
+  }
+}
+
+//#endregion
+
+//#region Statement parsing
+
+const STATEMENT_RE = /^(\$?[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/s;
+
+function classify(ref: string, expr: UiExpr): UiStatementKind {
+  if (ref.startsWith('$')) {
+    return 'state';
+  }
+  if (expr.kind === 'call' && !expr.builtin) {
+    if (expr.fn === 'Query') {
+      return 'query';
+    }
+    if (expr.fn === 'Mutation') {
+      return 'mutation';
+    }
+    return 'component';
+  }
+  return 'value';
+}
+
+/** Parse one statement line. Returns null for fences/comments; throws never. */
+function parseStatement(source: string, line: number): UiAssignment | UiDiagnostic | null {
+  if (source.startsWith(FENCE_PREFIX) || COMMENT_PREFIXES.some((p) => source.startsWith(p))) {
+    return null;
+  }
+  const match = STATEMENT_RE.exec(source);
+  if (!match) {
+    return {
+      line,
+      message: 'not an assignment statement',
+      source,
+    };
+  }
+  const ref = match[1] ?? '';
+  const rhs = match[2] ?? '';
+  try {
+    const expr = new ExprParser(rhs).parseComplete();
+    return {
+      ref,
+      kind: classify(ref, expr),
+      expr,
+      line,
+    };
+  } catch (e) {
+    const message = e instanceof ParseFailure ? e.message : String(e);
+    return {
+      line,
+      message,
+      source,
+    };
+  }
+}
+
+function isAssignment(value: UiAssignment | UiDiagnostic): value is UiAssignment {
+  return 'ref' in value;
+}
+
+/**
+ * Streaming parser: feed deltas with `push`, read completed assignments as
+ * they land, and `end()` to flush the trailing unterminated line and get the
+ * document. Also usable one-shot via `parseDocument`.
+ */
+export class OpenUiLangParser {
+  private readonly scanner = freshScannerState();
+  private readonly doc: UiDocument;
+
+  constructor(dialect?: string) {
+    this.doc = emptyDocument(dialect);
+  }
+
+  /** Feed a text delta; returns assignments completed by this chunk. */
+  push(delta: string): UiAssignment[] {
+    return scanStatements(this.scanner, delta)
+      .map(({ source, line }) => this.accept(source, line))
+      .filter((a): a is UiAssignment => a !== null);
+  }
+
+  /** Flush the trailing line and return the finished document. */
+  end(): UiDocument {
+    const completed: ScannedStatement[] = [];
+    flushStatement(this.scanner, completed);
+    for (const { source, line } of completed) {
+      this.accept(source, line);
+    }
+    return this.doc;
+  }
+
+  private accept(source: string, line: number): UiAssignment | null {
+    const parsed = parseStatement(source, line);
+    if (parsed === null) {
+      return null;
+    }
+    if (!isAssignment(parsed)) {
+      this.doc.diagnostics.push(parsed);
+      return null;
+    }
+    const existing = this.doc.assignments[parsed.ref];
+    this.doc.assignments[parsed.ref] = parsed;
+    if (existing !== undefined) {
+      this.doc.order.splice(this.doc.order.indexOf(parsed.ref), 1);
+    }
+    this.doc.order.push(parsed.ref);
+    if (parsed.ref === OPENUI_ROOT_REF) {
+      this.doc.root = OPENUI_ROOT_REF;
+    }
+    return parsed;
+  }
+}
+
+/** One-shot parse of a full turn's output. */
+export function parseDocument(text: string, dialect?: string): UiDocument {
+  const parser = new OpenUiLangParser(dialect);
+  parser.push(text);
+  return parser.end();
+}
+
+//#endregion
diff --git a/packages/openui-playground/src/lang/prompt.ts b/packages/openui-playground/src/lang/prompt.ts
new file mode 100644
index 00000000..5b9f4c84
--- /dev/null
+++ b/packages/openui-playground/src/lang/prompt.ts
@@ -0,0 +1,69 @@
+/**
+ * Component-library system prompt — playground emulation of what the API's
+ * `openui` plugin will inject server-side (DEV-771). Generated from the same
+ * `UiLibrary` shape the SDK ships, so prompts here and API-side stay
+ * comparable when we bench the two paths against each other.
+ */
+import type { ComponentDefinition, UiLibrary } from '@openrouter/agent';
+import { componentProps } from '@openrouter/agent';
+import * as z4 from 'zod/v4';
+import type { $ZodType } from 'zod/v4/core';
+
+function describeSchema(schema: $ZodType): string {
+  try {
+    const json = z4.toJSONSchema(schema, {
+      io: 'input',
+    });
+    if (typeof json.type === 'string') {
+      return json.type;
+    }
+    if (Array.isArray(json.anyOf)) {
+      const types = json.anyOf
+        .map((s) => (typeof s === 'object' && s !== null && 'type' in s ? String(s.type) : 'any'))
+        .filter((t) => t !== 'null');
+      if (types.length > 0) {
+        return types.join(' | ');
+      }
+    }
+    if (Array.isArray(json.enum)) {
+      return json.enum.map((v) => JSON.stringify(v)).join(' | ');
+    }
+  } catch {
+    // Exotic schema — fall through to the permissive label.
+  }
+  return 'any';
+}
+
+function renderComponentLine(def: ComponentDefinition): string {
+  const props = componentProps(def)
+    .map((p) => `${p.name}${p.optional ? '?' : ''}: ${describeSchema(p.schema)}`)
+    .join(', ');
+  const doc = def.description ? ` — ${def.description}` : '';
+  return `- ${def.name}(${props})${doc}`;
+}
+
+/** Render the system prompt for a library. */
+export function libraryPrompt(library: UiLibrary): string {
+  return [
+    `Respond in OpenUI Lang (${library.dialect}): one assignment statement per line, \`name = Expression\`.`,
+    'Rules:',
+    '- Components: `ref = Component(arg1, arg2, ...)` — positional args map to props in signature order.',
+    '- The statement assigned to `root` is the rendered root.',
+    '- Reactive state: `$name = defaultValue`. Passing `$name` to an input two-way binds it.',
+    '- Data: `ref = Query("tool_name", { args })` fetches on load and when referenced `$vars` change; `ref = Mutation("tool_name", { args })` runs only via `@Run(ref)`.',
+    '- Actions: `Action([@Run(ref), @Set($var, value), @ToAssistant("message")])` — steps run sequentially.',
+    '- Reference other statements by their `ref`. Member access plucks fields (`data.rows.title`).',
+    '- Arguments are POSITIONAL only — never `name: value` pairs. Skip an optional prop by ending the argument list early.',
+    '- Emit only OpenUI Lang statements — no prose, no code fences.',
+    '',
+    'Example:',
+    '$query = ""',
+    'results = Table(["Name", "Score"], [["alpha", "9.1"], ["beta", "8.4"]])',
+    'root = Card("Leaderboard", [Input("search", $query, "Filter…"), results])',
+    '',
+    'Available components:',
+    ...[
+      ...library.components.values(),
+    ].map(renderComponentLine),
+  ].join('\n');
+}
diff --git a/packages/openui-playground/src/server.ts b/packages/openui-playground/src/server.ts
new file mode 100644
index 00000000..61ef09c6
--- /dev/null
+++ b/packages/openui-playground/src/server.ts
@@ -0,0 +1,192 @@
+/**
+ * OpenUI playground server.
+ *
+ *   OPENROUTER_API_KEY=sk-... pnpm --filter @openrouter/openui-playground dev
+ *
+ * Routes:
+ * - GET  /               → the playground UI (public/)
+ * - GET  /api/library    → the demo library (names, prompt, dialect)
+ * - POST /api/generate   → run one generation, streamed as SSE
+ *     body: { prompt, model?, mode?: 'emulate' | 'native', system? }
+ *
+ * Plain node:http — no framework, nothing to build; the client is static.
+ */
+import { readFile } from 'node:fs/promises';
+import type { ServerResponse } from 'node:http';
+import { createServer } from 'node:http';
+import { dirname, extname, join, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { OpenRouter } from '@openrouter/agent';
+import { demoLibrary } from './demo-library.js';
+import type { GenerateRequest, PlaygroundEvent } from './generate.js';
+import { generate } from './generate.js';
+import { libraryPrompt } from './lang/prompt.js';
+
+const PORT = Number(process.env['PORT'] ?? 5170);
+const DEFAULT_MODEL = process.env['OPENUI_PLAYGROUND_MODEL'] ?? 'anthropic/claude-sonnet-5';
+const PUBLIC_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'public');
+
+const apiKey = process.env['OPENROUTER_API_KEY'];
+if (!apiKey) {
+  console.error('OPENROUTER_API_KEY is required');
+  process.exit(1);
+}
+const client = new OpenRouter({
+  apiKey,
+});
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+};
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function sseFrame(event: PlaygroundEvent): string {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}
+
+async function readBody(req: import('node:http').IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+  }
+  const text = Buffer.concat(chunks).toString('utf8');
+  return text.length > 0 ? JSON.parse(text) : {};
+}
+
+function parseGenerateRequest(body: unknown): GenerateRequest | null {
+  if (typeof body !== 'object' || body === null) {
+    return null;
+  }
+  const record = body as Record<string, unknown>;
+  if (typeof record['prompt'] !== 'string' || record['prompt'].length === 0) {
+    return null;
+  }
+  const mode = record['mode'];
+  if (mode !== undefined && mode !== 'emulate' && mode !== 'native') {
+    return null;
+  }
+  const request: GenerateRequest = {
+    prompt: record['prompt'],
+    model: typeof record['model'] === 'string' && record['model'] ? record['model'] : DEFAULT_MODEL,
+  };
+  if (mode !== undefined) {
+    request.mode = mode;
+  }
+  if (typeof record['system'] === 'string' && record['system']) {
+    request.system = record['system'];
+  }
+  return request;
+}
+
+async function serveStatic(res: ServerResponse, urlPath: string): Promise<void> {
+  const rel = urlPath === '/' ? 'index.html' : urlPath.slice(1);
+  const file = normalize(join(PUBLIC_DIR, rel));
+  if (!file.startsWith(PUBLIC_DIR)) {
+    sendJson(res, 404, {
+      error: 'not found',
+    });
+    return;
+  }
+  try {
+    const content = await readFile(file);
+    res.writeHead(200, {
+      'content-type': MIME[extname(file)] ?? 'application/octet-stream',
+    });
+    res.end(content);
+  } catch {
+    sendJson(res, 404, {
+      error: 'not found',
+    });
+  }
+}
+
+async function handleRequest(
+  req: import('node:http').IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const url = new URL(req.url ?? '/', `http://localhost:${PORT}`);
+
+  if (req.method === 'GET' && url.pathname === '/api/library') {
+    sendJson(res, 200, {
+      dialect: demoLibrary.dialect,
+      components: demoLibrary.componentNames,
+      prompt: libraryPrompt(demoLibrary),
+      defaultModel: DEFAULT_MODEL,
+    });
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/generate') {
+    let request: GenerateRequest | null = null;
+    try {
+      request = parseGenerateRequest(await readBody(req));
+    } catch {
+      request = null;
+    }
+    if (!request) {
+      sendJson(res, 400, {
+        error: 'body must be { prompt, model?, mode?, system? }',
+      });
+      return;
+    }
+
+    res.writeHead(200, {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-cache',
+      connection: 'keep-alive',
+    });
+    try {
+      for await (const event of generate(client, demoLibrary, request)) {
+        res.write(sseFrame(event));
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      res.write(
+        sseFrame({
+          type: 'error',
+          message,
+        }),
+      );
+    }
+    res.write('data: [DONE]\n\n');
+    res.end();
+    return;
+  }
+
+  if (req.method === 'GET') {
+    await serveStatic(res, url.pathname);
+    return;
+  }
+
+  sendJson(res, 405, {
+    error: 'method not allowed',
+  });
+}
+
+const server = createServer((req, res) => {
+  handleRequest(req, res).catch((error: unknown) => {
+    console.error(error);
+    if (!res.headersSent) {
+      sendJson(res, 500, {
+        error: 'internal error',
+      });
+    } else {
+      res.end();
+    }
+  });
+});
+
+server.listen(PORT, () => {
+  console.log(`OpenUI playground → http://localhost:${PORT} (default model: ${DEFAULT_MODEL})`);
+});
diff --git a/packages/openui-playground/tests/parser.test.ts b/packages/openui-playground/tests/parser.test.ts
new file mode 100644
index 00000000..30f3d9bb
--- /dev/null
+++ b/packages/openui-playground/tests/parser.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+import { OpenUiLangParser, parseDocument } from '../src/lang/parser.js';
+
+describe('OpenUiLangParser (streaming)', () => {
+  it('emits assignments only as their line completes', () => {
+    const parser = new OpenUiLangParser();
+    expect(parser.push('a = Text("hel')).toEqual([]);
+    const [a] = parser.push('lo")\n');
+    expect(a?.ref).toBe('a');
+    expect(a?.kind).toBe('component');
+    const doc = parser.end();
+    expect(doc.order).toEqual([
+      'a',
+    ]);
+  });
+
+  it('assembles statements whose brackets span lines', () => {
+    const parser = new OpenUiLangParser();
+    parser.push('root = Stack([\n  Text("a"),\n  Text("b")\n');
+    expect(parser.push('])\n')).toHaveLength(1);
+    const doc = parser.end();
+    expect(doc.root).toBe('root');
+  });
+
+  it('flushes a trailing statement without a final newline at end()', () => {
+    const parser = new OpenUiLangParser();
+    parser.push('a = Text("x")');
+    const doc = parser.end();
+    expect(doc.order).toEqual([
+      'a',
+    ]);
+  });
+
+  it('newlines inside strings do not split statements', () => {
+    const doc = parseDocument('a = Text("line one\nline two")\n');
+    expect(doc.order).toEqual([
+      'a',
+    ]);
+    expect(doc.diagnostics).toEqual([]);
+  });
+});
+
+describe('parseDocument (tolerance + semantics)', () => {
+  it('classifies statements', () => {
+    const doc = parseDocument(
+      [
+        '$tab = "overview"',
+        'data = Query("list_models", {limit: 3})',
+        'save = Mutation("save_report", {})',
+        'title = "Usage"',
+        'root = Card(title, [Text("hi")])',
+      ].join('\n'),
+    );
+    expect(doc.assignments['$tab']?.kind).toBe('state');
+    expect(doc.assignments['data']?.kind).toBe('query');
+    expect(doc.assignments['save']?.kind).toBe('mutation');
+    expect(doc.assignments['title']?.kind).toBe('value');
+    expect(doc.assignments['root']?.kind).toBe('component');
+    expect(doc.root).toBe('root');
+  });
+
+  it('turns prose into diagnostics, never throws', () => {
+    const doc = parseDocument('Here is your dashboard:\nroot = Card("ok")\nEnjoy!');
+    expect(doc.order).toEqual([
+      'root',
+    ]);
+    expect(doc.diagnostics).toHaveLength(2);
+    expect(doc.diagnostics[0]?.message).toBe('not an assignment statement');
+  });
+
+  it('skips fences and comments silently', () => {
+    const doc = parseDocument('```openui\nroot = Text("x")\n```\n# comment\n// also');
+    expect(doc.order).toEqual([
+      'root',
+    ]);
+    expect(doc.diagnostics).toEqual([]);
+  });
+
+  it('re-assignment replaces and moves the ref to the end', () => {
+    const doc = parseDocument('a = Text("1")\nb = Text("2")\na = Text("3")');
+    expect(doc.order).toEqual([
+      'b',
+      'a',
+    ]);
+    const a = doc.assignments['a'];
+    expect(a?.expr).toMatchObject({
+      kind: 'call',
+      args: [
+        {
+          kind: 'literal',
+          value: '3',
+        },
+      ],
+    });
+  });
+
+  it('parses builtins, state refs, member access, and nesting', () => {
+    const doc = parseDocument(
+      'btn = Button("Add", Action([@Run(save), @Set($title, ""), @ToAssistant("done")]))\nrows = data.rows.title',
+    );
+    expect(doc.diagnostics).toEqual([]);
+    expect(doc.assignments['btn']?.expr).toMatchObject({
+      kind: 'call',
+      fn: 'Button',
+    });
+    expect(doc.assignments['rows']?.expr).toMatchObject({
+      kind: 'member',
+      base: {
+        kind: 'ref',
+        name: 'data',
+      },
+      path: [
+        'rows',
+        'title',
+      ],
+    });
+  });
+
+  it('parses literals: numbers, booleans, null, escapes', () => {
+    const doc = parseDocument('a = {n: -1.5e2, t: true, f: false, z: null, s: "a\\"b\\nc"}');
+    expect(doc.diagnostics).toEqual([]);
+    expect(doc.assignments['a']?.expr).toMatchObject({
+      kind: 'object',
+      entries: [
+        {
+          key: 'n',
+          value: {
+            kind: 'literal',
+            value: -150,
+          },
+        },
+        {
+          key: 't',
+          value: {
+            kind: 'literal',
+            value: true,
+          },
+        },
+        {
+          key: 'f',
+          value: {
+            kind: 'literal',
+            value: false,
+          },
+        },
+        {
+          key: 'z',
+          value: {
+            kind: 'literal',
+            value: null,
+          },
+        },
+        {
+          key: 's',
+          value: {
+            kind: 'literal',
+            value: 'a"b\nc',
+          },
+        },
+      ],
+    });
+  });
+
+  it('reports unparseable expressions as diagnostics with the source line', () => {
+    const doc = parseDocument('bad = Card(("unclosed"\ngood = Text("ok")');
+    // The unbalanced paren swallows the newline; only one statement completes.
+    expect(doc.diagnostics.length + doc.order.length).toBeGreaterThan(0);
+    expect(parseDocument('x = = =').diagnostics).toHaveLength(1);
+  });
+});
diff --git a/packages/openui-playground/tsconfig.json b/packages/openui-playground/tsconfig.json
new file mode 100644
index 00000000..6412ea8d
--- /dev/null
+++ b/packages/openui-playground/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "esm",
+    "noEmit": true
+  },
+  "include": ["src", "tests"],
+  "exclude": ["node_modules", "esm"]
+}
diff --git a/packages/openui-playground/vitest.config.ts b/packages/openui-playground/vitest.config.ts
new file mode 100644
index 00000000..4a58023e
--- /dev/null
+++ b/packages/openui-playground/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a98d76a5..e6fd9aa1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -37,7 +37,7 @@ importers:
         version: 5.8.3
       vitest:
         specifier: ^4.1.5
-        version: 4.1.10(@types/node@22.19.15)(@vitest/coverage-v8@4.1.10)(vite@7.3.1(@types/node@22.19.15))
+        version: 4.1.10(@types/node@22.19.15)(@vitest/coverage-v8@4.1.10)(vite@7.3.1(@types/node@22.19.15)(tsx@4.23.1))
 
   packages/agent:
     dependencies:
@@ -60,6 +60,28 @@ importers:
         specifier: ^4.0.0
         version: 4.3.6
 
+  packages/openui-playground:
+    dependencies:
+      '@openrouter/agent':
+        specifier: workspace:*
+        version: link:../agent
+      '@openrouter/sdk':
+        specifier: ^0.13.7
+        version: 0.13.7
+      zod:
+        specifier: ^4.0.0
+        version: 4.3.6
+    devDependencies:
+      tsx:
+        specifier: ^4.19.0
+        version: 4.23.1
+      typescript:
+        specifier: ~5.8.3
+        version: 5.8.3
+      vitest:
+        specifier: ^4.1.5
+        version: 4.1.10(@types/node@22.19.15)(@vitest/coverage-v8@4.1.10)(vite@7.3.1(@types/node@22.19.15)(tsx@4.23.1))
+
 packages:
 
   '@babel/helper-string-parser@7.29.7':
@@ -207,156 +229,312 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
+  '@esbuild/aix-ppc64@0.28.1':
+    resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
   '@esbuild/android-arm64@0.27.4':
     resolution: {integrity: sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [android]
 
+  '@esbuild/android-arm64@0.28.1':
+    resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
   '@esbuild/android-arm@0.27.4':
     resolution: {integrity: sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==}
     engines: {node: '>=18'}
     cpu: [arm]
     os: [android]
 
+  '@esbuild/android-arm@0.28.1':
+    resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
   '@esbuild/android-x64@0.27.4':
     resolution: {integrity: sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [android]
 
+  '@esbuild/android-x64@0.28.1':
+    resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
   '@esbuild/darwin-arm64@0.27.4':
     resolution: {integrity: sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [darwin]
 
+  '@esbuild/darwin-arm64@0.28.1':
+    resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@esbuild/darwin-x64@0.27.4':
     resolution: {integrity: sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [darwin]
 
+  '@esbuild/darwin-x64@0.28.1':
+    resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
   '@esbuild/freebsd-arm64@0.27.4':
     resolution: {integrity: sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [freebsd]
 
+  '@esbuild/freebsd-arm64@0.28.1':
+    resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
   '@esbuild/freebsd-x64@0.27.4':
     resolution: {integrity: sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [freebsd]
 
+  '@esbuild/freebsd-x64@0.28.1':
+    resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@esbuild/linux-arm64@0.27.4':
     resolution: {integrity: sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [linux]
 
+  '@esbuild/linux-arm64@0.28.1':
+    resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
   '@esbuild/linux-arm@0.27.4':
     resolution: {integrity: sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==}
     engines: {node: '>=18'}
     cpu: [arm]
     os: [linux]
 
+  '@esbuild/linux-arm@0.28.1':
+    resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
   '@esbuild/linux-ia32@0.27.4':
     resolution: {integrity: sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==}
     engines: {node: '>=18'}
     cpu: [ia32]
     os: [linux]
 
+  '@esbuild/linux-ia32@0.28.1':
+    resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
   '@esbuild/linux-loong64@0.27.4':
     resolution: {integrity: sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==}
     engines: {node: '>=18'}
     cpu: [loong64]
     os: [linux]
 
+  '@esbuild/linux-loong64@0.28.1':
+    resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
   '@esbuild/linux-mips64el@0.27.4':
     resolution: {integrity: sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==}
     engines: {node: '>=18'}
     cpu: [mips64el]
     os: [linux]
 
+  '@esbuild/linux-mips64el@0.28.1':
+    resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
   '@esbuild/linux-ppc64@0.27.4':
     resolution: {integrity: sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==}
     engines: {node: '>=18'}
     cpu: [ppc64]
     os: [linux]
 
+  '@esbuild/linux-ppc64@0.28.1':
+    resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
   '@esbuild/linux-riscv64@0.27.4':
     resolution: {integrity: sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==}
     engines: {node: '>=18'}
     cpu: [riscv64]
     os: [linux]
 
+  '@esbuild/linux-riscv64@0.28.1':
+    resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
   '@esbuild/linux-s390x@0.27.4':
     resolution: {integrity: sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==}
     engines: {node: '>=18'}
     cpu: [s390x]
     os: [linux]
 
+  '@esbuild/linux-s390x@0.28.1':
+    resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
   '@esbuild/linux-x64@0.27.4':
     resolution: {integrity: sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [linux]
 
+  '@esbuild/linux-x64@0.28.1':
+    resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
   '@esbuild/netbsd-arm64@0.27.4':
     resolution: {integrity: sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [netbsd]
 
+  '@esbuild/netbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
   '@esbuild/netbsd-x64@0.27.4':
     resolution: {integrity: sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [netbsd]
 
+  '@esbuild/netbsd-x64@0.28.1':
+    resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
   '@esbuild/openbsd-arm64@0.27.4':
     resolution: {integrity: sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [openbsd]
 
+  '@esbuild/openbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
   '@esbuild/openbsd-x64@0.27.4':
     resolution: {integrity: sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [openbsd]
 
+  '@esbuild/openbsd-x64@0.28.1':
+    resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
   '@esbuild/openharmony-arm64@0.27.4':
     resolution: {integrity: sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [openharmony]
 
+  '@esbuild/openharmony-arm64@0.28.1':
+    resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
   '@esbuild/sunos-x64@0.27.4':
     resolution: {integrity: sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [sunos]
 
+  '@esbuild/sunos-x64@0.28.1':
+    resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
   '@esbuild/win32-arm64@0.27.4':
     resolution: {integrity: sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [win32]
 
+  '@esbuild/win32-arm64@0.28.1':
+    resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
   '@esbuild/win32-ia32@0.27.4':
     resolution: {integrity: sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==}
     engines: {node: '>=18'}
     cpu: [ia32]
     os: [win32]
 
+  '@esbuild/win32-ia32@0.28.1':
+    resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
   '@esbuild/win32-x64@0.27.4':
     resolution: {integrity: sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [win32]
 
+  '@esbuild/win32-x64@0.28.1':
+    resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
   '@hono/node-server@1.19.14':
     resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
     engines: {node: '>=18.14.1'}
@@ -793,6 +971,11 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  esbuild@0.28.1:
+    resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   escape-html@1.0.3:
     resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
 
@@ -1357,6 +1540,11 @@ packages:
   tr46@0.0.3:
     resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
 
+  tsx@4.23.1:
+    resolution: {integrity: sha512-GQHnkIfxyx1wYCOS/wonik5MVRZU9hi1TEZmzGZSCJB1y9YgoZ8H6itNE/u4suE+yLmOzuE4E5S4TZ/ZX2wcWQ==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
   turbo@2.9.6:
     resolution: {integrity: sha512-+v2QJey7ZUeUiuigkU+uFfklvNUyPI2VO2vBpMYJA+a1hKFLFiKtUYlRHdb3P9CrAvMzi0upbjI4WT+zKtqkBg==}
     hasBin: true
@@ -1708,81 +1896,159 @@ snapshots:
   '@esbuild/aix-ppc64@0.27.4':
     optional: true
 
+  '@esbuild/aix-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm64@0.27.4':
     optional: true
 
+  '@esbuild/android-arm64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm@0.27.4':
     optional: true
 
+  '@esbuild/android-arm@0.28.1':
+    optional: true
+
   '@esbuild/android-x64@0.27.4':
     optional: true
 
+  '@esbuild/android-x64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-arm64@0.27.4':
     optional: true
 
+  '@esbuild/darwin-arm64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-x64@0.27.4':
     optional: true
 
+  '@esbuild/darwin-x64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-arm64@0.27.4':
     optional: true
 
+  '@esbuild/freebsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-x64@0.27.4':
     optional: true
 
+  '@esbuild/freebsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm64@0.27.4':
     optional: true
 
+  '@esbuild/linux-arm64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm@0.27.4':
     optional: true
 
+  '@esbuild/linux-arm@0.28.1':
+    optional: true
+
   '@esbuild/linux-ia32@0.27.4':
     optional: true
 
+  '@esbuild/linux-ia32@0.28.1':
+    optional: true
+
   '@esbuild/linux-loong64@0.27.4':
     optional: true
 
+  '@esbuild/linux-loong64@0.28.1':
+    optional: true
+
   '@esbuild/linux-mips64el@0.27.4':
     optional: true
 
+  '@esbuild/linux-mips64el@0.28.1':
+    optional: true
+
   '@esbuild/linux-ppc64@0.27.4':
     optional: true
 
+  '@esbuild/linux-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/linux-riscv64@0.27.4':
     optional: true
 
+  '@esbuild/linux-riscv64@0.28.1':
+    optional: true
+
   '@esbuild/linux-s390x@0.27.4':
     optional: true
 
+  '@esbuild/linux-s390x@0.28.1':
+    optional: true
+
   '@esbuild/linux-x64@0.27.4':
     optional: true
 
+  '@esbuild/linux-x64@0.28.1':
+    optional: true
+
   '@esbuild/netbsd-arm64@0.27.4':
     optional: true
 
+  '@esbuild/netbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/netbsd-x64@0.27.4':
     optional: true
 
+  '@esbuild/netbsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/openbsd-arm64@0.27.4':
     optional: true
 
+  '@esbuild/openbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/openbsd-x64@0.27.4':
     optional: true
 
+  '@esbuild/openbsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/openharmony-arm64@0.27.4':
     optional: true
 
+  '@esbuild/openharmony-arm64@0.28.1':
+    optional: true
+
   '@esbuild/sunos-x64@0.27.4':
     optional: true
 
+  '@esbuild/sunos-x64@0.28.1':
+    optional: true
+
   '@esbuild/win32-arm64@0.27.4':
     optional: true
 
+  '@esbuild/win32-arm64@0.28.1':
+    optional: true
+
   '@esbuild/win32-ia32@0.27.4':
     optional: true
 
+  '@esbuild/win32-ia32@0.28.1':
+    optional: true
+
   '@esbuild/win32-x64@0.27.4':
     optional: true
 
+  '@esbuild/win32-x64@0.28.1':
+    optional: true
+
   '@hono/node-server@1.19.14(hono@4.12.27)':
     dependencies:
       hono: 4.12.27
@@ -1979,7 +2245,7 @@ snapshots:
       obug: 2.1.4
       std-env: 4.2.0
       tinyrainbow: 3.1.0
-      vitest: 4.1.10(@types/node@22.19.15)(@vitest/coverage-v8@4.1.10)(vite@7.3.1(@types/node@22.19.15))
+      vitest: 4.1.10(@types/node@22.19.15)(@vitest/coverage-v8@4.1.10)(vite@7.3.1(@types/node@22.19.15)(tsx@4.23.1))
 
   '@vitest/expect@4.1.10':
     dependencies:
@@ -1990,13 +2256,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.10(vite@7.3.1(@types/node@22.19.15))':
+  '@vitest/mocker@4.1.10(vite@7.3.1(@types/node@22.19.15)(tsx@4.23.1))':
     dependencies:
       '@vitest/spy': 4.1.10
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.1(@types/node@22.19.15)
+      vite: 7.3.1(@types/node@22.19.15)(tsx@4.23.1)
 
   '@vitest/pretty-format@4.1.10':
     dependencies:
@@ -2191,6 +2457,35 @@ snapshots:
       '@esbuild/win32-ia32': 0.27.4
       '@esbuild/win32-x64': 0.27.4
 
+  esbuild@0.28.1:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.1
+      '@esbuild/android-arm': 0.28.1
+      '@esbuild/android-arm64': 0.28.1
+      '@esbuild/android-x64': 0.28.1
+      '@esbuild/darwin-arm64': 0.28.1
+      '@esbuild/darwin-x64': 0.28.1
+      '@esbuild/freebsd-arm64': 0.28.1
+      '@esbuild/freebsd-x64': 0.28.1
+      '@esbuild/linux-arm': 0.28.1
+      '@esbuild/linux-arm64': 0.28.1
+      '@esbuild/linux-ia32': 0.28.1
+      '@esbuild/linux-loong64': 0.28.1
+      '@esbuild/linux-mips64el': 0.28.1
+      '@esbuild/linux-ppc64': 0.28.1
+      '@esbuild/linux-riscv64': 0.28.1
+      '@esbuild/linux-s390x': 0.28.1
+      '@esbuild/linux-x64': 0.28.1
+      '@esbuild/netbsd-arm64': 0.28.1
+      '@esbuild/netbsd-x64': 0.28.1
+      '@esbuild/openbsd-arm64': 0.28.1
+      '@esbuild/openbsd-x64': 0.28.1
+      '@esbuild/openharmony-arm64': 0.28.1
+      '@esbuild/sunos-x64': 0.28.1
+      '@esbuild/win32-arm64': 0.28.1
+      '@esbuild/win32-ia32': 0.28.1
+      '@esbuild/win32-x64': 0.28.1
+
   escape-html@1.0.3: {}
 
   esprima@4.0.1: {}
@@ -2748,6 +3043,12 @@ snapshots:
 
   tr46@0.0.3: {}
 
+  tsx@4.23.1:
+    dependencies:
+      esbuild: 0.28.1
+    optionalDependencies:
+      fsevents: 2.3.3
+
   turbo@2.9.6:
     optionalDependencies:
       '@turbo/darwin-64': 2.9.6
@@ -2773,7 +3074,7 @@ snapshots:
 
   vary@1.1.2: {}
 
-  vite@7.3.1(@types/node@22.19.15):
+  vite@7.3.1(@types/node@22.19.15)(tsx@4.23.1):
     dependencies:
       esbuild: 0.27.4
       fdir: 6.5.0(picomatch@4.0.4)
@@ -2784,11 +3085,12 @@ snapshots:
     optionalDependencies:
       '@types/node': 22.19.15
       fsevents: 2.3.3
+      tsx: 4.23.1
 
-  vitest@4.1.10(@types/node@22.19.15)(@vitest/coverage-v8@4.1.10)(vite@7.3.1(@types/node@22.19.15)):
+  vitest@4.1.10(@types/node@22.19.15)(@vitest/coverage-v8@4.1.10)(vite@7.3.1(@types/node@22.19.15)(tsx@4.23.1)):
     dependencies:
       '@vitest/expect': 4.1.10
-      '@vitest/mocker': 4.1.10(vite@7.3.1(@types/node@22.19.15))
+      '@vitest/mocker': 4.1.10(vite@7.3.1(@types/node@22.19.15)(tsx@4.23.1))
       '@vitest/pretty-format': 4.1.10
       '@vitest/runner': 4.1.10
       '@vitest/snapshot': 4.1.10
@@ -2805,7 +3107,7 @@ snapshots:
       tinyexec: 1.2.4
       tinyglobby: 0.2.15
       tinyrainbow: 3.1.0
-      vite: 7.3.1(@types/node@22.19.15)
+      vite: 7.3.1(@types/node@22.19.15)(tsx@4.23.1)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.19.15

From 69bfb14250842e840db248516ba0ad01ed9eb90e Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Mon, 3 Aug 2026 13:59:00 -0500
Subject: [PATCH 04/19] fix(openui): quote non-identifier object keys, guard
 non-finite numbers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

serializeExpr emitted object keys raw, so a key with spaces, quotes,
punctuation, or a leading digit produced source the parser rejects. Keys
come from arbitrary tool-authored objects via toExpr, so they cannot be
assumed to be identifiers. The grammar already accepts a quoted key
(parseObject branches on '"'), so quoting the rest round-trips.

String(NaN)/String(Infinity) also emitted bare identifiers, which parse
back as refs to undefined names. JSON resolves the same hole as null; do
that rather than emit source that cannot round-trip.

fix(playground): describe enum props by their values, not "string"

describeSchema returned on json.type before checking json.enum, but an
enum serializes as {type: 'string', enum: [...]} — so every enum prop was
described to the model as a plain string and it never saw which values
are legal for Badge.tone, Stack.direction, Button.variant.

docs(changeset): add the required minor changeset for the OpenUI exports

~30 new exports plus ModelResult.getUiStream and the toUIOutput tool
option had no changeset, which the public-api-examples skill requires.
The example is compile-checked against the real signatures.
---
 .changeset/openui-bindings.md                 | 76 +++++++++++++++++
 packages/agent/src/lib/openui/document.ts     | 34 +++++++-
 packages/agent/tests/unit/openui.test.ts      | 83 +++++++++++++++++++
 packages/openui-playground/src/lang/prompt.ts | 12 ++-
 .../openui-playground/tests/prompt.test.ts    | 34 ++++++++
 5 files changed, 234 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/openui-bindings.md
 create mode 100644 packages/openui-playground/tests/prompt.test.ts

diff --git a/.changeset/openui-bindings.md b/.changeset/openui-bindings.md
new file mode 100644
index 00000000..049a851f
--- /dev/null
+++ b/.changeset/openui-bindings.md
@@ -0,0 +1,76 @@
+---
+'@openrouter/agent': minor
+---
+
+OpenUI bindings: a component-library model (`defineComponent`, `createLibrary`, `componentProps`), a typed fragment builder (`fragment`, `uiRef`, `uiState`, `uiBuiltin`), the `openui` plugin helper, `serializeExpr`/`OPENUI_LANG_DIALECT` for emitting OpenUI Lang, a `toUIOutput` tool option that renders a tool's result as UI, and `ModelResult.getUiStream()` for consuming fragments as they arrive.
+
+A tool declares how its output renders, and the caller streams the fragments:
+
+```ts
+import {
+  callModel,
+  createLibrary,
+  defineComponent,
+  fragment,
+  openui,
+  tool,
+} from '@openrouter/agent';
+import { z } from 'zod/v4';
+
+const library = createLibrary([
+  defineComponent({
+    name: 'Card',
+    description: 'Container with a title',
+    props: z.object({
+      title: z.string(),
+      children: z.array(z.unknown()).optional(),
+    }),
+  }),
+  defineComponent({
+    name: 'Text',
+    props: z.object({
+      value: z.string(),
+    }),
+  }),
+]);
+
+const ui = fragment(library);
+
+const weather = tool({
+  name: 'weather',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    summary: z.string(),
+  }),
+  execute: ({ city }) => ({
+    summary: `Clear in ${city}`,
+  }),
+  // Renders the tool's result instead of leaving the model to describe it.
+  toUIOutput: ({ input, output }) =>
+    ui.Card(input.city, [
+      ui.Text(output.summary),
+    ]),
+});
+
+const result = callModel(client, {
+  model: 'anthropic/claude-sonnet-4.5',
+  input: 'What is the weather in Lisbon?',
+  tools: [
+    weather,
+  ],
+  plugins: [
+    // `as never` until the SDK regen adds `openui` to its plugin union; the
+    // wire shape is already accepted by the API.
+    openui(library) as never,
+  ],
+});
+
+for await (const event of result.getUiStream()) {
+  if (event.type === 'fragment') {
+    // source: 'root = Card("Lisbon", [Text("Clear in Lisbon")])'
+    console.log(event.source);
+  }
+}
+```
diff --git a/packages/agent/src/lib/openui/document.ts b/packages/agent/src/lib/openui/document.ts
index 7efb8aeb..7a496fef 100644
--- a/packages/agent/src/lib/openui/document.ts
+++ b/packages/agent/src/lib/openui/document.ts
@@ -63,11 +63,41 @@ export interface UiFragment {
   source: string;
 }
 
+/**
+ * Bare-identifier object keys, which the grammar accepts unquoted. Anything
+ * else — spaces, quotes, punctuation, a leading digit, the empty string — must
+ * be quoted or the emitted source does not parse.
+ */
+const BARE_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Object keys reach here from arbitrary tool-authored objects via `toExpr`, so
+ * they cannot be assumed to be identifiers. The parser accepts a quoted key
+ * (`parseObject` branches on `"`), so quoting the rest round-trips.
+ */
+function serializeKey(key: string): string {
+  return BARE_KEY.test(key) ? key : JSON.stringify(key);
+}
+
+/**
+ * Numbers that have no OpenUI Lang literal: `String(NaN)` is `NaN` and
+ * `String(Infinity)` is `Infinity`, both of which serialize as bare identifiers
+ * and would parse back as refs to undefined names (or fail outright). JSON has
+ * the same hole and resolves it as `null`; do the same rather than emit source
+ * that cannot round-trip.
+ */
+function serializeNumber(value: number): string {
+  return Number.isFinite(value) ? String(value) : 'null';
+}
+
 /** Serialize an expression to OpenUI Lang source. */
 export function serializeExpr(expr: UiExpr): string {
   switch (expr.kind) {
     case 'literal':
-      return typeof expr.value === 'string' ? JSON.stringify(expr.value) : String(expr.value);
+      if (typeof expr.value === 'string') {
+        return JSON.stringify(expr.value);
+      }
+      return typeof expr.value === 'number' ? serializeNumber(expr.value) : String(expr.value);
     case 'ref':
       return expr.name;
     case 'state-ref':
@@ -77,7 +107,7 @@ export function serializeExpr(expr: UiExpr): string {
     case 'array':
       return `[${expr.items.map(serializeExpr).join(', ')}]`;
     case 'object':
-      return `{${expr.entries.map((e) => `${e.key}: ${serializeExpr(e.value)}`).join(', ')}}`;
+      return `{${expr.entries.map((e) => `${serializeKey(e.key)}: ${serializeExpr(e.value)}`).join(', ')}}`;
     case 'call':
       return `${expr.builtin ? '@' : ''}${expr.fn}(${expr.args.map(serializeExpr).join(', ')})`;
   }
diff --git a/packages/agent/tests/unit/openui.test.ts b/packages/agent/tests/unit/openui.test.ts
index 74758d84..acde5ddf 100644
--- a/packages/agent/tests/unit/openui.test.ts
+++ b/packages/agent/tests/unit/openui.test.ts
@@ -54,6 +54,89 @@ describe('serializeExpr', () => {
     ).toBe('null');
   });
 
+  /*
+   * Keys arrive from arbitrary tool-authored objects via `toExpr`, so a key
+   * with spaces, quotes, punctuation, or a leading digit would emit source the
+   * parser rejects. The grammar accepts a quoted key, so quoting round-trips.
+   */
+  it('quotes object keys that are not bare identifiers', () => {
+    expect(
+      serializeExpr({
+        kind: 'object',
+        entries: [
+          {
+            key: 'ok_key1',
+            value: {
+              kind: 'literal',
+              value: 1,
+            },
+          },
+          {
+            key: 'has space',
+            value: {
+              kind: 'literal',
+              value: 2,
+            },
+          },
+          {
+            key: '2leading',
+            value: {
+              kind: 'literal',
+              value: 3,
+            },
+          },
+          {
+            key: 'has"quote',
+            value: {
+              kind: 'literal',
+              value: 4,
+            },
+          },
+          {
+            key: '',
+            value: {
+              kind: 'literal',
+              value: 5,
+            },
+          },
+        ],
+      }),
+    ).toBe('{ok_key1: 1, "has space": 2, "2leading": 3, "has\\"quote": 4, "": 5}');
+  });
+
+  /*
+   * `String(NaN)`/`String(Infinity)` emit bare identifiers, which parse back as
+   * refs to undefined names rather than numbers. JSON has the same hole and
+   * resolves it as null.
+   */
+  it('serializes non-finite numbers as null rather than bare identifiers', () => {
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: Number.NaN,
+      }),
+    ).toBe('null');
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: Number.POSITIVE_INFINITY,
+      }),
+    ).toBe('null');
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: Number.NEGATIVE_INFINITY,
+      }),
+    ).toBe('null');
+    /* Finite numbers, including negative zero, are untouched. */
+    expect(
+      serializeExpr({
+        kind: 'literal',
+        value: -1.5,
+      }),
+    ).toBe('-1.5');
+  });
+
   it('serializes refs, state refs, and member access', () => {
     expect(
       serializeExpr({
diff --git a/packages/openui-playground/src/lang/prompt.ts b/packages/openui-playground/src/lang/prompt.ts
index 5b9f4c84..e1efb1bc 100644
--- a/packages/openui-playground/src/lang/prompt.ts
+++ b/packages/openui-playground/src/lang/prompt.ts
@@ -14,6 +14,15 @@ function describeSchema(schema: $ZodType): string {
     const json = z4.toJSONSchema(schema, {
       io: 'input',
     });
+    /*
+     * Before `type`: an enum serializes as `{type: 'string', enum: [...]}`, so
+     * checking `type` first labels every enum prop a plain `string` and the
+     * model never learns which values are legal for `Badge.tone`,
+     * `Stack.direction`, `Button.variant`, and the rest.
+     */
+    if (Array.isArray(json.enum)) {
+      return json.enum.map((v) => JSON.stringify(v)).join(' | ');
+    }
     if (typeof json.type === 'string') {
       return json.type;
     }
@@ -25,9 +34,6 @@ function describeSchema(schema: $ZodType): string {
         return types.join(' | ');
       }
     }
-    if (Array.isArray(json.enum)) {
-      return json.enum.map((v) => JSON.stringify(v)).join(' | ');
-    }
   } catch {
     // Exotic schema — fall through to the permissive label.
   }
diff --git a/packages/openui-playground/tests/prompt.test.ts b/packages/openui-playground/tests/prompt.test.ts
new file mode 100644
index 00000000..0f4839d8
--- /dev/null
+++ b/packages/openui-playground/tests/prompt.test.ts
@@ -0,0 +1,34 @@
+import { createLibrary, defineComponent } from '@openrouter/agent';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod/v4';
+import { libraryPrompt } from '../src/lang/prompt.js';
+
+/*
+ * The prompt is the only place the model learns a prop's legal values. An enum
+ * serializes as `{type: 'string', enum: [...]}`, so a `type`-first check labels
+ * it a bare `string` and every enum prop's values stay invisible.
+ */
+describe('libraryPrompt enum props', () => {
+  const library = createLibrary([
+    defineComponent({
+      name: 'Badge',
+      props: z.object({
+        tone: z.enum([
+          'info',
+          'warn',
+          'danger',
+        ]),
+        label: z.string(),
+      }),
+    }),
+  ]);
+
+  it('lists an enum prop’s valid values instead of "string"', () => {
+    const prompt = libraryPrompt(library);
+    expect(prompt).toContain('tone: "info" | "warn" | "danger"');
+  });
+
+  it('still labels non-enum props by type', () => {
+    expect(libraryPrompt(library)).toContain('label: string');
+  });
+});

From 3720fde9bf1ad92c4ffc53a780603d849f74aebc Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Mon, 3 Aug 2026 14:04:54 -0500
Subject: [PATCH 05/19] =?UTF-8?q?refactor:=20clear=20the=20structural=20ga?=
 =?UTF-8?q?te=20=E2=80=94=20god=20file=20and=204=20complex=20functions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The gate's no_god_files rule is fan-out > 15, not file size:
model-result.ts sat at exactly 15 outbound edges and this PR's
./openui/ui-stream.js import made it 16. Verified by removing that one
import — the violation disappears. Re-exported UiStreamEvent and
translateUiEvent from stream-transformers.js, which model-result.ts
already depends on and which owns every other wire-event translation the
loop performs, so no new edge is added.

Complex functions were 9 -> 13, all four new here. Each is split along a
seam it already had:

- translateUiEvent: one function per wire event type (cc=18 -> under)
- scanStatements: string-literal and bracket-depth state machines extracted
- generate: the native path's per-variant event mapping extracted
- renderCall: form controls and Table extracted to renderControl/renderTable

Verified with sentrux 0.5.7, the version CI pins: God files 0 -> 0,
complex functions back to 9 (the 9 remaining are all pre-existing on main
and untouched), gate reports 'No degradation detected'. Behavior unchanged
— full suite green, typecheck and lint clean.
---
 packages/agent/src/lib/model-result.ts        |   5 +-
 packages/agent/src/lib/openui/ui-stream.ts    | 210 ++++++++++--------
 packages/agent/src/lib/stream-transformers.ts |  13 ++
 packages/openui-playground/public/app.js      | 181 ++++++++-------
 packages/openui-playground/src/generate.ts    |  49 ++--
 packages/openui-playground/src/lang/parser.ts |  42 ++--
 6 files changed, 286 insertions(+), 214 deletions(-)

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index 8940f7d5..ebf60e56 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -31,11 +31,9 @@ import {
   applyNextTurnParamsToRequest,
   executeNextTurnParamsFunctions,
 } from './next-turn-params.js';
-import type { UiStreamEvent } from './openui/ui-stream.js';
-import { translateUiEvent } from './openui/ui-stream.js';
 import { ReusableReadableStream } from './reusable-stream.js';
 import { isStopConditionMet } from './stop-conditions.js';
-import type { ItemInProgress, StreamableOutputItem } from './stream-transformers.js';
+import type { ItemInProgress, StreamableOutputItem, UiStreamEvent } from './stream-transformers.js';
 import {
   buildItemsStream,
   buildResponsesMessageStream,
@@ -49,6 +47,7 @@ import {
   extractToolDeltas,
   itemsStreamHandlers,
   streamTerminationEvents,
+  translateUiEvent,
 } from './stream-transformers.js';
 import {
   hasTypeProperty,
diff --git a/packages/agent/src/lib/openui/ui-stream.ts b/packages/agent/src/lib/openui/ui-stream.ts
index 6414fe12..7796cb1f 100644
--- a/packages/agent/src/lib/openui/ui-stream.ts
+++ b/packages/agent/src/lib/openui/ui-stream.ts
@@ -85,109 +85,129 @@ function str(value: unknown): string | undefined {
  * `tool.ui_fragment` and the API's `response.openui.*` wire events (including
  * their pre-regen `Unknown` encoding).
  */
-export function translateUiEvent(event: unknown): UiStreamEvent | null {
-  const payload = unwrapEvent(event);
-  if (!payload) {
+/** `tool.ui_fragment`: a local tool's fragment, carried on the tool stream. */
+function toolFragmentEvent(payload: Record<string, unknown>): UiStreamEvent | null {
+  const fragment = payload['fragment'];
+  if (!isRecord(fragment)) {
+    return null;
+  }
+  const dialect = str(fragment['dialect']);
+  const source = str(fragment['source']);
+  if (dialect === undefined || source === undefined) {
     return null;
   }
+  const result: UiFragmentEvent = {
+    type: 'fragment',
+    dialect,
+    source,
+  };
+  const toolCallId = str(payload['toolCallId']);
+  if (toolCallId !== undefined) {
+    result.toolCallId = toolCallId;
+  }
+  const toolName = str(payload['toolName']);
+  if (toolName !== undefined) {
+    result.toolName = toolName;
+  }
+  return result;
+}
 
-  switch (payload['type']) {
-    case 'tool.ui_fragment': {
-      const fragment = payload['fragment'];
-      if (!isRecord(fragment)) {
-        return null;
-      }
-      const dialect = str(fragment['dialect']);
-      const source = str(fragment['source']);
-      if (dialect === undefined || source === undefined) {
-        return null;
-      }
-      const result: UiFragmentEvent = {
-        type: 'fragment',
-        dialect,
-        source,
-      };
-      const toolCallId = str(payload['toolCallId']);
-      if (toolCallId !== undefined) {
-        result.toolCallId = toolCallId;
-      }
-      const toolName = str(payload['toolName']);
-      if (toolName !== undefined) {
-        result.toolName = toolName;
-      }
-      return result;
-    }
+/** `response.openui.statement`: one completed assignment from the API. */
+function statementEvent(payload: Record<string, unknown>): UiStreamEvent | null {
+  const ref = str(payload['ref']);
+  const kind = str(payload['kind']);
+  const source = str(payload['source']);
+  if (ref === undefined || kind === undefined || source === undefined) {
+    return null;
+  }
+  return {
+    type: 'statement',
+    ref,
+    kind,
+    source,
+  };
+}
 
-    case OPENUI_WIRE_EVENT.Statement: {
-      const ref = str(payload['ref']);
-      const kind = str(payload['kind']);
-      const source = str(payload['source']);
-      if (ref === undefined || kind === undefined || source === undefined) {
-        return null;
-      }
-      return {
-        type: 'statement',
-        ref,
-        kind,
-        source,
-      };
-    }
+/** `response.openui.fragment`: a server tool's fragment. */
+function wireFragmentEvent(payload: Record<string, unknown>): UiStreamEvent | null {
+  const dialect = str(payload['dialect']);
+  const source = str(payload['source']);
+  if (dialect === undefined || source === undefined) {
+    return null;
+  }
+  const result: UiFragmentEvent = {
+    type: 'fragment',
+    dialect,
+    source,
+  };
+  // Wire field is snake_case; tolerate camelCase for forward compat.
+  const callId = str(payload['call_id']) ?? str(payload['callId']);
+  if (callId !== undefined) {
+    result.toolCallId = callId;
+  }
+  return result;
+}
 
-    case OPENUI_WIRE_EVENT.Fragment: {
-      const dialect = str(payload['dialect']);
-      const source = str(payload['source']);
-      if (dialect === undefined || source === undefined) {
-        return null;
-      }
-      const result: UiFragmentEvent = {
-        type: 'fragment',
-        dialect,
-        source,
-      };
-      // Wire field is snake_case; tolerate camelCase for forward compat.
-      const callId = str(payload['call_id']) ?? str(payload['callId']);
-      if (callId !== undefined) {
-        result.toolCallId = callId;
-      }
-      return result;
+/** Diagnostics on a document event, skipping any entry without a message. */
+function documentDiagnostics(raw: unknown): UiDocumentEvent['diagnostics'] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.filter(isRecord).flatMap((d) => {
+    const message = str(d['message']);
+    if (message === undefined) {
+      return [];
     }
-
-    case OPENUI_WIRE_EVENT.Document: {
-      const dialect = str(payload['dialect']);
-      if (dialect === undefined) {
-        return null;
-      }
-      const root = str(payload['root']) ?? null;
-      const rawDiagnostics = payload['diagnostics'];
-      const diagnostics: UiDocumentEvent['diagnostics'] = Array.isArray(rawDiagnostics)
-        ? rawDiagnostics.filter(isRecord).flatMap((d) => {
-            const message = str(d['message']);
-            if (message === undefined) {
-              return [];
-            }
-            const diagnostic: UiDocumentEvent['diagnostics'][number] = {
-              message,
-            };
-            if (typeof d['line'] === 'number') {
-              diagnostic.line = d['line'];
-            }
-            const source = str(d['source']);
-            if (source !== undefined) {
-              diagnostic.source = source;
-            }
-            return [
-              diagnostic,
-            ];
-          })
-        : [];
-      return {
-        type: 'document',
-        root,
-        dialect,
-        diagnostics,
-      };
+    const diagnostic: UiDocumentEvent['diagnostics'][number] = {
+      message,
+    };
+    if (typeof d['line'] === 'number') {
+      diagnostic.line = d['line'];
     }
+    const source = str(d['source']);
+    if (source !== undefined) {
+      diagnostic.source = source;
+    }
+    return [
+      diagnostic,
+    ];
+  });
+}
+
+/** `response.openui.document`: turn-end summary (root ref + diagnostics). */
+function documentEvent(payload: Record<string, unknown>): UiStreamEvent | null {
+  const dialect = str(payload['dialect']);
+  if (dialect === undefined) {
+    return null;
+  }
+  return {
+    type: 'document',
+    root: str(payload['root']) ?? null,
+    dialect,
+    diagnostics: documentDiagnostics(payload['diagnostics']),
+  };
+}
 
+/*
+ * Wire event -> stream event. Each case is its own function: the switch was one
+ * body holding every field-validation branch, which put it over the structural
+ * gate's per-function complexity ceiling.
+ */
+export function translateUiEvent(event: unknown): UiStreamEvent | null {
+  const payload = unwrapEvent(event);
+  if (!payload) {
+    return null;
+  }
+
+  switch (payload['type']) {
+    case 'tool.ui_fragment':
+      return toolFragmentEvent(payload);
+    case OPENUI_WIRE_EVENT.Statement:
+      return statementEvent(payload);
+    case OPENUI_WIRE_EVENT.Fragment:
+      return wireFragmentEvent(payload);
+    case OPENUI_WIRE_EVENT.Document:
+      return documentEvent(payload);
     default:
       return null;
   }
diff --git a/packages/agent/src/lib/stream-transformers.ts b/packages/agent/src/lib/stream-transformers.ts
index b35b56b9..f165b0de 100644
--- a/packages/agent/src/lib/stream-transformers.ts
+++ b/packages/agent/src/lib/stream-transformers.ts
@@ -6,6 +6,8 @@ import type {
   ClaudeTextCitation,
   UnsupportedContent,
 } from '../api-shape-helpers/claude-message.js';
+import type { UiStreamEvent } from './openui/ui-stream.js';
+import { translateUiEvent } from './openui/ui-stream.js';
 import type { ReusableReadableStream } from './reusable-stream.js';
 import {
   isFileCitationAnnotation,
@@ -1240,3 +1242,14 @@ export function getUnsupportedContentSummary(message: ClaudeMessage): Record<str
 
   return summary;
 }
+
+/*
+ * The OpenUI stream translation is re-exported from here rather than imported
+ * directly by `model-result.ts`. That module already depends on this one, and it
+ * sits at the structural gate's fan-out ceiling (`no_god_files` trips above 15
+ * outbound edges) — a 16th dependency for one translation call makes it a god
+ * file. Every wire-event → stream-event translation the loop performs already
+ * lives in this module, so this is where it belongs anyway.
+ */
+export type { UiStreamEvent };
+export { translateUiEvent };
diff --git a/packages/openui-playground/public/app.js b/packages/openui-playground/public/app.js
index c76d3496..bf6ab0a0 100644
--- a/packages/openui-playground/public/app.js
+++ b/packages/openui-playground/public/app.js
@@ -216,6 +216,100 @@ function propsOf(call) {
   return props;
 }
 
+/*
+ * Form controls and meters, split out of `renderCall` so neither function
+ * exceeds the structural gate's per-function complexity ceiling. `val` and
+ * `children` are passed in rather than recomputed — they close over `depth`.
+ */
+function renderControl(call, val) {
+  switch (call.fn) {
+    case 'Input': {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.className = 'ui-input';
+      input.placeholder = String(val('placeholder', ''));
+      const v = val('value', '');
+      if (v) {
+        input.value = String(v);
+      }
+      return input;
+    }
+    case 'Select': {
+      const select = document.createElement('select');
+      select.className = 'ui-select';
+      for (const opt of val('options', [])) {
+        const o = document.createElement('option');
+        o.textContent = String(opt);
+        select.appendChild(o);
+      }
+      return select;
+    }
+    case 'Button': {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = `ui-button ${val('variant', 'secondary')}`;
+      btn.textContent = String(val('label', 'Button'));
+      btn.addEventListener('click', () =>
+        setStatus('action fired (client event ingestion is Phase 3 — DEV-774)'),
+      );
+      return btn;
+    }
+    case 'Progress': {
+      const value = Math.min(100, Math.max(0, Number(val('value', 0))));
+      const bar = el('div', 'ui-progress', [
+        el('div'),
+      ]);
+      bar.firstChild.style.width = `${value}%`;
+      const label = val('label', null);
+      return label
+        ? el('div', null, [
+            textNode(String(label), 'ui-text muted'),
+            bar,
+          ])
+        : bar;
+    }
+    default:
+      return undefined; // not a control — caller falls through
+  }
+}
+
+/** Tabular data, split out for the same reason as `renderControl`. */
+function renderTable(val) {
+  const columns = val('columns', []);
+  const rows = val('rows', []);
+  const table = document.createElement('table');
+  table.className = 'ui-table';
+  if (Array.isArray(columns)) {
+    const tr = document.createElement('tr');
+    for (const c of columns) {
+      tr.appendChild(
+        el('th', null, [
+          document.createTextNode(String(c)),
+        ]),
+      );
+    }
+    table.appendChild(tr);
+  }
+  if (Array.isArray(rows)) {
+    for (const row of rows) {
+      const tr = document.createElement('tr');
+      for (const cell of Array.isArray(row)
+        ? row
+        : [
+            row,
+          ]) {
+        tr.appendChild(
+          el('td', null, [
+            document.createTextNode(String(cell)),
+          ]),
+        );
+      }
+      table.appendChild(tr);
+    }
+  }
+  return table;
+}
+
 function renderCall(call, depth) {
   if (call.builtin) {
     return null; // @Run/@Set/... are action steps, not DOM
@@ -227,6 +321,11 @@ function renderCall(call, depth) {
   };
   const children = (name) => (p[name] ? renderExpr(p[name], depth + 1) : null);
 
+  const control = renderControl(call, val);
+  if (control !== undefined) {
+    return control;
+  }
+
   switch (call.fn) {
     case 'Stack': {
       const node = el('div', `ui-stack${val('direction', 'column') === 'row' ? ' row' : ''}`, [
@@ -271,86 +370,8 @@ function renderCall(call, depth) {
     }
     case 'Badge':
       return textNode(String(val('text', '')), `ui-badge ${val('tone', 'neutral')}`);
-    case 'Table': {
-      const columns = val('columns', []);
-      const rows = val('rows', []);
-      const table = document.createElement('table');
-      table.className = 'ui-table';
-      if (Array.isArray(columns)) {
-        const tr = document.createElement('tr');
-        for (const c of columns) {
-          tr.appendChild(
-            el('th', null, [
-              document.createTextNode(String(c)),
-            ]),
-          );
-        }
-        table.appendChild(tr);
-      }
-      if (Array.isArray(rows)) {
-        for (const row of rows) {
-          const tr = document.createElement('tr');
-          for (const cell of Array.isArray(row)
-            ? row
-            : [
-                row,
-              ]) {
-            tr.appendChild(
-              el('td', null, [
-                document.createTextNode(String(cell)),
-              ]),
-            );
-          }
-          table.appendChild(tr);
-        }
-      }
-      return table;
-    }
-    case 'Input': {
-      const input = document.createElement('input');
-      input.type = 'text';
-      input.className = 'ui-input';
-      input.placeholder = String(val('placeholder', ''));
-      const v = val('value', '');
-      if (v) {
-        input.value = String(v);
-      }
-      return input;
-    }
-    case 'Select': {
-      const select = document.createElement('select');
-      select.className = 'ui-select';
-      for (const opt of val('options', [])) {
-        const o = document.createElement('option');
-        o.textContent = String(opt);
-        select.appendChild(o);
-      }
-      return select;
-    }
-    case 'Button': {
-      const btn = document.createElement('button');
-      btn.type = 'button';
-      btn.className = `ui-button ${val('variant', 'secondary')}`;
-      btn.textContent = String(val('label', 'Button'));
-      btn.addEventListener('click', () =>
-        setStatus('action fired (client event ingestion is Phase 3 — DEV-774)'),
-      );
-      return btn;
-    }
-    case 'Progress': {
-      const value = Math.min(100, Math.max(0, Number(val('value', 0))));
-      const bar = el('div', 'ui-progress', [
-        el('div'),
-      ]);
-      bar.firstChild.style.width = `${value}%`;
-      const label = val('label', null);
-      return label
-        ? el('div', null, [
-            textNode(String(label), 'ui-text muted'),
-            bar,
-          ])
-        : bar;
-    }
+    case 'Table':
+      return renderTable(val);
     case 'Query':
     case 'Mutation':
     case 'Action':
diff --git a/packages/openui-playground/src/generate.ts b/packages/openui-playground/src/generate.ts
index 9fcfab81..d427bcd1 100644
--- a/packages/openui-playground/src/generate.ts
+++ b/packages/openui-playground/src/generate.ts
@@ -14,7 +14,7 @@
  * count, token usage, cost) so the playground doubles as an eval harness.
  */
 
-import type { UiLibrary } from '@openrouter/agent';
+import type { UiLibrary, UiStreamEvent } from '@openrouter/agent';
 import { callModel, openui, serializeExpr } from '@openrouter/agent';
 import type { OpenRouterCore } from '@openrouter/sdk/core';
 import type { UiAssignment, UiDocument } from './lang/parser.js';
@@ -110,6 +110,31 @@ function extractUsage(response: unknown): UsageSummary {
   };
 }
 
+/*
+ * One native `getUiStream()` event -> one playground event. Split out of
+ * `generate` so the per-variant field mapping does not count toward that
+ * function's complexity, which the structural gate caps.
+ */
+function toPlaygroundEvent(event: UiStreamEvent, at: number, statements: number): PlaygroundEvent {
+  if (event.type === 'document') {
+    return {
+      type: 'document',
+      root: event.root,
+      dialect: event.dialect,
+      statements,
+      diagnostics: event.diagnostics.map((d) => ({
+        line: d.line ?? 0,
+        message: d.message,
+        source: d.source ?? '',
+      })),
+    };
+  }
+  return {
+    ...event,
+    at,
+  };
+}
+
 /**
  * Run one generation and yield playground events as they materialize.
  */
@@ -148,28 +173,8 @@ export async function* generate(
         }
         statements += 1;
         chars += event.source.length;
-        yield {
-          ...event,
-          at: Date.now() - start,
-        };
-      } else if (event.type === 'fragment') {
-        yield {
-          ...event,
-          at: Date.now() - start,
-        };
-      } else {
-        yield {
-          type: 'document',
-          root: event.root,
-          dialect: event.dialect,
-          statements,
-          diagnostics: event.diagnostics.map((d) => ({
-            line: d.line ?? 0,
-            message: d.message,
-            source: d.source ?? '',
-          })),
-        };
       }
+      yield toPlaygroundEvent(event, Date.now() - start, statements);
     }
 
     const usage = extractUsage(await result.getResponse());
diff --git a/packages/openui-playground/src/lang/parser.ts b/packages/openui-playground/src/lang/parser.ts
index 4eb5f1ba..6746117b 100644
--- a/packages/openui-playground/src/lang/parser.ts
+++ b/packages/openui-playground/src/lang/parser.ts
@@ -94,6 +94,32 @@ interface ScannedStatement {
  * Consume raw text, returning each completed top-level statement line.
  * Newlines inside brackets or strings do not terminate a statement.
  */
+/** Advance string-literal state for one character inside a string. */
+function scanInString(state: ScannerState, ch: string): void {
+  if (state.escaped) {
+    state.escaped = false;
+    return;
+  }
+  if (ch === '\\') {
+    state.escaped = true;
+    return;
+  }
+  if (ch === '"') {
+    state.inString = false;
+  }
+}
+
+/** Track bracket nesting so a statement can span lines. */
+function scanDepth(state: ScannerState, ch: string): void {
+  if (ch === '(' || ch === '[' || ch === '{') {
+    state.depth += 1;
+    return;
+  }
+  if (ch === ')' || ch === ']' || ch === '}') {
+    state.depth -= 1;
+  }
+}
+
 function scanStatements(state: ScannerState, text: string): ScannedStatement[] {
   const completed: ScannedStatement[] = [];
   for (const ch of text) {
@@ -103,26 +129,14 @@ function scanStatements(state: ScannerState, text: string): ScannedStatement[] {
     }
     state.buffer += ch;
     if (state.inString) {
-      if (state.escaped) {
-        state.escaped = false;
-      } else if (ch === '\\') {
-        state.escaped = true;
-      } else if (ch === '"') {
-        state.inString = false;
-      }
+      scanInString(state, ch);
       continue;
     }
     if (ch === '"') {
       state.inString = true;
       continue;
     }
-    if (ch === '(' || ch === '[' || ch === '{') {
-      state.depth += 1;
-      continue;
-    }
-    if (ch === ')' || ch === ']' || ch === '}') {
-      state.depth -= 1;
-    }
+    scanDepth(state, ch);
   }
   return completed;
 }

From e5759d34099ee2eec4e70ec3540e8d6c1586d796 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Mon, 3 Aug 2026 14:10:04 -0500
Subject: [PATCH 06/19] docs(agent): list getUiStream in the README stream
 table

The table of what each stream emits is the reference consumers use to
pick one; getUiStream was absent.
---
 packages/agent/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/agent/README.md b/packages/agent/README.md
index 86cdd66d..8ce73c9f 100644
--- a/packages/agent/README.md
+++ b/packages/agent/README.md
@@ -110,6 +110,7 @@ What each stream emits:
 | `getToolStream()` | tool-call **argument deltas**; `preliminary_result` events for generator tools — *not* execution results |
 | `getToolCallsStream()` | parsed tool calls as they complete |
 | `getItemsStream()` | all output items (messages, function calls, …) |
+| `getUiStream()` | OpenUI events — `statement` / `fragment` / `document` — from tools declaring `toUIOutput` and from the `openui` plugin |
 | `getFullResponsesStream()` | every response event, including `tool.result` / `tool.call_output` execution events |
 
 ### Tool Types

From b388f3506191d6b02f46dbd02636b0ada44ebe86 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Mon, 3 Aug 2026 19:02:59 -0500
Subject: [PATCH 07/19] fix(playground): escape diagnostic messages; label
 rendered controls
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two findings from cortex's review pass.

XSS: the diagnostics panel escaped `source` but interpolated `message` and
`line` raw into innerHTML. Every field there is model-controlled —
`ParseFailure.message` is built from the offending source line, and in
native mode diagnostics arrive verbatim off the wire — so a model could
inject markup by emitting a crafted statement. All three fields are now
escaped.

A11y: rendered Input/Select carried no accessible name, so a screen reader
announced an unlabelled field. Both signatures already have a `name` prop
that was going unused for labelling; it now sets aria-label (and the real
`name` attribute), falling back to the placeholder for Input.
---
 packages/openui-playground/public/app.js | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/packages/openui-playground/public/app.js b/packages/openui-playground/public/app.js
index bf6ab0a0..4e4b6396 100644
--- a/packages/openui-playground/public/app.js
+++ b/packages/openui-playground/public/app.js
@@ -232,11 +232,24 @@ function renderControl(call, val) {
       if (v) {
         input.value = String(v);
       }
+      // The signature's `name` is the only human label these controls carry;
+      // without it a screen reader announces an unlabelled text field. Fall
+      // back to the placeholder when a name wasn't supplied.
+      const inputLabel = String(val('name', '') || val('placeholder', ''));
+      if (inputLabel) {
+        input.setAttribute('aria-label', inputLabel);
+        input.name = String(val('name', ''));
+      }
       return input;
     }
     case 'Select': {
       const select = document.createElement('select');
       select.className = 'ui-select';
+      const selectLabel = String(val('name', ''));
+      if (selectLabel) {
+        select.setAttribute('aria-label', selectLabel);
+        select.name = selectLabel;
+      }
       for (const opt of val('options', [])) {
         const o = document.createElement('option');
         o.textContent = String(opt);
@@ -570,7 +583,14 @@ function handleEvent(event) {
     case 'document': {
       if (event.diagnostics.length) {
         $('diagnostics').innerHTML = event.diagnostics
-          .map((d) => `<div class="diag">L${d.line}: ${d.message} — ${escapeHtml(d.source)}</div>`)
+          // Every interpolated field is model-controlled: `source` is the
+          // offending line and `message` carries parser text built from it
+          // (ParseFailure.message), or arrives verbatim off the wire in native
+          // mode. Escaping only `source` left an injection through `message`.
+          .map(
+            (d) =>
+              `<div class="diag">L${escapeHtml(String(d.line))}: ${escapeHtml(d.message)} — ${escapeHtml(d.source)}</div>`,
+          )
           .join('');
       } else {
         $('diagnostics').innerHTML =

From 37f816dc68fe000f7c806e51c487182fb59670f8 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Mon, 3 Aug 2026 19:07:47 -0500
Subject: [PATCH 08/19] =?UTF-8?q?fix(openui):=20address=20cortex=20review?=
 =?UTF-8?q?=20=E2=80=94=20security,=20a11y,=20perf?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- escape diagnostic messages and history model names before innerHTML (XSS)
- bind playground server to 127.0.0.1 (API-key-backed endpoint)
- require trailing separator in static-file public-root prefix check
- validate uiRef/uiState/uiBuiltin names as identifiers at construction
- aria-label form controls from their name prop; progressbar ARIA + text %
- aria-live status/diagnostics regions; error frames no longer overwritten
  by the green 'done' status
- rename toUIOutput -> toUiOutput (match Ui casing convention pre-release)
- warn (tool name + call id) when toUiOutput throws instead of catch {}
- collect toUiOutput broadcasts and await as one batch off the follow-up
  critical path
- sticky regexes + charCode skipWs in the playground parser (was O(n^2))
- memoize openui(library) wire shape per library (WeakMap)
- drop the playground's no-op build script / outDir
---
 .changeset/openui-bindings.md                 |  4 +-
 packages/agent/README.md                      |  2 +-
 packages/agent/src/index.ts                   |  2 +-
 packages/agent/src/lib/model-result.ts        | 28 +++++++++----
 packages/agent/src/lib/openui/fragment.ts     | 21 ++++++++--
 packages/agent/src/lib/openui/plugin.ts       | 18 ++++++++
 packages/agent/src/lib/openui/ui-stream.ts    |  4 +-
 packages/agent/src/lib/tool-types.ts          | 10 ++---
 packages/agent/src/lib/tool.ts                | 26 ++++++------
 .../agent/tests/unit/openui-stream.test.ts    | 30 +++++++-------
 packages/openui-playground/package.json       |  1 -
 packages/openui-playground/public/app.js      | 41 +++++++++++++++++--
 packages/openui-playground/public/index.html  |  4 +-
 packages/openui-playground/src/lang/parser.ts | 21 ++++++++--
 packages/openui-playground/src/server.ts      | 10 +++--
 packages/openui-playground/tsconfig.json      |  3 +-
 16 files changed, 160 insertions(+), 65 deletions(-)

diff --git a/.changeset/openui-bindings.md b/.changeset/openui-bindings.md
index 049a851f..c6489672 100644
--- a/.changeset/openui-bindings.md
+++ b/.changeset/openui-bindings.md
@@ -2,7 +2,7 @@
 '@openrouter/agent': minor
 ---
 
-OpenUI bindings: a component-library model (`defineComponent`, `createLibrary`, `componentProps`), a typed fragment builder (`fragment`, `uiRef`, `uiState`, `uiBuiltin`), the `openui` plugin helper, `serializeExpr`/`OPENUI_LANG_DIALECT` for emitting OpenUI Lang, a `toUIOutput` tool option that renders a tool's result as UI, and `ModelResult.getUiStream()` for consuming fragments as they arrive.
+OpenUI bindings: a component-library model (`defineComponent`, `createLibrary`, `componentProps`), a typed fragment builder (`fragment`, `uiRef`, `uiState`, `uiBuiltin`), the `openui` plugin helper, `serializeExpr`/`OPENUI_LANG_DIALECT` for emitting OpenUI Lang, a `toUiOutput` tool option that renders a tool's result as UI, and `ModelResult.getUiStream()` for consuming fragments as they arrive.
 
 A tool declares how its output renders, and the caller streams the fragments:
 
@@ -48,7 +48,7 @@ const weather = tool({
     summary: `Clear in ${city}`,
   }),
   // Renders the tool's result instead of leaving the model to describe it.
-  toUIOutput: ({ input, output }) =>
+  toUiOutput: ({ input, output }) =>
     ui.Card(input.city, [
       ui.Text(output.summary),
     ]),
diff --git a/packages/agent/README.md b/packages/agent/README.md
index 8ce73c9f..fe988d5e 100644
--- a/packages/agent/README.md
+++ b/packages/agent/README.md
@@ -110,7 +110,7 @@ What each stream emits:
 | `getToolStream()` | tool-call **argument deltas**; `preliminary_result` events for generator tools — *not* execution results |
 | `getToolCallsStream()` | parsed tool calls as they complete |
 | `getItemsStream()` | all output items (messages, function calls, …) |
-| `getUiStream()` | OpenUI events — `statement` / `fragment` / `document` — from tools declaring `toUIOutput` and from the `openui` plugin |
+| `getUiStream()` | OpenUI events — `statement` / `fragment` / `document` — from tools declaring `toUiOutput` and from the `openui` plugin |
 | `getFullResponsesStream()` | every response event, including `tool.result` / `tool.call_output` execution events |
 
 ### Tool Types
diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts
index fc094e20..8bbbbea8 100644
--- a/packages/agent/src/index.ts
+++ b/packages/agent/src/index.ts
@@ -286,7 +286,7 @@ export type {
   ToolUiFragmentEvent,
   ToolWithExecute,
   ToolWithGenerator,
-  ToUIOutputFunction,
+  ToUiOutputFunction,
   TurnContext,
   TurnEndEvent,
   TurnStartEvent,
diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index ebf60e56..3b7b419c 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -2582,6 +2582,10 @@ export class ModelResult<
     const settledResults = await Promise.allSettled(toolCallPromises);
     const toolResults: models.FunctionCallOutputItem[] = [];
     const pausedCalls: ParsedToolCall<Tool>[] = [];
+    // Render-only work (toUiOutput) collected during aggregation and awaited
+    // as one batch below, so user-supplied fragment builders don't serially
+    // delay the follow-up model turn.
+    const uiFragmentPromises: Promise<void>[] = [];
 
     for (let i = 0; i < settledResults.length; i++) {
       const settled = settledResults[i];
@@ -2673,9 +2677,13 @@ export class ModelResult<
         timestamp: Date.now(),
       } satisfies ToolCallOutputEvent);
 
-      await this.broadcastUiFragment(value);
+      uiFragmentPromises.push(this.broadcastUiFragment(value));
     }
 
+    // broadcastUiFragment never rejects (errors degrade to a console.warn),
+    // so a plain all() is safe here.
+    await Promise.all(uiFragmentPromises);
+
     return {
       toolResults,
       pausedCalls,
@@ -2685,7 +2693,7 @@ export class ModelResult<
   /**
    * Compute and broadcast a tool-authored OpenUI fragment for a successful
    * execution. Render-only: the fragment never reaches the model, so a
-   * throwing `toUIOutput` degrades to "no fragment" instead of failing the
+   * throwing `toUiOutput` degrades to "no fragment" instead of failing the
    * round — the model-facing output has already been pushed.
    */
   private async broadcastUiFragment(value: {
@@ -2699,7 +2707,7 @@ export class ModelResult<
     if (
       value.result.error ||
       !isAutoResolvableTool(value.tool) ||
-      !value.tool.function.toUIOutput
+      !value.tool.function.toUiOutput
     ) {
       return;
     }
@@ -2708,7 +2716,7 @@ export class ModelResult<
       return;
     }
     try {
-      const fragment = await value.tool.function.toUIOutput({
+      const fragment = await value.tool.function.toUiOutput({
         output: value.result.result,
         input: rawArgs,
       });
@@ -2725,8 +2733,14 @@ export class ModelResult<
         },
         timestamp: Date.now(),
       } satisfies ToolUiFragmentEvent);
-    } catch {
-      // Fragment construction failed — drop it; rendering is best-effort.
+    } catch (error) {
+      // Fragment construction failed — drop it; rendering is best-effort. But
+      // surface the cause, or a throwing toUiOutput is undebuggable ("no
+      // fragment ever arrives", with nothing in the console).
+      console.warn(
+        `toUiOutput for tool "${value.toolCall.name}" (call ${value.toolCall.id}) threw; dropping UI fragment:`,
+        error,
+      );
     }
   }
 
@@ -4648,7 +4662,7 @@ export class ModelResult<
    * Stream OpenUI events from all turns: completed OpenUI Lang statements
    * authored by the model (`response.openui.*` wire events from the `openui`
    * plugin) and tool-authored fragments (`tool.ui_fragment` events produced
-   * by tools declaring `toUIOutput`).
+   * by tools declaring `toUiOutput`).
    *
    * Wire events not yet in the SDK's stream-event union arrive through its
    * forward-compat catch-all; translation reads the raw payload, so this
diff --git a/packages/agent/src/lib/openui/fragment.ts b/packages/agent/src/lib/openui/fragment.ts
index 3e86185a..38bde498 100644
--- a/packages/agent/src/lib/openui/fragment.ts
+++ b/packages/agent/src/lib/openui/fragment.ts
@@ -16,6 +16,21 @@ import { componentProps } from './library.js';
 
 const FRAGMENT_EXPR: unique symbol = Symbol.for('openrouter.openui.fragment-expr');
 
+/*
+ * Ref/state/builtin names are emitted verbatim into OpenUI Lang source (every
+ * other value channel is quoted/JSON-escaped by the serializer), so a name
+ * derived from model-controlled input could otherwise inject arbitrary
+ * expressions into what the client treats as trusted tool-authored UI.
+ */
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function assertIdent(kind: string, name: string): string {
+  if (!IDENT_RE.test(name)) {
+    throw new Error(`${kind} name ${JSON.stringify(name)} must match ${IDENT_RE.source}`);
+  }
+  return name;
+}
+
 /** A composable fragment node: a {@link UiFragment} that also nests as a child argument. */
 export interface FragmentNode extends UiFragment {
   [FRAGMENT_EXPR]: UiExpr;
@@ -71,7 +86,7 @@ function makeNode(dialect: string, expr: UiExpr): FragmentNode {
 export function uiRef(name: string, dialect?: string): FragmentNode {
   return makeNode(dialect ?? OPENUI_LANG_DIALECT, {
     kind: 'ref',
-    name,
+    name: assertIdent('uiRef', name),
   });
 }
 
@@ -79,7 +94,7 @@ export function uiRef(name: string, dialect?: string): FragmentNode {
 export function uiState(name: string, dialect?: string): FragmentNode {
   return makeNode(dialect ?? OPENUI_LANG_DIALECT, {
     kind: 'state-ref',
-    name,
+    name: assertIdent('uiState', name),
   });
 }
 
@@ -87,7 +102,7 @@ export function uiState(name: string, dialect?: string): FragmentNode {
 export function uiBuiltin(fn: string, ...args: FragmentArg[]): FragmentNode {
   return makeNode(OPENUI_LANG_DIALECT, {
     kind: 'call',
-    fn,
+    fn: assertIdent('uiBuiltin', fn),
     builtin: true,
     args: args.map(toExpr),
   });
diff --git a/packages/agent/src/lib/openui/plugin.ts b/packages/agent/src/lib/openui/plugin.ts
index 204dcf9d..0f32fb9d 100644
--- a/packages/agent/src/lib/openui/plugin.ts
+++ b/packages/agent/src/lib/openui/plugin.ts
@@ -29,6 +29,14 @@ export interface OpenUiPlugin {
   dialect?: string;
 }
 
+/*
+ * Libraries are immutable after `createLibrary`, so the wire shape (including
+ * the Zod→JSON-Schema conversion per component) is computed once per library
+ * rather than once per request — `plugins: [openui(library)]` inline per call
+ * is the documented usage.
+ */
+const wireCache = new WeakMap<UiLibrary, OpenUiPlugin>();
+
 /**
  * Build the `openui` plugin preference from a component library.
  *
@@ -42,6 +50,16 @@ export interface OpenUiPlugin {
  * ```
  */
 export function openui(library: UiLibrary): OpenUiPlugin {
+  const cached = wireCache.get(library);
+  if (cached) {
+    return cached;
+  }
+  const plugin = buildPlugin(library);
+  wireCache.set(library, plugin);
+  return plugin;
+}
+
+function buildPlugin(library: UiLibrary): OpenUiPlugin {
   return {
     id: 'openui',
     library: [
diff --git a/packages/agent/src/lib/openui/ui-stream.ts b/packages/agent/src/lib/openui/ui-stream.ts
index 7796cb1f..6d8910cb 100644
--- a/packages/agent/src/lib/openui/ui-stream.ts
+++ b/packages/agent/src/lib/openui/ui-stream.ts
@@ -4,7 +4,7 @@
  *
  * Two sources feed the UI stream:
  * - `tool.ui_fragment` — SDK-synthetic events broadcast when a local tool's
- *   `toUIOutput` produces a fragment.
+ *   `toUiOutput` produces a fragment.
  * - `response.openui.*` — API wire events emitted by the `openui` plugin.
  *   Until `@openrouter/sdk` regenerates with these union members (DEV-772),
  *   they arrive through the SDK's forward-compat catch-all as
@@ -23,7 +23,7 @@ export interface UiStatementEvent {
   source: string;
 }
 
-/** A tool-authored fragment (local `toUIOutput` or API `response.openui.fragment`). */
+/** A tool-authored fragment (local `toUiOutput` or API `response.openui.fragment`). */
 export interface UiFragmentEvent {
   type: 'fragment';
   /** The tool call this fragment belongs to, when tool-authored. */
diff --git a/packages/agent/src/lib/tool-types.ts b/packages/agent/src/lib/tool-types.ts
index 5c8e798e..71a4a537 100644
--- a/packages/agent/src/lib/tool-types.ts
+++ b/packages/agent/src/lib/tool-types.ts
@@ -275,7 +275,7 @@ export type ToModelOutputFunction<TInput, TOutput> = {
  * @template TOutput - The tool's output type
  */
 // Object-with-method form for bivariant param checking — see ToModelOutputFunction.
-export type ToUIOutputFunction<TInput, TOutput> = {
+export type ToUiOutputFunction<TInput, TOutput> = {
   bivarianceHack(params: {
     output: TOutput;
     input: TInput;
@@ -337,7 +337,7 @@ export interface ToolFunctionWithExecute<
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  toUiOutput?: ToUiOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 }
 
 /**
@@ -380,7 +380,7 @@ export interface ToolFunctionWithGenerator<
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  toUiOutput?: ToUiOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 }
 
 /**
@@ -431,7 +431,7 @@ export interface HITLToolFunction<
   ): Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  toUiOutput?: ToUiOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 }
 
 /**
@@ -990,7 +990,7 @@ export type ToolCallOutputEvent = {
 /**
  * Tool UI fragment event carrying a tool-authored OpenUI fragment.
  * Broadcast by executeToolRound after a successful execution when the tool
- * declares `toUIOutput`. Client-render only — never sent to the model.
+ * declares `toUiOutput`. Client-render only — never sent to the model.
  */
 export type ToolUiFragmentEvent = {
   type: 'tool.ui_fragment';
diff --git a/packages/agent/src/lib/tool.ts b/packages/agent/src/lib/tool.ts
index 72a76cf9..3661ce02 100644
--- a/packages/agent/src/lib/tool.ts
+++ b/packages/agent/src/lib/tool.ts
@@ -15,7 +15,7 @@ import type {
   ToolLoopKey,
   ToolWithExecute,
   ToolWithGenerator,
-  ToUIOutputFunction,
+  ToUiOutputFunction,
 } from './tool-types.js';
 import { isClientTool, SHARED_CONTEXT_KEY, ToolType } from './tool-types.js';
 
@@ -50,7 +50,7 @@ type RegularToolConfigWithOutput<
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  toUiOutput?: ToUiOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 };
 
 /**
@@ -80,7 +80,7 @@ type RegularToolConfigWithoutOutput<
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, TReturn>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, TReturn>;
+  toUiOutput?: ToUiOutputFunction<zodInfer<TInput>, TReturn>;
 };
 
 /**
@@ -111,7 +111,7 @@ type GeneratorToolConfig<
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  toUiOutput?: ToUiOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 };
 
 /**
@@ -179,7 +179,7 @@ type HITLToolConfig<
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
+  toUiOutput?: ToUiOutputFunction<zodInfer<TInput>, zodInfer<TOutput>>;
 };
 
 /**
@@ -213,7 +213,7 @@ type ToolConfigWithSharedContext<
   /** Convert tool execution output to model-facing output */
   toModelOutput?: ToModelOutputFunction<Record<string, unknown>, unknown>;
   /** Convert tool execution output to a renderable OpenUI fragment */
-  toUIOutput?: ToUIOutputFunction<Record<string, unknown>, unknown>;
+  toUiOutput?: ToUiOutputFunction<Record<string, unknown>, unknown>;
 };
 
 //#endregion
@@ -390,8 +390,8 @@ export function tool(
       fn.toModelOutput = config.toModelOutput;
     }
 
-    if (config.toUIOutput !== undefined) {
-      fn.toUIOutput = config.toUIOutput;
+    if (config.toUiOutput !== undefined) {
+      fn.toUiOutput = config.toUiOutput;
     }
 
     return {
@@ -479,8 +479,8 @@ export function tool(
       fn.toModelOutput = config.toModelOutput;
     }
 
-    if ('toUIOutput' in config && config.toUIOutput !== undefined) {
-      fn.toUIOutput = config.toUIOutput;
+    if ('toUiOutput' in config && config.toUiOutput !== undefined) {
+      fn.toUiOutput = config.toUiOutput;
     }
 
     return {
@@ -516,9 +516,9 @@ export function tool(
       config.toModelOutput !== undefined && {
         toModelOutput: config.toModelOutput,
       }),
-    ...('toUIOutput' in config &&
-      config.toUIOutput !== undefined && {
-        toUIOutput: config.toUIOutput,
+    ...('toUiOutput' in config &&
+      config.toUiOutput !== undefined && {
+        toUiOutput: config.toUiOutput,
       }),
   };
 
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index a13ea237..e31285a5 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -1,5 +1,5 @@
 /**
- * Tests for the OpenUI streaming half: toUIOutput plumbing through tool(),
+ * Tests for the OpenUI streaming half: toUiOutput plumbing through tool(),
  * the tool.ui_fragment broadcast, translateUiEvent (including the SDK's
  * forward-compat Unknown encoding of response.openui.* wire events), and
  * getUiStream()'s no-tools fast path.
@@ -32,7 +32,7 @@ const library = createLibrary([
 ]);
 const ui = fragment(library);
 
-describe('tool() carries toUIOutput', () => {
+describe('tool() carries toUiOutput', () => {
   it('regular tool', () => {
     const t = tool({
       name: 'usage',
@@ -42,9 +42,9 @@ describe('tool() carries toUIOutput', () => {
       execute: async () => ({
         total: 12,
       }),
-      toUIOutput: ({ output }) => ui.Card(`$${output.total}`),
+      toUiOutput: ({ output }) => ui.Card(`$${output.total}`),
     });
-    expect(t.function.toUIOutput).toBeTypeOf('function');
+    expect(t.function.toUiOutput).toBeTypeOf('function');
   });
 
   it('generator tool', () => {
@@ -62,9 +62,9 @@ describe('tool() carries toUIOutput', () => {
           done: true,
         };
       },
-      toUIOutput: () => ui.Text('done'),
+      toUiOutput: () => ui.Text('done'),
     });
-    expect(t.function.toUIOutput).toBeTypeOf('function');
+    expect(t.function.toUiOutput).toBeTypeOf('function');
   });
 
   it('HITL tool', () => {
@@ -75,9 +75,9 @@ describe('tool() carries toUIOutput', () => {
         ok: z.boolean(),
       }),
       onToolCalled: () => null,
-      toUIOutput: () => ui.Text('pending'),
+      toUiOutput: () => ui.Text('pending'),
     });
-    expect(t.function.toUIOutput).toBeTypeOf('function');
+    expect(t.function.toUiOutput).toBeTypeOf('function');
   });
 
   it('omitted stays absent', () => {
@@ -86,7 +86,7 @@ describe('tool() carries toUIOutput', () => {
       inputSchema: z.object({}),
       execute: async () => 'ok',
     });
-    expect('toUIOutput' in t.function && t.function.toUIOutput !== undefined).toBe(false);
+    expect('toUiOutput' in t.function && t.function.toUiOutput !== undefined).toBe(false);
   });
 });
 
@@ -394,7 +394,7 @@ describe('broadcastUiFragment', () => {
       execute: async () => ({
         total: 12,
       }),
-      toUIOutput: ({ output, input }) => ui.Card(`$${output.total} over ${input.days}d`),
+      toUiOutput: ({ output, input }) => ui.Card(`$${output.total} over ${input.days}d`),
     });
 
     await internal.broadcastUiFragment(
@@ -419,7 +419,7 @@ describe('broadcastUiFragment', () => {
     });
   });
 
-  it('skips tools without toUIOutput and errored executions', async () => {
+  it('skips tools without toUiOutput and errored executions', async () => {
     const { internal, pushed } = makeHarness();
     const plain = tool({
       name: 'plain',
@@ -440,7 +440,7 @@ describe('broadcastUiFragment', () => {
         days: z.number(),
       }),
       execute: async () => 'ok',
-      toUIOutput: () => ui.Text('never'),
+      toUiOutput: () => ui.Text('never'),
     });
     await internal.broadcastUiFragment(
       makeCall(withUi, {
@@ -452,7 +452,7 @@ describe('broadcastUiFragment', () => {
     expect(pushed).toEqual([]);
   });
 
-  it('drops the fragment when toUIOutput returns null or throws', async () => {
+  it('drops the fragment when toUiOutput returns null or throws', async () => {
     const { internal, pushed } = makeHarness();
     const nullTool = tool({
       name: 'null_ui',
@@ -460,7 +460,7 @@ describe('broadcastUiFragment', () => {
         days: z.number(),
       }),
       execute: async () => 'ok',
-      toUIOutput: () => null,
+      toUiOutput: () => null,
     });
     await internal.broadcastUiFragment(
       makeCall(nullTool, {
@@ -474,7 +474,7 @@ describe('broadcastUiFragment', () => {
         days: z.number(),
       }),
       execute: async () => 'ok',
-      toUIOutput: () => {
+      toUiOutput: () => {
         throw new Error('render bug');
       },
     });
diff --git a/packages/openui-playground/package.json b/packages/openui-playground/package.json
index 5df05291..fb54fd1b 100644
--- a/packages/openui-playground/package.json
+++ b/packages/openui-playground/package.json
@@ -7,7 +7,6 @@
   "scripts": {
     "lint": "biome check src tests public",
     "lint:fix": "biome check --write src tests public",
-    "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest --run",
     "dev": "tsx watch src/server.ts",
diff --git a/packages/openui-playground/public/app.js b/packages/openui-playground/public/app.js
index bf6ab0a0..2317289f 100644
--- a/packages/openui-playground/public/app.js
+++ b/packages/openui-playground/public/app.js
@@ -228,6 +228,12 @@ function renderControl(call, val) {
       input.type = 'text';
       input.className = 'ui-input';
       input.placeholder = String(val('placeholder', ''));
+      // Placeholder text is not an accessible name — surface `name` to AT.
+      const name = val('name', '');
+      if (name) {
+        input.name = String(name);
+        input.setAttribute('aria-label', String(name));
+      }
       const v = val('value', '');
       if (v) {
         input.value = String(v);
@@ -237,6 +243,11 @@ function renderControl(call, val) {
     case 'Select': {
       const select = document.createElement('select');
       select.className = 'ui-select';
+      const name = val('name', '');
+      if (name) {
+        select.name = String(name);
+        select.setAttribute('aria-label', String(name));
+      }
       for (const opt of val('options', [])) {
         const o = document.createElement('option');
         o.textContent = String(opt);
@@ -260,10 +271,18 @@ function renderControl(call, val) {
         el('div'),
       ]);
       bar.firstChild.style.width = `${value}%`;
+      // The fill width is invisible to AT — mirror the value into ARIA.
+      bar.setAttribute('role', 'progressbar');
+      bar.setAttribute('aria-valuenow', String(value));
+      bar.setAttribute('aria-valuemin', '0');
+      bar.setAttribute('aria-valuemax', '100');
       const label = val('label', null);
+      if (label) {
+        bar.setAttribute('aria-label', String(label));
+      }
       return label
         ? el('div', null, [
-            textNode(String(label), 'ui-text muted'),
+            textNode(`${String(label)} (${value}%)`, 'ui-text muted'),
             bar,
           ])
         : bar;
@@ -445,7 +464,7 @@ function renderHistory() {
   const rows = history
     .map(
       (h) =>
-        `<tr><td>${h.model} · ${h.mode}</td><td>${h.ttfbMs ?? '—'}</td><td>${h.firstStatementMs ?? '—'}</td><td>${h.totalMs}</td><td>${h.statements}</td><td>${h.diagnostics}</td><td>${h.outputTokens ?? '—'}</td><td>${h.cost !== null ? `$${h.cost.toFixed(5)}` : '—'}</td></tr>`,
+        `<tr><td>${escapeHtml(`${h.model} · ${h.mode}`)}</td><td>${h.ttfbMs ?? '—'}</td><td>${h.firstStatementMs ?? '—'}</td><td>${h.totalMs}</td><td>${h.statements}</td><td>${h.diagnostics}</td><td>${h.outputTokens ?? '—'}</td><td>${h.cost !== null ? `$${h.cost.toFixed(5)}` : '—'}</td></tr>`,
     )
     .join('');
   $('history').innerHTML =
@@ -478,9 +497,17 @@ async function boot() {
   }
 }
 
+/*
+ * Whether the current run streamed an `error` frame. The server always ends
+ * the SSE stream normally after an error frame, so `run()` must not overwrite
+ * the error status with a green "done" when the reader drains.
+ */
+let streamErrored = false;
+
 async function run() {
   const runBtn = $('run');
   runBtn.disabled = true;
+  streamErrored = false;
   resetDoc();
   $('lang').replaceChildren();
   $('events').textContent = '';
@@ -537,7 +564,9 @@ async function run() {
         handleEvent(JSON.parse(payload));
       }
     }
-    setStatus('done');
+    if (!streamErrored) {
+      setStatus('done');
+    }
   } catch (error) {
     setStatus(String(error.message ?? error), true);
   } finally {
@@ -570,7 +599,10 @@ function handleEvent(event) {
     case 'document': {
       if (event.diagnostics.length) {
         $('diagnostics').innerHTML = event.diagnostics
-          .map((d) => `<div class="diag">L${d.line}: ${d.message} — ${escapeHtml(d.source)}</div>`)
+          .map(
+            (d) =>
+              `<div class="diag">L${d.line}: ${escapeHtml(d.message)} — ${escapeHtml(d.source)}</div>`,
+          )
           .join('');
       } else {
         $('diagnostics').innerHTML =
@@ -584,6 +616,7 @@ function handleEvent(event) {
       renderHistory();
       break;
     case 'error':
+      streamErrored = true;
       setStatus(event.message, true);
       break;
   }
diff --git a/packages/openui-playground/public/index.html b/packages/openui-playground/public/index.html
index c05757fe..6aac0969 100644
--- a/packages/openui-playground/public/index.html
+++ b/packages/openui-playground/public/index.html
@@ -100,7 +100,7 @@
 <header>
   <h1>OpenUI Playground</h1>
   <span class="dialect" id="dialect"></span>
-  <span class="dialect" style="margin-left:auto" id="status"></span>
+  <span class="dialect" style="margin-left:auto" id="status" role="status" aria-live="polite"></span>
 </header>
 <main>
   <div class="col">
@@ -130,7 +130,7 @@ <h2 class="pane">Library prompt sent to the model</h2>
     <h2 class="pane">Rendered surface</h2>
     <div id="surface"><div class="placeholder">Run a prompt to render generated UI here.</div></div>
     <h2 class="pane">Diagnostics</h2>
-    <div id="diagnostics"><span style="color:var(--muted)">—</span></div>
+    <div id="diagnostics" aria-live="polite"><span style="color:var(--muted)">—</span></div>
   </div>
 
   <div class="col">
diff --git a/packages/openui-playground/src/lang/parser.ts b/packages/openui-playground/src/lang/parser.ts
index 6746117b..e5183f2a 100644
--- a/packages/openui-playground/src/lang/parser.ts
+++ b/packages/openui-playground/src/lang/parser.ts
@@ -407,8 +407,14 @@ class ExprParser {
     }
   }
 
+  // Sticky (`y`) regexes anchored via `lastIndex` — scanning must not slice
+  // the remaining source per token, or long statements parse in O(n²).
+  private static readonly NUMBER_RE = /-?\d+(\.\d+)?([eE][+-]?\d+)?/y;
+  private static readonly IDENT_RE = /[A-Za-z_][A-Za-z0-9_]*/y;
+
   private parseNumber(): number {
-    const match = /^-?\d+(\.\d+)?([eE][+-]?\d+)?/.exec(this.src.slice(this.pos));
+    ExprParser.NUMBER_RE.lastIndex = this.pos;
+    const match = ExprParser.NUMBER_RE.exec(this.src);
     if (!match) {
       throw new ParseFailure('invalid number');
     }
@@ -417,7 +423,8 @@ class ExprParser {
   }
 
   private parseIdent(): string {
-    const match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.src.slice(this.pos));
+    ExprParser.IDENT_RE.lastIndex = this.pos;
+    const match = ExprParser.IDENT_RE.exec(this.src);
     if (!match) {
       throw new ParseFailure(`expected identifier at '${this.src.slice(this.pos, this.pos + 8)}'`);
     }
@@ -438,8 +445,14 @@ class ExprParser {
   }
 
   private skipWs(): void {
-    while (this.pos < this.src.length && /\s/.test(this.src[this.pos] ?? '')) {
-      this.pos += 1;
+    // charCode comparison instead of a per-character regex: space, tab, LF, CR.
+    for (;;) {
+      const c = this.src.charCodeAt(this.pos);
+      if (c === 32 || c === 9 || c === 10 || c === 13) {
+        this.pos += 1;
+      } else {
+        return;
+      }
     }
   }
 }
diff --git a/packages/openui-playground/src/server.ts b/packages/openui-playground/src/server.ts
index 61ef09c6..64174c37 100644
--- a/packages/openui-playground/src/server.ts
+++ b/packages/openui-playground/src/server.ts
@@ -14,7 +14,7 @@
 import { readFile } from 'node:fs/promises';
 import type { ServerResponse } from 'node:http';
 import { createServer } from 'node:http';
-import { dirname, extname, join, normalize } from 'node:path';
+import { dirname, extname, join, normalize, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { OpenRouter } from '@openrouter/agent';
 import { demoLibrary } from './demo-library.js';
@@ -92,7 +92,9 @@ function parseGenerateRequest(body: unknown): GenerateRequest | null {
 async function serveStatic(res: ServerResponse, urlPath: string): Promise<void> {
   const rel = urlPath === '/' ? 'index.html' : urlPath.slice(1);
   const file = normalize(join(PUBLIC_DIR, rel));
-  if (!file.startsWith(PUBLIC_DIR)) {
+  // Trailing separator so `public.bak`/`public-anything` siblings can't
+  // satisfy a bare prefix check.
+  if (!file.startsWith(PUBLIC_DIR + sep)) {
     sendJson(res, 404, {
       error: 'not found',
     });
@@ -187,6 +189,8 @@ const server = createServer((req, res) => {
   });
 });
 
-server.listen(PORT, () => {
+// Local-only tool backed by the developer's API key — never expose it to the
+// LAN by listening on all interfaces.
+server.listen(PORT, '127.0.0.1', () => {
   console.log(`OpenUI playground → http://localhost:${PORT} (default model: ${DEFAULT_MODEL})`);
 });
diff --git a/packages/openui-playground/tsconfig.json b/packages/openui-playground/tsconfig.json
index 6412ea8d..6e3a0dad 100644
--- a/packages/openui-playground/tsconfig.json
+++ b/packages/openui-playground/tsconfig.json
@@ -1,9 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "outDir": "esm",
     "noEmit": true
   },
   "include": ["src", "tests"],
-  "exclude": ["node_modules", "esm"]
+  "exclude": ["node_modules"]
 }

From 3d4a582531126536af44c534c3a33e7a190b47e2 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 13:37:23 -0500
Subject: [PATCH 09/19] fix(openui): address review findings

---
 packages/agent/src/lib/openui/fragment.ts     | 40 +++++++++----------
 packages/agent/src/lib/openui/library.ts      | 11 +++++
 packages/agent/tests/unit/openui.test.ts      | 25 ++++++++++++
 packages/openui-playground/public/app.js      |  2 +-
 packages/openui-playground/src/generate.ts    |  5 ++-
 packages/openui-playground/src/lang/parser.ts | 25 +++++++++---
 .../openui-playground/tests/parser.test.ts    | 15 +++++++
 7 files changed, 94 insertions(+), 29 deletions(-)

diff --git a/packages/agent/src/lib/openui/fragment.ts b/packages/agent/src/lib/openui/fragment.ts
index e89be771..2ed54918 100644
--- a/packages/agent/src/lib/openui/fragment.ts
+++ b/packages/agent/src/lib/openui/fragment.ts
@@ -12,25 +12,10 @@ import * as z4 from 'zod/v4';
 import type { UiExpr, UiFragment, UiLiteralValue } from './document.js';
 import { OPENUI_LANG_DIALECT, OPENUI_ROOT_REF, serializeExpr } from './document.js';
 import type { UiLibrary } from './library.js';
-import { componentProps, OPENUI_BUILTIN_COMPONENTS } from './library.js';
+import { assertIdent, componentProps, OPENUI_BUILTIN_COMPONENTS } from './library.js';
 
 const FRAGMENT_EXPR: unique symbol = Symbol.for('openrouter.openui.fragment-expr');
 
-/*
- * Ref/state/builtin names are emitted verbatim into OpenUI Lang source (every
- * other value channel is quoted/JSON-escaped by the serializer), so a name
- * derived from model-controlled input could otherwise inject arbitrary
- * expressions into what the client treats as trusted tool-authored UI.
- */
-const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-
-function assertIdent(kind: string, name: string): string {
-  if (!IDENT_RE.test(name)) {
-    throw new Error(`${kind} name ${JSON.stringify(name)} must match ${IDENT_RE.source}`);
-  }
-  return name;
-}
-
 /** A composable fragment node: a {@link UiFragment} that also nests as a child argument. */
 export interface FragmentNode extends UiFragment {
   [FRAGMENT_EXPR]: UiExpr;
@@ -38,6 +23,7 @@ export interface FragmentNode extends UiFragment {
 
 /** Any value accepted as a fragment constructor argument. */
 export type FragmentArg =
+  | undefined
   | UiLiteralValue
   | FragmentNode
   | FragmentArg[]
@@ -62,10 +48,22 @@ function toExpr(arg: FragmentArg): UiExpr {
   if (typeof arg === 'object' && arg !== null) {
     return {
       kind: 'object',
-      entries: Object.entries(arg).map(([key, value]) => ({
-        key,
-        value: toExpr(value),
-      })),
+      entries: Object.entries(arg).flatMap(([key, value]) =>
+        value === undefined
+          ? []
+          : [
+              {
+                key,
+                value: toExpr(value),
+              },
+            ],
+      ),
+    };
+  }
+  if (arg === undefined) {
+    return {
+      kind: 'literal',
+      value: null,
     };
   }
   return {
@@ -137,7 +135,7 @@ export function fragment<N extends string>(library: UiLibrary<N>): FragmentBuild
       const exprs = args.map((arg, i) => {
         const expr = toExpr(arg);
         const prop = props[i];
-        if (prop && expr.kind === 'literal') {
+        if (arg !== undefined && prop && expr.kind === 'literal') {
           const parsed = z4.safeParse(prop.schema, expr.value);
           if (!parsed.success) {
             throw new Error(
diff --git a/packages/agent/src/lib/openui/library.ts b/packages/agent/src/lib/openui/library.ts
index 67188739..338b9e9e 100644
--- a/packages/agent/src/lib/openui/library.ts
+++ b/packages/agent/src/lib/openui/library.ts
@@ -24,10 +24,20 @@ export interface ComponentDefinition<N extends string = string> {
   props?: ZodObject<ZodRawShape>;
 }
 
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function assertIdent(kind: string, name: string): string {
+  if (!IDENT_RE.test(name)) {
+    throw new Error(`${kind} name ${JSON.stringify(name)} must match ${IDENT_RE.source}`);
+  }
+  return name;
+}
+
 /** Declare a component the model (or a tool) may render. */
 export function defineComponent<const N extends string>(
   def: ComponentDefinition<N>,
 ): ComponentDefinition<N> {
+  assertIdent('component', def.name);
   return def;
 }
 
@@ -61,6 +71,7 @@ export function createLibrary<const D extends readonly ComponentDefinition[]>(
 ): UiLibrary<D[number]['name']> {
   const components = new Map<string, ComponentDefinition>();
   for (const def of definitions) {
+    assertIdent('component', def.name);
     if (components.has(def.name)) {
       throw new Error(`duplicate component name '${def.name}' in library`);
     }
diff --git a/packages/agent/tests/unit/openui.test.ts b/packages/agent/tests/unit/openui.test.ts
index de6e7c31..0436e0e6 100644
--- a/packages/agent/tests/unit/openui.test.ts
+++ b/packages/agent/tests/unit/openui.test.ts
@@ -225,6 +225,21 @@ describe('createLibrary / componentProps', () => {
     ).toThrow(/duplicate component name 'A'/);
   });
 
+  it('rejects component names that are not identifiers', () => {
+    expect(() =>
+      defineComponent({
+        name: 'Card); injected = Text("pwned")',
+      }),
+    ).toThrow(/component name .* must match/);
+    expect(() =>
+      createLibrary([
+        {
+          name: 'Card-name',
+        },
+      ]),
+    ).toThrow(/component name .* must match/);
+  });
+
   it('reports prop signatures in declaration order with optionality', () => {
     const card = library.components.get('Card');
     expect(card).toBeDefined();
@@ -290,6 +305,16 @@ describe('fragment builder', () => {
     expect(wrapped.source).toBe('root = Card("W", [Text("ok"), {nested: [1, true, null]}])');
   });
 
+  it('serializes undefined arguments as null and omits undefined object properties', () => {
+    expect(ui.Card(undefined).source).toBe('root = Card(null)');
+    expect(
+      ui.Query('weather', {
+        city: undefined,
+        units: 'metric',
+      }).source,
+    ).toBe('root = Query("weather", {units: "metric"})');
+  });
+
   it('validates literal props at construction time', () => {
     expect(() => ui.Text(42)).toThrow(/Text\(\) prop 'value' rejects 42/);
   });
diff --git a/packages/openui-playground/public/app.js b/packages/openui-playground/public/app.js
index ccb56c9b..4941309b 100644
--- a/packages/openui-playground/public/app.js
+++ b/packages/openui-playground/public/app.js
@@ -92,7 +92,7 @@ function evalExpr(expr, depth = 0) {
     case 'member': {
       let base = evalExpr(expr.base, depth + 1);
       for (const key of expr.path) {
-        base = base !== null ? base[key] : null;
+        base = base === null || base === undefined ? undefined : base[key];
       }
       return base;
     }
diff --git a/packages/openui-playground/src/generate.ts b/packages/openui-playground/src/generate.ts
index 3b4277ab..dc628d49 100644
--- a/packages/openui-playground/src/generate.ts
+++ b/packages/openui-playground/src/generate.ts
@@ -148,6 +148,7 @@ export async function* generate(
   let ttfbMs: number | null = null;
   let firstStatementMs: number | null = null;
   let statements = 0;
+  let diagnostics = 0;
   let chars = 0;
 
   if (mode === 'native') {
@@ -173,6 +174,8 @@ export async function* generate(
         }
         statements += 1;
         chars += event.source.length;
+      } else if (event.type === 'document') {
+        diagnostics += event.diagnostics.length;
       }
       yield toPlaygroundEvent(event, Date.now() - start, statements);
     }
@@ -186,7 +189,7 @@ export async function* generate(
       firstStatementMs,
       totalMs: Date.now() - start,
       statements,
-      diagnostics: 0,
+      diagnostics,
       chars,
       ...usage,
     };
diff --git a/packages/openui-playground/src/lang/parser.ts b/packages/openui-playground/src/lang/parser.ts
index e5183f2a..25c77012 100644
--- a/packages/openui-playground/src/lang/parser.ts
+++ b/packages/openui-playground/src/lang/parser.ts
@@ -397,13 +397,26 @@ class ExprParser {
         throw new ParseFailure('unterminated escape');
       }
       this.pos += 1;
-      if (esc === 'n') {
-        out += '\n';
-      } else if (esc === 't') {
-        out += '\t';
-      } else {
-        out += esc;
+      if (esc === 'u') {
+        const hex = this.src.slice(this.pos, this.pos + 4);
+        if (!/^[0-9A-Fa-f]{4}$/.test(hex)) {
+          throw new ParseFailure(`invalid unicode escape '\\u${hex}'`);
+        }
+        out += String.fromCharCode(Number.parseInt(hex, 16));
+        this.pos += 4;
+        continue;
       }
+      const escaped = {
+        '"': '"',
+        '\\': '\\',
+        '/': '/',
+        b: '\b',
+        f: '\f',
+        n: '\n',
+        r: '\r',
+        t: '\t',
+      }[esc];
+      out += escaped ?? esc;
     }
   }
 
diff --git a/packages/openui-playground/tests/parser.test.ts b/packages/openui-playground/tests/parser.test.ts
index 30f3d9bb..f3f1db8b 100644
--- a/packages/openui-playground/tests/parser.test.ts
+++ b/packages/openui-playground/tests/parser.test.ts
@@ -1,3 +1,4 @@
+import { serializeExpr } from '@openrouter/agent';
 import { describe, expect, it } from 'vitest';
 import { OpenUiLangParser, parseDocument } from '../src/lang/parser.js';
 
@@ -161,6 +162,20 @@ describe('parseDocument (tolerance + semantics)', () => {
     });
   });
 
+  it('round-trips strings serialized by the SDK', () => {
+    const value = 'bell:\u0007 newline:\n tab:\t return:\r slash:\\ quote:"';
+    const source = serializeExpr({
+      kind: 'literal',
+      value,
+    });
+    const doc = parseDocument(`value = ${source}`);
+    expect(doc.diagnostics).toEqual([]);
+    expect(doc.assignments['value']?.expr).toEqual({
+      kind: 'literal',
+      value,
+    });
+  });
+
   it('reports unparseable expressions as diagnostics with the source line', () => {
     const doc = parseDocument('bad = Card(("unclosed"\ngood = Text("ok")');
     // The unbalanced paren swallows the newline; only one statement completes.

From 3cefbdcd95bffe8cc53496620021fa99998fc5ff Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 13:47:32 -0500
Subject: [PATCH 10/19] refactor(openui): simplify native diagnostics counting

---
 packages/openui-playground/src/generate.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/packages/openui-playground/src/generate.ts b/packages/openui-playground/src/generate.ts
index dc628d49..5ba035ee 100644
--- a/packages/openui-playground/src/generate.ts
+++ b/packages/openui-playground/src/generate.ts
@@ -115,6 +115,10 @@ function extractUsage(response: unknown): UsageSummary {
  * `generate` so the per-variant field mapping does not count toward that
  * function's complexity, which the structural gate caps.
  */
+function countDiagnostics(event: UiStreamEvent): number {
+  return event.type === 'document' ? event.diagnostics.length : 0;
+}
+
 function toPlaygroundEvent(event: UiStreamEvent, at: number, statements: number): PlaygroundEvent {
   if (event.type === 'document') {
     return {
@@ -174,9 +178,8 @@ export async function* generate(
         }
         statements += 1;
         chars += event.source.length;
-      } else if (event.type === 'document') {
-        diagnostics += event.diagnostics.length;
       }
+      diagnostics += countDiagnostics(event);
       yield toPlaygroundEvent(event, Date.now() - start, statements);
     }
 

From 829a94c1d45d5fceaa1b68443befbb1c7d808284 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 14:29:02 -0500
Subject: [PATCH 11/19] fix(agent): bound OpenUI fragment rendering

---
 packages/agent/src/index.ts                   |   1 +
 packages/agent/src/lib/model-result.ts        |  31 +++-
 packages/agent/src/lib/openui/fragment.ts     |  26 +++-
 packages/agent/src/lib/openui/index.ts        |   1 +
 .../agent/tests/unit/openui-stream.test.ts    | 133 ++++++++++++++++--
 packages/agent/tests/unit/openui.test.ts      |  16 +++
 6 files changed, 187 insertions(+), 21 deletions(-)

diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts
index 11b98a21..9f3e933c 100644
--- a/packages/agent/src/index.ts
+++ b/packages/agent/src/index.ts
@@ -210,6 +210,7 @@ export type {
   OpenUiPlugin,
   OpenUiWireComponent,
   PropSignature,
+  UiBuiltinOptions,
   UiDocumentEvent,
   UiExpr,
   UiFragment,
diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index 40a6538d..12fe6ace 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -143,6 +143,8 @@ import {
 export const DEFAULT_FINAL_RESPONSE_DIRECTIVE =
   'You have reached the tool-use limit, and tools are no longer available. Do not attempt to call any more tools. Using the information you already have, write your final answer now.';
 
+const UI_FRAGMENT_RENDER_TIMEOUT_MS = 50;
+
 /**
  * Typeguard for plain-object records (non-null, non-array).
  */
@@ -3095,7 +3097,7 @@ export class ModelResult<
           (candidate) => isClientTool(candidate) && candidate.function.name === task.name,
         );
         if (tool) {
-          await this.broadcastUiFragment({
+          await this.awaitUiFragment({
             toolCall: {
               id: task.callId,
               name: task.name,
@@ -3675,11 +3677,9 @@ export class ModelResult<
         timestamp: Date.now(),
       } satisfies ToolCallOutputEvent);
 
-      uiFragmentPromises.push(this.broadcastUiFragment(value));
+      uiFragmentPromises.push(this.awaitUiFragment(value));
     }
 
-    // broadcastUiFragment never rejects (errors degrade to a console.warn),
-    // so a plain all() is safe here.
     await Promise.all(uiFragmentPromises);
 
     return {
@@ -3840,7 +3840,7 @@ export class ModelResult<
             },
           };
           const outputForModel = await this.computeToolOutputForModel(settledValue);
-          await this.broadcastUiFragment(settledValue);
+          await this.awaitUiFragment(settledValue);
           return {
             output: {
               type: 'function_call_output' as const,
@@ -4345,6 +4345,27 @@ export class ModelResult<
     };
   }
 
+  private awaitUiFragment(value: {
+    toolCall: ParsedToolCall<Tool>;
+    tool: Tool;
+    result: {
+      result: unknown;
+      error?: Error;
+    };
+  }): Promise<void> {
+    const rendering = this.broadcastUiFragment(value);
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, UI_FRAGMENT_RENDER_TIMEOUT_MS);
+      if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
+        timer.unref();
+      }
+      rendering.then(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+
   /**
    * Compute and broadcast a tool-authored OpenUI fragment for a successful
    * execution. Render-only: the fragment never reaches the model, so a
diff --git a/packages/agent/src/lib/openui/fragment.ts b/packages/agent/src/lib/openui/fragment.ts
index 2ed54918..fdd1e19e 100644
--- a/packages/agent/src/lib/openui/fragment.ts
+++ b/packages/agent/src/lib/openui/fragment.ts
@@ -96,9 +96,31 @@ export function uiState(name: string, dialect?: string): FragmentNode {
   });
 }
 
+/** Options for stamping a standalone built-in with a custom dialect. */
+export interface UiBuiltinOptions {
+  dialect?: string;
+}
+
 /** A built-in function step (`uiBuiltin('Run', uiRef('save'))` → `@Run(save)`). */
-export function uiBuiltin(fn: string, ...args: FragmentArg[]): FragmentNode {
-  return makeNode(OPENUI_LANG_DIALECT, {
+export function uiBuiltin(fn: string, ...args: FragmentArg[]): FragmentNode;
+export function uiBuiltin(
+  options: UiBuiltinOptions,
+  fn: string,
+  ...args: FragmentArg[]
+): FragmentNode;
+export function uiBuiltin(
+  fnOrOptions: string | UiBuiltinOptions,
+  ...fnAndArgs:
+    | [
+        string,
+        ...FragmentArg[],
+      ]
+    | FragmentArg[]
+): FragmentNode {
+  const hasOptions = typeof fnOrOptions !== 'string';
+  const fn = hasOptions ? (fnAndArgs[0] as string) : fnOrOptions;
+  const args = hasOptions ? fnAndArgs.slice(1) : fnAndArgs;
+  return makeNode(hasOptions ? (fnOrOptions.dialect ?? OPENUI_LANG_DIALECT) : OPENUI_LANG_DIALECT, {
     kind: 'call',
     fn: assertIdent('uiBuiltin', fn),
     builtin: true,
diff --git a/packages/agent/src/lib/openui/index.ts b/packages/agent/src/lib/openui/index.ts
index 78cf91f1..d18646b8 100644
--- a/packages/agent/src/lib/openui/index.ts
+++ b/packages/agent/src/lib/openui/index.ts
@@ -19,6 +19,7 @@ export {
   type FragmentBuilder,
   type FragmentNode,
   fragment,
+  type UiBuiltinOptions,
   uiBuiltin,
   uiRef,
   uiState,
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index e93886cb..55d2858a 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -40,6 +40,56 @@ const library = createLibrary([
 ]);
 const ui = fragment(library);
 
+const response = (id: string, output: models.OpenResponsesResult['output']) =>
+  ({
+    id,
+    object: 'response',
+    createdAt: 0,
+    model: 'test-model',
+    status: 'completed',
+    output,
+    error: null,
+    incompleteDetails: null,
+    tools: [],
+    toolChoice: 'auto',
+    parallelToolCalls: false,
+  }) as models.OpenResponsesResult;
+
+function mockToolRound(toolName: string): void {
+  mockBetaResponsesSend
+    .mockResolvedValueOnce({
+      ok: true,
+      value: response('r1', [
+        {
+          type: 'function_call',
+          id: 'fc1',
+          callId: 'c1',
+          name: toolName,
+          arguments: '{}',
+          status: 'completed',
+        },
+      ]),
+    })
+    .mockResolvedValueOnce({
+      ok: true,
+      value: response('r2', [
+        {
+          type: 'message',
+          id: 'm1',
+          role: 'assistant',
+          status: 'completed',
+          content: [
+            {
+              type: 'output_text',
+              text: 'done',
+              annotations: [],
+            },
+          ],
+        },
+      ]),
+    });
+}
+
 describe('tool() carries toUiOutput', () => {
   it('regular tool', () => {
     const t = tool({
@@ -336,6 +386,75 @@ describe('getUiStream (no-tools fast path)', () => {
   });
 });
 
+describe('toUiOutput round lifecycle', () => {
+  it('does not block the run when rendering never settles', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockToolRound('hanging_ui');
+    const hanging = tool({
+      name: 'hanging_ui',
+      inputSchema: z.object({}),
+      execute: () => 'ok',
+      toUiOutput: () => new Promise(() => undefined),
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          hanging,
+        ] as const,
+      },
+    );
+
+    await expect(
+      Promise.race([
+        result.getText(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('run stalled')), 100)),
+      ]),
+    ).resolves.toBe('done');
+    expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
+  });
+
+  it('delivers a normally-fast fragment before the UI stream closes', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockToolRound('fast_ui');
+    const fast = tool({
+      name: 'fast_ui',
+      inputSchema: z.object({}),
+      execute: () => 'ok',
+      toUiOutput: () => ui.Text('ready'),
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          fast,
+        ] as const,
+      },
+    );
+    const events = [];
+
+    for await (const event of result.getUiStream()) {
+      events.push(event);
+    }
+
+    expect(events).toContainEqual({
+      type: 'fragment',
+      toolCallId: 'c1',
+      toolName: 'fast_ui',
+      dialect: 'openui-lang/0.5',
+      source: 'root = Text("ready")',
+    });
+  });
+});
+
 describe('async tool settlement', () => {
   it('emits UI after background work settles past its grace window', async () => {
     mockBetaResponsesSend.mockReset();
@@ -358,20 +477,6 @@ describe('async tool settlement', () => {
       run: () => gate,
       toUiOutput: ({ input, output }) => ui.Card(`${input.city}: ${output.summary}`),
     });
-    const response = (id: string, output: models.OpenResponsesResult['output']) =>
-      ({
-        id,
-        object: 'response',
-        createdAt: 0,
-        model: 'test-model',
-        status: 'completed',
-        output,
-        error: null,
-        incompleteDetails: null,
-        tools: [],
-        toolChoice: 'auto',
-        parallelToolCalls: false,
-      }) as models.OpenResponsesResult;
     mockBetaResponsesSend
       .mockResolvedValueOnce({
         ok: true,
diff --git a/packages/agent/tests/unit/openui.test.ts b/packages/agent/tests/unit/openui.test.ts
index 0436e0e6..49539f99 100644
--- a/packages/agent/tests/unit/openui.test.ts
+++ b/packages/agent/tests/unit/openui.test.ts
@@ -290,6 +290,22 @@ describe('fragment builder', () => {
     expect(ui.Query('weather', {}).source).toBe('root = Query("weather", {})');
   });
 
+  it('stamps standalone builtins with a custom library dialect', () => {
+    const custom = createLibrary([], {
+      dialect: 'openui-lang/0.6',
+    });
+    const node = uiBuiltin(
+      {
+        dialect: custom.dialect,
+      },
+      'Run',
+      uiRef('save', custom.dialect),
+    );
+
+    expect(node.dialect).toBe(custom.dialect);
+    expect(node.source).toBe('root = @Run(save)');
+  });
+
   it('accepts plain objects and arrays as args', () => {
     const node = ui.Text('ok');
     const wrapped = ui.Card('W', [

From 67011562d47553e96553375d762e51f6e878865c Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 14:54:18 -0500
Subject: [PATCH 12/19] fix(openui): finish review feedback

---
 packages/agent/src/lib/model-result.ts        | 59 +++++++-----
 .../agent/tests/unit/openui-stream.test.ts    | 90 +++++++++++++++----
 packages/openui-playground/public/app.js      | 15 +---
 .../openui-playground/public/render-utils.js  | 16 ++++
 packages/openui-playground/src/server.ts      | 10 +--
 packages/openui-playground/src/static.ts      |  6 ++
 .../openui-playground/tests/security.test.ts  | 40 +++++++++
 7 files changed, 180 insertions(+), 56 deletions(-)
 create mode 100644 packages/openui-playground/public/render-utils.js
 create mode 100644 packages/openui-playground/src/static.ts
 create mode 100644 packages/openui-playground/tests/security.test.ts

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index 12fe6ace..249cd8c6 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -143,8 +143,6 @@ import {
 export const DEFAULT_FINAL_RESPONSE_DIRECTIVE =
   'You have reached the tool-use limit, and tools are no longer available. Do not attempt to call any more tools. Using the information you already have, write your final answer now.';
 
-const UI_FRAGMENT_RENDER_TIMEOUT_MS = 50;
-
 /**
  * Typeguard for plain-object records (non-null, non-array).
  */
@@ -628,6 +626,7 @@ export class ModelResult<
   private turnBroadcaster: ToolEventBroadcaster<
     ResponseStreamEvent<InferToolEventsUnion<TTools>, InferToolOutputsUnion<TTools>>
   > | null = null;
+  private pendingUiFragments = new Set<Promise<void>>();
   private initialStreamPipeStarted = false;
   private initialPipePromise: Promise<void> | null = null;
 
@@ -1020,7 +1019,7 @@ export class ModelResult<
    * Set up the turn broadcaster with tool execution and return the consumer.
    * Used by stream methods that need to iterate over all turns.
    */
-  private startTurnBroadcasterExecution(): {
+  private startTurnBroadcasterExecution(options?: { drainUiFragments?: boolean }): {
     consumer: AsyncIterableIterator<
       ResponseStreamEvent<InferToolEventsUnion<TTools>, InferToolOutputsUnion<TTools>>
     >;
@@ -1037,6 +1036,9 @@ export class ModelResult<
       if (this.initialPipePromise) {
         await this.initialPipePromise;
       }
+      if (options?.drainUiFragments) {
+        await this.drainUiFragments();
+      }
       broadcaster.complete();
     });
     return {
@@ -3097,7 +3099,7 @@ export class ModelResult<
           (candidate) => isClientTool(candidate) && candidate.function.name === task.name,
         );
         if (tool) {
-          await this.awaitUiFragment({
+          this.dispatchUiFragment({
             toolCall: {
               id: task.callId,
               name: task.name,
@@ -3550,7 +3552,6 @@ export class ModelResult<
     const toolResults: models.FunctionCallOutputItem[] = [];
     const pausedCalls: ParsedToolCall<Tool>[] = [];
     const deferredTasks: PendingAsyncTool[] = [];
-    const uiFragmentPromises: Promise<void>[] = [];
 
     // Start ALL async invocations before consuming any outcome: the work
     // (and its grace window) begins in handleAsyncInvocation, so awaiting
@@ -3677,11 +3678,9 @@ export class ModelResult<
         timestamp: Date.now(),
       } satisfies ToolCallOutputEvent);
 
-      uiFragmentPromises.push(this.awaitUiFragment(value));
+      this.dispatchUiFragment(value);
     }
 
-    await Promise.all(uiFragmentPromises);
-
     return {
       toolResults,
       pausedCalls,
@@ -3840,7 +3839,7 @@ export class ModelResult<
             },
           };
           const outputForModel = await this.computeToolOutputForModel(settledValue);
-          await this.awaitUiFragment(settledValue);
+          this.dispatchUiFragment(settledValue);
           return {
             output: {
               type: 'function_call_output' as const,
@@ -4345,25 +4344,39 @@ export class ModelResult<
     };
   }
 
-  private awaitUiFragment(value: {
+  private dispatchUiFragment(value: {
     toolCall: ParsedToolCall<Tool>;
     tool: Tool;
     result: {
       result: unknown;
       error?: Error;
     };
-  }): Promise<void> {
+  }): void {
     const rendering = this.broadcastUiFragment(value);
-    return new Promise((resolve) => {
-      const timer = setTimeout(resolve, UI_FRAGMENT_RENDER_TIMEOUT_MS);
-      if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
-        timer.unref();
-      }
-      rendering.then(() => {
-        clearTimeout(timer);
-        resolve();
-      });
-    });
+    this.pendingUiFragments.add(rendering);
+    rendering.finally(() => this.pendingUiFragments.delete(rendering));
+  }
+
+  private async drainUiFragments(): Promise<void> {
+    if (this.pendingUiFragments.size === 0) {
+      return;
+    }
+    const timeoutMs = this.options.asyncTools?.drainTimeoutMs ?? 30_000;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    await Promise.race([
+      Promise.all([
+        ...this.pendingUiFragments,
+      ]),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+        if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
+          timer.unref();
+        }
+      }),
+    ]);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
   }
 
   /**
@@ -6853,7 +6866,9 @@ export class ModelResult<
         return;
       }
 
-      const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+      const { consumer, executionPromise } = this.startTurnBroadcasterExecution({
+        drainUiFragments: true,
+      });
 
       for await (const event of consumer) {
         const uiEvent = translateUiEvent(event);
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index 55d2858a..26d11d88 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -6,6 +6,7 @@
  */
 import type { OpenRouterCore } from '@openrouter/sdk/core';
 import type * as models from '@openrouter/sdk/models';
+import { StreamEvents$inboundSchema } from '@openrouter/sdk/models/streamevents';
 import { describe, expect, it, vi } from 'vitest';
 import { z } from 'zod/v4';
 import { callModel } from '../../src/inner-loop/call-model.js';
@@ -184,18 +185,21 @@ describe('translateUiEvent', () => {
     });
   });
 
-  it("unwraps the SDK's Unknown forward-compat encoding", () => {
-    const event = translateUiEvent({
+  it("unwraps the installed SDK's runtime Unknown encoding", () => {
+    const raw = {
+      type: 'response.openui.statement',
+      ref: '$tab',
+      kind: 'state',
+      source: '$tab = "overview"',
+    };
+    const encoded = StreamEvents$inboundSchema.parse(raw);
+
+    expect(encoded).toEqual({
       type: 'UNKNOWN',
       isUnknown: true,
-      raw: {
-        type: 'response.openui.statement',
-        ref: '$tab',
-        kind: 'state',
-        source: '$tab = "overview"',
-      },
+      raw,
     });
-    expect(event).toEqual({
+    expect(translateUiEvent(encoded)).toEqual({
       type: 'statement',
       ref: '$tab',
       kind: 'state',
@@ -418,14 +422,14 @@ describe('toUiOutput round lifecycle', () => {
     expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
   });
 
-  it('delivers a normally-fast fragment before the UI stream closes', async () => {
+  it('bounds UI-stream close with the configured drain deadline', async () => {
     mockBetaResponsesSend.mockReset();
-    mockToolRound('fast_ui');
-    const fast = tool({
-      name: 'fast_ui',
+    mockToolRound('hanging_ui');
+    const hanging = tool({
+      name: 'hanging_ui',
       inputSchema: z.object({}),
       execute: () => 'ok',
-      toUiOutput: () => ui.Text('ready'),
+      toUiOutput: () => new Promise(() => undefined),
     });
     const result = callModel(
       {
@@ -435,20 +439,72 @@ describe('toUiOutput round lifecycle', () => {
         model: 'test-model',
         input: 'test',
         tools: [
-          fast,
+          hanging,
         ] as const,
+        asyncTools: {
+          drainTimeoutMs: 10,
+        },
       },
     );
-    const events = [];
 
+    const events = [];
     for await (const event of result.getUiStream()) {
       events.push(event);
     }
 
+    expect(events).toEqual([]);
+    expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
+  });
+
+  it('advances the model while retaining ordinary async rendering until UI drain', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockToolRound('async_ui');
+    let release: (() => void) | undefined;
+    const rendering = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const asyncUi = tool({
+      name: 'async_ui',
+      inputSchema: z.object({}),
+      execute: () => 'ok',
+      toUiOutput: async () => {
+        await rendering;
+        return ui.Text('ready');
+      },
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          asyncUi,
+        ] as const,
+      },
+    );
+    const events: unknown[] = [];
+    async function consumeUiStream() {
+      for await (const event of result.getUiStream()) {
+        events.push(event);
+      }
+    }
+    const consuming = consumeUiStream();
+
+    await vi.waitFor(() => expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2));
+    expect(events).not.toContainEqual(
+      expect.objectContaining({
+        type: 'fragment',
+      }),
+    );
+    release?.();
+    await consuming;
+
     expect(events).toContainEqual({
       type: 'fragment',
       toolCallId: 'c1',
-      toolName: 'fast_ui',
+      toolName: 'async_ui',
       dialect: 'openui-lang/0.5',
       source: 'root = Text("ready")',
     });
diff --git a/packages/openui-playground/public/app.js b/packages/openui-playground/public/app.js
index 4941309b..ae2f90b6 100644
--- a/packages/openui-playground/public/app.js
+++ b/packages/openui-playground/public/app.js
@@ -7,6 +7,8 @@
  * client resolves refs/state and materializes DOM without its own parser.
  */
 
+import { escapeHtml, resolveMember } from './render-utils.js';
+
 const $ = (id) => document.getElementById(id);
 
 const PRESETS = [
@@ -89,13 +91,8 @@ function evalExpr(expr, depth = 0) {
       const target = doc.assignments.get(expr.name);
       return target ? evalExpr(target.expr, depth + 1) : null;
     }
-    case 'member': {
-      let base = evalExpr(expr.base, depth + 1);
-      for (const key of expr.path) {
-        base = base === null || base === undefined ? undefined : base[key];
-      }
-      return base;
-    }
+    case 'member':
+      return resolveMember(evalExpr(expr.base, depth + 1), expr.path);
     case 'call':
       return expr; // calls materialize as DOM, not values
     default:
@@ -628,9 +625,5 @@ function handleEvent(event) {
   }
 }
 
-function escapeHtml(s) {
-  return s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
-}
-
 $('run').addEventListener('click', run);
 boot().catch((error) => setStatus(String(error), true));
diff --git a/packages/openui-playground/public/render-utils.js b/packages/openui-playground/public/render-utils.js
new file mode 100644
index 00000000..2bd288a7
--- /dev/null
+++ b/packages/openui-playground/public/render-utils.js
@@ -0,0 +1,16 @@
+/** @param {any} base @param {string[]} path */
+export function resolveMember(base, path) {
+  let value = base;
+  for (const key of path) {
+    if (value === null || value === undefined) {
+      return undefined;
+    }
+    value = value[key];
+  }
+  return value;
+}
+
+/** @param {string} value */
+export function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
+}
diff --git a/packages/openui-playground/src/server.ts b/packages/openui-playground/src/server.ts
index 64174c37..95d81209 100644
--- a/packages/openui-playground/src/server.ts
+++ b/packages/openui-playground/src/server.ts
@@ -14,13 +14,14 @@
 import { readFile } from 'node:fs/promises';
 import type { ServerResponse } from 'node:http';
 import { createServer } from 'node:http';
-import { dirname, extname, join, normalize, sep } from 'node:path';
+import { dirname, extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { OpenRouter } from '@openrouter/agent';
 import { demoLibrary } from './demo-library.js';
 import type { GenerateRequest, PlaygroundEvent } from './generate.js';
 import { generate } from './generate.js';
 import { libraryPrompt } from './lang/prompt.js';
+import { resolveStaticPath } from './static.js';
 
 const PORT = Number(process.env['PORT'] ?? 5170);
 const DEFAULT_MODEL = process.env['OPENUI_PLAYGROUND_MODEL'] ?? 'anthropic/claude-sonnet-5';
@@ -90,11 +91,8 @@ function parseGenerateRequest(body: unknown): GenerateRequest | null {
 }
 
 async function serveStatic(res: ServerResponse, urlPath: string): Promise<void> {
-  const rel = urlPath === '/' ? 'index.html' : urlPath.slice(1);
-  const file = normalize(join(PUBLIC_DIR, rel));
-  // Trailing separator so `public.bak`/`public-anything` siblings can't
-  // satisfy a bare prefix check.
-  if (!file.startsWith(PUBLIC_DIR + sep)) {
+  const file = resolveStaticPath(PUBLIC_DIR, urlPath);
+  if (!file) {
     sendJson(res, 404, {
       error: 'not found',
     });
diff --git a/packages/openui-playground/src/static.ts b/packages/openui-playground/src/static.ts
new file mode 100644
index 00000000..b073368c
--- /dev/null
+++ b/packages/openui-playground/src/static.ts
@@ -0,0 +1,6 @@
+import { dirname, resolve, sep } from 'node:path';
+
+export function resolveStaticPath(publicDir: string, urlPath: string): string | null {
+  const file = resolve(publicDir, urlPath === '/' ? 'index.html' : `.${urlPath}`);
+  return dirname(file) === publicDir || file.startsWith(publicDir + sep) ? file : null;
+}
diff --git a/packages/openui-playground/tests/security.test.ts b/packages/openui-playground/tests/security.test.ts
new file mode 100644
index 00000000..af1e9655
--- /dev/null
+++ b/packages/openui-playground/tests/security.test.ts
@@ -0,0 +1,40 @@
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { escapeHtml, resolveMember } from '../public/render-utils.js';
+import { resolveStaticPath } from '../src/static.js';
+
+describe('playground rendering', () => {
+  it('returns undefined when a nested member is missing', () => {
+    expect(
+      resolveMember(
+        {
+          rows: undefined,
+        },
+        [
+          'rows',
+          'title',
+        ],
+      ),
+    ).toBeUndefined();
+  });
+
+  it('escapes every model-controlled diagnostics HTML character', () => {
+    expect(escapeHtml(`<img src="x" onerror='alert(1)'>&`)).toBe(
+      '&#60;img src=&#34;x&#34; onerror=&#39;alert(1)&#39;&#62;&#38;',
+    );
+  });
+});
+
+describe('static path containment', () => {
+  const publicDir = resolve('/tmp/openui-playground/public');
+
+  it('accepts files inside public', () => {
+    expect(resolveStaticPath(publicDir, '/app.js')).toBe(resolve(publicDir, 'app.js'));
+    expect(resolveStaticPath(publicDir, '/')).toBe(resolve(publicDir, 'index.html'));
+  });
+
+  it('rejects traversal and sibling-prefix paths', () => {
+    expect(resolveStaticPath(publicDir, '/../public-notes/secret.txt')).toBeNull();
+    expect(resolveStaticPath(publicDir, '/../../secret.txt')).toBeNull();
+  });
+});

From ff7098264e731b9e1913353f6cd9b0c8eb212bd0 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 15:06:07 -0500
Subject: [PATCH 13/19] fix(openui): release timed-out UI renders

---
 packages/agent/src/lib/model-result.ts        | 33 +++++----
 .../agent/tests/unit/openui-stream.test.ts    | 73 +++++++++++++++++++
 2 files changed, 93 insertions(+), 13 deletions(-)

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index 249cd8c6..a4a2ee1f 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -4361,21 +4361,28 @@ export class ModelResult<
     if (this.pendingUiFragments.size === 0) {
       return;
     }
+    const pending = [
+      ...this.pendingUiFragments,
+    ];
     const timeoutMs = this.options.asyncTools?.drainTimeoutMs ?? 30_000;
     let timer: ReturnType<typeof setTimeout> | undefined;
-    await Promise.race([
-      Promise.all([
-        ...this.pendingUiFragments,
-      ]),
-      new Promise<void>((resolve) => {
-        timer = setTimeout(resolve, timeoutMs);
-        if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
-          timer.unref();
-        }
-      }),
-    ]);
-    if (timer !== undefined) {
-      clearTimeout(timer);
+    try {
+      await Promise.race([
+        Promise.all(pending),
+        new Promise<void>((resolve) => {
+          timer = setTimeout(resolve, timeoutMs);
+          if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
+            timer.unref();
+          }
+        }),
+      ]);
+    } finally {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      for (const rendering of pending) {
+        this.pendingUiFragments.delete(rendering);
+      }
     }
   }
 
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index 26d11d88..7b912de1 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -627,6 +627,16 @@ describe('broadcastUiFragment', () => {
     turnBroadcaster: {
       push: (event: unknown) => void;
     } | null;
+    pendingUiFragments: Set<Promise<void>>;
+    dispatchUiFragment: (value: {
+      toolCall: ParsedToolCall<Tool>;
+      tool: Tool;
+      result: {
+        result: unknown;
+        error?: Error;
+      };
+    }) => void;
+    drainUiFragments: () => Promise<void>;
     broadcastUiFragment: (value: {
       toolCall: ParsedToolCall<Tool>;
       tool: Tool;
@@ -678,6 +688,69 @@ describe('broadcastUiFragment', () => {
     };
   }
 
+  it('releases timed-out renders without removing renders added during the drain', async () => {
+    vi.useFakeTimers();
+    try {
+      const { internal, pushed } = makeHarness();
+      let releaseLater: (() => void) | undefined;
+      const hanging = tool({
+        name: 'hanging_ui',
+        inputSchema: z.object({
+          days: z.number(),
+        }),
+        execute: async () => 'old',
+        toUiOutput: () => new Promise(() => undefined),
+      });
+      const later = tool({
+        name: 'later_ui',
+        inputSchema: z.object({
+          days: z.number(),
+        }),
+        execute: async () => 'new',
+        toUiOutput: async () => {
+          await new Promise<void>((resolve) => {
+            releaseLater = resolve;
+          });
+          return ui.Text('later');
+        },
+      });
+
+      internal.dispatchUiFragment(
+        makeCall(hanging, {
+          result: 'old',
+        }),
+      );
+      const firstDrain = internal.drainUiFragments();
+      internal.dispatchUiFragment(
+        makeCall(later, {
+          result: 'new',
+        }),
+      );
+
+      await vi.advanceTimersByTimeAsync(30_000);
+      await firstDrain;
+      expect(internal.pendingUiFragments).toHaveLength(1);
+
+      let secondDrainFinished = false;
+      const secondDrain = internal.drainUiFragments().then(() => {
+        secondDrainFinished = true;
+      });
+      await vi.advanceTimersByTimeAsync(0);
+      expect(secondDrainFinished).toBe(false);
+
+      releaseLater?.();
+      await secondDrain;
+      expect(internal.pendingUiFragments).toHaveLength(0);
+      expect(pushed).toContainEqual(
+        expect.objectContaining({
+          toolName: 'later_ui',
+        }),
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('pushes a tool.ui_fragment event for a successful execution', async () => {
     const { internal, pushed } = makeHarness();
     const t = tool({

From e956e1ec16f71ecd47026d64e55ffbdca8d5f58a Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 15:16:26 -0500
Subject: [PATCH 14/19] fix(openui): drain renders added before close

---
 packages/agent/src/lib/model-result.ts        |  38 +++--
 .../agent/tests/unit/openui-stream.test.ts    | 142 +++++++++++-------
 2 files changed, 109 insertions(+), 71 deletions(-)

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index a4a2ee1f..2cdc7317 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -4361,28 +4361,38 @@ export class ModelResult<
     if (this.pendingUiFragments.size === 0) {
       return;
     }
-    const pending = [
-      ...this.pendingUiFragments,
-    ];
     const timeoutMs = this.options.asyncTools?.drainTimeoutMs ?? 30_000;
     let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<true>((resolve) => {
+      timer = setTimeout(() => resolve(true), timeoutMs);
+      if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
+        timer.unref();
+      }
+    });
     try {
-      await Promise.race([
-        Promise.all(pending),
-        new Promise<void>((resolve) => {
-          timer = setTimeout(resolve, timeoutMs);
-          if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
-            timer.unref();
+      while (this.pendingUiFragments.size > 0) {
+        const pending = [
+          ...this.pendingUiFragments,
+        ];
+        try {
+          const timedOut = await Promise.race([
+            Promise.all(pending).then(() => false),
+            deadline,
+          ]);
+          if (timedOut) {
+            this.pendingUiFragments.clear();
+            return;
           }
-        }),
-      ]);
+        } finally {
+          for (const rendering of pending) {
+            this.pendingUiFragments.delete(rendering);
+          }
+        }
+      }
     } finally {
       if (timer !== undefined) {
         clearTimeout(timer);
       }
-      for (const rendering of pending) {
-        this.pendingUiFragments.delete(rendering);
-      }
     }
   }
 
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index 7b912de1..e72a86d8 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -454,6 +454,13 @@ describe('toUiOutput round lifecycle', () => {
 
     expect(events).toEqual([]);
     expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
+    expect(
+      (
+        result as unknown as {
+          pendingUiFragments: Set<Promise<void>>;
+        }
+      ).pendingUiFragments,
+    ).toHaveLength(0);
   });
 
   it('advances the model while retaining ordinary async rendering until UI drain', async () => {
@@ -688,67 +695,88 @@ describe('broadcastUiFragment', () => {
     };
   }
 
-  it('releases timed-out renders without removing renders added during the drain', async () => {
-    vi.useFakeTimers();
-    try {
-      const { internal, pushed } = makeHarness();
-      let releaseLater: (() => void) | undefined;
-      const hanging = tool({
-        name: 'hanging_ui',
-        inputSchema: z.object({
-          days: z.number(),
-        }),
-        execute: async () => 'old',
-        toUiOutput: () => new Promise(() => undefined),
-      });
-      const later = tool({
-        name: 'later_ui',
-        inputSchema: z.object({
-          days: z.number(),
-        }),
-        execute: async () => 'new',
-        toUiOutput: async () => {
-          await new Promise<void>((resolve) => {
-            releaseLater = resolve;
-          });
-          return ui.Text('later');
-        },
-      });
-
-      internal.dispatchUiFragment(
-        makeCall(hanging, {
-          result: 'old',
-        }),
-      );
-      const firstDrain = internal.drainUiFragments();
-      internal.dispatchUiFragment(
-        makeCall(later, {
-          result: 'new',
-        }),
-      );
-
-      await vi.advanceTimersByTimeAsync(30_000);
-      await firstDrain;
-      expect(internal.pendingUiFragments).toHaveLength(1);
+  it('delivers renders added during the production drain before closing the UI stream', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockToolRound('initial_ui');
+    let releaseInitial: (() => void) | undefined;
+    let releaseLater: (() => void) | undefined;
+    const initial = tool({
+      name: 'initial_ui',
+      inputSchema: z.object({}),
+      execute: () => 'initial',
+      toUiOutput: async () => {
+        await new Promise<void>((resolve) => {
+          releaseInitial = resolve;
+        });
+        return ui.Text('initial');
+      },
+    });
+    const later = tool({
+      name: 'later_ui',
+      inputSchema: z.object({}),
+      execute: () => 'later',
+      toUiOutput: async () => {
+        await new Promise<void>((resolve) => {
+          releaseLater = resolve;
+        });
+        return ui.Text('later');
+      },
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          initial,
+        ] as const,
+      },
+    );
+    const internal = result as unknown as Internal;
+    let notifyDrainStarted: (() => void) | undefined;
+    const drainStarted = new Promise<void>((resolve) => {
+      notifyDrainStarted = resolve;
+    });
+    const drainUiFragments = internal.drainUiFragments.bind(internal);
+    internal.drainUiFragments = async () => {
+      notifyDrainStarted?.();
+      await drainUiFragments();
+    };
 
-      let secondDrainFinished = false;
-      const secondDrain = internal.drainUiFragments().then(() => {
-        secondDrainFinished = true;
-      });
-      await vi.advanceTimersByTimeAsync(0);
-      expect(secondDrainFinished).toBe(false);
+    const events: unknown[] = [];
+    async function consumeUiStream() {
+      for await (const event of result.getUiStream()) {
+        events.push(event);
+      }
+    }
+    const consuming = consumeUiStream();
 
-      releaseLater?.();
-      await secondDrain;
-      expect(internal.pendingUiFragments).toHaveLength(0);
-      expect(pushed).toContainEqual(
+    await drainStarted;
+    expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
+    internal.dispatchUiFragment(
+      makeCall(later, {
+        result: 'later',
+      }),
+    );
+    releaseInitial?.();
+    await vi.waitFor(() =>
+      expect(events).toContainEqual(
         expect.objectContaining({
-          toolName: 'later_ui',
+          toolName: 'initial_ui',
         }),
-      );
-    } finally {
-      vi.useRealTimers();
-    }
+      ),
+    );
+    releaseLater?.();
+    await consuming;
+
+    expect(internal.pendingUiFragments).toHaveLength(0);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        toolName: 'later_ui',
+      }),
+    );
   });
 
   it('pushes a tool.ui_fragment event for a successful execution', async () => {

From 0f7eb506b0d6d1ecbabbea060506288b6b59c659 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 15:36:19 -0500
Subject: [PATCH 15/19] fix(agent): drain UI fragments before stream completion

---
 packages/agent/src/lib/model-result.ts        |  36 +++---
 .../agent/tests/unit/openui-stream.test.ts    | 119 ++++++++++++++++++
 packages/openui-playground/public/app.js      |   7 +-
 .../openui-playground/public/render-utils.js  |   5 +
 .../openui-playground/tests/security.test.ts  |  14 ++-
 5 files changed, 156 insertions(+), 25 deletions(-)

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index 2cdc7317..1a0eb788 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -627,6 +627,7 @@ export class ModelResult<
     ResponseStreamEvent<InferToolEventsUnion<TTools>, InferToolOutputsUnion<TTools>>
   > | null = null;
   private pendingUiFragments = new Set<Promise<void>>();
+  private turnBroadcasterCompletionPromise: Promise<void> | null = null;
   private initialStreamPipeStarted = false;
   private initialPipePromise: Promise<void> | null = null;
 
@@ -1019,7 +1020,7 @@ export class ModelResult<
    * Set up the turn broadcaster with tool execution and return the consumer.
    * Used by stream methods that need to iterate over all turns.
    */
-  private startTurnBroadcasterExecution(options?: { drainUiFragments?: boolean }): {
+  private startTurnBroadcasterExecution(): {
     consumer: AsyncIterableIterator<
       ResponseStreamEvent<InferToolEventsUnion<TTools>, InferToolOutputsUnion<TTools>>
     >;
@@ -1028,22 +1029,21 @@ export class ModelResult<
     const broadcaster = this.ensureTurnBroadcaster();
     this.startInitialStreamPipe();
     const consumer = broadcaster.createConsumer();
-    const executionPromise = this.executeToolsIfNeeded().finally(async () => {
-      // Wait for the initial stream pipe to finish pushing all events
-      // (including turn.end) before marking the broadcaster as complete.
-      // Without this, turn.end can be silently dropped if the pipe hasn't
-      // finished when executeToolsIfNeeded completes.
-      if (this.initialPipePromise) {
-        await this.initialPipePromise;
-      }
-      if (options?.drainUiFragments) {
+    if (!this.turnBroadcasterCompletionPromise) {
+      this.turnBroadcasterCompletionPromise = this.executeToolsIfNeeded().finally(async () => {
+        // Wait for every event producer before closing the shared broadcaster.
+        // UI rendering is best-effort and bounded; the drain is a no-op when
+        // no fragments are pending.
+        if (this.initialPipePromise) {
+          await this.initialPipePromise;
+        }
         await this.drainUiFragments();
-      }
-      broadcaster.complete();
-    });
+        broadcaster.complete();
+      });
+    }
     return {
       consumer,
-      executionPromise,
+      executionPromise: this.turnBroadcasterCompletionPromise,
     };
   }
 
@@ -3098,12 +3098,12 @@ export class ModelResult<
         const tool = this.options.tools?.find(
           (candidate) => isClientTool(candidate) && candidate.function.name === task.name,
         );
-        if (tool) {
+        if (tool && task.input !== undefined) {
           this.dispatchUiFragment({
             toolCall: {
               id: task.callId,
               name: task.name,
-              arguments: task.input ?? {},
+              arguments: task.input,
             } as ParsedToolCall<Tool>,
             tool,
             result: {
@@ -6883,9 +6883,7 @@ export class ModelResult<
         return;
       }
 
-      const { consumer, executionPromise } = this.startTurnBroadcasterExecution({
-        drainUiFragments: true,
-      });
+      const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
 
       for await (const event of consumer) {
         const uiEvent = translateUiEvent(event);
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index e72a86d8..ebab007c 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -463,6 +463,69 @@ describe('toUiOutput round lifecycle', () => {
     ).toHaveLength(0);
   });
 
+  it('delivers async UI when UI, text, and item streams are consumed concurrently', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockToolRound('concurrent_ui');
+    let release: (() => void) | undefined;
+    const rendering = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const concurrentUi = tool({
+      name: 'concurrent_ui',
+      inputSchema: z.object({}),
+      execute: () => 'ok',
+      toUiOutput: async () => {
+        await rendering;
+        return ui.Text('concurrent');
+      },
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          concurrentUi,
+        ] as const,
+      },
+    );
+    const text: string[] = [];
+    const items: unknown[] = [];
+    const events: unknown[] = [];
+    async function collect<T>(stream: AsyncIterable<T>, values: T[]) {
+      for await (const value of stream) {
+        values.push(value);
+      }
+    }
+    const consumeText = collect(result.getTextStream(), text);
+    const consumeItems = collect(result.getItemsStream(), items);
+    const consumeUi = collect(result.getUiStream(), events);
+
+    await vi.waitFor(() => expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2));
+    release?.();
+    await Promise.all([
+      consumeText,
+      consumeItems,
+      consumeUi,
+    ]);
+
+    expect(text).toEqual([]);
+    expect(items).toContainEqual(
+      expect.objectContaining({
+        type: 'function_call_output',
+      }),
+    );
+    expect(events).toContainEqual({
+      type: 'fragment',
+      toolCallId: 'c1',
+      toolName: 'concurrent_ui',
+      dialect: 'openui-lang/0.5',
+      source: 'root = Text("concurrent")',
+    });
+  });
+
   it('advances the model while retaining ordinary async rendering until UI drain', async () => {
     mockBetaResponsesSend.mockReset();
     mockToolRound('async_ui');
@@ -629,6 +692,62 @@ describe('async tool settlement', () => {
   });
 });
 
+describe('late async tool UI settlement', () => {
+  it('skips rendering when deferred settlement has no retained input', async () => {
+    const toUiOutput = vi.fn(() => ui.Text('never'));
+    const deferred = tool({
+      name: 'deferred_ui',
+      lifecycle: 'deferred',
+      inputSchema: z.object({
+        city: z.string(),
+      }),
+      outputSchema: z.object({
+        summary: z.string(),
+      }),
+      run: () => ({
+        taskId: 'task_1',
+      }),
+      toUiOutput,
+    });
+    const result = new ModelResult({
+      request: {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          deferred,
+        ],
+      },
+      client: {} as OpenRouterCore,
+    });
+    const internal = result as unknown as {
+      asyncToolRegistry: {
+        takeSettled: () => Array<Record<string, unknown>>;
+      };
+      flushAsyncToolDeliveries: () => Promise<boolean>;
+      injectAppendPromptMessage: () => Promise<void>;
+    };
+    internal.asyncToolRegistry = {
+      takeSettled: () => [
+        {
+          callId: 'c1',
+          taskId: 'task_1',
+          name: 'deferred_ui',
+          status: 'completed',
+          result: {
+            summary: 'Clear',
+          },
+          durationMs: 1,
+        },
+      ],
+    };
+    internal.injectAppendPromptMessage = async () => undefined;
+
+    await internal.flushAsyncToolDeliveries();
+
+    expect(toUiOutput).not.toHaveBeenCalled();
+  });
+});
+
 describe('broadcastUiFragment', () => {
   type Internal = {
     turnBroadcaster: {
diff --git a/packages/openui-playground/public/app.js b/packages/openui-playground/public/app.js
index ae2f90b6..e1218ea9 100644
--- a/packages/openui-playground/public/app.js
+++ b/packages/openui-playground/public/app.js
@@ -7,7 +7,7 @@
  * client resolves refs/state and materializes DOM without its own parser.
  */
 
-import { escapeHtml, resolveMember } from './render-utils.js';
+import { escapeHtml, renderDiagnostic, resolveMember } from './render-utils.js';
 
 const $ = (id) => document.getElementById(id);
 
@@ -602,10 +602,7 @@ function handleEvent(event) {
           // offending line and `message` carries parser text built from it
           // (ParseFailure.message), or arrives verbatim off the wire in native
           // mode. Escaping only `source` left an injection through `message`.
-          .map(
-            (d) =>
-              `<div class="diag">L${escapeHtml(String(d.line))}: ${escapeHtml(d.message)} — ${escapeHtml(d.source)}</div>`,
-          )
+          .map(renderDiagnostic)
           .join('');
       } else {
         $('diagnostics').innerHTML =
diff --git a/packages/openui-playground/public/render-utils.js b/packages/openui-playground/public/render-utils.js
index 2bd288a7..f8cd06ae 100644
--- a/packages/openui-playground/public/render-utils.js
+++ b/packages/openui-playground/public/render-utils.js
@@ -14,3 +14,8 @@ export function resolveMember(base, path) {
 export function escapeHtml(value) {
   return value.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
 }
+
+/** @param {{ line: unknown, message: string, source: string }} diagnostic */
+export function renderDiagnostic({ line, message, source }) {
+  return `<div class="diag">L${escapeHtml(String(line))}: ${escapeHtml(message)} — ${escapeHtml(source)}</div>`;
+}
diff --git a/packages/openui-playground/tests/security.test.ts b/packages/openui-playground/tests/security.test.ts
index af1e9655..d4b740cc 100644
--- a/packages/openui-playground/tests/security.test.ts
+++ b/packages/openui-playground/tests/security.test.ts
@@ -1,6 +1,6 @@
 import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
-import { escapeHtml, resolveMember } from '../public/render-utils.js';
+import { escapeHtml, renderDiagnostic, resolveMember } from '../public/render-utils.js';
 import { resolveStaticPath } from '../src/static.js';
 
 describe('playground rendering', () => {
@@ -23,6 +23,18 @@ describe('playground rendering', () => {
       '&#60;img src=&#34;x&#34; onerror=&#39;alert(1)&#39;&#62;&#38;',
     );
   });
+
+  it('escapes hostile diagnostic line, message, and source fields', () => {
+    expect(
+      renderDiagnostic({
+        line: `<img src=x onerror='line()'>`,
+        message: `<img src=x onerror='message()'>`,
+        source: `<img src=x onerror='source()'>`,
+      }),
+    ).toBe(
+      '<div class="diag">L&#60;img src=x onerror=&#39;line()&#39;&#62;: &#60;img src=x onerror=&#39;message()&#39;&#62; — &#60;img src=x onerror=&#39;source()&#39;&#62;</div>',
+    );
+  });
 });
 
 describe('static path containment', () => {

From bccd1ad5ae87a454d68caa7020f0dfa9c565e130 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 16:23:30 -0500
Subject: [PATCH 16/19] fix(agent): isolate UI stream lifecycle

---
 packages/agent/src/lib/model-result.ts        |  36 ++++-
 .../agent/tests/unit/openui-stream.test.ts    | 148 ++++++++++++------
 2 files changed, 131 insertions(+), 53 deletions(-)

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index 1a0eb788..dd345c2e 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -258,6 +258,9 @@ function extractServerToolIdentity(item: ServerToolResultItem): Record<string, u
 // buggy handler fails fast with a visible warning.
 const MAX_FORCE_RESUME_OVERRIDES = 3;
 
+/** Maximum time a UI consumer waits for asynchronous fragment rendering. */
+const DEFAULT_UI_DRAIN_TIMEOUT_MS = 30_000;
+
 /**
  * Sentinel marking a tool-call id that appeared MORE THAN ONCE in one batch.
  * Ids are model-emitted and nothing upstream enforces uniqueness; a colliding
@@ -626,7 +629,9 @@ export class ModelResult<
   private turnBroadcaster: ToolEventBroadcaster<
     ResponseStreamEvent<InferToolEventsUnion<TTools>, InferToolOutputsUnion<TTools>>
   > | null = null;
+  private uiBroadcaster: ToolEventBroadcaster<ToolUiFragmentEvent> | null = null;
   private pendingUiFragments = new Set<Promise<void>>();
+  private uiBroadcasterCompletionPromise: Promise<void> | null = null;
   private turnBroadcasterCompletionPromise: Promise<void> | null = null;
   private initialStreamPipeStarted = false;
   private initialPipePromise: Promise<void> | null = null;
@@ -1031,13 +1036,10 @@ export class ModelResult<
     const consumer = broadcaster.createConsumer();
     if (!this.turnBroadcasterCompletionPromise) {
       this.turnBroadcasterCompletionPromise = this.executeToolsIfNeeded().finally(async () => {
-        // Wait for every event producer before closing the shared broadcaster.
-        // UI rendering is best-effort and bounded; the drain is a no-op when
-        // no fragments are pending.
+        // Preserve turn.end, but never couple non-UI stream completion to UI rendering.
         if (this.initialPipePromise) {
           await this.initialPipePromise;
         }
-        await this.drainUiFragments();
         broadcaster.complete();
       });
     }
@@ -4352,6 +4354,9 @@ export class ModelResult<
       error?: Error;
     };
   }): void {
+    if (!this.uiBroadcaster) {
+      return;
+    }
     const rendering = this.broadcastUiFragment(value);
     this.pendingUiFragments.add(rendering);
     rendering.finally(() => this.pendingUiFragments.delete(rendering));
@@ -4361,7 +4366,7 @@ export class ModelResult<
     if (this.pendingUiFragments.size === 0) {
       return;
     }
-    const timeoutMs = this.options.asyncTools?.drainTimeoutMs ?? 30_000;
+    const timeoutMs = DEFAULT_UI_DRAIN_TIMEOUT_MS;
     let timer: ReturnType<typeof setTimeout> | undefined;
     const deadline = new Promise<true>((resolve) => {
       timer = setTimeout(() => resolve(true), timeoutMs);
@@ -4429,7 +4434,7 @@ export class ModelResult<
       if (!fragment) {
         return;
       }
-      this.turnBroadcaster?.push({
+      this.uiBroadcaster?.push({
         type: 'tool.ui_fragment' as const,
         toolCallId: value.toolCall.id,
         toolName: value.toolCall.name,
@@ -6883,7 +6888,18 @@ export class ModelResult<
         return;
       }
 
+      if (!this.uiBroadcaster) {
+        this.uiBroadcaster = new ToolEventBroadcaster();
+      }
+      const uiBroadcaster = this.uiBroadcaster;
+      const uiConsumer = uiBroadcaster.createConsumer();
       const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+      if (!this.uiBroadcasterCompletionPromise) {
+        this.uiBroadcasterCompletionPromise = executionPromise.finally(async () => {
+          await this.drainUiFragments();
+          uiBroadcaster.complete();
+        });
+      }
 
       for await (const event of consumer) {
         const uiEvent = translateUiEvent(event);
@@ -6891,8 +6907,14 @@ export class ModelResult<
           yield uiEvent;
         }
       }
+      for await (const event of uiConsumer) {
+        const uiEvent = translateUiEvent(event);
+        if (uiEvent) {
+          yield uiEvent;
+        }
+      }
 
-      await executionPromise;
+      await this.uiBroadcasterCompletionPromise;
     }.call(this);
   }
 
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index ebab007c..9753e1b9 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -391,14 +391,15 @@ describe('getUiStream (no-tools fast path)', () => {
 });
 
 describe('toUiOutput round lifecycle', () => {
-  it('does not block the run when rendering never settles', async () => {
+  it('does not render or block the run without a UI consumer', async () => {
     mockBetaResponsesSend.mockReset();
     mockToolRound('hanging_ui');
+    const toUiOutput = vi.fn(() => new Promise<never>(() => undefined));
     const hanging = tool({
       name: 'hanging_ui',
       inputSchema: z.object({}),
       execute: () => 'ok',
-      toUiOutput: () => new Promise(() => undefined),
+      toUiOutput,
     });
     const result = callModel(
       {
@@ -413,54 +414,66 @@ describe('toUiOutput round lifecycle', () => {
       },
     );
 
-    await expect(
-      Promise.race([
-        result.getText(),
-        new Promise((_, reject) => setTimeout(() => reject(new Error('run stalled')), 100)),
-      ]),
-    ).resolves.toBe('done');
+    await expect(result.getText()).resolves.toBe('done');
+    expect(toUiOutput).not.toHaveBeenCalled();
     expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
   });
 
-  it('bounds UI-stream close with the configured drain deadline', async () => {
-    mockBetaResponsesSend.mockReset();
-    mockToolRound('hanging_ui');
-    const hanging = tool({
-      name: 'hanging_ui',
-      inputSchema: z.object({}),
-      execute: () => 'ok',
-      toUiOutput: () => new Promise(() => undefined),
-    });
-    const result = callModel(
-      {
-        _options: {},
-      } as OpenRouterCore,
-      {
-        model: 'test-model',
-        input: 'test',
-        tools: [
-          hanging,
-        ] as const,
-        asyncTools: {
-          drainTimeoutMs: 10,
+  it('finishes text immediately and closes hanging UI at its own deadline', async () => {
+    vi.useFakeTimers();
+    try {
+      mockBetaResponsesSend.mockReset();
+      mockToolRound('hanging_ui');
+      const hanging = tool({
+        name: 'hanging_ui',
+        inputSchema: z.object({}),
+        execute: () => 'ok',
+        toUiOutput: () => new Promise(() => undefined),
+      });
+      const result = callModel(
+        {
+          _options: {},
+        } as OpenRouterCore,
+        {
+          model: 'test-model',
+          input: 'test',
+          tools: [
+            hanging,
+          ] as const,
+          asyncTools: {
+            drainTimeoutMs: 1,
+          },
         },
-      },
-    );
-
-    const events = [];
-    for await (const event of result.getUiStream()) {
-      events.push(event);
-    }
+      );
 
-    expect(events).toEqual([]);
-    expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
-    expect(
-      (
-        result as unknown as {
-          pendingUiFragments: Set<Promise<void>>;
+      async function consumeUiStream() {
+        for await (const _event of result.getUiStream()) {
+          // No fragment is produced by the hanging renderer.
         }
-      ).pendingUiFragments,
-    ).toHaveLength(0);
+      }
+      const uiDone = consumeUiStream();
+      await expect(result.getText()).resolves.toBe('done');
+
+      let closed = false;
+      void uiDone.then(() => {
+        closed = true;
+      });
+      await vi.advanceTimersByTimeAsync(29_999);
+      expect(closed).toBe(false);
+      await vi.advanceTimersByTimeAsync(1);
+      await uiDone;
+
+      expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2);
+      expect(
+        (
+          result as unknown as {
+            pendingUiFragments: Set<Promise<void>>;
+          }
+        ).pendingUiFragments,
+      ).toHaveLength(0);
+    } finally {
+      vi.useRealTimers();
+    }
   });
 
   it('delivers async UI when UI, text, and item streams are consumed concurrently', async () => {
@@ -526,6 +539,49 @@ describe('toUiOutput round lifecycle', () => {
     });
   });
 
+  it('delivers the same fragment to concurrent UI consumers', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockToolRound('shared_ui');
+    const sharedUi = tool({
+      name: 'shared_ui',
+      inputSchema: z.object({}),
+      execute: () => 'ok',
+      toUiOutput: () => ui.Text('shared'),
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          sharedUi,
+        ] as const,
+      },
+    );
+    const collect = async (stream: AsyncIterable<unknown>) => {
+      const events = [];
+      for await (const event of stream) {
+        events.push(event);
+      }
+      return events;
+    };
+
+    const [first, second] = await Promise.all([
+      collect(result.getUiStream()),
+      collect(result.getUiStream()),
+    ]);
+
+    expect(first).toEqual(second);
+    expect(first).toContainEqual(
+      expect.objectContaining({
+        type: 'fragment',
+        toolName: 'shared_ui',
+      }),
+    );
+  });
+
   it('advances the model while retaining ordinary async rendering until UI drain', async () => {
     mockBetaResponsesSend.mockReset();
     mockToolRound('async_ui');
@@ -750,7 +806,7 @@ describe('late async tool UI settlement', () => {
 
 describe('broadcastUiFragment', () => {
   type Internal = {
-    turnBroadcaster: {
+    uiBroadcaster: {
       push: (event: unknown) => void;
     } | null;
     pendingUiFragments: Set<Promise<void>>;
@@ -783,7 +839,7 @@ describe('broadcastUiFragment', () => {
       client: {} as OpenRouterCore,
     });
     const internal = modelResult as unknown as Internal;
-    internal.turnBroadcaster = {
+    internal.uiBroadcaster = {
       push: (event: unknown) => {
         pushed.push(event);
       },

From cbfd884422bfec89e9ad9374a33f157de9a002bd Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 16:32:18 -0500
Subject: [PATCH 17/19] fix(agent): release exited UI consumers

---
 packages/agent/src/lib/model-result.ts        |  50 +++--
 .../agent/src/lib/tool-event-broadcaster.ts   |  13 +-
 .../agent/tests/unit/openui-stream.test.ts    | 173 ++++++++++++++++++
 .../tests/unit/tool-event-broadcaster.test.ts |   2 +
 4 files changed, 212 insertions(+), 26 deletions(-)

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index dd345c2e..b3759bf4 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -4354,7 +4354,7 @@ export class ModelResult<
       error?: Error;
     };
   }): void {
-    if (!this.uiBroadcaster) {
+    if (!this.uiBroadcaster?.activeConsumerCount) {
       return;
     }
     const rendering = this.broadcastUiFragment(value);
@@ -4434,7 +4434,10 @@ export class ModelResult<
       if (!fragment) {
         return;
       }
-      this.uiBroadcaster?.push({
+      if (!this.uiBroadcaster?.activeConsumerCount) {
+        return;
+      }
+      this.uiBroadcaster.push({
         type: 'tool.ui_fragment' as const,
         toolCallId: value.toolCall.id,
         toolName: value.toolCall.name,
@@ -6893,28 +6896,35 @@ export class ModelResult<
       }
       const uiBroadcaster = this.uiBroadcaster;
       const uiConsumer = uiBroadcaster.createConsumer();
-      const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
-      if (!this.uiBroadcasterCompletionPromise) {
-        this.uiBroadcasterCompletionPromise = executionPromise.finally(async () => {
-          await this.drainUiFragments();
-          uiBroadcaster.complete();
-        });
-      }
+      try {
+        const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+        if (!this.uiBroadcasterCompletionPromise) {
+          this.uiBroadcasterCompletionPromise = executionPromise.finally(async () => {
+            await this.drainUiFragments();
+            uiBroadcaster.complete();
+          });
+        }
 
-      for await (const event of consumer) {
-        const uiEvent = translateUiEvent(event);
-        if (uiEvent) {
-          yield uiEvent;
+        for await (const event of consumer) {
+          const uiEvent = translateUiEvent(event);
+          if (uiEvent) {
+            yield uiEvent;
+          }
         }
-      }
-      for await (const event of uiConsumer) {
-        const uiEvent = translateUiEvent(event);
-        if (uiEvent) {
-          yield uiEvent;
+        for await (const event of uiConsumer) {
+          const uiEvent = translateUiEvent(event);
+          if (uiEvent) {
+            yield uiEvent;
+          }
         }
-      }
 
-      await this.uiBroadcasterCompletionPromise;
+        await this.uiBroadcasterCompletionPromise;
+      } finally {
+        await uiConsumer.return?.();
+        if (uiBroadcaster.activeConsumerCount === 0) {
+          this.pendingUiFragments.clear();
+        }
+      }
     }.call(this);
   }
 
diff --git a/packages/agent/src/lib/tool-event-broadcaster.ts b/packages/agent/src/lib/tool-event-broadcaster.ts
index bc4fc069..a2c8a2e1 100644
--- a/packages/agent/src/lib/tool-event-broadcaster.ts
+++ b/packages/agent/src/lib/tool-event-broadcaster.ts
@@ -15,6 +15,11 @@ export class ToolEventBroadcaster<T> {
   private isComplete = false;
   private completionError: Error | null = null;
 
+  /** Number of consumers currently subscribed to this broadcaster. */
+  get activeConsumerCount(): number {
+    return this.consumers.size;
+  }
+
   /**
    * Push a new event to all consumers.
    * Events are buffered so late-joining consumers can catch up.
@@ -40,13 +45,9 @@ export class ToolEventBroadcaster<T> {
     queueMicrotask(() => this.cleanup());
   }
 
-  /**
-   * Clean up resources after all consumers have finished.
-   * Called automatically after complete(), but can be called manually.
-   */
+  /** Release buffered events once no consumer can read them. */
   private cleanup(): void {
-    // Only cleanup if complete and all consumers are done
-    if (this.isComplete && this.consumers.size === 0) {
+    if (this.consumers.size === 0) {
       this.buffer = [];
     }
   }
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index 9753e1b9..58d0481c 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -582,6 +582,177 @@ describe('toUiOutput round lifecycle', () => {
     );
   });
 
+  it('unsubscribes after an early break and skips later rendering', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockToolRound('first_ui');
+    const firstUi = tool({
+      name: 'first_ui',
+      inputSchema: z.object({}),
+      execute: () => 'first',
+      toUiOutput: () => ui.Text('first'),
+    });
+    const laterRenderer = vi.fn(() => ui.Text('later'));
+    const laterUi = tool({
+      name: 'later_ui',
+      inputSchema: z.object({}),
+      execute: () => 'later',
+      toUiOutput: laterRenderer,
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          firstUi,
+        ] as const,
+      },
+    );
+
+    for await (const event of result.getUiStream()) {
+      expect(event).toMatchObject({
+        type: 'fragment',
+        toolName: 'first_ui',
+      });
+      break;
+    }
+
+    const internal = result as unknown as {
+      uiBroadcaster: {
+        activeConsumerCount: number;
+      };
+      pendingUiFragments: Set<Promise<void>>;
+      dispatchUiFragment: (value: {
+        toolCall: ParsedToolCall<Tool>;
+        tool: Tool;
+        result: {
+          result: unknown;
+        };
+      }) => void;
+    };
+    expect(internal.uiBroadcaster.activeConsumerCount).toBe(0);
+    internal.dispatchUiFragment({
+      toolCall: {
+        id: 'c2',
+        name: 'later_ui',
+        arguments: {},
+      } as unknown as ParsedToolCall<Tool>,
+      tool: laterUi,
+      result: {
+        result: 'later',
+      },
+    });
+
+    expect(laterRenderer).not.toHaveBeenCalled();
+    expect(internal.pendingUiFragments).toHaveLength(0);
+  });
+
+  it('keeps rendering for a remaining UI consumer after another exits', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockBetaResponsesSend
+      .mockResolvedValueOnce({
+        ok: true,
+        value: response('r1', [
+          {
+            type: 'function_call',
+            id: 'fc1',
+            callId: 'c1',
+            name: 'fast_ui',
+            arguments: '{}',
+            status: 'completed',
+          },
+          {
+            type: 'function_call',
+            id: 'fc2',
+            callId: 'c2',
+            name: 'slow_ui',
+            arguments: '{}',
+            status: 'completed',
+          },
+        ]),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        value: response('r2', [
+          {
+            type: 'message',
+            id: 'm1',
+            role: 'assistant',
+            status: 'completed',
+            content: [],
+          },
+        ]),
+      });
+    let releaseSlow: (() => void) | undefined;
+    const slowGate = new Promise<void>((resolve) => {
+      releaseSlow = resolve;
+    });
+    const fastUi = tool({
+      name: 'fast_ui',
+      inputSchema: z.object({}),
+      execute: () => 'fast',
+      toUiOutput: () => ui.Text('fast'),
+    });
+    const slowRenderer = vi.fn(async () => {
+      await slowGate;
+      return ui.Text('slow');
+    });
+    const slowUi = tool({
+      name: 'slow_ui',
+      inputSchema: z.object({}),
+      execute: () => 'slow',
+      toUiOutput: slowRenderer,
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          fastUi,
+          slowUi,
+        ] as const,
+      },
+    );
+    const first = result.getUiStream();
+    const remaining = result.getUiStream();
+
+    const [firstEvent, remainingFirstEvent] = await Promise.all([
+      first.next(),
+      remaining.next(),
+    ]);
+    expect(firstEvent.value).toMatchObject({
+      type: 'fragment',
+      toolName: 'fast_ui',
+    });
+    expect(remainingFirstEvent.value).toEqual(firstEvent.value);
+    await first.return();
+    expect(
+      (
+        result as unknown as {
+          uiBroadcaster: {
+            activeConsumerCount: number;
+          };
+        }
+      ).uiBroadcaster.activeConsumerCount,
+    ).toBe(1);
+
+    releaseSlow?.();
+    await expect(remaining.next()).resolves.toMatchObject({
+      done: false,
+      value: {
+        type: 'fragment',
+        toolName: 'slow_ui',
+      },
+    });
+    await remaining.return();
+    expect(slowRenderer).toHaveBeenCalledOnce();
+  });
+
   it('advances the model while retaining ordinary async rendering until UI drain', async () => {
     mockBetaResponsesSend.mockReset();
     mockToolRound('async_ui');
@@ -807,6 +978,7 @@ describe('late async tool UI settlement', () => {
 describe('broadcastUiFragment', () => {
   type Internal = {
     uiBroadcaster: {
+      activeConsumerCount: number;
       push: (event: unknown) => void;
     } | null;
     pendingUiFragments: Set<Promise<void>>;
@@ -840,6 +1012,7 @@ describe('broadcastUiFragment', () => {
     });
     const internal = modelResult as unknown as Internal;
     internal.uiBroadcaster = {
+      activeConsumerCount: 1,
       push: (event: unknown) => {
         pushed.push(event);
       },
diff --git a/packages/agent/tests/unit/tool-event-broadcaster.test.ts b/packages/agent/tests/unit/tool-event-broadcaster.test.ts
index 290f13f6..405dd7c5 100644
--- a/packages/agent/tests/unit/tool-event-broadcaster.test.ts
+++ b/packages/agent/tests/unit/tool-event-broadcaster.test.ts
@@ -42,6 +42,7 @@ describe('ToolEventBroadcaster', () => {
       const broadcaster = new ToolEventBroadcaster<number>();
       const consumer = broadcaster.createConsumer();
 
+      expect(broadcaster.activeConsumerCount).toBe(1);
       broadcaster.push(1);
       broadcaster.push(2);
 
@@ -53,6 +54,7 @@ describe('ToolEventBroadcaster', () => {
       // Cancel consumer
       await consumer.return!();
 
+      expect(broadcaster.activeConsumerCount).toBe(0);
       // Should be done now
       const after = await consumer.next();
       expect(after.done).toBe(true);

From 1f68c5e40433ede694d39e66d05363745eb6d451 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 16:52:27 -0500
Subject: [PATCH 18/19] fix(agent): merge OpenUI event streams

---
 packages/agent/src/lib/model-result.ts        | 87 +++++++++++++++++--
 .../agent/src/lib/tool-event-broadcaster.ts   |  6 +-
 .../agent/tests/unit/openui-stream.test.ts    | 76 ++++++++++++++++
 .../tests/unit/tool-event-broadcaster.test.ts | 41 +++++++++
 4 files changed, 201 insertions(+), 9 deletions(-)

diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index b3759bf4..f19fead3 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -261,6 +261,82 @@ const MAX_FORCE_RESUME_OVERRIDES = 3;
 /** Maximum time a UI consumer waits for asynchronous fragment rendering. */
 const DEFAULT_UI_DRAIN_TIMEOUT_MS = 30_000;
 
+type IteratorOutcome<T> =
+  | {
+      source: 0 | 1;
+      result: IteratorResult<T>;
+    }
+  | {
+      source: 0 | 1;
+      error: unknown;
+    };
+
+async function* mergeAsyncIterators<T>(
+  iterators: readonly [
+    AsyncIterator<T>,
+    AsyncIterator<T>,
+  ],
+): AsyncGenerator<T> {
+  const active = [
+    true,
+    true,
+  ];
+  const pending: Array<Promise<IteratorOutcome<T>> | null> = [
+    null,
+    null,
+  ];
+  let preferred: 0 | 1 = 0;
+  const next = async (source: 0 | 1): Promise<IteratorOutcome<T>> => {
+    try {
+      return {
+        source,
+        result: await iterators[source].next(),
+      };
+    } catch (error) {
+      return {
+        source,
+        error,
+      };
+    }
+  };
+
+  try {
+    while (active[0] || active[1]) {
+      for (const source of [
+        0,
+        1,
+      ] as const) {
+        if (active[source] && !pending[source]) {
+          pending[source] = next(source);
+        }
+      }
+      const other: 0 | 1 = preferred === 0 ? 1 : 0;
+      const outcome: IteratorOutcome<T> = await Promise.race(
+        [
+          pending[preferred],
+          pending[other],
+        ].filter((promise): promise is Promise<IteratorOutcome<T>> => promise !== null),
+      );
+      pending[outcome.source] = null;
+      if ('error' in outcome) {
+        throw outcome.error;
+      }
+      if (outcome.result.done) {
+        active[outcome.source] = false;
+        preferred = outcome.source === 0 ? 1 : 0;
+        continue;
+      }
+      preferred = outcome.source === 0 ? 1 : 0;
+      yield outcome.result.value;
+    }
+  } finally {
+    await Promise.allSettled(iterators.map((iterator) => iterator.return?.()));
+    await Promise.all(
+      pending.filter((promise): promise is Promise<IteratorOutcome<T>> => !!promise),
+    );
+  }
+}
+
 /**
  * Sentinel marking a tool-call id that appeared MORE THAN ONCE in one batch.
  * Ids are model-emitted and nothing upstream enforces uniqueness; a colliding
@@ -6905,13 +6981,10 @@ export class ModelResult<
           });
         }
 
-        for await (const event of consumer) {
-          const uiEvent = translateUiEvent(event);
-          if (uiEvent) {
-            yield uiEvent;
-          }
-        }
-        for await (const event of uiConsumer) {
+        for await (const event of mergeAsyncIterators([
+          consumer,
+          uiConsumer,
+        ])) {
           const uiEvent = translateUiEvent(event);
           if (uiEvent) {
             yield uiEvent;
diff --git a/packages/agent/src/lib/tool-event-broadcaster.ts b/packages/agent/src/lib/tool-event-broadcaster.ts
index a2c8a2e1..0bc733d6 100644
--- a/packages/agent/src/lib/tool-event-broadcaster.ts
+++ b/packages/agent/src/lib/tool-event-broadcaster.ts
@@ -45,9 +45,9 @@ export class ToolEventBroadcaster<T> {
     queueMicrotask(() => this.cleanup());
   }
 
-  /** Release buffered events once no consumer can read them. */
+  /** Release completed history once no consumer can read it. */
   private cleanup(): void {
-    if (this.consumers.size === 0) {
+    if (this.isComplete && this.consumers.size === 0) {
       this.buffer = [];
     }
   }
@@ -133,6 +133,7 @@ export class ToolEventBroadcaster<T> {
         const consumer = self.consumers.get(consumerId);
         if (consumer) {
           consumer.cancelled = true;
+          consumer.waitingPromise?.resolve();
           self.consumers.delete(consumerId);
           self.cleanup();
         }
@@ -146,6 +147,7 @@ export class ToolEventBroadcaster<T> {
         const consumer = self.consumers.get(consumerId);
         if (consumer) {
           consumer.cancelled = true;
+          consumer.waitingPromise?.resolve();
           self.consumers.delete(consumerId);
           self.cleanup();
         }
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index 58d0481c..afaea68f 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -753,6 +753,82 @@ describe('toUiOutput round lifecycle', () => {
     expect(slowRenderer).toHaveBeenCalledOnce();
   });
 
+  it('yields a tool fragment before the later model round completes', async () => {
+    mockBetaResponsesSend.mockReset();
+    let finishRound: ((value: { ok: true; value: models.OpenResponsesResult }) => void) | undefined;
+    const laterRound = new Promise<{
+      ok: true;
+      value: models.OpenResponsesResult;
+    }>((resolve) => {
+      finishRound = resolve;
+    });
+    mockBetaResponsesSend
+      .mockResolvedValueOnce({
+        ok: true,
+        value: response('r1', [
+          {
+            type: 'function_call',
+            id: 'fc1',
+            callId: 'c1',
+            name: 'progressive_ui',
+            arguments: '{}',
+            status: 'completed',
+          },
+        ]),
+      })
+      .mockReturnValueOnce(laterRound);
+    const progressiveUi = tool({
+      name: 'progressive_ui',
+      inputSchema: z.object({}),
+      execute: () => 'ready',
+      toUiOutput: () => ui.Text('progressive'),
+    });
+    const result = callModel(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        model: 'test-model',
+        input: 'test',
+        tools: [
+          progressiveUi,
+        ] as const,
+      },
+    );
+    const stream = result.getUiStream();
+    let firstEvent: IteratorResult<unknown> | undefined;
+    const pendingFirst = stream.next().then((event) => {
+      firstEvent = event;
+      return event;
+    });
+
+    await vi.waitFor(() => expect(mockBetaResponsesSend).toHaveBeenCalledTimes(2));
+    await vi.waitFor(() => expect(firstEvent).toBeDefined());
+    expect(await pendingFirst).toMatchObject({
+      done: false,
+      value: {
+        type: 'fragment',
+        toolName: 'progressive_ui',
+      },
+    });
+
+    finishRound?.({
+      ok: true,
+      value: response('r2', [
+        {
+          type: 'message',
+          id: 'm1',
+          role: 'assistant',
+          status: 'completed',
+          content: [],
+        },
+      ]),
+    });
+    while (!(await stream.next()).done) {
+      // Drain the completed round so no execution work escapes the test.
+    }
+  });
+
   it('advances the model while retaining ordinary async rendering until UI drain', async () => {
     mockBetaResponsesSend.mockReset();
     mockToolRound('async_ui');
diff --git a/packages/agent/tests/unit/tool-event-broadcaster.test.ts b/packages/agent/tests/unit/tool-event-broadcaster.test.ts
index 405dd7c5..1bd06641 100644
--- a/packages/agent/tests/unit/tool-event-broadcaster.test.ts
+++ b/packages/agent/tests/unit/tool-event-broadcaster.test.ts
@@ -59,6 +59,47 @@ describe('ToolEventBroadcaster', () => {
       const after = await consumer.next();
       expect(after.done).toBe(true);
     });
+
+    it('preserves history when the last consumer exits before completion', async () => {
+      const broadcaster = new ToolEventBroadcaster<number>();
+      const first = broadcaster.createConsumer();
+
+      broadcaster.push(1);
+      expect(await first.next()).toMatchObject({
+        value: 1,
+      });
+      await first.return?.();
+      broadcaster.push(2);
+
+      const later = broadcaster.createConsumer();
+      broadcaster.push(3);
+      broadcaster.complete();
+
+      const events: number[] = [];
+      for await (const event of later) {
+        events.push(event);
+      }
+      expect(events).toEqual([
+        1,
+        2,
+        3,
+      ]);
+    });
+
+    it('releases completed history when no consumers remain', async () => {
+      const broadcaster = new ToolEventBroadcaster<number>();
+      broadcaster.push(1);
+      broadcaster.complete();
+      await Promise.resolve();
+
+      expect(
+        (
+          broadcaster as unknown as {
+            buffer: number[];
+          }
+        ).buffer,
+      ).toEqual([]);
+    });
   });
 
   describe('multiple consumers', () => {

From 11eac753cd48a28e77b85754d9d977dff0516a44 Mon Sep 17 00:00:00 2001
From: Luke Parke <5702154+LukasParke@users.noreply.github.com>
Date: Tue, 11 Aug 2026 17:18:16 -0500
Subject: [PATCH 19/19] fix(agent): render deferred tool UI results

---
 .../src/inner-loop/resume-tool-results.ts     |  31 +++-
 packages/agent/src/lib/async-tool-registry.ts |   5 +
 packages/agent/src/lib/model-result.ts        |  52 +++++-
 packages/agent/src/lib/tool-types.ts          |   2 +
 .../tests/unit/async-tool-deferred.test.ts    |   6 +
 .../tests/unit/async-tool-registry.test.ts    |  29 +++
 .../agent/tests/unit/openui-stream.test.ts    | 173 +++++++++++++++---
 7 files changed, 274 insertions(+), 24 deletions(-)

diff --git a/packages/agent/src/inner-loop/resume-tool-results.ts b/packages/agent/src/inner-loop/resume-tool-results.ts
index a3c0145f..9320f28c 100644
--- a/packages/agent/src/inner-loop/resume-tool-results.ts
+++ b/packages/agent/src/inner-loop/resume-tool-results.ts
@@ -221,6 +221,12 @@ export async function resumeToolResults<TTools extends readonly Tool[]>(
   const settledIds = new Set(state.settledAsyncCallIds ?? []);
 
   const envelopes: models.BaseInputsUnion[] = [];
+  const uiToolResults: Array<{
+    callId: string;
+    name: string;
+    input: Record<string, unknown>;
+    output: unknown;
+  }> = [];
   /** callId → the terminal lifecycle status persisted for that entry. */
   const settledNow = new Map<string, ToolTaskStatus>();
 
@@ -249,6 +255,7 @@ export async function resumeToolResults<TTools extends readonly Tool[]>(
     const envelope = buildResumeEnvelope(entry, task, request.tools);
 
     envelopes.push(buildTaskResultMessage(envelope));
+    collectUiToolResult(uiToolResults, envelope, task);
     // Persist the entry's real terminal status. 'expired' / 'timed_out'
     // have no ToolTaskStatus member — they persist as 'failed'.
     settledNow.set(
@@ -313,7 +320,7 @@ export async function resumeToolResults<TTools extends readonly Tool[]>(
 
   // Continue the conversation: the envelopes are already in persisted
   // history, so no fresh input is supplied.
-  return callModel(
+  const result = callModel(
     client,
     {
       ...request.run,
@@ -325,6 +332,28 @@ export async function resumeToolResults<TTools extends readonly Tool[]>(
     },
     options,
   );
+  result.queueUiToolResults(uiToolResults);
+  return result;
+}
+
+function collectUiToolResult(
+  results: Array<{
+    callId: string;
+    name: string;
+    input: Record<string, unknown>;
+    output: unknown;
+  }>,
+  envelope: ToolTaskResultEnvelope,
+  task: PendingAsyncTool,
+): void {
+  if (envelope.status === 'completed' && task.input !== undefined) {
+    results.push({
+      callId: task.callId,
+      name: task.name,
+      input: task.input,
+      output: envelope.result,
+    });
+  }
 }
 
 /**
diff --git a/packages/agent/src/lib/async-tool-registry.ts b/packages/agent/src/lib/async-tool-registry.ts
index 27f49146..aa8cda25 100644
--- a/packages/agent/src/lib/async-tool-registry.ts
+++ b/packages/agent/src/lib/async-tool-registry.ts
@@ -147,6 +147,7 @@ export class AsyncToolRegistry {
     callId: string;
     taskId: string;
     name: string;
+    input: Record<string, unknown>;
     expiresAt?: number;
     pollAfterMs?: number;
   }): ToolTask {
@@ -155,6 +156,7 @@ export class AsyncToolRegistry {
       callId: entry.callId,
       toolName: entry.name,
       mode: 'defer',
+      input: entry.input,
       ...(entry.expiresAt !== undefined && {
         expiresAt: entry.expiresAt,
       }),
@@ -301,6 +303,9 @@ export class AsyncToolRegistry {
       mode: t.mode,
       status: t.status,
       startedAt: t.startedAt,
+      ...(t.input !== undefined && {
+        input: t.input,
+      }),
       ...(t.expiresAt !== undefined && {
         expiresAt: t.expiresAt,
       }),
diff --git a/packages/agent/src/lib/model-result.ts b/packages/agent/src/lib/model-result.ts
index f19fead3..87ab4910 100644
--- a/packages/agent/src/lib/model-result.ts
+++ b/packages/agent/src/lib/model-result.ts
@@ -707,6 +707,12 @@ export class ModelResult<
   > | null = null;
   private uiBroadcaster: ToolEventBroadcaster<ToolUiFragmentEvent> | null = null;
   private pendingUiFragments = new Set<Promise<void>>();
+  private queuedUiToolResults: Array<{
+    callId: string;
+    name: string;
+    input: Record<string, unknown>;
+    output: unknown;
+  }> = [];
   private uiBroadcasterCompletionPromise: Promise<void> | null = null;
   private turnBroadcasterCompletionPromise: Promise<void> | null = null;
   private initialStreamPipeStarted = false;
@@ -2775,10 +2781,12 @@ export class ModelResult<
     }
 
     const registry = this.ensureAsyncToolRegistry();
+    const input = (tc.arguments ?? {}) as Record<string, unknown>;
     const liveTask = registry.trackDeferred({
       callId: tc.id,
       taskId: invocation.taskId,
       name: String(tc.name),
+      input,
       ...(invocation.pollAfterMs !== undefined && {
         pollAfterMs: invocation.pollAfterMs,
       }),
@@ -2793,6 +2801,7 @@ export class ModelResult<
       mode: 'defer',
       status: 'working',
       startedAt: liveTask.startedAt,
+      input,
       ...(invocation.pollAfterMs !== undefined && {
         pollAfterMs: invocation.pollAfterMs,
       }),
@@ -3797,10 +3806,12 @@ export class ModelResult<
       if (collision) {
         return collision;
       }
+      const input = (toolCall.arguments ?? {}) as Record<string, unknown>;
       const liveTask = registry.trackDeferred({
         callId: toolCall.id,
         taskId: invocation.taskId,
         name: String(toolCall.name),
+        input,
         ...(invocation.expiresAt !== undefined && {
           expiresAt: invocation.expiresAt,
         }),
@@ -3816,6 +3827,7 @@ export class ModelResult<
         mode: 'defer',
         status: 'working',
         startedAt: liveTask.startedAt,
+        input,
         ...(invocation.pollAfterMs !== undefined && {
           pollAfterMs: invocation.pollAfterMs,
         }),
@@ -4422,6 +4434,41 @@ export class ModelResult<
     };
   }
 
+  /** @internal Queue externally resumed tool results for the UI lifecycle. */
+  queueUiToolResults(
+    results: Array<{
+      callId: string;
+      name: string;
+      input: Record<string, unknown>;
+      output: unknown;
+    }>,
+  ): void {
+    this.queuedUiToolResults.push(...results);
+  }
+
+  private dispatchQueuedUiToolResults(): void {
+    const queued = this.queuedUiToolResults;
+    this.queuedUiToolResults = [];
+    for (const result of queued) {
+      const tool = this.options.tools?.find(
+        (candidate) => isClientTool(candidate) && candidate.function.name === result.name,
+      );
+      if (tool) {
+        this.dispatchUiFragment({
+          toolCall: {
+            id: result.callId,
+            name: result.name,
+            arguments: result.input,
+          } as ParsedToolCall<Tool>,
+          tool,
+          result: {
+            result: result.output,
+          },
+        });
+      }
+    }
+  }
+
   private dispatchUiFragment(value: {
     toolCall: ParsedToolCall<Tool>;
     tool: Tool;
@@ -6945,9 +6992,8 @@ export class ModelResult<
    */
   getUiStream(): AsyncIterableIterator<UiStreamEvent> {
     return async function* (this: ModelResult<TTools, TShared>) {
-      await this.initStreamGuarded();
-
       if (!this.options.tools?.length) {
+        await this.initStreamGuarded();
         let streamFailed = false;
         try {
           if (this.reusableStream) {
@@ -6973,6 +7019,8 @@ export class ModelResult<
       const uiBroadcaster = this.uiBroadcaster;
       const uiConsumer = uiBroadcaster.createConsumer();
       try {
+        this.dispatchQueuedUiToolResults();
+        await this.initStreamGuarded();
         const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
         if (!this.uiBroadcasterCompletionPromise) {
           this.uiBroadcasterCompletionPromise = executionPromise.finally(async () => {
diff --git a/packages/agent/src/lib/tool-types.ts b/packages/agent/src/lib/tool-types.ts
index c5c8b41d..e37efe02 100644
--- a/packages/agent/src/lib/tool-types.ts
+++ b/packages/agent/src/lib/tool-types.ts
@@ -1622,6 +1622,8 @@ export interface PendingAsyncTool {
   status: ToolTaskStatus;
   /** Unix ms when the task started. */
   startedAt: number;
+  /** The original call arguments, retained for deferred UI rendering. */
+  input?: Record<string, unknown>;
   /** Unix ms after which the task is considered expired. */
   expiresAt?: number;
   /** Poll-interval hint surfaced to the model and external pollers. */
diff --git a/packages/agent/tests/unit/async-tool-deferred.test.ts b/packages/agent/tests/unit/async-tool-deferred.test.ts
index 2a115bf8..257604df 100644
--- a/packages/agent/tests/unit/async-tool-deferred.test.ts
+++ b/packages/agent/tests/unit/async-tool-deferred.test.ts
@@ -152,6 +152,9 @@ describe('tool.deferred — pause & placeholder', () => {
       name: 'request_legal_review',
       mode: 'defer',
       status: 'working',
+      input: {
+        contractId: 'c-9',
+      },
     });
 
     // No follow-up request — the loop paused after the placeholder.
@@ -724,6 +727,9 @@ describe('tool.deferred — cross-process resume', () => {
       callId: 'call_d1',
       taskId: 'ticket_c-9',
       mode: 'defer',
+      input: {
+        contractId: 'c-9',
+      },
     });
   });
 
diff --git a/packages/agent/tests/unit/async-tool-registry.test.ts b/packages/agent/tests/unit/async-tool-registry.test.ts
index aeecb148..6cb10e79 100644
--- a/packages/agent/tests/unit/async-tool-registry.test.ts
+++ b/packages/agent/tests/unit/async-tool-registry.test.ts
@@ -84,6 +84,35 @@ describe('AsyncToolRegistry — timeout settlement', () => {
   });
 });
 
+describe('AsyncToolRegistry — deferred input', () => {
+  it('retains input in settlement and persistence snapshots', () => {
+    const registry = new AsyncToolRegistry();
+    const task = registry.trackDeferred({
+      callId: 'call_d1',
+      taskId: 'task_d1',
+      name: 'weather',
+      input: {
+        city: 'Lisbon',
+      },
+    });
+
+    expect(task.input).toEqual({
+      city: 'Lisbon',
+    });
+    expect(registry.snapshot()[0]).toMatchObject({
+      input: {
+        city: 'Lisbon',
+      },
+    });
+    registry.cancelTask('task_d1');
+    expect(registry.takeSettled()[0]).toMatchObject({
+      input: {
+        city: 'Lisbon',
+      },
+    });
+  });
+});
+
 describe('AsyncToolRegistry — grace-window visibility (register/untrack)', () => {
   it('a registered (not yet tracked) task is reachable by steer and cancel', () => {
     const registry = new AsyncToolRegistry();
diff --git a/packages/agent/tests/unit/openui-stream.test.ts b/packages/agent/tests/unit/openui-stream.test.ts
index afaea68f..919388c2 100644
--- a/packages/agent/tests/unit/openui-stream.test.ts
+++ b/packages/agent/tests/unit/openui-stream.test.ts
@@ -10,13 +10,19 @@ import { StreamEvents$inboundSchema } from '@openrouter/sdk/models/streamevents'
 import { describe, expect, it, vi } from 'vitest';
 import { z } from 'zod/v4';
 import { callModel } from '../../src/inner-loop/call-model.js';
+import { resumeToolResults } from '../../src/inner-loop/resume-tool-results.js';
 import { ModelResult } from '../../src/lib/model-result.js';
 import { fragment } from '../../src/lib/openui/fragment.js';
 import { createLibrary, defineComponent } from '../../src/lib/openui/library.js';
 import { translateUiEvent } from '../../src/lib/openui/ui-stream.js';
 import { ReusableReadableStream } from '../../src/lib/reusable-stream.js';
 import { tool } from '../../src/lib/tool.js';
-import type { ParsedToolCall, Tool } from '../../src/lib/tool-types.js';
+import type {
+  ConversationState,
+  ParsedToolCall,
+  StateAccessor,
+  Tool,
+} from '../../src/lib/tool-types.js';
 import { isToolUiFragmentEvent } from '../../src/lib/tool-types.js';
 
 const mockBetaResponsesSend = vi.hoisted(() => vi.fn());
@@ -996,38 +1002,48 @@ describe('async tool settlement', () => {
 });
 
 describe('late async tool UI settlement', () => {
-  it('skips rendering when deferred settlement has no retained input', async () => {
-    const toUiOutput = vi.fn(() => ui.Text('never'));
-    const deferred = tool({
-      name: 'deferred_ui',
-      lifecycle: 'deferred',
-      inputSchema: z.object({
-        city: z.string(),
-      }),
-      outputSchema: z.object({
-        summary: z.string(),
-      }),
-      run: () => ({
-        taskId: 'task_1',
-      }),
-      toUiOutput,
-    });
+  const deferred = tool({
+    name: 'deferred_ui',
+    lifecycle: 'deferred',
+    inputSchema: z.object({
+      city: z.string(),
+    }),
+    outputSchema: z.object({
+      summary: z.string(),
+    }),
+    run: () => ({
+      taskId: 'task_1',
+    }),
+    toUiOutput: ({ input, output }) => ui.Text(`${input.city}: ${output.summary}`),
+  });
+
+  function makeSettlementHarness(input?: Record<string, unknown>) {
     const result = new ModelResult({
       request: {
         model: 'test-model',
         input: 'test',
-        tools: [
-          deferred,
-        ],
       },
+      tools: [
+        deferred,
+      ],
       client: {} as OpenRouterCore,
     });
+    const pushed: unknown[] = [];
     const internal = result as unknown as {
       asyncToolRegistry: {
         takeSettled: () => Array<Record<string, unknown>>;
       };
+      uiBroadcaster: {
+        activeConsumerCount: number;
+        push: (event: unknown) => void;
+      };
       flushAsyncToolDeliveries: () => Promise<boolean>;
       injectAppendPromptMessage: () => Promise<void>;
+      drainUiFragments: () => Promise<void>;
+    };
+    internal.uiBroadcaster = {
+      activeConsumerCount: 1,
+      push: (event) => pushed.push(event),
     };
     internal.asyncToolRegistry = {
       takeSettled: () => [
@@ -1039,15 +1055,130 @@ describe('late async tool UI settlement', () => {
           result: {
             summary: 'Clear',
           },
+          ...(input !== undefined && {
+            input,
+          }),
           durationMs: 1,
         },
       ],
     };
     internal.injectAppendPromptMessage = async () => undefined;
+    return {
+      internal,
+      pushed,
+    };
+  }
+
+  it('renders same-run deferred settlement with retained input', async () => {
+    const { internal, pushed } = makeSettlementHarness({
+      city: 'Lisbon',
+    });
 
     await internal.flushAsyncToolDeliveries();
+    await internal.drainUiFragments();
 
-    expect(toUiOutput).not.toHaveBeenCalled();
+    expect(pushed).toContainEqual(
+      expect.objectContaining({
+        type: 'tool.ui_fragment',
+        toolCallId: 'c1',
+        fragment: {
+          dialect: 'openui-lang/0.5',
+          source: 'root = Text("Lisbon: Clear")',
+        },
+      }),
+    );
+  });
+
+  it('renders externally resumed deferred settlement through the UI stream', async () => {
+    mockBetaResponsesSend.mockReset();
+    mockBetaResponsesSend.mockResolvedValueOnce({
+      ok: true,
+      value: response('r2', [
+        {
+          type: 'message',
+          id: 'm1',
+          role: 'assistant',
+          status: 'completed',
+          content: [
+            {
+              type: 'output_text',
+              text: 'done',
+              annotations: [],
+            },
+          ],
+        },
+      ]),
+    });
+    let state: ConversationState = {
+      id: 'conversation_1',
+      messages: [],
+      status: 'awaiting_async_tools',
+      pendingAsyncTools: [
+        {
+          callId: 'c1',
+          taskId: 'task_1',
+          name: 'deferred_ui',
+          mode: 'defer',
+          status: 'working',
+          startedAt: Date.now(),
+          input: {
+            city: 'Lisbon',
+          },
+        },
+      ],
+    };
+    const accessor: StateAccessor = {
+      load: async () => state,
+      save: async (next) => {
+        state = next;
+      },
+    };
+
+    const result = await resumeToolResults(
+      {
+        _options: {},
+      } as OpenRouterCore,
+      {
+        state: accessor,
+        tools: [
+          deferred,
+        ] as const,
+        results: [
+          {
+            taskId: 'task_1',
+            output: {
+              summary: 'Clear',
+            },
+          },
+        ],
+        run: {
+          model: 'test-model',
+        },
+      },
+    );
+    const events: unknown[] = [];
+    if (result) {
+      for await (const event of result.getUiStream()) {
+        events.push(event);
+      }
+    }
+
+    expect(events).toContainEqual({
+      type: 'fragment',
+      toolCallId: 'c1',
+      toolName: 'deferred_ui',
+      dialect: 'openui-lang/0.5',
+      source: 'root = Text("Lisbon: Clear")',
+    });
+  });
+
+  it('skips legacy deferred settlement without retained input', async () => {
+    const { internal, pushed } = makeSettlementHarness();
+
+    await internal.flushAsyncToolDeliveries();
+    await internal.drainUiFragments();
+
+    expect(pushed).toEqual([]);
   });
 });