@otto-code/protocol 0.6.7 → 0.7.1

package/dist/widgets/theme.js

@@ -0,0 +1,149 @@
+/**
+ * The CSS custom properties a widget fragment is written against, and the
+ * mapping from Otto's semantic theme tokens onto them.
+ *
+ * The HOST assembles the guest document, not the daemon — because only the
+ * client knows which theme is live, and a theme switch has to re-skin an
+ * already-rendered widget without a daemon round trip. The variable NAMES are
+ * frozen here so the contract document, the fixtures, and every renderer agree.
+ */
+const FALLBACK_WARNING = "#d97706";
+const FALLBACK_SERIF = "Georgia, 'Times New Roman', serif";
+/**
+ * Parse `#rgb` / `#rrggbb` / `#rrggbbaa`. Alpha is dropped: these tints are
+ * composited against a known surface here, so carrying alpha through would
+ * double-apply it. Returns null for anything else (named colors, rgb(), the
+ * `rgba(0,0,0,0.06)` hover token) and callers pass such values through
+ * untouched rather than guessing.
+ */
+function parseHex(value) {
+    const hex = value.trim();
+    if (!hex.startsWith("#")) {
+        return null;
+    }
+    const body = hex.slice(1);
+    if (body.length === 3) {
+        const r = Number.parseInt(body[0] + body[0], 16);
+        const g = Number.parseInt(body[1] + body[1], 16);
+        const b = Number.parseInt(body[2] + body[2], 16);
+        return Number.isNaN(r + g + b) ? null : { r, g, b };
+    }
+    if (body.length === 6 || body.length === 8) {
+        const r = Number.parseInt(body.slice(0, 2), 16);
+        const g = Number.parseInt(body.slice(2, 4), 16);
+        const b = Number.parseInt(body.slice(4, 6), 16);
+        return Number.isNaN(r + g + b) ? null : { r, g, b };
+    }
+    return null;
+}
+function toHex({ r, g, b }) {
+    const channel = (value) => Math.max(0, Math.min(255, Math.round(value)))
+        .toString(16)
+        .padStart(2, "0");
+    return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+/** Composite `color` over `base` at `amount` opacity, opaquely. */
+function mix(color, base, amount) {
+    const from = parseHex(color);
+    const to = parseHex(base);
+    if (!from || !to) {
+        return color;
+    }
+    return toHex({
+        r: to.r + (from.r - to.r) * amount,
+        g: to.g + (from.g - to.g) * amount,
+        b: to.b + (from.b - to.b) * amount,
+    });
+}
+/**
+ * A role color legible as TEXT on the widget background. The raw accent/danger
+ * tokens are tuned to sit on Otto's chrome, which is not always the same
+ * contrast problem as body copy on `--surface-0`, so nudge toward the
+ * foreground on dark themes and away from it on light ones.
+ */
+function roleText(color, input) {
+    return input.isDark ? mix(color, "#ffffff", 0.78) : mix(color, "#000000", 0.85);
+}
+/** A wash of a role color usable as a fill behind role text. */
+function roleTint(color, input) {
+    return mix(color, input.surface0, input.isDark ? 0.22 : 0.12);
+}
+/** SVG palette. Fixed hues rather than theme tokens — a chart needs categorical
+ * separation that survives every theme, and the two dark/light rows keep each
+ * hue legible on whichever surface it lands on. */
+const SVG_PALETTE_LIGHT = {
+    blue: "#2563eb",
+    teal: "#0d9488",
+    amber: "#b45309",
+    red: "#dc2626",
+    green: "#16a34a",
+    purple: "#7c3aed",
+    pink: "#db2777",
+    gray: "#52525b",
+};
+const SVG_PALETTE_DARK = {
+    blue: "#60a5fa",
+    teal: "#2dd4bf",
+    amber: "#fbbf24",
+    red: "#f87171",
+    green: "#4ade80",
+    purple: "#c084fc",
+    pink: "#f472b6",
+    gray: "#a1a1aa",
+};
+export function widgetPaletteFor(isDark) {
+    return isDark ? SVG_PALETTE_DARK : SVG_PALETTE_LIGHT;
+}
+/**
+ * The `:root` custom-property block. Split out from the stylesheet so a theme
+ * change can be reasoned about (and tested) without the 200 lines of rules.
+ */
+export function buildWidgetThemeVariables(input) {
+    const warning = input.warning ?? FALLBACK_WARNING;
+    const serif = input.fontSerif ?? FALLBACK_SERIF;
+    const palette = widgetPaletteFor(input.isDark);
+    const paletteVars = Object.entries(palette)
+        .map(([name, value]) => `  --c-${name}: ${value};`)
+        .join("\n");
+    return [
+        ":root {",
+        `  --surface-0: ${input.surface0};`,
+        `  --surface-1: ${input.surface1};`,
+        `  --surface-2: ${input.surface2};`,
+        `  --text-primary: ${input.foreground};`,
+        `  --text-secondary: ${mix(input.foreground, input.surface0, 0.75)};`,
+        `  --text-muted: ${input.foregroundMuted};`,
+        `  --text-accent: ${roleText(input.accent, input)};`,
+        `  --text-danger: ${roleText(input.danger, input)};`,
+        `  --text-success: ${roleText(input.success, input)};`,
+        `  --text-warning: ${roleText(warning, input)};`,
+        `  --bg-accent: ${roleTint(input.accent, input)};`,
+        `  --bg-danger: ${roleTint(input.danger, input)};`,
+        `  --bg-success: ${roleTint(input.success, input)};`,
+        `  --bg-warning: ${roleTint(warning, input)};`,
+        `  --border: ${input.border};`,
+        `  --border-strong: ${mix(input.foreground, input.border, 0.25)};`,
+        `  --border-stronger: ${mix(input.foreground, input.border, 0.5)};`,
+        `  --border-accent: ${mix(input.accent, input.border, 0.6)};`,
+        `  --border-danger: ${mix(input.danger, input.border, 0.6)};`,
+        `  --border-success: ${mix(input.success, input.border, 0.6)};`,
+        `  --border-warning: ${mix(warning, input.border, 0.6)};`,
+        `  --font-sans: ${input.fontSans};`,
+        `  --font-mono: ${input.fontMono};`,
+        `  --font-voice: ${serif};`,
+        "  --radius: 8px;",
+        "  --radius-sm: 4px;",
+        "  --pad-sm: 8px;",
+        "  --pad-md: 12px;",
+        "  --pad-lg: 16px;",
+        "  --pad-xl: 24px;",
+        "  --gap-xs: 4px;",
+        "  --gap-sm: 8px;",
+        "  --gap-md: 12px;",
+        "  --gap-lg: 16px;",
+        "  --gap-xl: 24px;",
+        paletteVars,
+        "}",
+    ].join("\n");
+}
+//# sourceMappingURL=theme.js.map

package/dist/widgets/types.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+/**
+ * Inline widgets — an agent emits a tool call carrying a fragment of HTML or
+ * SVG, and Otto renders it inline in the transcript at that call's position.
+ *
+ * Widgets are NOT artifacts. An artifact is a file-backed document the user
+ * keeps (see `../artifacts/types.ts`); a widget is a thought the model had in
+ * the middle of a sentence. It has no file, no versioning, and no lifetime
+ * beyond its transcript position — the tool-call input IS the content, so a
+ * re-opened chat re-renders its widgets from the stored timeline for free.
+ *
+ * See `docs/widgets.md`.
+ */
+/** Otto tool that carries a widget fragment. */
+export declare const WIDGET_TOOL_NAME = "show_widget";
+/** Companion tool returning the host contract the model codes against. */
+export declare const WIDGET_CONTRACT_TOOL_NAME = "widget_contract";
+/**
+ * Key under a tool call's `metadata` where the normalized widget payload rides.
+ *
+ * Deliberately NOT a new `ToolCallDetail` variant: `ToolCallDetailPayloadSchema`
+ * (messages.ts) is a `z.discriminatedUnion`, so a client that predates widgets
+ * would reject an unknown discriminator and fail to parse the ENTIRE timeline
+ * message, not just the widget. `metadata` is `z.record(z.string(), z.unknown())`
+ * — an old client carries this through untouched and renders the tool call's
+ * `plain_text` detail as an ordinary row. That is the protocol contract doing
+ * its job.
+ */
+export declare const WIDGET_METADATA_KEY = "ottoWidget";
+/**
+ * Payload shape version. Bumped only on a breaking change to the fields below;
+ * a client that does not recognize the version renders the fallback row rather
+ * than guessing.
+ */
+export declare const WIDGET_PAYLOAD_VERSION = 1;
+/**
+ * How the fragment is interpreted. Auto-detected from the code itself (a
+ * fragment starting with `<svg` is SVG), never asked of the model — one less
+ * thing for it to get wrong.
+ */
+export declare const WIDGET_MODES: readonly ["html", "svg"];
+export type WidgetMode = (typeof WIDGET_MODES)[number];
+/**
+ * Hard ceiling on a fragment. A widget rides in the timeline and is re-sent on
+ * every backfill, so an unbounded one is a permanent tax on the conversation.
+ * Generous enough for a dense dashboard; anything past it is a document, and a
+ * document is an artifact.
+ */
+export declare const WIDGET_MAX_CODE_CHARS = 128000;
+/** Loading messages shown while the fragment streams in. */
+export declare const WIDGET_MAX_LOADING_MESSAGES = 4;
+export declare const WIDGET_MAX_LOADING_MESSAGE_CHARS = 120;
+export declare const WIDGET_MAX_TITLE_CHARS = 120;
+declare const WidgetPayloadSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    id: z.ZodString;
+    title: z.ZodString;
+    mode: z.ZodEnum<{
+        html: "html";
+        svg: "svg";
+    }>;
+    code: z.ZodString;
+    loadingMessages: z.ZodArray<z.ZodString>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WidgetPayload = z.infer<typeof WidgetPayloadSchema>;
+/**
+ * Read a widget payload out of a tool call's metadata bag.
+ *
+ * Returns null for anything that is not a widget of a version this build
+ * understands — the caller renders the ordinary tool-call row instead. Never
+ * throws: metadata is `unknown` by contract and may come from a newer daemon.
+ */
+export declare function readWidgetPayload(metadata: Record<string, unknown> | undefined): WidgetPayload | null;
+/** Detect the render mode from the fragment itself. */
+export declare function detectWidgetMode(code: string): WidgetMode;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/widgets/types.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/**
+ * Inline widgets — an agent emits a tool call carrying a fragment of HTML or
+ * SVG, and Otto renders it inline in the transcript at that call's position.
+ *
+ * Widgets are NOT artifacts. An artifact is a file-backed document the user
+ * keeps (see `../artifacts/types.ts`); a widget is a thought the model had in
+ * the middle of a sentence. It has no file, no versioning, and no lifetime
+ * beyond its transcript position — the tool-call input IS the content, so a
+ * re-opened chat re-renders its widgets from the stored timeline for free.
+ *
+ * See `docs/widgets.md`.
+ */
+/** Otto tool that carries a widget fragment. */
+export const WIDGET_TOOL_NAME = "show_widget";
+/** Companion tool returning the host contract the model codes against. */
+export const WIDGET_CONTRACT_TOOL_NAME = "widget_contract";
+/**
+ * Key under a tool call's `metadata` where the normalized widget payload rides.
+ *
+ * Deliberately NOT a new `ToolCallDetail` variant: `ToolCallDetailPayloadSchema`
+ * (messages.ts) is a `z.discriminatedUnion`, so a client that predates widgets
+ * would reject an unknown discriminator and fail to parse the ENTIRE timeline
+ * message, not just the widget. `metadata` is `z.record(z.string(), z.unknown())`
+ * — an old client carries this through untouched and renders the tool call's
+ * `plain_text` detail as an ordinary row. That is the protocol contract doing
+ * its job.
+ */
+export const WIDGET_METADATA_KEY = "ottoWidget";
+/**
+ * Payload shape version. Bumped only on a breaking change to the fields below;
+ * a client that does not recognize the version renders the fallback row rather
+ * than guessing.
+ */
+export const WIDGET_PAYLOAD_VERSION = 1;
+/**
+ * How the fragment is interpreted. Auto-detected from the code itself (a
+ * fragment starting with `<svg` is SVG), never asked of the model — one less
+ * thing for it to get wrong.
+ */
+export const WIDGET_MODES = ["html", "svg"];
+/**
+ * Hard ceiling on a fragment. A widget rides in the timeline and is re-sent on
+ * every backfill, so an unbounded one is a permanent tax on the conversation.
+ * Generous enough for a dense dashboard; anything past it is a document, and a
+ * document is an artifact.
+ */
+export const WIDGET_MAX_CODE_CHARS = 128000;
+/** Loading messages shown while the fragment streams in. */
+export const WIDGET_MAX_LOADING_MESSAGES = 4;
+export const WIDGET_MAX_LOADING_MESSAGE_CHARS = 120;
+export const WIDGET_MAX_TITLE_CHARS = 120;
+const WidgetPayloadSchema = z.object({
+    version: z.number().int().positive(),
+    id: z.string().min(1),
+    title: z.string(),
+    mode: z.enum(WIDGET_MODES),
+    code: z.string(),
+    loadingMessages: z.array(z.string()),
+    /** Set when the fragment hit {@link WIDGET_MAX_CODE_CHARS} and was cut. */
+    truncated: z.boolean().optional(),
+});
+/**
+ * Read a widget payload out of a tool call's metadata bag.
+ *
+ * Returns null for anything that is not a widget of a version this build
+ * understands — the caller renders the ordinary tool-call row instead. Never
+ * throws: metadata is `unknown` by contract and may come from a newer daemon.
+ */
+export function readWidgetPayload(metadata) {
+    const raw = metadata?.[WIDGET_METADATA_KEY];
+    if (raw === undefined || raw === null) {
+        return null;
+    }
+    const parsed = WidgetPayloadSchema.safeParse(raw);
+    if (!parsed.success) {
+        return null;
+    }
+    if (parsed.data.version !== WIDGET_PAYLOAD_VERSION) {
+        return null;
+    }
+    return parsed.data;
+}
+/** Detect the render mode from the fragment itself. */
+export function detectWidgetMode(code) {
+    return /^\s*<svg[\s>]/i.test(code) ? "svg" : "html";
+}
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-code/protocol",
-  "version": "0.6.7",
+  "version": "0.7.1",
   "description": "Otto shared protocol schemas and wire types",
   "license": "AGPL-3.0-or-later",
   "files": [