@tt-a1i/openpi 0.5.0 → 0.6.1

package/extensions/cron/index.ts

@@ -17,6 +17,9 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   advanceDeliveredJobs,
+  CRON_DELIVERY_MAX_BYTES,
+  CRON_DELIVERY_MAX_JOBS,
+  CRON_MAX_JOBS,
   type CronJob,
   dueJobs,
   formatInterval,
@@ -41,6 +44,48 @@ const SYSTEM_RUNTIME: CronRuntime = {
   },
 };
 
+function deliveryMessage(due: readonly CronJob[]) {
+  const jobs = due.map((job) => ({
+    id: job.id,
+    prompt: job.prompt,
+    recurring: job.intervalMs !== undefined,
+  }));
+  return due.length === 1
+    ? {
+        customType: "cron-fire",
+        content: `[cron ${jobs[0]!.id} · ${jobs[0]!.recurring ? "recurring" : "once"}]\n${jobs[0]!.prompt}`,
+        display: true,
+        details: jobs[0]!,
+      }
+    : {
+        customType: "cron-fire",
+        content: `${due.length} scheduled prompts are due:\n\n${jobs
+          .map(
+            (job) =>
+              `[cron ${job.id} · ${job.recurring ? "recurring" : "once"}]\n${job.prompt}`,
+          )
+          .join("\n\n")}`,
+        display: true,
+        details: { count: jobs.length, jobs },
+      };
+}
+
+function dueDeliveryBatch(due: readonly CronJob[]) {
+  const selected: CronJob[] = [];
+  for (const job of due.slice(0, CRON_DELIVERY_MAX_JOBS)) {
+    const candidate = [...selected, job];
+    const message = deliveryMessage(candidate);
+    if (
+      new TextEncoder().encode(message.content).byteLength >
+      CRON_DELIVERY_MAX_BYTES
+    ) {
+      break;
+    }
+    selected.push(job);
+  }
+  return selected;
+}
+
 export default function cron(
   pi: ExtensionAPI,
   runtime: CronRuntime = SYSTEM_RUNTIME,
@@ -58,30 +103,7 @@ export default function cron(
   const fire = (due: readonly CronJob[]) => {
     if (due.length === 0) return true;
     try {
-      const jobs = due.map((job) => ({
-        id: job.id,
-        prompt: job.prompt,
-        recurring: job.intervalMs !== undefined,
-      }));
-      const message =
-        due.length === 1
-          ? {
-              customType: "cron-fire",
-              content: `[cron ${jobs[0]!.id} · ${jobs[0]!.recurring ? "recurring" : "once"}]\n${jobs[0]!.prompt}`,
-              display: true,
-              details: jobs[0],
-            }
-          : {
-              customType: "cron-fire",
-              content: `${due.length} scheduled prompts are due:\n\n${jobs
-                .map(
-                  (job) =>
-                    `[cron ${job.id} · ${job.recurring ? "recurring" : "once"}]\n${job.prompt}`,
-                )
-                .join("\n\n")}`,
-              display: true,
-              details: { count: jobs.length, jobs },
-            };
+      const message = deliveryMessage(due);
       pi.sendMessage<
         | { id: number; prompt: string; recurring: boolean }
         | {
@@ -109,9 +131,11 @@ export default function cron(
     const now = runtime.now();
     const due = dueJobs(jobs, now);
     if (due.length === 0) return;
+    const batch = dueDeliveryBatch(due);
+    if (batch.length === 0) return;
     const deliveredIds = new Set<number>();
-    if (fire(due)) {
-      for (const job of due) deliveredIds.add(job.id);
+    if (fire(batch)) {
+      for (const job of batch) deliveredIds.add(job.id);
     }
     jobs = advanceDeliveredJobs(jobs, deliveredIds, runtime.now());
     if (jobs.length === 0) stopTicker();
@@ -170,12 +194,29 @@ export default function cron(
         return;
       }
 
+      if (jobs.length >= CRON_MAX_JOBS) {
+        ctx.ui.notify(
+          `A session can have at most ${CRON_MAX_JOBS} scheduled prompts. Remove one before adding another.`,
+          "warning",
+        );
+        return;
+      }
+
       const intervalMs = parsed.intervalMs!;
+      const now = runtime.now();
+      const nextRunAt = now + intervalMs;
+      if (!Number.isSafeInteger(now) || !Number.isSafeInteger(nextRunAt)) {
+        ctx.ui.notify(
+          "Scheduled time is too far in the future. Use a shorter duration.",
+          "warning",
+        );
+        return;
+      }
       const job: CronJob = {
         id: nextId++,
         prompt: parsed.prompt!,
         ...(parsed.oneShot ? {} : { intervalMs }),
-        nextRunAt: runtime.now() + intervalMs,
+        nextRunAt,
       };
       jobs.push(job);
       startTicker();

package/extensions/cron/schedule.ts

@@ -22,6 +22,9 @@ const UNITS: Record<string, number> = {
 
 export const MIN_INTERVAL_MS = 30_000;
 export const CRON_PROMPT_MAX_CHARS = 2_000;
+export const CRON_MAX_JOBS = 64;
+export const CRON_DELIVERY_MAX_JOBS = 16;
+export const CRON_DELIVERY_MAX_BYTES = 48 * 1024;
 
 /**
  * Parse a duration like `30s`, `5m`, `2h`. Deliberately a small duration
@@ -33,7 +36,8 @@ export function parseDuration(text: string): number | undefined {
   if (!match) return undefined;
   const value = Number(match[1]);
   if (!Number.isFinite(value) || value <= 0) return undefined;
-  return value * UNITS[match[2].toLowerCase()];
+  const durationMs = value * UNITS[match[2].toLowerCase()];
+  return Number.isSafeInteger(durationMs) ? durationMs : undefined;
 }
 
 export interface ParsedCronCommand {

package/extensions/model-info/cache-diagnostics.ts

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import type { Usage } from "@earendil-works/pi-ai";
+
+export const CACHE_DIAGNOSTICS_CHANNEL = "model-info:cache-diagnostics";
+
+export const CACHE_WARM_MINIMUM_TOKENS = 2_048;
+
+export type CacheSemantics =
+  | "explicit-prefix"
+  | "implicit-best-effort"
+  | "unknown";
+
+export type CacheObservationKind =
+  | "first-turn"
+  | "cold"
+  | "warm"
+  | "partial-hit"
+  | "miss-after-warm-prefix"
+  | "unknown";
+
+export type CacheCorrelation =
+  | "model-change"
+  | "thinking-change"
+  | "tool-surface-change"
+  | "system-prompt-change"
+  | "compaction"
+  | "branch-change";
+
+export interface CacheTurnIdentity {
+  provider: string;
+  modelId: string;
+  thinking: string;
+  toolSurfaceFingerprint: string;
+  systemPromptFingerprint: string;
+}
+
+export interface CacheTurnObservation {
+  turnIndex: number;
+  provider: string;
+  semantics: CacheSemantics;
+  kind: CacheObservationKind;
+  usage: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    promptTokens: number;
+  };
+  previousCacheRead: number | null;
+  reprocessedTokens: number | null;
+  correlations: CacheCorrelation[];
+  evidence: "observation";
+  verifiedCause: null;
+  explanation: string;
+}
+
+type TurnSample = {
+  identity: CacheTurnIdentity;
+  usage: CacheTurnObservation["usage"];
+};
+
+const IMPLICIT_CACHE_PROVIDERS = new Set([
+  "azure-openai-responses",
+  "google",
+  "google-antigravity",
+  "google-gemini-cli",
+  "openai",
+  "openai-codex",
+  "openai-responses",
+]);
+
+export function cacheSemanticsForProvider(provider: string): CacheSemantics {
+  const normalized = provider.trim().toLowerCase();
+  if (normalized === "anthropic") return "explicit-prefix";
+  if (IMPLICIT_CACHE_PROVIDERS.has(normalized)) return "implicit-best-effort";
+  return "unknown";
+}
+
+export function fingerprintCacheSurface(value: unknown) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+function finiteUsage(value: number) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function promptUsage(usage: Usage): CacheTurnObservation["usage"] {
+  const input = finiteUsage(usage.input);
+  const cacheRead = finiteUsage(usage.cacheRead);
+  const cacheWrite = finiteUsage(usage.cacheWrite);
+  return {
+    input,
+    cacheRead,
+    cacheWrite,
+    promptTokens: input + cacheRead + cacheWrite,
+  };
+}
+
+function identityCorrelations(
+  previous: CacheTurnIdentity,
+  current: CacheTurnIdentity,
+) {
+  const correlations: CacheCorrelation[] = [];
+  if (
+    previous.provider !== current.provider ||
+    previous.modelId !== current.modelId
+  ) {
+    correlations.push("model-change");
+  }
+  if (previous.thinking !== current.thinking) {
+    correlations.push("thinking-change");
+  }
+  if (previous.toolSurfaceFingerprint !== current.toolSurfaceFingerprint) {
+    correlations.push("tool-surface-change");
+  }
+  if (previous.systemPromptFingerprint !== current.systemPromptFingerprint) {
+    correlations.push("system-prompt-change");
+  }
+  return correlations;
+}
+
+function classify(
+  semantics: CacheSemantics,
+  current: CacheTurnObservation["usage"],
+  previous: TurnSample | undefined,
+): Pick<CacheTurnObservation, "kind" | "reprocessedTokens" | "explanation"> {
+  if (!previous) {
+    return {
+      kind: "first-turn",
+      reprocessedTokens: null,
+      explanation:
+        "No prior turn exists, so cache continuity cannot be inferred.",
+    };
+  }
+
+  const previousWarm = previous.usage.cacheRead >= CACHE_WARM_MINIMUM_TOKENS;
+  if (current.cacheRead > 0) {
+    return {
+      kind:
+        current.cacheRead < previous.usage.cacheRead ? "partial-hit" : "warm",
+      reprocessedTokens: null,
+      explanation:
+        current.cacheRead < previous.usage.cacheRead
+          ? "The provider reported a smaller cache read than on the prior turn."
+          : "The provider reported cached prompt tokens on this turn.",
+    };
+  }
+  if (!previousWarm) {
+    return {
+      kind: "cold",
+      reprocessedTokens: null,
+      explanation:
+        "The prior turn had no sufficiently warm prefix, so this cold turn is not an invalidation signal.",
+    };
+  }
+  if (semantics !== "explicit-prefix") {
+    return {
+      kind: "unknown",
+      reprocessedTokens: null,
+      explanation:
+        semantics === "implicit-best-effort"
+          ? "A warm-to-cold transition was observed, but this provider exposes only best-effort cache usage."
+          : "A warm-to-cold transition was observed, but the provider cache contract is unknown.",
+    };
+  }
+  return {
+    kind: "miss-after-warm-prefix",
+    reprocessedTokens: current.input,
+    explanation:
+      "An explicit-prefix provider reported a warm prior turn and zero cache read now; local boundaries are correlations, not verified causes.",
+  };
+}
+
+export function createCacheDiagnosticsTracker() {
+  let previous: TurnSample | undefined;
+  let pendingCorrelations = new Set<CacheCorrelation>();
+
+  const reset = () => {
+    previous = undefined;
+    pendingCorrelations = new Set();
+  };
+
+  const mark = (correlation: CacheCorrelation) => {
+    pendingCorrelations.add(correlation);
+  };
+
+  const observe = (options: {
+    turnIndex: number;
+    identity: CacheTurnIdentity;
+    usage: Usage;
+  }) => {
+    const usage = promptUsage(options.usage);
+    const semantics = cacheSemanticsForProvider(options.identity.provider);
+    const classification = classify(semantics, usage, previous);
+    const correlations = previous
+      ? identityCorrelations(previous.identity, options.identity)
+      : [];
+    for (const pending of pendingCorrelations) correlations.push(pending);
+    const uniqueCorrelations = [...new Set(correlations)];
+
+    const observation: CacheTurnObservation = {
+      turnIndex: options.turnIndex,
+      provider: options.identity.provider,
+      semantics,
+      kind: classification.kind,
+      usage,
+      previousCacheRead: previous?.usage.cacheRead ?? null,
+      reprocessedTokens: classification.reprocessedTokens,
+      correlations: uniqueCorrelations,
+      evidence: "observation",
+      verifiedCause: null,
+      explanation: classification.explanation,
+    };
+
+    previous = { identity: options.identity, usage };
+    pendingCorrelations.clear();
+    return observation;
+  };
+
+  return { mark, observe, reset };
+}

package/extensions/model-info/index.ts

@@ -8,6 +8,12 @@ import {
   REFRESH_CHANNEL,
 } from "../shared/dashboard-state.ts";
 import { createSessionMetricsTracker } from "./session-metrics.ts";
+import {
+  CACHE_DIAGNOSTICS_CHANNEL,
+  createCacheDiagnosticsTracker,
+  fingerprintCacheSurface,
+  type CacheTurnIdentity,
+} from "./cache-diagnostics.ts";
 
 const CHARS_PER_ESTIMATED_TOKEN = 4;
 const LIVE_UPDATE_INTERVAL_MS = 200;
@@ -29,6 +35,8 @@ export default function modelInfo(pi: ExtensionAPI) {
   let lastLiveUpdate = 0;
   let currentContext: ExtensionContext | undefined;
   const sessionMetrics = createSessionMetricsTracker();
+  const cacheDiagnostics = createCacheDiagnosticsTracker();
+  let cacheIdentity: CacheTurnIdentity | undefined;
 
   const publish = () => pi.events.emit(MODEL_INFO_CHANNEL, { ...state });
 
@@ -74,11 +82,14 @@ export default function modelInfo(pi: ExtensionAPI) {
     runContentStreamMs = 0;
     state = { ...state, tokensPerSecond: null, generating: false };
     sessionMetrics.reset();
+    cacheDiagnostics.reset();
+    cacheIdentity = undefined;
     syncSessionMetrics(ctx);
     refresh(ctx);
   });
 
   pi.on("model_select", (event, ctx) => {
+    cacheDiagnostics.mark("model-change");
     state = {
       ...state,
       provider: event.model.provider,
@@ -91,6 +102,7 @@ export default function modelInfo(pi: ExtensionAPI) {
   });
 
   pi.on("thinking_level_select", (event) => {
+    cacheDiagnostics.mark("thinking-change");
     state = { ...state, thinking: event.level };
     publish();
   });
@@ -103,6 +115,17 @@ export default function modelInfo(pi: ExtensionAPI) {
     refresh(ctx);
   });
 
+  pi.on("before_agent_start", (event, ctx) => {
+    const selectedTools = event.systemPromptOptions.selectedTools ?? [];
+    cacheIdentity = {
+      provider: ctx.model?.provider ?? "",
+      modelId: ctx.model?.id ?? "no-model",
+      thinking: ctx.model?.reasoning ? pi.getThinkingLevel() : "off",
+      toolSurfaceFingerprint: fingerprintCacheSurface(selectedTools),
+      systemPromptFingerprint: fingerprintCacheSurface(event.systemPrompt),
+    };
+  });
+
   pi.on("message_start", (event) => {
     if (event.message.role === "assistant") resetMessageTracking();
   });
@@ -191,20 +214,39 @@ export default function modelInfo(pi: ExtensionAPI) {
     refresh(ctx);
   });
 
-  pi.on("turn_end", (_event, ctx) => {
+  pi.on("turn_end", (event, ctx) => {
     syncSessionMetrics(ctx);
     refresh(ctx);
+    // Failed/cancelled responses may carry placeholder zero usage. They do
+    // not establish a cache observation or replace the last valid baseline.
+    if (
+      event.message?.role === "assistant" &&
+      event.message.stopReason !== "error" &&
+      event.message.stopReason !== "aborted" &&
+      cacheIdentity
+    ) {
+      pi.events.emit(
+        CACHE_DIAGNOSTICS_CHANNEL,
+        cacheDiagnostics.observe({
+          turnIndex: event.turnIndex,
+          identity: cacheIdentity,
+          usage: event.message.usage,
+        }),
+      );
+    }
   });
 
   // Compaction and branch moves rewrite history, so the cached percentage is
   // stale the moment they land. Pi reports unknown occupancy until the next
   // assistant reply, which is the honest state to show.
   pi.on("session_compact", (_event, ctx) => {
+    cacheDiagnostics.mark("compaction");
     syncSessionMetrics(ctx);
     refresh(ctx);
   });
 
   pi.on("session_tree", (_event, ctx) => {
+    cacheDiagnostics.mark("branch-change");
     syncSessionMetrics(ctx);
     refresh(ctx);
   });
@@ -218,5 +260,7 @@ export default function modelInfo(pi: ExtensionAPI) {
     stopRefreshListener();
     currentContext = undefined;
     sessionMetrics.reset();
+    cacheDiagnostics.reset();
+    cacheIdentity = undefined;
   });
 }

package/extensions/plan-mode/index.ts

@@ -26,11 +26,14 @@
  * may predate the plan and still hold the full tool set.
  */
 
-import type {
-  ExtensionAPI,
-  ExtensionCommandContext,
-  ExtensionContext,
+import {
+  getMarkdownTheme,
+  keyHint,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { Markdown, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
   PLAN_MODE_CHANNEL,
@@ -46,6 +49,8 @@ import { planBashDecision } from "./bash-policy.ts";
 
 export const MAX_READY_PLAN_CHARS = 50_000;
 export const MAX_READY_PLAN_UTF8_BYTES = 48_000;
+/** Preview lines shown in the collapsed plan_ready result. */
+const PLAN_PREVIEW_LINES = 10;
 export const PLAN_MODE_STATE_ENTRY = "my-pi-setup-plan-mode-state";
 
 export type PersistedPlanModeState =
@@ -450,6 +455,72 @@ export default function planMode(pi: ExtensionAPI) {
         terminate: true,
       };
     },
+    /**
+     * Render a completed plan for the TUI. Collapsed shows the line count
+     * plus a bounded preview (PLAN_PREVIEW_LINES) with an expand hint;
+     * expanded renders the full plan as Markdown. Pi only reflects the
+     * expanded flag — it never truncates custom renderer output, so this
+     * renderer owns the collapsed/expanded contract.
+     */
+    renderResult(result, { expanded }, theme) {
+      const plan = (result.details as { plan?: string } | undefined)?.plan;
+      if (!plan) {
+        // Failed invocations (not in plan mode, empty plan, size cap, abort)
+        // produce {content:[{text:reason}], details:{}} from agent-loop's
+        // createErrorToolResult; surface the real reason instead of a
+        // placeholder, mirroring subagent_spawn's fallback.
+        const first = result.content?.[0];
+        return new Text(
+          first?.type === "text"
+            ? first.text
+            : theme.fg("muted", "(no plan content)"),
+          0,
+          0,
+        );
+      }
+      if (!expanded) {
+        // Bound the collapsed preview by rendered rows, not source lines: a
+        // single long source line wraps into many terminal rows at narrow
+        // widths, so render the body at the caller's width, keep the first
+        // PLAN_PREVIEW_LINES rows, and truncate every row to the viewport
+        // width (same contract as renderWaitResult's fixedRows).
+        const body = new Text(
+          plan
+            .split("\n")
+            .map((line) => theme.fg("toolOutput", line))
+            .join("\n"),
+          0,
+          0,
+        );
+        return {
+          render(width: number) {
+            const bodyRows = body.render(width);
+            const shown = bodyRows.slice(0, PLAN_PREVIEW_LINES);
+            const hidden = bodyRows.length - shown.length;
+            const header = theme.fg(
+              "muted",
+              `Plan ready · ${plan.split("\n").length} lines`,
+            );
+            const rows = [header, ...shown];
+            if (hidden > 0) {
+              // The hint gets its own row: tucking it into the header tail
+              // lets a narrow viewport clip it away along with the rest of
+              // the header, hiding the expand affordance exactly when the
+              // preview is clipped.
+              rows.push(keyHint("app.tools.expand", "to expand"));
+              rows.push(theme.fg("muted", `... (${hidden} more rows)`));
+            }
+            return rows.map((row) => truncateToWidth(row, Math.max(1, width)));
+          },
+          invalidate() {
+            body.invalidate();
+          },
+        };
+      }
+      // A plan is prose to read, not source to inspect. Without a renderer the
+      // TUI falls back to plain text and shows raw Markdown syntax.
+      return new Markdown(plan, 0, 0, getMarkdownTheme());
+    },
   });
 
   pi.registerCommand("plan", {

package/extensions/setup/index.ts

@@ -36,11 +36,13 @@ import {
   POST_EDIT_COMMAND_MAX_CHARS,
   REASONING_LEVELS,
   SETUP_CONFIG_CHANGED_CHANNEL,
+  WEB_THEMES,
   type FooterLayoutItem,
   type CapabilityDiscoveryMode,
   type FooterPreset,
   type FooterStyle,
   type MyPiSetupConfig,
+  type WebTheme,
 } from "../shared/setup-config.ts";
 
 const subagentRoleModelValueSchema = Type.Union([
@@ -107,7 +109,7 @@ export function buildInteractiveSetupPrompt(options: {
 }) {
   const configurationState = options.savedConfigExists
     ? [
-        "This package has already been configured. Explain the current settings in the user's language, then ask whether they want to keep them or change Capability discovery, Next-action suggestions, Workflow limits, UI/Footer, result detail display, Post-edit, Agent role models, or review everything.",
+        "This package has already been configured. Explain the current settings in the user's language, then ask whether they want to keep them or change Capability discovery, Next-action suggestions, Workflow limits, UI theme/Footer, result detail display, Post-edit, Agent role models, or review everything.",
         "If the user keeps the current settings, do not call configure_my_pi_setup. If they choose a category, ask only the follow-up needed for that category.",
       ]
     : [
@@ -130,7 +132,7 @@ export function buildInteractiveSetupPrompt(options: {
     "- Capability discovery: explicit is the safe default and keeps OpenPI model tools absent until the user asks for a capability. adaptive is opt-in and keeps only the small openpi_load_tools gateway visible, allowing the model to load Subagents, Workflows, background terminals, structured search, or Session tracking when it judges them useful. Loaded groups remain session-stable, and normal permission, concurrency, and workflow limits still apply.",
     "- Next-action suggestions: disabled, or model-generated after a fully settled main-agent run. A suggestion appears as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. Right accepts it without submitting, and any other editor input dismisses it. Enabling requires an available provider/model and reasoning level and adds one small model call per settled run.",
     "- Workflow fan-out: concurrency controls simultaneous agents and resource pressure; max agent calls controls the total capacity of one workflow. Valid ranges are 1-64 and 1-1024.",
-    "- UI: the large header costs vertical space; the custom footer is a declarative dashboard. Presets: powerline (one-line ANSI256 blocks), powerline-mono (one-line high-contrast gray powerline), and compact (one-line plain text); the default is plain with model/context on the left and git/pr/cwd on the right. Style can also be set independently: plain, powerline, powerline-mono. Custom lines are a 2D layout of cwd/model/thinking/context/cache/cost/throughput/git/pr plus at most one flex per line for left/right alignment. Footer metrics use Codicon outline glyphs for model, context, and directory; a Nerd Font renders them as designed while the text stays readable without it. Changes apply immediately in the active TUI session.",
+    "- UI: the Web theme is system (default), light, or dark and is projected from this canonical configuration without browser-local overrides. The large header costs vertical space; the custom footer is a declarative dashboard. Presets: powerline (one-line ANSI256 blocks), powerline-mono (one-line high-contrast gray powerline), and compact (one-line plain text); the default is plain with model/context on the left and git/pr/cwd on the right. Style can also be set independently: plain, powerline, powerline-mono. Custom lines are a 2D layout of cwd/model/thinking/context/cache/cost/throughput/git/pr plus at most one flex per line for left/right alignment. Footer metrics use Codicon outline glyphs for model, context, and directory; a Nerd Font renders them as designed while the text stays readable without it. Changes apply immediately in the active TUI session; Web theme changes apply on its next canonical snapshot.",
     "- Operational activity for Subagents, Workflows, and background terminals is core status and always remains visible whenever the custom footer is enabled.",
     "- Post-edit command: one optional shell command (maximum 500 characters) run in the background after a turn with successful Write/Edit operations (e.g. `npm run format`). Off by default, interactive TUI sessions only, failures surface as a notification. This is a single command, not an event-hook system.",
     "- Result detail display: Subagent results, Bash operations, and Write/Edit operations can each default to full or compact; all three default to compact. Compact Subagent results show only bounded status rows and keep raw child reports behind app.tools.expand; compact Bash and Write/Edit operations use one-line semantic activity summaries. Read, grep, find, and ls use the same compact activity-row projection. Ctrl+O restores Pi's native full arguments, output, errors, diffs, and timing. Recommend compact for users who scan activity first and inspect evidence on demand.",
@@ -139,6 +141,7 @@ export function buildInteractiveSetupPrompt(options: {
     "Natural-language configuration examples the user might ask for:",
     '- "let the model discover OpenPI capabilities when useful" → capability_discovery=adaptive',
     '- "only use OpenPI capabilities when I ask" → capability_discovery=explicit',
+    '- "use dark theme in OpenPI Web" → ui_web_theme=dark',
     '- "switch footer to powerline" → ui_footer_preset=powerline',
     '- "use mono powerline" → ui_footer_preset=powerline-mono',
     '- "compact footer" → ui_footer_preset=compact',
@@ -309,7 +312,7 @@ export default function openPiSetup(pi: ExtensionAPI) {
     name: "configure_my_pi_setup",
     label: "Configure OpenPI",
     description:
-      "Apply a user-requested configuration change for this Pi setup. Configures capability discovery (explicit or opt-in adaptive), next-action suggestions, workflow fan-out, UI/Footer (presets, style, multi-line layout), result detail display, optional Post-edit, and built-in Agent-role model assignments shared by subagent_spawn and workflow agent_type. Role models must be available in the Pi registry; null clears a role back to parent-model inheritance. Footer examples: powerline preset, powerline-mono, compact, or custom ui_footer_lines with flex. Preserve current values for settings the user did not ask to change. Changes apply immediately to the capability gateway and active TUI footer.",
+      "Apply a user-requested configuration change for this Pi setup. Configures capability discovery (explicit or opt-in adaptive), next-action suggestions, workflow fan-out, the canonical OpenPI Web theme, UI/Footer (presets, style, multi-line layout), result detail display, optional Post-edit, and built-in Agent-role model assignments shared by subagent_spawn and workflow agent_type. Role models must be available in the Pi registry; null clears a role back to parent-model inheritance. Footer examples: powerline preset, powerline-mono, compact, or custom ui_footer_lines with flex. Preserve current values for settings the user did not ask to change. Changes apply immediately to the capability gateway and active TUI footer; Web observes theme changes through canonical snapshots.",
     parameters: Type.Object({
       capability_discovery: Type.Optional(
         StringEnum(CAPABILITY_DISCOVERY_MODES, {
@@ -356,6 +359,12 @@ export default function openPiSetup(pi: ExtensionAPI) {
             "Whether to show the large decorative Pi header. Defaults to false; omit to preserve the current value.",
         }),
       ),
+      ui_web_theme: Type.Optional(
+        StringEnum(WEB_THEMES, {
+          description:
+            "Canonical OpenPI Web theme: system follows the browser/OS color scheme, light and dark force that appearance. Stored in package setup rather than browser storage. Omit to preserve the current value.",
+        }),
+      ),
       ui_custom_footer: Type.Optional(
         Type.Boolean({
           description:
@@ -503,6 +512,9 @@ export default function openPiSetup(pi: ExtensionAPI) {
               current.workflows.maxAgentCalls,
           },
           ui: {
+            webTheme:
+              (params.ui_web_theme as WebTheme | undefined) ??
+              current.ui.webTheme,
             showHeader: params.ui_show_header ?? current.ui.showHeader,
             customFooter: params.ui_custom_footer ?? current.ui.customFooter,
             ...footer,