@tt-a1i/openpi 0.4.0 → 0.6.0

package/extensions/shared/result-delivery.ts

@@ -0,0 +1,34 @@
+/** Minimum lifecycle contract shared by deferred result queues. */
+export interface ResultDeliveryQueue<T> {
+  defer(result: T): void;
+  size(): number;
+  clear(): void;
+}
+
+/** One-shot results are removed by either an explicit consumer or delivery. */
+export interface ConsumableResultDeliveryQueue<T, TId = string>
+  extends ResultDeliveryQueue<T> {
+  consume(ids: Iterable<TId>): void;
+}
+
+/** Stable identity carried by a durable, at-least-once result. */
+export interface DurableResultEnvelope {
+  deliveryId: string;
+}
+
+/** Per-result acknowledgement for a durable delivery attempt. */
+export interface DurableResultDeliveryReceipt {
+  deliveryId: string;
+  delivered: boolean;
+  error?: string;
+}
+
+/**
+ * Durable queues can reconstruct pending ownership after restart and retry it
+ * at an explicit lifecycle boundary without changing the stable delivery id.
+ */
+export interface DurableResultDeliveryQueue<T extends DurableResultEnvelope>
+  extends ResultDeliveryQueue<T> {
+  restore(result: T): boolean;
+  retryPending(): Promise<void>;
+}

package/extensions/shared/setup-config.ts

@@ -63,6 +63,9 @@ export type FooterLines = readonly (readonly FooterLayoutItem[])[];
 export const DETAIL_DISPLAYS = ["full", "compact"] as const;
 export type DetailDisplay = (typeof DETAIL_DISPLAYS)[number];
 
+export const WEB_THEMES = ["system", "light", "dark"] as const;
+export type WebTheme = (typeof WEB_THEMES)[number];
+
 export const CAPABILITY_DISCOVERY_MODES = ["explicit", "adaptive"] as const;
 export type CapabilityDiscoveryMode =
   (typeof CAPABILITY_DISCOVERY_MODES)[number];
@@ -72,6 +75,22 @@ export const DEFAULT_FOOTER_LINES: FooterLines = [
   ["model", "context", "flex", "git", "pr", "cwd"],
 ];
 
+/** Stable skeleton for the legacy flat-selection adapter. */
+const FLAT_FOOTER_ITEM_LINES: FooterLines = [
+  [
+    "model",
+    "thinking",
+    "context",
+    "cache",
+    "cost",
+    "throughput",
+    "flex",
+    "git",
+    "pr",
+    "cwd",
+  ],
+];
+
 /** The persisted canonical default before model/context moved to the left. */
 const LEGACY_DEFAULT_FOOTER_LINES: FooterLines = [
   ["cwd", "git", "pr", "flex", "model", "context"],
@@ -133,12 +152,11 @@ export interface MyPiSetupConfig {
     readonly maxAgentCalls: number;
   };
   readonly ui: {
+    readonly webTheme: WebTheme;
     readonly showHeader: boolean;
     readonly customFooter: boolean;
     readonly footerStyle: FooterStyle;
-    /** Canonical footer layout. `footerItems` is always derived from this. */
     readonly footerLines: FooterLines;
-    readonly footerItems: readonly FooterItem[];
     readonly subagentResultDisplay: DetailDisplay;
     readonly bashToolDisplay: DetailDisplay;
     readonly fileMutationDisplay: DetailDisplay;
@@ -165,12 +183,12 @@ export const DEFAULT_SETUP_CONFIG: MyPiSetupConfig = {
     maxAgentCalls: DEFAULT_WORKFLOW_MAX_AGENT_CALLS,
   },
   ui: {
+    webTheme: "system",
     showHeader: false,
     customFooter: true,
     footerStyle: DEFAULT_FOOTER_STYLE,
     footerLines: DEFAULT_FOOTER_LINES,
-    footerItems: DEFAULT_FOOTER_ITEMS,
-    subagentResultDisplay: "full",
+    subagentResultDisplay: "compact",
     bashToolDisplay: "compact",
     fileMutationDisplay: "compact",
   },
@@ -213,6 +231,9 @@ const isCapabilityDiscoveryMode = (
   typeof value === "string" &&
   CAPABILITY_DISCOVERY_MODES.includes(value as CapabilityDiscoveryMode);
 
+const isWebTheme = (value: unknown): value is WebTheme =>
+  typeof value === "string" && WEB_THEMES.includes(value as WebTheme);
+
 export function flattenFooterItems(lines: FooterLines): readonly FooterItem[] {
   const items: FooterItem[] = [];
   const seen = new Set<FooterItem>();
@@ -261,13 +282,13 @@ export function normalizeFooterLines(value: unknown): FooterLines {
   return lines.length > 0 ? lines : DEFAULT_FOOTER_LINES;
 }
 
-/** Map a flat item list onto the default one-line skeleton (legacy compat). */
+/** Map a flat item list onto the stable one-line skeleton (legacy compat). */
 export function footerLinesFromItems(
   items: readonly FooterItem[],
 ): FooterLines {
   const selected = new Set(items);
   return normalizeFooterLines(
-    DEFAULT_FOOTER_LINES.map((line) =>
+    FLAT_FOOTER_ITEM_LINES.map((line) =>
       line.filter((item) => item === "flex" || selected.has(item)),
     ),
   );
@@ -335,7 +356,6 @@ export function applyFooterConfig(
   return {
     footerStyle: style,
     footerLines: normalized,
-    footerItems: flattenFooterItems(normalized),
   };
 }
 
@@ -358,7 +378,7 @@ function sameFooterLines(left: FooterLines, right: FooterLines) {
 
 function parseUiFooter(
   ui: Record<string, unknown>,
-): Pick<MyPiSetupConfig["ui"], "footerStyle" | "footerLines" | "footerItems"> {
+): Pick<MyPiSetupConfig["ui"], "footerStyle" | "footerLines"> {
   const style = isFooterStyle(ui.footerStyle)
     ? ui.footerStyle
     : DEFAULT_FOOTER_STYLE;
@@ -371,7 +391,6 @@ function parseUiFooter(
     return {
       footerStyle: style,
       footerLines: lines,
-      footerItems: flattenFooterItems(lines),
     };
   }
 
@@ -382,14 +401,12 @@ function parseUiFooter(
     return {
       footerStyle: style,
       footerLines: lines,
-      footerItems: flattenFooterItems(lines),
     };
   }
 
   return {
     footerStyle: style,
     footerLines: DEFAULT_FOOTER_LINES,
-    footerItems: DEFAULT_FOOTER_ITEMS,
   };
 }
 
@@ -476,6 +493,7 @@ export function parseSetupConfig(value: unknown): MyPiSetupConfig {
       ),
     },
     ui: {
+      webTheme: isWebTheme(ui.webTheme) ? ui.webTheme : "system",
       showHeader: typeof ui.showHeader === "boolean" ? ui.showHeader : false,
       customFooter:
         typeof ui.customFooter === "boolean" ? ui.customFooter : true,
@@ -484,7 +502,7 @@ export function parseSetupConfig(value: unknown): MyPiSetupConfig {
         ui.subagentResultDisplay as DetailDisplay,
       )
         ? (ui.subagentResultDisplay as DetailDisplay)
-        : "full",
+        : "compact",
       bashToolDisplay: DETAIL_DISPLAYS.includes(
         ui.bashToolDisplay as DetailDisplay,
       )
@@ -504,9 +522,9 @@ export function parseSetupConfig(value: unknown): MyPiSetupConfig {
 /** An empty or invalid value disables the post-edit command (the safe default). */
 function parsePostEditCommand(value: unknown) {
   if (!isRecord(value)) return "";
-  return typeof value.command === "string"
-    ? value.command.trim().slice(0, POST_EDIT_COMMAND_MAX_CHARS)
-    : "";
+  if (typeof value.command !== "string") return "";
+  const command = value.command.trim();
+  return command.length <= POST_EDIT_COMMAND_MAX_CHARS ? command : "";
 }
 
 export function hasSavedSetupConfig() {
@@ -561,6 +579,9 @@ function replacedFields(
   ) {
     paths.push("summaries → suggestions");
   }
+  if (path === "ui" && "footerItems" in raw && "footerLines" in normalized) {
+    paths.push("ui.footerItems");
+  }
   for (const [key, value] of Object.entries(normalized)) {
     if (!(key in raw)) continue;
     const here = path ? `${path}.${key}` : key;
@@ -627,24 +648,55 @@ const sameOwner = (left: LockOwner, right: LockOwner) =>
 const sameFile = (left: Stats, right: Stats) =>
   left.dev === right.dev && left.ino === right.ino;
 
+const parsePowerShellProcessStartedAt = (stdout: string) => {
+  const startedAt = Number(stdout.trim());
+  return isPositiveInteger(startedAt) ? startedAt : undefined;
+};
+
+const parsePsProcessStartedAt = (stdout: string) => {
+  const startedAt = Date.parse(stdout.trim());
+  return Number.isFinite(startedAt) ? startedAt : undefined;
+};
+
+export function processStartedAtQuery(
+  pid: number,
+  platform = process.platform,
+) {
+  if (platform === "win32") {
+    const script = [
+      "$ErrorActionPreference='Stop'",
+      `$p=Get-Process -Id ${pid}`,
+      "[Console]::Out.Write(([DateTimeOffset]$p.StartTime).ToUnixTimeMilliseconds())",
+    ].join("; ");
+    return {
+      command: "powershell.exe",
+      args: ["-NoProfile", "-NonInteractive", "-Command", script],
+      env: undefined,
+      parseOutput: parsePowerShellProcessStartedAt,
+    };
+  }
+  return {
+    command: "ps",
+    args: ["-o", "lstart=", "-p", String(pid)],
+    env: { LC_ALL: "C" },
+    parseOutput: parsePsProcessStartedAt,
+  };
+}
+
 const queryProcessStartedAt = (pid: number) =>
   new Promise<number | undefined>((resolve) => {
-    if (process.platform === "win32") {
-      resolve(undefined);
-      return;
-    }
+    const query = processStartedAtQuery(pid);
     try {
       execFile(
-        "ps",
-        ["-o", "lstart=", "-p", String(pid)],
+        query.command,
+        query.args,
         {
           encoding: "utf8",
-          env: { ...process.env, LC_ALL: "C" },
+          env: query.env ? { ...process.env, ...query.env } : process.env,
           timeout: 1_000,
         },
         (error, stdout) => {
-          const startedAt = error ? Number.NaN : Date.parse(stdout.trim());
-          resolve(Number.isFinite(startedAt) ? startedAt : undefined);
+          resolve(error ? undefined : query.parseOutput(stdout));
         },
       );
     } catch {
@@ -938,13 +990,15 @@ async function withSetupConfigLock<A>(action: () => Promise<A>) {
 }
 
 async function writeSetupConfig(config: MyPiSetupConfig) {
+  const canonical = parseSetupConfig(config);
   const tempPath = `${SETUP_CONFIG_PATH}.${process.pid}.${randomUUID()}.tmp`;
   try {
-    await writeFile(tempPath, `${JSON.stringify(config, null, 2)}\n`, {
+    await writeFile(tempPath, `${JSON.stringify(canonical, null, 2)}\n`, {
       encoding: "utf8",
       mode: 0o600,
     });
     await rename(tempPath, SETUP_CONFIG_PATH);
+    return canonical;
   } catch (error) {
     await unlink(tempPath).catch(() => undefined);
     throw error;
@@ -958,10 +1012,7 @@ export async function saveSetupConfig(config: MyPiSetupConfig) {
   });
 }
 
-export function formatSetupConfig(
-  config = loadSetupConfig(),
-  integrationLines: readonly string[] = [],
-) {
+export function formatSetupConfig(config = loadSetupConfig()) {
   const suggestionModel = config.suggestions.model;
   const suggestions =
     !config.suggestions.enabled || !suggestionModel
@@ -974,13 +1025,12 @@ export function formatSetupConfig(
     `Capability discovery: ${config.capabilities.discovery}`,
     suggestions,
     `Workflows: ${config.workflows.concurrency} concurrent agents · ${config.workflows.maxAgentCalls} total calls`,
-    `UI: large header ${config.ui.showHeader ? "on" : "off"} · custom footer ${footer}`,
+    `UI: Web theme ${config.ui.webTheme} · large header ${config.ui.showHeader ? "on" : "off"} · custom footer ${footer}`,
     `Subagent results: ${config.ui.subagentResultDisplay === "full" ? "full by default" : "compact status summary (Ctrl+O expands full output)"}`,
     `Bash operations: ${config.ui.bashToolDisplay === "full" ? "expanded by default" : "one-line activity summary (Ctrl+O restores native evidence)"}`,
     `Write/Edit operations: ${config.ui.fileMutationDisplay === "full" ? "expanded by default" : "one-line activity summary (Ctrl+O restores native evidence)"}`,
-    `Post-edit command: ${config.postEdit.command ? config.postEdit.command : "off"}`,
+    `Post-edit command: ${config.postEdit.command ? "configured" : "off"}`,
     `Agent role models (Subagents + Workflows): ${SUBAGENT_ROLE_NAMES.map((role) => `${role} ${config.subagents.roleModels[role] ? `${config.subagents.roleModels[role].provider}/${config.subagents.roleModels[role].model}` : "inherit"}`).join(" · ")}`,
-    ...integrationLines,
   ].join("\n");
 }
 
@@ -998,8 +1048,7 @@ export async function updateSetupConfig(
   return withSetupConfigLock(async () => {
     const raw = readDocumentForWrite();
     const current = parseSetupConfig(raw);
-    const config = mutate(current);
-    await writeSetupConfig(config);
+    const config = await writeSetupConfig(mutate(current));
     return { config, replaced: replacedFields(raw, current) };
   });
 }

package/extensions/shared/setup-episode-state.ts

@@ -2,6 +2,6 @@
 export const OPENPI_SETUP_EPISODE_CHANNEL = "openpi:setup-episode";
 
 export interface OpenPiSetupEpisodeState {
-  /** True for both armed and actively running setup episodes. */
+  /** True only while the owned setup writer is active for a delivered request. */
   readonly active: boolean;
 }

package/extensions/shared/structured-output.ts

@@ -0,0 +1,154 @@
+import {
+  defineTool,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+
+export const STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION =
+  "When your task is complete, call the `structured_output` tool exactly once as your final action, with fields matching the required schema. Do not write any other text after it.";
+
+export const STRUCTURED_OUTPUT_TOOL_DESCRIPTION =
+  "Return your final result as structured data matching the required schema. Call this exactly once, as your last action; do not write any other text after it.";
+
+export const STRUCTURED_RESULT_LIMITS = Object.freeze({
+  schemaDepth: 24,
+  schemaNodes: 10_000,
+  resultBytes: 2 * 1024 * 1024,
+  resultDepth: 24,
+  resultNodes: 100_000,
+  resultStringBytes: 1024 * 1024,
+});
+
+export interface EncodedStructuredResult {
+  readonly value: unknown;
+  readonly json: string;
+  readonly byteLength: number;
+}
+
+function safeRecordKey(key: string) {
+  return key !== "__proto__" && key !== "constructor" && key !== "prototype";
+}
+
+/** Preserve the caller's full JSON Schema instead of lossy keyword conversion. */
+export function jsonSchemaToTypebox(schema: unknown): TSchema {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error("structured output schema must be a bounded JSON object");
+  }
+  const seen = new WeakSet<object>();
+  let nodes = 0;
+  const validate = (current: unknown, depth: number): boolean => {
+    if (
+      ++nodes > STRUCTURED_RESULT_LIMITS.schemaNodes ||
+      depth > STRUCTURED_RESULT_LIMITS.schemaDepth
+    ) {
+      return false;
+    }
+    if (
+      current === null ||
+      typeof current === "string" ||
+      typeof current === "boolean"
+    ) {
+      return true;
+    }
+    if (typeof current === "number") return Number.isFinite(current);
+    if (Array.isArray(current)) {
+      return current.every((item) => validate(item, depth + 1));
+    }
+    if (typeof current !== "object" || seen.has(current)) return false;
+    seen.add(current);
+    return Object.keys(current).every(
+      (key) =>
+        safeRecordKey(key) &&
+        validate((current as Record<string, unknown>)[key], depth + 1),
+    );
+  };
+  if (!validate(schema, 0)) {
+    throw new Error("structured output schema must be a bounded JSON object");
+  }
+  return Type.Unsafe(schema);
+}
+
+/** Encode one complete JSON result or fail before any truncated artifact exists. */
+export function encodeStructuredResult(
+  value: unknown,
+): EncodedStructuredResult {
+  const seen = new WeakSet<object>();
+  let nodes = 0;
+  const validate = (current: unknown, depth: number): void => {
+    if (++nodes > STRUCTURED_RESULT_LIMITS.resultNodes) {
+      throw new Error("structured result exceeds the node limit");
+    }
+    if (depth > STRUCTURED_RESULT_LIMITS.resultDepth) {
+      throw new Error("structured result exceeds the depth limit");
+    }
+    if (typeof current === "string") {
+      if (
+        Buffer.byteLength(current, "utf8") >
+        STRUCTURED_RESULT_LIMITS.resultStringBytes
+      ) {
+        throw new Error("structured result contains an oversized string");
+      }
+      return;
+    }
+    if (
+      current === null ||
+      typeof current === "boolean" ||
+      (typeof current === "number" && Number.isFinite(current))
+    ) {
+      return;
+    }
+    if (typeof current !== "object" || seen.has(current)) {
+      throw new Error(
+        "structured result must contain only acyclic JSON values",
+      );
+    }
+    seen.add(current);
+    if (Array.isArray(current)) {
+      for (const item of current) validate(item, depth + 1);
+      return;
+    }
+    for (const [key, item] of Object.entries(current)) {
+      if (!safeRecordKey(key)) {
+        throw new Error("structured result contains an unsafe object key");
+      }
+      validate(item, depth + 1);
+    }
+  };
+  validate(value, 0);
+  const json = JSON.stringify(value);
+  const byteLength = Buffer.byteLength(json, "utf8");
+  if (byteLength > STRUCTURED_RESULT_LIMITS.resultBytes) {
+    throw new Error("structured result exceeds the total byte limit");
+  }
+  return { value, json, byteLength };
+}
+
+/** One-shot terminating child tool shared by Workflow and Direct Subagent. */
+export function createStructuredOutputTool(
+  schema: unknown,
+  capture: (value: unknown) => void,
+): ToolDefinition {
+  return defineTool({
+    name: "structured_output",
+    label: "Structured Output",
+    description: STRUCTURED_OUTPUT_TOOL_DESCRIPTION,
+    parameters: jsonSchemaToTypebox(schema),
+    async execute(_toolCallId, params) {
+      capture(params);
+      return {
+        content: [{ type: "text", text: "Recorded structured result." }],
+        details: params,
+        terminate: true,
+      };
+    },
+  });
+}
+
+export function childToolsWithStructuredOutput(
+  tools: readonly string[] | undefined,
+  structured: boolean,
+) {
+  return tools
+    ? [...new Set([...tools, ...(structured ? ["structured_output"] : [])])]
+    : undefined;
+}

package/extensions/shared/terminal-text.ts

@@ -1,35 +1,122 @@
-// OSC may end in BEL or ST. DCS/SOS/PM/APC end only in ST; treating BEL as
-// their terminator would expose the rest of a still-hidden payload. Both
-// patterns consume an unterminated string through the bounded input's end.
-// eslint-disable-next-line no-control-regex
-const OSC_PATTERN =
-  /(?:\u001b\]|\u009d)(?:[^\u0007\u001b\u009c]|\u001b(?!\\))*(?:\u0007|\u001b\\|\u009c|$)/g;
-// eslint-disable-next-line no-control-regex
-const ST_STRING_PATTERN =
-  /(?:\u001b[PX^_]|[\u0090\u0098\u009e\u009f])(?:[^\u001b\u009c]|\u001b(?!\\))*(?:\u001b\\|\u009c|$)/g;
-// eslint-disable-next-line no-control-regex
-const CSI_PATTERN = /(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]/g;
-// Remaining two-byte/charset escape forms (for example ESC ( 0).
-// eslint-disable-next-line no-control-regex
-const ESCAPE_PATTERN = /\u001b(?:[()][0-2A-Z]|[ -/]*[@-~])/g;
 // Invisible Unicode format controls can reorder or disguise untrusted text.
 // Keep only ZWNJ/ZWJ (U+200C/U+200D), which carry legitimate shaping and emoji
 // semantics; variation selectors are marks rather than Cf and remain intact.
-const UNSAFE_FORMAT_PATTERN = /(?![\u200c\u200d])\p{Cf}/gu;
+const UNSAFE_FORMAT_CHARACTER = /\p{Cf}/u;
 // eslint-disable-next-line no-control-regex
 const TERMINAL_CONTROL_PATTERN =
   /[\u0000-\u001f\u007f-\u009f]|(?:(?![\u200c\u200d])\p{Cf})/u;
 
+type SanitizerState =
+  | "text"
+  | "escape"
+  | "escape_intermediate"
+  | "csi"
+  | "osc"
+  | "st_string";
+
+/** Stateful terminal-text projection for streams whose retained head can move. */
+export class TerminalTextSanitizer {
+  private state: SanitizerState = "text";
+  private stringEscape = false;
+
+  push(text: string) {
+    let safe = "";
+    for (const character of text) {
+      const code = character.codePointAt(0)!;
+
+      if (this.state === "osc" || this.state === "st_string") {
+        if (character === "\u009c") {
+          this.state = "text";
+          this.stringEscape = false;
+        } else if (this.state === "osc" && character === "\u0007") {
+          this.state = "text";
+          this.stringEscape = false;
+        } else if (this.stringEscape && character === "\\") {
+          this.state = "text";
+          this.stringEscape = false;
+        } else {
+          this.stringEscape = character === "\u001b";
+        }
+        continue;
+      }
+
+      if (this.state === "csi") {
+        if (code >= 0x40 && code <= 0x7e) this.state = "text";
+        else if (code < 0x20 || code > 0x3f) {
+          this.state = "text";
+          safe += this.safeCharacter(character, code);
+        }
+        continue;
+      }
+
+      if (this.state === "escape" || this.state === "escape_intermediate") {
+        if (this.state === "escape") {
+          if (character === "[") {
+            this.state = "csi";
+            continue;
+          }
+          if (character === "]") {
+            this.state = "osc";
+            continue;
+          }
+          if (
+            character === "P" ||
+            character === "X" ||
+            character === "^" ||
+            character === "_"
+          ) {
+            this.state = "st_string";
+            continue;
+          }
+        }
+        if (code >= 0x20 && code <= 0x2f) {
+          this.state = "escape_intermediate";
+        } else if (code >= 0x30 && code <= 0x7e) {
+          this.state = "text";
+        } else {
+          this.state = "text";
+          safe += this.safeCharacter(character, code);
+        }
+        continue;
+      }
+
+      if (character === "\u001b") {
+        this.state = "escape";
+      } else if (character === "\u009b") {
+        this.state = "csi";
+      } else if (character === "\u009d") {
+        this.state = "osc";
+      } else if (
+        character === "\u0090" ||
+        character === "\u0098" ||
+        character === "\u009e" ||
+        character === "\u009f"
+      ) {
+        this.state = "st_string";
+      } else {
+        safe += this.safeCharacter(character, code);
+      }
+    }
+    return safe;
+  }
+
+  private safeCharacter(character: string, code: number) {
+    if (character === "\t") return "  ";
+    if (
+      character === "\n" ||
+      character === "\u200c" ||
+      character === "\u200d"
+    ) {
+      return character;
+    }
+    if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) return "";
+    return UNSAFE_FORMAT_CHARACTER.test(character) ? "" : character;
+  }
+}
+
 /** Strip terminal control sequences and direction-spoofing format controls. */
 export function sanitizeTerminalText(text: string) {
-  return text
-    .replace(OSC_PATTERN, "")
-    .replace(ST_STRING_PATTERN, "")
-    .replace(CSI_PATTERN, "")
-    .replace(ESCAPE_PATTERN, "")
-    .replace(UNSAFE_FORMAT_PATTERN, "")
-    .replaceAll("\t", "  ")
-    .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+  return new TerminalTextSanitizer().push(text);
 }
 
 /** Reject raw terminal or direction-spoofing controls in display patterns. */