@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/utility/src/rename/index.ts

@@ -0,0 +1,191 @@
+/**
+ * @pi-unipi/utility — Automatic session naming
+ *
+ * After every confirmed round (agent_end without error/abort) whose prompt the
+ * user typed: gate (prefilter + jev) → isolated one-tool rename session →
+ * pi.setSessionName. Names the user sets (pi's /name) are respected: once the
+ * current name differs from the last auto name, auto-rename stops for that
+ * session. "Rename now" in /unipi:settings bypasses the gate.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { askJev, registerCommandRunner, resolveDecisionModel } from "@pi-unipi/core";
+import { readRenameSettings } from "../settings.js";
+import { detectHerdr, syncPaneTitle, type HerdrEnv } from "../herdr-sync.js";
+import { decide, gateRequest, isIdleRound } from "./gate.js";
+import { runRenameSession } from "./session.js";
+
+/** Custom entry recording names auto-rename set (so resume can tell them from /name). */
+export const AUTO_NAME_ENTRY = "unipi:auto-name";
+/** Rounds that must pass between two automatic renames (never twice in one round). */
+const MIN_ROUNDS_BETWEEN = 1;
+const HERDR_POLL_MS = 3000;
+
+/** Debug trail, gated by UNIPI_DEBUG_RENAME=1 → ~/.unipi/logs/rename.log. */
+function debugLog(line: string): void {
+  if (process.env.UNIPI_DEBUG_RENAME !== "1") return;
+  try {
+    const dir = join(homedir(), ".unipi", "logs");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "rename.log"), `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // best effort
+  }
+}
+
+/** Text of the last assistant message of a round (what the agent concluded). */
+export function lastReplyText(messages: readonly unknown[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i] as { role?: string; content?: unknown };
+    if (m.role !== "assistant") continue;
+    const text = typeof m.content === "string"
+      ? m.content
+      : Array.isArray(m.content) ? m.content.filter((c: { type?: string }) => c?.type === "text").map((c: { text?: string }) => c.text ?? "").join("\n") : "";
+    if (text.trim()) return text.replace(/<\/?summary>/g, "").trim().slice(0, 1500);
+  }
+  return "";
+}
+
+export function countToolCalls(messages: readonly unknown[]): number {
+  let n = 0;
+  for (const m of messages as Array<{ role?: string; content?: unknown }>) {
+    if (m.role === "assistant" && Array.isArray(m.content)) n += m.content.filter((c: { type?: string }) => c?.type === "toolCall").length;
+  }
+  return n;
+}
+
+export function registerAutoRename(pi: ExtensionAPI): void {
+  let requests: string[] = [];
+  /** The round that triggered the current rename (the name should describe it). */
+  let lastRound: { reply: string; toolCalls: number } = { reply: "", toolCalls: 0 };
+  let pending: string | null = null;
+  let lastAutoName: string | null = null;
+  let roundsSinceRename = Number.POSITIVE_INFINITY;
+  let inFlight = false;
+  let herdr: HerdrEnv = { enabled: false };
+  let herdrShown: string | null = null;
+  let herdrTimer: ReturnType<typeof setInterval> | null = null;
+
+  const currentName = (): string | null => {
+    try {
+      return pi.getSessionName() ?? null;
+    } catch {
+      return null;
+    }
+  };
+
+  const syncHerdr = (name: string | null): void => {
+    if (!herdr.enabled || name === herdrShown || !readRenameSettings().herdrSync) return;
+    herdrShown = name;
+    void syncPaneTitle(herdr, name);
+  };
+
+  const apply = (name: string): void => {
+    if (name === currentName()) return;
+    pi.setSessionName(name);
+    lastAutoName = name;
+    roundsSinceRename = 0;
+    pi.appendEntry(AUTO_NAME_ENTRY, { name });
+    syncHerdr(name);
+  };
+
+  const rename = async (ctx: ExtensionContext, force: boolean, topicChanged = false): Promise<string | undefined> => {
+    if (inFlight) return undefined;
+    inFlight = true;
+    try {
+      const settings = readRenameSettings(ctx.cwd);
+      const name = await runRenameSession(ctx, { currentName: currentName(), requests, model: settings.model, topicChanged, reply: lastRound.reply }, debugLog);
+      debugLog(`rename session → ${name === undefined ? "(no name)" : JSON.stringify(name)}`);
+      if (name && (force || name !== currentName())) apply(name);
+      return name;
+    } catch (error) {
+      debugLog(`rename session failed: ${error instanceof Error ? error.message : String(error)}`);
+      return undefined;
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  registerCommandRunner("unipi:rename-now", async (raw: unknown) => {
+    const ctx = raw as ExtensionContext;
+    if (requests.length === 0) {
+      ctx.ui?.notify?.("Nothing to name yet — send a request first.", "info");
+      return;
+    }
+    const name = await rename(ctx, true);
+    ctx.ui?.notify?.(name ? `Session named "${name}"` : "Could not generate a name.", name ? "info" : "warning");
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    try {
+      requests = [];
+      pending = null;
+      roundsSinceRename = Number.POSITIVE_INFINITY;
+      const entries = (ctx.sessionManager?.getEntries?.() ?? []) as Array<{ type?: string; customType?: string; data?: { name?: unknown } }>;
+      const last = entries.findLast((e) => e.type === "custom" && e.customType === AUTO_NAME_ENTRY);
+      lastAutoName = typeof last?.data?.name === "string" ? last.data.name : null;
+      herdr = detectHerdr();
+      herdrShown = null;
+      syncHerdr(currentName());
+      if (herdrTimer) clearInterval(herdrTimer);
+      herdrTimer = herdr.enabled ? setInterval(() => syncHerdr(currentName()), HERDR_POLL_MS) : null;
+      herdrTimer?.unref?.();
+    } catch {
+      // Naming is best-effort — never block session start.
+    }
+  });
+
+  pi.on("input", (event) => {
+    try {
+      if (event.source === "extension") return;
+      const text = (event.text ?? "").trim();
+      if (!text || text.startsWith("/")) return;
+      requests = [...requests, text].slice(-6);
+      pending = text;
+    } catch {
+      // ignore
+    }
+  });
+
+  pi.on("agent_end", (event, ctx) => {
+    const prompt = pending;
+    pending = null;
+    roundsSinceRename++;
+    try {
+      if (!prompt || inFlight) return;
+      const skip = (why: string) => debugLog(`skip ${JSON.stringify(prompt.slice(0, 60))}: ${why}`);
+      if (!readRenameSettings(ctx.cwd).auto) return skip("auto-rename off");
+      const lastAssistant = [...(event.messages ?? [])].reverse().find((m) => (m as { role?: string }).role === "assistant") as { stopReason?: string } | undefined;
+      if (lastAssistant?.stopReason === "error" || lastAssistant?.stopReason === "aborted") return skip(`round ${lastAssistant.stopReason}`);
+      const name = currentName();
+      if (name && name !== lastAutoName) return skip("user-set name"); // user-set name wins
+      if (name && roundsSinceRename < MIN_ROUNDS_BETWEEN) return skip("renamed recently");
+      const reply = lastReplyText(event.messages ?? []);
+      const toolCalls = countToolCalls(event.messages ?? []);
+      const input = { prompt, currentName: name, earlier: requests, reply, toolCalls };
+      if (isIdleRound(input)) return skip("chatter");
+      lastRound = { reply, toolCalls };
+      // Detached: the next prompt never waits on naming.
+      void (async () => {
+        try {
+          const answers = await askJev({ ...gateRequest(input), settings: resolveDecisionModel(ctx.cwd ?? process.cwd(), "utility"), env: process.env });
+          const decision = decide(input, answers);
+          debugLog(`gate ${JSON.stringify(prompt.slice(0, 60))} name=${JSON.stringify(name)} → ${decision.rename ? "rename" : "skip"} (${decision.reason})`);
+          if (decision.rename) await rename(ctx, false, Boolean(name));
+        } catch {
+          // Naming must never disturb the main session.
+        }
+      })();
+    } catch {
+      // ignore
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    if (herdrTimer) clearInterval(herdrTimer);
+    herdrTimer = null;
+  });
+}

package/packages/utility/src/rename/session.ts

@@ -0,0 +1,170 @@
+/**
+ * @pi-unipi/utility — Rename session
+ *
+ * A throwaway in-memory pi session (the /unipi:btw shape) whose ONLY tool is
+ * `rename_session`. It never loads extensions, skills or context files, never
+ * sees the main transcript, and nothing it does reaches the main session
+ * except the name it sets. The main agent never has a rename tool.
+ */
+
+import {
+  createAgentSession,
+  createExtensionRuntime,
+  defineTool,
+  SessionManager,
+  type ModelRuntime,
+  type ResourceLoader,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { sanitizeName } from "./gate.js";
+
+const SYSTEM_PROMPT = [
+  "You name coding-agent sessions so the user can find them later.",
+  "Call rename_session exactly once with a short title (2-6 words, Title Case) describing the user's current task.",
+  "Name the task, not the conversation: 'Kanboard Lane Ordering', not 'User Asks About Lanes'.",
+  "If the current title still describes the current task, call rename_session with the current title unchanged.",
+  "Do not write anything else.",
+].join("\n");
+
+const RENAME_TIMEOUT_MS = 45_000;
+
+export interface RenameCtx {
+  cwd?: string;
+  model?: unknown;
+  modelRegistry?: unknown;
+}
+
+export interface RenameRequest {
+  currentName: string | null;
+  requests: readonly string[];
+  /** "" = session model; otherwise "provider/model-id". */
+  model: string;
+  /** The gate found the latest request leaves the current title's topic. */
+  topicChanged?: boolean;
+  /** The agent's reply in the triggering round — often the clearest subject. */
+  reply?: string;
+}
+
+function resourceLoader(): ResourceLoader {
+  const extensions = { extensions: [], errors: [], runtime: createExtensionRuntime() };
+  return {
+    getExtensions: () => extensions,
+    getSkills: () => ({ skills: [], diagnostics: [] }),
+    getPrompts: () => ({ prompts: [], diagnostics: [] }),
+    getThemes: () => ({ themes: [], diagnostics: [] }),
+    getAgentsFiles: () => ({ agentsFiles: [] }),
+    getSystemPrompt: () => SYSTEM_PROMPT,
+    getSystemPromptSource: () => undefined,
+    getAppendSystemPrompt: () => [],
+    getAppendSystemPromptSources: () => [],
+    extendResources: () => {},
+    reload: async () => {},
+  } as unknown as ResourceLoader;
+}
+
+function resolveModel(ref: string, ctx: RenameCtx): unknown {
+  const registry = ctx.modelRegistry as { find?: (p: string, id: string) => unknown } | undefined;
+  const slash = ref.indexOf("/");
+  if (ref && slash > 0 && registry?.find) {
+    const found = registry.find(ref.slice(0, slash), ref.slice(slash + 1));
+    if (found) return found;
+  }
+  return ctx.model;
+}
+
+export function renamePrompt(req: RenameRequest): string {
+  const clip = (r: string) => r.replace(/\s+/g, " ").slice(0, 400);
+  if (req.topicChanged && req.currentName) {
+    const latest = req.requests.at(-1) ?? "";
+    return [
+      `Current title: ${req.currentName}`,
+      "",
+      "The user has moved on to a different task, so the current title no longer fits. Name the NEW task:",
+      `- ${clip(latest)}`,
+      ...(req.reply ? ["", `What the assistant did about it:\n${clip(req.reply)}`] : []),
+    ].join("\n");
+  }
+  const recent = req.requests.slice(-4).map((r) => `- ${clip(r)}`).join("\n");
+  return [
+    req.currentName ? `Current title: ${req.currentName}` : "The session has no title yet.",
+    "",
+    "Recent user requests (oldest first; the last one is the current task):",
+    recent || "- (none)",
+    ...(req.reply ? ["", `The assistant's latest reply (use it when the request itself is vague):\n${clip(req.reply)}`] : []),
+  ].join("\n");
+}
+
+/** Run the one-tool session; resolves to the sanitized name it chose, if any.
+ *  A configured naming model that fails (removed from the catalog, no key)
+ *  falls back once to the session model. */
+export async function runRenameSession(
+  ctx: RenameCtx,
+  req: RenameRequest,
+  debug: (line: string) => void = () => {},
+): Promise<string | undefined> {
+  const runtime = (ctx.modelRegistry as { runtime?: ModelRuntime } | undefined)?.runtime;
+  if (!runtime) {
+    debug("no model runtime available");
+    return undefined;
+  }
+  const configured = resolveModel(req.model, ctx);
+  const candidates = configured && configured !== ctx.model ? [configured, ctx.model] : [ctx.model];
+  for (const model of candidates) {
+    if (!model) continue;
+    const name = await attempt(model, runtime, ctx, req, debug);
+    if (name) return name;
+  }
+  return undefined;
+}
+
+async function attempt(
+  model: unknown,
+  runtime: ModelRuntime,
+  ctx: RenameCtx,
+  req: RenameRequest,
+  debug: (line: string) => void,
+): Promise<string | undefined> {
+  let chosen: string | undefined;
+  const renameTool = defineTool({
+    name: "rename_session",
+    label: "Rename session",
+    description: "Set the session title (2-6 words, Title Case).",
+    parameters: Type.Object({ name: Type.String({ description: "The new session title" }) }),
+    async execute(_id, params) {
+      const name = sanitizeName(String((params as { name?: unknown }).name ?? ""));
+      if (!name) return { content: [{ type: "text", text: "Error: empty title." }], details: undefined };
+      chosen = name;
+      return { content: [{ type: "text", text: `Title set: ${name}` }], details: { name } };
+    },
+  });
+
+  const { session } = await createAgentSession({
+    sessionManager: SessionManager.inMemory(ctx.cwd ?? process.cwd()),
+    model: model as never,
+    modelRuntime: runtime,
+    thinkingLevel: "off" as never,
+    tools: ["rename_session"],
+    customTools: [renameTool as never],
+    resourceLoader: resourceLoader(),
+  });
+  const s = session as unknown as {
+    prompt: (m: string, o?: unknown) => Promise<void>;
+    abort?: () => Promise<void> | void;
+    dispose?: () => void;
+    state?: { messages?: Array<{ role?: string; stopReason?: string; errorMessage?: string; content?: unknown }> };
+  };
+  const timer = setTimeout(() => void s.abort?.(), RENAME_TIMEOUT_MS);
+  timer.unref?.();
+  try {
+    await s.prompt(renamePrompt(req), { source: "extension" });
+    if (!chosen) {
+      const last = (s.state?.messages ?? []).findLast((m) => m.role === "assistant");
+      const id = (model as { provider?: string; id?: string });
+      debug(`${id.provider}/${id.id}: no rename_session call; stop=${last?.stopReason ?? "?"} ${last?.errorMessage ?? JSON.stringify(last?.content ?? "").slice(0, 200)}`);
+    }
+  } finally {
+    clearTimeout(timer);
+    s.dispose?.();
+  }
+  return chosen;
+}

package/packages/utility/src/render/delegated.ts

@@ -0,0 +1,285 @@
+/**
+ * @pi-unipi/utility — the approved UNI-2 "delegated work" panel: one outer
+ * dark-cyan fill (#12363b) with a bright cyan ▏ rail (#22d3ee) on every row
+ * (blank interior rows included), replacing today's nested per-card
+ * backgrounds. Rendered content comes from the shared style helpers
+ * (styledToolCallLines / styledTextLines / nativeToolComponent for regular
+ * raw-args); every nested background SGR is stripped atomically before the
+ * single outer fill is applied, so foreground colours (native card fg, syntax,
+ * markdown semantics) survive untouched.
+ *
+ * The returned component carries spacingGroup metadata so adjacent steps join
+ * into one continuous panel (spacing.ts resolves it through the host's
+ * CustomEntryComponent.customComponent wrapper).
+ */
+import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { nativeToolComponent, renderStyle, styledTextLines, styledToolCallLines, type RenderStyle, type StyledTheme } from "./styled.js";
+import { paintLine, trimEdgeBlankLines } from "./reply-bg.js";
+import type { SpacingGroupPosition } from "./spacing.js";
+
+/** Minimal single-width component; the cache key (e.g. active render style)
+ *  invalidates without host help, `invalidate()` clears unconditionally. */
+function styledComponentLike(build: (width: number) => string[], cacheKey: (width: number) => string = () => ""): Component & Record<PropertyKey, unknown> {
+  let cache: { width: number; key: string; lines: string[] } | undefined;
+  return {
+    invalidate(): void {
+      cache = undefined;
+    },
+    render(width: number): string[] {
+      const key = cacheKey(width);
+      if (cache === undefined || cache.width !== width || cache.key !== key) cache = { width, key, lines: build(width) };
+      return cache.lines;
+    },
+  } as Component & Record<PropertyKey, unknown>;
+}
+
+/** A SidekickStep-compatible step (structural, fusion/subagent agnostic). */
+export type DelegatedStep =
+  | { kind: "tool"; name: string; arg: string; output: string; isError: boolean; durationMs: number; args?: Record<string, unknown> }
+  | { kind: "text"; text: string; thinking?: string };
+
+export interface DelegatedIdentity {
+  /** spacingGroup for the panel run — unique per agent/handoff. */
+  group: string;
+  /** Panel header, drawn once on the first group position (index 0). */
+  label?: string;
+  /** Render style override; defaults to the active utility render style. */
+  style?: RenderStyle;
+}
+
+// ── approved palette (truecolor, 256-colour fallback) ──────────────────────
+export const DELEGATED_PANEL_HEX = "#12363b";
+export const DELEGATED_RAIL_HEX = "#22d3ee";
+const RAIL = "▏ ";
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const c = hex.replace("#", "");
+  return { r: parseInt(c.slice(0, 2), 16), g: parseInt(c.slice(2, 4), 16), b: parseInt(c.slice(4, 6), 16) };
+}
+
+function hexTo256(hex: string): number {
+  const { r, g, b } = hexToRgb(hex);
+  // Weighted RGB distance (perceptual weights), mirroring pi's own converter:
+  // nearest 6×6×6-cube cell vs nearest grayscale ramp entry, closer wins.
+  const dist = (r2: number, g2: number, b2: number) => 0.299 * (r - r2) ** 2 + 0.587 * (g - g2) ** 2 + 0.114 * (b - b2) ** 2;
+  const cube = [0, 95, 135, 175, 215, 255];
+  const nearest = (v: number) => cube.reduce((best, x) => (Math.abs(v - x) < Math.abs(v - best) ? x : best), cube[0]!);
+  const ri = cube.indexOf(nearest(r)), gi = cube.indexOf(nearest(g)), bi = cube.indexOf(nearest(b));
+  const cubeIndex = 16 + 36 * ri + 6 * gi + bi;
+  const cubeDist = dist(cube[ri]!, cube[gi]!, cube[bi]!);
+  const gray = Array.from({ length: 24 }, (_, i) => 8 + i * 10);
+  let grayBest = 0;
+  for (let i = 1; i < gray.length; i++) if (dist(gray[i]!, gray[i]!, gray[i]!) < dist(gray[grayBest]!, gray[grayBest]!, gray[grayBest]!)) grayBest = i;
+  const grayIndex = 232 + grayBest;
+  const grayDist = dist(gray[grayBest]!, gray[grayBest]!, gray[grayBest]!);
+  return cubeDist <= grayDist ? cubeIndex : grayIndex;
+}
+
+type ColorMode = "truecolor" | "256color";
+function modeOf(theme: { getColorMode?: () => ColorMode } | undefined): ColorMode {
+  try {
+    return theme?.getColorMode?.() ?? "truecolor";
+  } catch {
+    return "truecolor";
+  }
+}
+
+function fgAnsi(hex: string, mode: ColorMode): string {
+  if (mode === "256color") return `\x1b[38;5;${String(hexTo256(hex))}m`;
+  const { r, g, b } = hexToRgb(hex);
+  return `\x1b[38;2;${String(r)};${String(g)};${String(b)}m`;
+}
+function bgAnsi(hex: string, mode: ColorMode): string {
+  if (mode === "256color") return `\x1b[48;5;${String(hexTo256(hex))}m`;
+  const { r, g, b } = hexToRgb(hex);
+  return `\x1b[48;2;${String(r)};${String(g)};${String(b)}m`;
+}
+
+/** The panel fill (dark cyan) in the theme's colour mode. */
+export function delegatedPanelBg(theme?: { getColorMode?: () => ColorMode }): string {
+  return bgAnsi(DELEGATED_PANEL_HEX, modeOf(theme));
+}
+/** The rail colour (bright cyan) in the theme's colour mode. */
+export function delegatedRailFg(theme?: { getColorMode?: () => ColorMode }): string {
+  return fgAnsi(DELEGATED_RAIL_HEX, modeOf(theme));
+}
+
+/**
+ * Strip every nested background SGR from a rendered line — truecolor, 256 and
+ * 8-colour backgrounds plus bg resets — while preserving foreground. Extended
+ * sequences (38;2;r;g;b / 38;5;n) are consumed atomically so their colour
+ * components can't be mistaken for background params.
+ */
+export function stripNestedBackgrounds(line: string): string {
+  return line.replace(/\x1b\[([0-9;]*)m/g, (seq, params: string) => {
+    if (params === "") return "\x1b[0m";
+    const parts = params.split(";");
+    const keep: string[] = [];
+    for (let i = 0; i < parts.length; i++) {
+      const n = Number(parts[i] || "0");
+      if (n === 38 || n === 48) {
+        const sub = Number(parts[i + 1]);
+        const span = sub === 2 ? 5 : sub === 5 ? 3 : 1;
+        const atom = parts.slice(i, i + span).join(";");
+        i += span - 1;
+        if (n === 38) keep.push(atom);
+        continue;
+      }
+      if (n === 49 || (n >= 40 && n <= 47) || (n >= 100 && n <= 107)) continue;
+      keep.push(parts[i]!);
+    }
+    return keep.length > 0 ? `\x1b[${keep.join(";")}m` : "";
+  });
+}
+
+/**
+ * One rail-painted panel row: cyan ▏ + content on the single outer fill,
+ * padded to `width` — blank interior rows get the same treatment, so a panel
+ * is continuous with no unpainted gaps. Content backgrounds are stripped.
+ */
+export function paintDelegatedLine(line: string, width: number, theme?: { getColorMode?: () => ColorMode }): string {
+  const w = Math.max(1, Math.trunc(width) || 1);
+  const painted = paintLine(
+    `${delegatedRailFg(theme)}${RAIL}\x1b[39m${stripNestedBackgrounds(line)}`,
+    w,
+    delegatedPanelBg(theme),
+  );
+  return truncateToWidth(painted, w);
+}
+
+/**
+ * Semantic fg overrides for delegated panels: cyan accents/titles/results,
+ * neutral light output/text, fixed muted metadata and red errors — the user's
+ * global theme is never modified. Markdown semantic colours are untouched
+ * (they come from the global markdown theme); only these keys are remapped.
+ */
+export function delegatedTheme(theme: StyledTheme, mode: ColorMode = "truecolor"): StyledTheme {
+  const overrides = new Map<string, string>([
+    ["accent", fgAnsi(DELEGATED_RAIL_HEX, mode)],
+    ["success", fgAnsi(DELEGATED_RAIL_HEX, mode)],
+    ["toolTitle", fgAnsi(DELEGATED_RAIL_HEX, mode)],
+    ["toolOutput", fgAnsi("#e8f4f4", mode)],
+    ["text", fgAnsi("#e8f4f4", mode)],
+    ["error", fgAnsi("#ff6b6b", mode)],
+    ["muted", fgAnsi("#86b0b5", mode)],
+    ["dim", fgAnsi("#5f8a8f", mode)],
+    ["borderMuted", fgAnsi("#5f8a8f", mode)],
+  ]);
+  return {
+    fg(color: string, text: string): string {
+      const ansi = overrides.get(color);
+      return ansi !== undefined ? `${ansi}${text}\x1b[39m` : theme.fg(color as never, text);
+    },
+    bold: (t: string) => theme.bold(t),
+  } as StyledTheme;
+}
+
+// ── the step renderer ──────────────────────────────────────────────────────
+
+/** Test seam: how many times the native component factory actually ran. */
+export const nativeFactoryStats = { calls: 0 };
+
+/** Raw native rows for a regular-style step with raw args. The component is
+ *  cached per (width, expanded, output, error) — the host's rebuild supplies a
+ *  fresh inner component (and theme) anyway, so within one inner lifetime a
+ *  repeated render at the same key reuses the native instance instead of
+ *  re-running the factory. */
+function makeNativeCache() {
+  let comp: Component | undefined;
+  let key = "";
+  return (step: DelegatedStep & { kind: "tool" }, expanded: boolean, inner: number): string[] | undefined => {
+    if (step.args === undefined) return undefined;
+    const k = `${String(inner)}|${String(expanded)}|${String(step.isError)}|${String(step.output.length)}`;
+    if (comp === undefined || key !== k) {
+      key = k;
+      try {
+        nativeFactoryStats.calls++;
+        comp = nativeToolComponent({
+          name: step.name,
+          args: step.args,
+          output: step.output,
+          isError: step.isError,
+          expanded,
+        }) ?? undefined;
+      } catch {
+        comp = undefined;
+      }
+    }
+    if (comp === undefined) return undefined;
+    try {
+      return trimEdgeBlankLines(comp.render(inner));
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/**
+ * One delegated step as a transcript component in the approved panel design.
+ * The component carries `spacingGroup`/`spacingKind`/`setGroupPosition` so
+ * spacing.ts can join adjacent members of the same group into one continuous
+ * panel: connectors `├` while another tool step follows in the run, `└` on the
+ * last; the `label` (when given) is drawn only on group position 0. A fresh
+ * native component is cached per inner component instance (keyed by width,
+ * expansion, error and output length), so repeated renders reuse it while a
+ * theme/expansion rebuild — which creates a fresh inner component — never sees
+ * stale state.
+ */
+/** Theme colour mode, read from the passed theme when it exposes one. */
+type ModeTheme = StyledTheme & { getColorMode?: () => "truecolor" | "256color" };
+
+export function renderDelegatedStep(step: DelegatedStep, expanded: boolean, theme: StyledTheme, options: DelegatedIdentity): Component & {
+  spacingGroup: string;
+  spacingKind: string;
+  setGroupPosition: (pos: SpacingGroupPosition) => void;
+} {
+  const modeTheme = theme as ModeTheme;
+  const mode = modeOf(modeTheme);
+  const dTheme = delegatedTheme(modeTheme, mode);
+  let pos: SpacingGroupPosition | undefined;
+  const nativeFor = makeNativeCache();
+  const comp = styledComponentLike((width: number) => {
+    const inner = Math.max(3, width - visibleWidth(RAIL));
+    const style = options.style ?? renderStyle();
+    const lines: string[] = [];
+    const first = pos === undefined || pos.index === 0;
+    if (first && options.label !== undefined) {
+      lines.push(`${dTheme.fg("accent", "◆")} ${dTheme.fg("accent", dTheme.bold(options.label))}`);
+    }
+    if (step.kind === "text") {
+      lines.push(...styledTextLines(style, step.text, { thinking: expanded ? step.thinking : undefined }, dTheme, inner));
+    } else {
+      const connector: "├" | "└" = pos?.nextKind === "tool" ? "├" : "└";
+      const native = style === "regular" ? nativeFor(step, expanded, inner) : undefined;
+      if (native !== undefined) {
+        lines.push(...native);
+      } else {
+        lines.push(...styledToolCallLines(style, {
+          name: step.name,
+          arg: step.arg,
+          output: step.output,
+          isError: step.isError,
+          expanded,
+          durationMs: step.durationMs,
+          connector: style === "simple" ? connector : undefined,
+        }, dTheme, inner));
+      }
+    }
+    return lines.map((l) => truncateToWidth(l, inner)).map((l) => paintDelegatedLine(l, width, modeTheme));
+  }, () => options.style ?? renderStyle());
+  comp.spacingGroup = options.group;
+  comp.spacingKind = step.kind === "tool" ? "tool" : "text";
+  comp.setGroupPosition = (p: SpacingGroupPosition) => {
+    // Only a real position change invalidates — the host re-renders twice per
+    // pass (initial + positioned), and identical positions must not churn the
+    // native/paint caches (and must never invalidate from inside render).
+    const same = pos !== undefined && pos.index === p.index && pos.count === p.count && pos.prevKind === p.prevKind && pos.nextKind === p.nextKind;
+    pos = p;
+    if (!same) comp.invalidate();
+  };
+  return comp as unknown as Component & {
+    spacingGroup: string;
+    spacingKind: string;
+    setGroupPosition: (pos: SpacingGroupPosition) => void;
+  };
+}