@dungle-scrubs/admin-ui-soft 0.0.0-stage → 0.1.0

package/dist/ai/compositions/usage-meter/usage-format.js

@@ -0,0 +1,107 @@
+//#region src/ai/compositions/usage-meter/usage-format.ts
+/** A finite, non-negative number, or `undefined`. */
+function known(value) {
+	return value !== void 0 && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+/**
+* A token count, compact: 840, 48.2k, 1.2M. Like formatLatency, the unit is
+* chosen after rounding, so 999,950 reads "1M", not "1000k".
+*/
+function formatTokens(tokens) {
+	const trim = (value) => value.toFixed(1).replace(/\.0$/, "");
+	const count = Math.round(tokens);
+	if (count < 1e3) return `${count}`;
+	const thousands = Math.round(count / 100) / 10;
+	if (thousands < 1e3) return `${trim(thousands)}k`;
+	return `${trim(Math.round(count / 1e5) / 10)}M`;
+}
+/**
+* A cost in US dollars. Agent calls often cost fractions of a cent, so a cost
+* under a dollar keeps up to four decimals ("$0.0034", "$0.0912", "$0.42")
+* rather than rounding to "$0.00"; a dollar or more keeps two.
+*/
+function formatCost(costUsd) {
+	if (costUsd > 0 && costUsd < 1e-4) return "<$0.0001";
+	const decimals = costUsd < 1 ? 4 : 2;
+	return `$${costUsd.toLocaleString("en-US", {
+		minimumFractionDigits: 2,
+		maximumFractionDigits: decimals
+	})}`;
+}
+/**
+* A wall-clock duration: 840 ms, 2.4 s, 1 m 12 s. Each unit is chosen after
+* rounding to the precision it prints, so 999.6 ms reads "1 s", not "1000 ms",
+* and 59,950 ms reads "1 m", not "60 s".
+*/
+function formatLatency(latencyMs) {
+	const ms = Math.round(latencyMs);
+	if (ms < 1e3) return `${ms} ms`;
+	const tenths = Math.round(latencyMs / 100);
+	if (tenths < 600) return `${(tenths / 10).toFixed(1).replace(/\.0$/, "")} s`;
+	const totalSeconds = Math.round(latencyMs / 1e3);
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	return seconds === 0 ? `${minutes} m` : `${minutes} m ${seconds} s`;
+}
+/** Reads a Usage record, dropping missing, negative and non-finite numbers. */
+function readUsage(usage) {
+	const inputTokens = known(usage.inputTokens);
+	const outputTokens = known(usage.outputTokens);
+	const hasTokens = inputTokens !== void 0 || outputTokens !== void 0;
+	return {
+		model: usage.model?.trim() || void 0,
+		inputTokens,
+		outputTokens,
+		cachedInputTokens: known(usage.cachedInputTokens),
+		reasoningTokens: known(usage.reasoningTokens),
+		totalTokens: hasTokens ? (inputTokens ?? 0) + (outputTokens ?? 0) : void 0,
+		costUsd: known(usage.costUsd),
+		contextWindow: known(usage.contextWindow) || void 0,
+		latencyMs: known(usage.latencyMs)
+	};
+}
+/** Whether the reading has anything to show. */
+function isEmptyReading(reading) {
+	return Object.values(reading).every((value) => value === void 0);
+}
+/** Whether the reading carries any token count, including only a cached or reasoning subset. */
+function hasTokenCounts(reading) {
+	return [
+		reading.inputTokens,
+		reading.cachedInputTokens,
+		reading.outputTokens,
+		reading.reasoningTokens
+	].some((tokens) => tokens !== void 0);
+}
+/**
+* What fills the context window, split so the slices add up to the total.
+* admin-ui's Usage contract counts cached input inside input and reasoning
+* inside output, so each pair splits into the subset and the rest. Empty
+* slices are left out.
+*/
+function contextSlices(reading) {
+	const input = reading.inputTokens ?? 0;
+	const output = reading.outputTokens ?? 0;
+	const cached = Math.min(reading.cachedInputTokens ?? 0, input);
+	const reasoning = Math.min(reading.reasoningTokens ?? 0, output);
+	return [
+		{
+			label: "Input",
+			tokens: input - cached
+		},
+		{
+			label: "Cached input",
+			tokens: cached
+		},
+		{
+			label: "Output",
+			tokens: output - reasoning
+		},
+		{
+			label: "Reasoning",
+			tokens: reasoning
+		}
+	].filter((slice) => slice.tokens > 0);
+}
+//#endregion
+export { contextSlices, formatCost, formatLatency, formatTokens, hasTokenCounts, isEmptyReading, readUsage };

package/dist/ai/compositions/usage-meter/usage-meter.d.ts

@@ -0,0 +1,32 @@
+import { Usage } from "../../types.js";
+import * as React from "react";
+//#region src/ai/compositions/usage-meter/usage-meter.d.ts
+export type UsageMeterVariant = "compact" | "expanded";
+/** What the usage covers. */
+export type UsageMeterScope = "run" | "thread";
+export interface UsageMeterProps {
+  /** The usage to show. Fields it does not carry are hidden, never shown as zero. */
+  usage: Usage;
+  /**
+   * `compact` is an inline reading for a header (model, tokens in and out,
+   * cost, latency and a context ring); `expanded` is a breakdown panel.
+   * Defaults to `compact`.
+   */
+  variant?: UsageMeterVariant;
+  /** Whether the usage covers one run or a whole thread. Defaults to `run`. */
+  scope?: UsageMeterScope;
+  /** Which side the compact context ring's breakdown opens on. Defaults to `bottom`. */
+  contextSide?: "top" | "bottom" | "left" | "right";
+  className?: string;
+}
+/**
+ * Tokens in and out, cost, context-window use and latency for one run or a
+ * whole thread, from a `Usage` record. A field the record does not carry is
+ * hidden: a run with no cost shows no cost row, not "$0.00".
+ *
+ * Built on the registry's ContextDisplay ring (compact), CostMeter and
+ * ContextBreakdown (expanded). Usage is always a prop, so nothing here reads
+ * thread state or needs `@assistant-ui/ai-sdk`.
+ */
+export declare function UsageMeter({ usage, variant, scope, contextSide, className }: UsageMeterProps): React.JSX.Element;
+//#endregion

package/dist/ai/compositions/usage-meter/usage-meter.js

@@ -0,0 +1,258 @@
+import { mono, paper } from "../../../components/assistant-ui/elements/surfaces.js";
+import { ContextBreakdown } from "../../../components/assistant-ui/elements/context-breakdown.js";
+import { ContextDisplay } from "../../../components/assistant-ui/elements/context-display.aui.js";
+import { CostMeter } from "../../../components/assistant-ui/elements/cost-meter.js";
+import { contextSlices, formatCost, formatLatency, formatTokens, hasTokenCounts, isEmptyReading, readUsage } from "./usage-format.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "cn";
+import { TimerIcon } from "lucide-react";
+//#region src/ai/compositions/usage-meter/usage-meter.tsx
+const SCOPE_TITLE = {
+	run: "Run usage",
+	thread: "Thread usage"
+};
+const SCOPE_LABEL = {
+	run: "this run",
+	thread: "this thread"
+};
+const SLICE_TINT = {
+	Input: "bg-info",
+	"Cached input": "bg-info",
+	Output: "bg-violet-500",
+	Reasoning: "bg-violet-300"
+};
+/**
+* The counts the ring's breakdown lists: the same split as the expanded
+* panel (uncached input, cached input, output less reasoning, reasoning), so
+* the rows add up to the total the ring shows.
+*/
+function ringUsage(reading, totalTokens) {
+	const slices = contextSlices(reading);
+	const slice = (label) => slices.find((item) => item.label === label)?.tokens;
+	return {
+		totalTokens,
+		inputTokens: slice("Input"),
+		cachedInputTokens: slice("Cached input"),
+		outputTokens: slice("Output"),
+		reasoningTokens: slice("Reasoning")
+	};
+}
+/**
+* Tokens in and out, cost, context-window use and latency for one run or a
+* whole thread, from a `Usage` record. A field the record does not carry is
+* hidden: a run with no cost shows no cost row, not "$0.00".
+*
+* Built on the registry's ContextDisplay ring (compact), CostMeter and
+* ContextBreakdown (expanded). Usage is always a prop, so nothing here reads
+* thread state or needs `@assistant-ui/ai-sdk`.
+*/
+function UsageMeter({ usage, variant = "compact", scope = "run", contextSide = "bottom", className }) {
+	const reading = readUsage(usage);
+	return variant === "expanded" ? /* @__PURE__ */ jsx(ExpandedUsage, {
+		reading,
+		scope,
+		className
+	}) : /* @__PURE__ */ jsx(CompactUsage, {
+		reading,
+		scope,
+		side: contextSide,
+		className
+	});
+}
+/** One term and its value; the term is for assistive technology only. */
+function Stat({ term, children, className }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "usage-meter-stat",
+		className: cn("flex items-center", className),
+		children: [/* @__PURE__ */ jsx("dt", {
+			className: "sr-only",
+			children: term
+		}), /* @__PURE__ */ jsx("dd", {
+			className: "flex min-w-0 items-center gap-1",
+			children
+		})]
+	});
+}
+/** A count with its unit word ("in", "out") shown but not read twice. */
+function TokenStat({ term, tokens, unit }) {
+	return /* @__PURE__ */ jsxs(Stat, {
+		term,
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "text-foreground tabular-nums",
+			children: formatTokens(tokens)
+		}), /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			children: unit
+		})]
+	});
+}
+function CompactUsage({ reading, scope, side, className }) {
+	const title = SCOPE_TITLE[scope];
+	const { contextWindow, totalTokens } = reading;
+	return /* @__PURE__ */ jsx("div", {
+		role: "group",
+		"aria-label": title,
+		"data-slot": "usage-meter",
+		"data-variant": "compact",
+		className: cn("text-muted-foreground inline-flex max-w-full text-xs", className),
+		children: isEmptyReading(reading) ? /* @__PURE__ */ jsx("span", { children: "No usage recorded" }) : /* @__PURE__ */ jsxs("dl", {
+			className: "flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1",
+			children: [
+				reading.model ? /* @__PURE__ */ jsx(Stat, {
+					term: "Model",
+					className: "min-w-0",
+					children: /* @__PURE__ */ jsx("span", {
+						className: "text-foreground truncate font-mono text-[11px]",
+						children: reading.model
+					})
+				}) : null,
+				reading.inputTokens !== void 0 ? /* @__PURE__ */ jsx(TokenStat, {
+					term: "Input tokens",
+					tokens: reading.inputTokens,
+					unit: "in"
+				}) : null,
+				reading.outputTokens !== void 0 ? /* @__PURE__ */ jsx(TokenStat, {
+					term: "Output tokens",
+					tokens: reading.outputTokens,
+					unit: "out"
+				}) : null,
+				reading.inputTokens === void 0 && reading.cachedInputTokens !== void 0 ? /* @__PURE__ */ jsx(TokenStat, {
+					term: "Cached input tokens",
+					tokens: reading.cachedInputTokens,
+					unit: "cached"
+				}) : null,
+				reading.outputTokens === void 0 && reading.reasoningTokens !== void 0 ? /* @__PURE__ */ jsx(TokenStat, {
+					term: "Reasoning tokens",
+					tokens: reading.reasoningTokens,
+					unit: "reasoning"
+				}) : null,
+				reading.costUsd !== void 0 ? /* @__PURE__ */ jsx(Stat, {
+					term: "Cost",
+					children: /* @__PURE__ */ jsx("span", {
+						className: "text-foreground tabular-nums",
+						children: formatCost(reading.costUsd)
+					})
+				}) : null,
+				reading.latencyMs !== void 0 ? /* @__PURE__ */ jsxs(Stat, {
+					term: "Latency",
+					children: [/* @__PURE__ */ jsx(TimerIcon, {
+						"aria-hidden": "true",
+						className: "size-3.5"
+					}), /* @__PURE__ */ jsx("span", {
+						className: "text-foreground tabular-nums",
+						children: formatLatency(reading.latencyMs)
+					})]
+				}) : null,
+				contextWindow !== void 0 && totalTokens !== void 0 ? /* @__PURE__ */ jsx(Stat, {
+					term: "Context window",
+					children: /* @__PURE__ */ jsx(ContextDisplay.Ring, {
+						modelContextWindow: contextWindow,
+						side,
+						className: "-my-1 -ms-1 px-1 outline-none hover:bg-foreground/[0.04] focus-visible:bg-foreground/[0.04] focus-visible:text-foreground focus-visible:ring-1 focus-visible:ring-ring/70",
+						usage: ringUsage(reading, totalTokens)
+					})
+				}) : null
+			]
+		})
+	});
+}
+const flatSection = "max-w-none rounded-none border-0 border-t border-border/60 bg-transparent px-4 py-3.5 dark:bg-transparent";
+function ExpandedUsage({ reading, scope, className }) {
+	const title = SCOPE_TITLE[scope];
+	const hasTokens = reading.totalTokens !== void 0;
+	const showContext = hasTokens && reading.contextWindow !== void 0;
+	const showTokenList = !showContext && hasTokenCounts(reading);
+	const slices = contextSlices(reading);
+	return /* @__PURE__ */ jsxs("section", {
+		"aria-label": title,
+		"data-slot": "usage-meter",
+		"data-variant": "expanded",
+		className: cn(paper, "flex w-full max-w-sm flex-col overflow-hidden rounded-2xl", className),
+		children: [
+			/* @__PURE__ */ jsxs("header", {
+				className: "flex min-w-0 items-center gap-3 px-4 py-3.5",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex min-w-0 flex-1 flex-col gap-0.5",
+					children: [/* @__PURE__ */ jsx("span", {
+						className: "text-[13.5px] font-medium",
+						children: title
+					}), reading.model ? /* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-muted-foreground truncate"),
+						children: reading.model
+					}) : null]
+				}), reading.latencyMs !== void 0 ? /* @__PURE__ */ jsx("dl", {
+					className: "text-muted-foreground shrink-0 text-xs",
+					children: /* @__PURE__ */ jsxs(Stat, {
+						term: "Latency",
+						children: [/* @__PURE__ */ jsx(TimerIcon, {
+							"aria-hidden": "true",
+							className: "size-3.5"
+						}), /* @__PURE__ */ jsx("span", {
+							className: "text-foreground tabular-nums",
+							children: formatLatency(reading.latencyMs)
+						})]
+					})
+				}) : null]
+			}),
+			isEmptyReading(reading) ? /* @__PURE__ */ jsxs("p", {
+				className: "text-muted-foreground border-border/60 border-t px-4 py-3.5 text-xs",
+				children: [
+					"No usage recorded for ",
+					SCOPE_LABEL[scope],
+					"."
+				]
+			}) : null,
+			reading.costUsd !== void 0 ? /* @__PURE__ */ jsx(CostMeter, {
+				className: cn(flatSection, "[&>div:has(>[role=meter])]:hidden"),
+				runCost: formatCost(reading.costUsd),
+				scopeLabel: SCOPE_LABEL[scope],
+				lines: hasTokens ? [{
+					model: reading.model ?? "All models",
+					inputTokens: reading.inputTokens ?? 0,
+					outputTokens: reading.outputTokens ?? 0,
+					cost: formatCost(reading.costUsd),
+					share: 1
+				}] : []
+			}) : null,
+			showContext ? /* @__PURE__ */ jsx(ContextBreakdown, {
+				className: flatSection,
+				limit: reading.contextWindow ?? 0,
+				segments: slices.map((slice) => ({
+					...slice,
+					tint: SLICE_TINT[slice.label] ?? "bg-foreground/25"
+				}))
+			}) : null,
+			showTokenList ? /* @__PURE__ */ jsx(TokenList, { reading }) : null
+		]
+	});
+}
+/** Token counts with no context window to measure them against. */
+function TokenList({ reading }) {
+	const rows = [
+		["Input", reading.inputTokens],
+		["Cached input", reading.cachedInputTokens],
+		["Output", reading.outputTokens],
+		["Reasoning", reading.reasoningTokens]
+	];
+	return /* @__PURE__ */ jsxs("div", {
+		className: "border-border/60 flex flex-col gap-3 border-t px-4 py-3.5",
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "text-[13.5px] font-medium",
+			children: "Tokens"
+		}), /* @__PURE__ */ jsx("dl", {
+			className: "flex flex-col gap-1.5",
+			children: rows.map(([term, tokens]) => tokens === void 0 ? null : /* @__PURE__ */ jsxs("div", {
+				className: "flex items-baseline gap-2",
+				children: [/* @__PURE__ */ jsx("dt", {
+					className: "text-muted-foreground min-w-0 flex-1 truncate text-[13px]",
+					children: term
+				}), /* @__PURE__ */ jsx("dd", {
+					className: cn(mono, "text-muted-foreground shrink-0 tabular-nums"),
+					children: tokens.toLocaleString("en-US")
+				})]
+			}, term))
+		})]
+	});
+}
+//#endregion
+export { UsageMeter };

package/dist/ai/testing/mock-clock.d.ts

@@ -0,0 +1,31 @@
+//#region src/ai/testing/mock-clock.d.ts
+/**
+ * The time source `MockRuntimeProvider` schedules its streaming on. The
+ * default is the real clock; a story's play function passes a manual clock and
+ * advances it with `tick()`, so streamed output is deterministic.
+ */
+export type MockClock = {
+  /** The current time in epoch milliseconds. */
+  now(): number;
+  /** Runs `callback` after `ms` milliseconds; returns a handle for `clear`. */
+  schedule(callback: () => void, ms: number): number;
+  /** Cancels a scheduled callback. Unknown handles are ignored. */
+  clear(handle: number): void;
+};
+/** A clock that only moves when told to. */
+export type ManualClock = MockClock & {
+  /** Moves time forward by `ms`, running every callback that falls due, in order. */
+  tick(ms: number): void;
+  /** Runs every scheduled callback, including ones they schedule, until none is left. */
+  runAll(): void;
+  /** How many callbacks are waiting. */
+  readonly pending: number;
+};
+/** The real clock: `Date.now` and `setTimeout`. */
+export declare const realClock: MockClock;
+/**
+ * Creates a manual clock. Time starts at `startAt` (default: the real time
+ * when the clock is created) and moves only through `tick` and `runAll`.
+ */
+export declare function createManualClock(startAt?: number): ManualClock;
+//#endregion

package/dist/ai/testing/mock-clock.js

@@ -0,0 +1,66 @@
+//#region src/ai/testing/mock-clock.ts
+/** The real clock: `Date.now` and `setTimeout`. */
+const realClock = {
+	now: () => Date.now(),
+	schedule: (callback, ms) => window.setTimeout(callback, ms),
+	clear: (handle) => window.clearTimeout(handle)
+};
+const RUN_ALL_LIMIT = 1e4;
+/**
+* Creates a manual clock. Time starts at `startAt` (default: the real time
+* when the clock is created) and moves only through `tick` and `runAll`.
+*/
+function createManualClock(startAt = Date.now()) {
+	let now = startAt;
+	let nextId = 1;
+	let timers = [];
+	const takeNextDue = (until) => {
+		let next;
+		for (const timer of timers) {
+			if (timer.at > until) continue;
+			if (next === void 0 || timer.at < next.at || timer.at === next.at && timer.id < next.id) next = timer;
+		}
+		if (next !== void 0) {
+			const due = next;
+			timers = timers.filter((timer) => timer !== due);
+		}
+		return next;
+	};
+	return {
+		now: () => now,
+		schedule(callback, ms) {
+			const id = nextId++;
+			timers.push({
+				id,
+				at: now + Math.max(0, ms),
+				callback
+			});
+			return id;
+		},
+		clear(handle) {
+			timers = timers.filter((timer) => timer.id !== handle);
+		},
+		tick(ms) {
+			const until = now + Math.max(0, ms);
+			for (let due = takeNextDue(until); due !== void 0; due = takeNextDue(until)) {
+				now = due.at;
+				due.callback();
+			}
+			now = until;
+		},
+		runAll() {
+			for (let count = 0; timers.length > 0; count++) {
+				if (count >= RUN_ALL_LIMIT) throw new Error(`ManualClock.runAll: still scheduling after ${RUN_ALL_LIMIT} callbacks`);
+				const due = takeNextDue(Number.POSITIVE_INFINITY);
+				if (due === void 0) break;
+				now = Math.max(now, due.at);
+				due.callback();
+			}
+		},
+		get pending() {
+			return timers.length;
+		}
+	};
+}
+//#endregion
+export { createManualClock, realClock };

package/dist/ai/testing/mock-reply.d.ts

@@ -0,0 +1,70 @@
+import { ThreadMessageLike } from "@assistant-ui/react";
+//#region src/ai/testing/mock-reply.d.ts
+/** A JSON value as assistant-ui's message parts carry it. */
+type ReplyJson = string | number | boolean | null | readonly ReplyJson[] | {
+  readonly [key: string]: ReplyJson;
+};
+/** A JSON object, such as a tool call's arguments. */
+type ReplyJsonObject = {
+  readonly [key: string]: ReplyJson;
+};
+/** Streams `text` into the reply one word at a time. */
+export type MockTextPart = {
+  readonly type: "text";
+  readonly text: string;
+};
+/** Streams `text` as the agent's reasoning, one word at a time. */
+export type MockReasoningPart = {
+  readonly type: "reasoning";
+  readonly text: string;
+};
+/** Adds a source citation to the reply. */
+export type MockSourcePart = {
+  readonly type: "source";
+  readonly url: string;
+  readonly title?: string;
+};
+/**
+ * Calls a tool: the call appears with its arguments, runs for `durationMs`,
+ * then settles with `result` (or fails with it when `isError`). With
+ * `approval`, the call stops before running until the owner approves or
+ * denies it in the UI.
+ */
+export type MockToolCallPart = {
+  readonly type: "tool-call";
+  readonly toolName: string;
+  readonly args: ReplyJsonObject;
+  /** What the tool returns. Leave it out to keep the call running forever. */
+  readonly result?: ReplyJson;
+  /** Whether `result` is an error. */
+  readonly isError?: boolean;
+  /** How long the call runs before its result lands, in ms. Default 800. */
+  readonly durationMs?: number;
+  /** A stable id; generated from the part's position when absent. */
+  readonly toolCallId?: string;
+  /** Gate the call on an owner decision, with this prompt. */
+  readonly approval?: {
+    readonly prompt?: string;
+    /** What the agent says when the owner denies the call; the reply ends there. */
+    readonly deniedText?: string;
+  };
+};
+/** Pauses the stream, as a model does between steps. */
+export type MockWaitPart = {
+  readonly type: "wait";
+  readonly ms: number;
+};
+/** One scripted piece of a reply, played in order. */
+export type MockReplyPart = MockTextPart | MockReasoningPart | MockSourcePart | MockToolCallPart | MockWaitPart;
+/** A scripted assistant reply that `MockRuntimeProvider` streams on its clock. */
+export type MockReply = {
+  /** The reply's parts, streamed in order. */
+  readonly parts: readonly MockReplyPart[];
+  /** Delay before the first token, in ms (time to first token). Default 400. */
+  readonly firstTokenMs?: number;
+  /** Delay between streamed words, in ms. Default 40. */
+  readonly tokenMs?: number;
+  /** End the reply with this error after the parts, as a failed run. */
+  readonly error?: string;
+};
+//#endregion

package/dist/ai/testing/mock-reply.js

@@ -0,0 +1,100 @@
+//#region src/ai/testing/mock-reply.ts
+const DEFAULT_FIRST_TOKEN_MS = 400;
+const DEFAULT_TOKEN_MS = 40;
+const DEFAULT_TOOL_MS = 800;
+const DEFAULT_DENIED_TEXT = "Understood. I did not run it.";
+/** Splits text into words that keep their trailing whitespace. */
+function tokenize(text) {
+	return text.match(/\s*\S+\s*/g) ?? (text.length > 0 ? [text] : []);
+}
+/**
+* Turns a reply script into timed steps. Pure: the same script always gives
+* the same steps, which is what makes a streamed story deterministic.
+*/
+function planReply(reply, idPrefix = "call") {
+	const firstTokenMs = reply.firstTokenMs ?? DEFAULT_FIRST_TOKEN_MS;
+	const tokenMs = reply.tokenMs ?? DEFAULT_TOKEN_MS;
+	const steps = [];
+	let partCount = 0;
+	let pendingDelay = 0;
+	const push = (op, delayMs) => {
+		const firstDelay = steps.length === 0 ? firstTokenMs : delayMs;
+		steps.push({
+			delayMs: firstDelay + pendingDelay,
+			op
+		});
+		pendingDelay = 0;
+	};
+	reply.parts.forEach((part, partIndex) => {
+		switch (part.type) {
+			case "wait":
+				pendingDelay += part.ms;
+				return;
+			case "text":
+			case "reasoning": {
+				const [first, ...rest] = tokenize(part.text);
+				if (first === void 0) return;
+				const index = partCount++;
+				push({
+					type: "add-part",
+					part: {
+						type: part.type,
+						text: first
+					}
+				}, tokenMs);
+				for (const token of rest) push({
+					type: "append-text",
+					index,
+					text: token
+				}, tokenMs);
+				return;
+			}
+			case "source":
+				partCount++;
+				push({
+					type: "add-part",
+					part: {
+						type: "source",
+						sourceType: "url",
+						id: `${idPrefix}-source-${partIndex}`,
+						url: part.url,
+						...part.title !== void 0 ? { title: part.title } : {}
+					}
+				}, tokenMs);
+				return;
+			case "tool-call": {
+				partCount++;
+				const toolCallId = part.toolCallId ?? `${idPrefix}-${partIndex}`;
+				push({
+					type: "add-part",
+					part: {
+						type: "tool-call",
+						toolCallId,
+						toolName: part.toolName,
+						args: part.args,
+						argsText: JSON.stringify(part.args, null, 2),
+						...part.approval !== void 0 ? { approval: {
+							id: `${toolCallId}-approval`,
+							...part.approval.prompt !== void 0 ? { prompt: part.approval.prompt } : {}
+						} } : {}
+					}
+				}, tokenMs);
+				if (part.approval !== void 0) push({
+					type: "await-approval",
+					toolCallId,
+					deniedText: part.approval.deniedText ?? DEFAULT_DENIED_TEXT
+				}, 0);
+				if (part.result !== void 0) push({
+					type: "settle-tool",
+					toolCallId,
+					result: part.result,
+					isError: part.isError ?? false
+				}, part.durationMs ?? DEFAULT_TOOL_MS);
+				return;
+			}
+		}
+	});
+	return steps;
+}
+//#endregion
+export { planReply, tokenize };