genui
Generative UI for Kortix: the agent writes typed UI blocks (cards, comparisons, charts, maps, tabs) in OpenUI Lang inside its replies, and web, mobile, and SDK hosts render them through `@kortix/sdk/g
SKILL.md.agents/skills/genui/SKILL.md
GitHubGenerative UI (genui)
Status (2026-10-24): on dev, always on. Generative UI has no feature flag and no kill switch. Every session lists the kortix-genui system skill, and every client renders openui blocks. SDK (@kortix/sdk/genui, /genui/react), runtime (the skill, channel guards), web, and mobile are implemented. Open: plan-5 task 7's device check and OTA publish, which wait on Jay (references/mobile-device-check.md).
The references/ plans and spec are the build record. Their genui project flag, GENUI_ENABLED kill switch and KORTIX_GENUI sandbox env were deleted on 2026-10-24. A stored experimental.genui project override is ignored, and the API sends experimental.genui: true for older clients.
Phase 0 (provisional, local stand-in models): GO (2026-10-09, prompt 00a9030e). Valid: deepseek-v4.1-flash 100.0%, glm-5.3-flash 100.0%, gate 97.0%; kimi-k3 unavailable (503); Jay's 4 models untested. See references/eval-results.md.
| Path | What it is |
|---|---|
references/spec.md |
The product spec: problem, goals, architecture, the 17 v1 components, streaming contract, toggle, requirements with acceptance criteria, Phase 4 guards, metrics, phases, risks, open questions |
references/plan.md |
Master implementation plan: architecture, global constraints, review focus, spec deltas D1–D12, file map, interface contracts, order of work, delivery |
references/plan-1-sdk.md |
@kortix/sdk/genui + /genui/react + default components (9 tasks; code verified before writing) |
references/plan-2-eval.md |
Phase 0 evaluation of 4 models on 46 synthetic cases, go/no-go gate (2 tasks) |
references/plan-3-runtime.md |
Channel guards, and the deleted flag and kill switch (3 tasks, historical; the prompt-injection tasks are removed) |
references/plan-4-web.md |
Web and desktop renderer, components, charts, map, settings, copy/export, telemetry, verification (8 tasks) |
references/plan-5-mobile.md |
Mobile renderer, components, charts, map, settings, copy, device check, OTA (7 tasks) |
references/eval-results.md |
Phase 0 results: one summary table per eval run, appended by scripts/eval.ts |
references/mobile-device-check.md |
On-device checklist for mobile (Jay runs it), the OTA publish procedure, the old-build check |
scripts/eval.ts |
Phase 0 runner: every case against each model through the LLM gateway; writes output/genui-eval/ and appends eval-results.md. GENUI_EVAL_CASES runs a subset; GENUI_EVAL_EFFORT sends reasoning_effort. A Codex model needs a project gateway key (POST /v1/projects/{projectId}/gateway/keys) as GENUI_EVAL_TOKEN: a PAT has no project, so the gateway answers provider_not_connected |
scripts/eval-prompts.json |
The 60 synthetic eval cases: prompt, optional tool result (context), expected UI use (expect), forbidden components (forbid), richness bar (rich) |
scripts/score.ts, scripts/score.test.ts |
Scores one reply (valid blocks, overuse, underuse, forbidden components, images, foreign images, interleaving, prose share, thin) and applies the go/no-go gate |
Rules that already hold
- UI travels as an
openuifenced block inside the existingtextpart.kortix.transcript.v1does not change. - Only
@kortix/sdk/genuiimports@openuidev/*. Pin it to an exact version. - Every component has a zod schema, a web renderer, a native renderer, and
toMarkdown. A component enters the prompt only when all four exist. - The catalog is the
kortix-genuimanaged system skill (packages/starter/templates/managed/skills/kortix-genui/SKILL.md), generated frombuildGenuiPrompt()bybun packages/sdk/scripts/genui-skill.ts;packages/sdk/src/genui/skill.test.tsfails while it is stale. It is never in the system prompt. Every session lists it; there is no flag (apps/kortix-sandbox-agent-server/src/__tests__/managed-skills-genui.test.ts). - No raw model output reaches Slack, push, email, or the CLI. Run
toMarkdown. - Query, Mutation, Form, Input, and Button are Phase 4 only, with the guards in
references/spec.md§9. - A Map draws tiles only from a style we configure: web
NEXT_PUBLIC_GENUI_MAP_STYLE_URL(optionalNEXT_PUBLIC_GENUI_MAP_STYLE_URL_DARK), mobileEXPO_PUBLIC_GENUI_MAP_STYLE_URL. Unset, it renders the place list with OpenStreetMap links. Never mapcn's CARTO default (commercial license). Web loads MapLibre only with a style set, and serves its worker from/maplibre/(copied out of node_modules byapps/web/scripts/viewer-wasm.mjs). - A node that fails its schema never takes valid content with it.
sanitizeTree(packages/sdk/src/genui/validate.ts) puts its valid subtrees in its place, in source order. A subtree the parent slot cannot hold rises to the nearest ancestor that can (any block fits a Stack); a non-block gives up its own children. A root that fails becomes a Stack of its subtrees. Only a block with no valid subtree hasroot: null. - Every host runs
separateGenuiClosers(@kortix/sdk/genui/fence) on reply text before it looks for fences: it moves a closer the model glued to the last statement (…")````) onto its own line.genuiToMarkdownruns it itself. The web (unified-markdown.tsx), mobile (selectable-markdown.tsx) andscripts/score.ts` call it directly. - A block's root is any block (
root = Steps(...));sanitizeTreewraps a non-Stack root in a Stack. The skill body is ours: PREAMBLE, SYNTAX, the lang-core signatures fromGENUI_LIBRARY.toSpec(), RULES, EXAMPLES (packages/sdk/src/genui/prompt.ts). lang-core's prose sections are not used. - Photos for a visual answer come from ONE batched
image_searchcall; a Checklist's ticks never leave the device. - A client whose bundled SDK predates a component cannot render or convert it: the parser reports
unknown-componentandno-root, and the block shows This content could not be displayed., not the component's markdown. This hits a published CLI (genuiToMarkdowninapps/cli), a mobile build without the OTA, and third-party hosts on an older@kortix/sdk. Ship order for a new component: publish the CLI on the new SDK and send the mobile OTA first; only then let the regeneratedkortix-genuiskill that teaches it reach sandboxes. - The
kortix-genuidescription leaves software installs and terminal steps out on purpose ("How do I install Node.js on macOS? Step by step." stays prose with code fences).scripts/eval.tsputs the skill in the system message, so it measures the reply shape, not whether the agent loads the skill: measure the trigger in a real session.