@openlines/opl-pi-sht 0.2.12 → 0.3.1

package/extensions/opl-init/index.ts

@@ -31,6 +31,7 @@ type Crawl = {
   extCounts: Map<string, number>;
   manifests: { path: string; content: string }[];
   workspaceMembers: string[];
+  skippedGlobs: string[];
   seen: Set<string>;
 };
 
@@ -42,41 +43,147 @@ const FP_MARKER = /<!-- opl-init:fp (\S+) -->/;
 // (vs HEAD, so staged changes count) and every untracked file. Only the root
 // AGENTS.md is excluded, so writing the guide does not make it stale;
 // subdirectory AGENTS.md files are repository facts.
+// /init computes the fingerprint synchronously on the command path, and a workspace can
+// hold a dataset, model weights or a recording. Content-hashing everything cost 135 ms and
+// 245 MB RSS for a single 200 MB file, so large files are represented by their metadata and
+// the whole pass runs under a path and byte budget.
+// Known blind spot, accepted deliberately: a rewrite that keeps size and mtime identical, or
+// any change past the caps, is invisible until a change the fingerprint can see happens.
+const FP_LIMITS = {
+  maxFileBytes: 2 * 1024 * 1024,
+  maxTotalBytes: 32 * 1024 * 1024,
+  maxPaths: 5000,
+};
+
+type FpLimits = typeof FP_LIMITS;
+type FpBudget = { bytes: number; paths: number; capped: boolean };
+
 // Returns null for non-git directories (caller falls back to fingerprintFallback).
-function fingerprintGit(root: string): string | null {
+function fingerprintGit(root: string, limits: FpLimits = FP_LIMITS): string | null {
   const head = gitOutput(root, ["rev-parse", "HEAD"]);
   if (head === null) return null;
   const hash = createHash("sha256").update(`schema:${GUIDE_SCHEMA_VERSION}\0head:${head}\0`);
+  const budget: FpBudget = { bytes: 0, paths: 0, capped: false };
   // --relative keeps diff paths cwd-relative and cwd-scoped, matching
   // ls-files --others and the crawl; without it a subdirectory session would
   // resolve every dirty path to a nonexistent file and hash "DELETED".
   for (const path of (gitOutput(root, ["diff", "HEAD", "--name-only", "-z", "--relative"]) ?? "").split("\0")) {
-    if (!path || path === "AGENTS.md") continue;
-    hash.update(`${path}\0`).update(hashFile(join(root, path))).update("\0");
+    hashFingerprintPath(hash, root, path, budget, limits);
   }
   for (const path of (gitOutput(root, ["ls-files", "--others", "--exclude-standard", "-z"]) ?? "").split("\0")) {
-    if (!path || path === "AGENTS.md") continue;
-    hash.update(`${path}\0`).update(hashFile(join(root, path))).update("\0");
+    hashFingerprintPath(hash, root, path, budget, limits);
   }
+  // Fold the budget state in so crossing a cap changes the digest once and then stays
+  // stable: an oscillating digest would make every /init run regenerate the guide.
+  hash.update(`budget:${budget.paths}:${budget.bytes}:${budget.capped ? 1 : 0}\0`);
   return hash.digest("hex").slice(0, 16);
 }
 
+function hashFingerprintPath(
+  hash: ReturnType<typeof createHash>,
+  root: string,
+  path: string,
+  budget: FpBudget,
+  limits: FpLimits,
+): void {
+  if (!path || path === "AGENTS.md") return;
+  // The name is always hashed even past a cap, so adding or removing a file is still
+  // visible; only content stops being read.
+  hash.update(`${path}\0`).update(budget.paths >= limits.maxPaths ? "OVER_CAP\0" : hashFile(join(root, path), budget, limits)).update("\0");
+  budget.paths++;
+  if (budget.paths >= limits.maxPaths) budget.capped = true;
+}
+
+// BEGIN SHARED GIT GUARD
+// A repository is attacker-chosen data: its local config, `.gitattributes` and system
+// config can name programs that git runs while answering what looks like a read-only query.
+// Measured on git 2.54: `git diff HEAD` executes a declared `[diff "x"] textconv` driver,
+// while `--name-only`, `status --porcelain`, `ls-files` and `rev-parse` do not. Every call
+// still goes through this guard so a future content-diff call cannot reintroduce the
+// execution path. Duplicated per extension because install.sh installs one directory at a
+// time; tests/net-guard-parity.test.mjs fails if the copies drift.
+const SAFE_GIT_GLOBAL_ARGS = [
+  "--no-pager",
+  "-c",
+  "core.fsmonitor=false",
+  "-c",
+  "core.hooksPath=",
+  "-c",
+  "protocol.ext.allow=never",
+  "-c",
+  "credential.helper=",
+];
+
+/** Refuse external content handlers. Diff-family subcommands only: plumbing rejects them. */
+const SAFE_GIT_DIFF_FLAGS = ["--no-ext-diff", "--no-textconv"];
+const GIT_DIFF_COMMANDS = new Set(["diff", "log", "show", "stash", "range-diff", "format-patch"]);
+
+const SAFE_GIT_ENV: Record<string, string> = {
+  // /etc/gitconfig and the user's own config can name helpers; a repo probe must not read them.
+  GIT_CONFIG_NOSYSTEM: "1",
+  GIT_ATTR_NOSYSTEM: "1",
+  GIT_PAGER: "cat",
+  // A credential prompt would hang the caller instead of failing fast.
+  GIT_TERMINAL_PROMPT: "0",
+  GIT_ASKPASS: "",
+  SSH_ASKPASS: "",
+  // Read-only plumbing must not create or wait on index.lock.
+  GIT_OPTIONAL_LOCKS: "0",
+};
+
+export function safeGitInvocation(args: string[]): string[] {
+  const [subcommand, ...rest] = args;
+  const diffFlags = subcommand && GIT_DIFF_COMMANDS.has(subcommand) ? SAFE_GIT_DIFF_FLAGS : [];
+  // A missing subcommand must not reach execFileSync/spawn as an undefined argv slot.
+  return subcommand
+    ? [...SAFE_GIT_GLOBAL_ARGS, subcommand, ...diffFlags, ...rest]
+    : [...SAFE_GIT_GLOBAL_ARGS, ...rest];
+}
+
+export function gitGuardEnv(base: Record<string, string | undefined> = process.env): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (typeof value === "string") env[key] = value;
+  }
+  return { ...env, ...SAFE_GIT_ENV };
+}
+// END SHARED GIT GUARD
+
 function gitOutput(root: string, args: string[]): string | null {
+  // Name-only/porcelain plumbing only; the guard above refuses patch content.
   try {
-    return execFileSync("git", args, {
+    return execFileSync("git", safeGitInvocation(args), {
       cwd: root,
+      env: gitGuardEnv(),
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
-      maxBuffer: 64 * 1024 * 1024,
+      // Name-only and porcelain output is path lists: 4 MB is on the order of 100k paths.
+      // A repo that needs more makes execFileSync throw, which reads as "not a git
+      // directory" and falls through to the stat-only fingerprintFallback.
+      maxBuffer: 4 * 1024 * 1024,
     });
   } catch {
     return null;
   }
 }
 
-function hashFile(path: string): string {
+function hashFile(path: string, budget: FpBudget, limits: FpLimits): string {
+  let stats;
+  try {
+    stats = statSync(path);
+  } catch {
+    return "DELETED";
+  }
+  // Above either threshold the entry is represented by metadata instead of bytes: a
+  // change to size or mtime is still detected, and the pass stays bounded.
+  if (!stats.isFile() || stats.size > limits.maxFileBytes || budget.bytes + stats.size > limits.maxTotalBytes) {
+    budget.capped = true;
+    return `meta:${stats.size}:${Math.round(stats.mtimeMs)}`;
+  }
   try {
-    return createHash("sha256").update(readFileSync(path)).digest("hex");
+    const body = readFileSync(path);
+    budget.bytes += body.length;
+    return createHash("sha256").update(body).digest("hex");
   } catch {
     return "DELETED";
   }
@@ -126,6 +233,7 @@ function crawl(root: string): Crawl {
     extCounts: new Map(),
     manifests: [],
     workspaceMembers: [],
+    skippedGlobs: [],
     seen: new Set(),
   };
 
@@ -190,6 +298,7 @@ function crawl(root: string): Crawl {
         break;
       }
       const entry = all[i];
+      if (entry === undefined) continue;
       result.tree.push(`${prefix}${entry}`);
       if (entry.endsWith("/") && depth < maxDepth) {
         walk(join(dir, entry.slice(0, -1)), depth + 1, `${prefix}  `, maxDepth);
@@ -202,7 +311,7 @@ function crawl(root: string): Crawl {
   // Manifest-first monorepo expansion: enumerate declared workspace members
   // with a fresh depth budget so packages/foo/src is not penalized by its
   // grouping prefix.
-  for (const member of workspaceMembers(root)) {
+  for (const member of workspaceMembers(root, result.skippedGlobs)) {
     if (result.tree.length >= MAX_TREE_LINES) break;
     const abs = join(root, member);
     let stats;
@@ -225,23 +334,42 @@ function crawl(root: string): Crawl {
   if (result.tree.length >= MAX_TREE_LINES) {
     result.tree.push(`(tree truncated at ${MAX_TREE_LINES} entries)`);
   }
+  if (result.skippedGlobs.length > 0) {
+    result.tree.push(
+      `(skipped workspace glob(s) that could not be compiled: ${result.skippedGlobs.join(", ")})`,
+    );
+  }
   return result;
 }
 
 // ponytail: naive glob matcher supporting only what workspace files use in
-// practice: `**` across segments, `*` within a segment, optional trailing "/".
-function globToRegExp(pattern: string): RegExp {
+// practice: `**` across segments, `*` within a segment, `?` for one character,
+// optional trailing "/". Everything else is escaped, so a directory name that is
+// itself regex syntax (`libs/c++/*`) matches literally instead of throwing.
+// Returns null for a pattern that cannot be compiled: workspace files are
+// user-authored, and one bad line must not abort /init.
+function globToRegExp(pattern: string): RegExp | null {
   const cleaned = pattern.replace(/\/$/, "");
-  const source = cleaned
-    .split("/**/")
-    .map((seg) => seg.replace(/[*]/g, "[^/]*"))
-    .join("(?:/.*)?");
-  return new RegExp(`^${source}$`);
+  if (cleaned === "") return null;
+  try {
+    const source = cleaned
+      .split("/**/")
+      .map((segment) =>
+        segment
+          .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+          .replace(/\*/g, "[^/]*")
+          .replace(/\?/g, "[^/]"),
+      )
+      .join("(?:/.*)?");
+    return new RegExp(`^${source}$`);
+  } catch {
+    return null;
+  }
 }
 
 // ponytail: line-based subset parsing of pnpm-workspace.yaml and Cargo.toml
 // [workspace] members. Full YAML/TOML parsing not warranted for glob lists.
-function workspaceMembers(root: string): string[] {
+function workspaceMembers(root: string, skipped: string[]): string[] {
   const globs: string[] = [];
 
   try {
@@ -254,7 +382,8 @@ function workspaceMembers(root: string): string[] {
         inPackages = false;
       } else if (inPackages) {
         const match = line.match(/^\s*-\s*["']?([^"'#]+)/);
-        if (match) globs.push(match[1].trim());
+        const pkg = match?.[1];
+        if (pkg) globs.push(pkg.trim());
       }
     }
   } catch {
@@ -264,10 +393,14 @@ function workspaceMembers(root: string): string[] {
   try {
     const toml = readFileSync(join(root, "Cargo.toml"), "utf8");
     const section = toml.match(/\[workspace\]([\s\S]*?)(?:\n\[|\s*$)/);
-    const membersBlock = section?.[1].match(/members\s*=\s*\[([^\]]*)\]/s);
+    const membersBlock = section?.[1]?.match(/members\s*=\s*\[([^\]]*)\]/s);
     if (membersBlock) {
-      for (const m of membersBlock[1].matchAll(/["']([^"']+)["']/g)) {
-        globs.push(m[1]);
+      const memberList = membersBlock[1];
+      if (memberList) {
+        for (const m of memberList.matchAll(/["']([^"']+)["']/g)) {
+          const name = m[1];
+          if (name) globs.push(name);
+        }
       }
     }
   } catch {
@@ -277,6 +410,10 @@ function workspaceMembers(root: string): string[] {
   const members = new Set<string>();
   for (const glob of globs) {
     const re = globToRegExp(glob);
+    if (!re) {
+      if (!skipped.includes(glob)) skipped.push(glob);
+      continue;
+    }
     // Match against shallow candidate paths from the tree we already walked,
     // plus one extra readdir of likely parent dirs. Simple approach: test every
     // tree dir line's relative path.
@@ -431,7 +568,9 @@ async function refineGuide(ctx: any, evidence: string, marker: string): Promise<
     const stream = ctx.modelRegistry.streamSimple(
       model,
       { systemPrompt: REFINE_SYSTEM_PROMPT, messages: [{ role: "user", content: evidence, timestamp: Date.now() }], tools: [] },
-      { reasoning: false, signal: AbortSignal.timeout(REFINE_TIMEOUT_MS) },
+      // ThinkingLevel has no "off": "minimal" is the cheapest level the adapters accept.
+      // `false` was silently dropped as "unset", so the refinement paid the provider default.
+      { reasoning: "minimal", signal: AbortSignal.timeout(REFINE_TIMEOUT_MS) },
     );
     const result = await stream.result();
     if (!result || result.stopReason === "error" || result.stopReason === "aborted") return null;
@@ -445,8 +584,50 @@ async function refineGuide(ctx: any, evidence: string, marker: string): Promise<
   }
 }
 
+// Offsets retain the user's original line endings and whitespace. Only ATX
+// headings outside fenced code blocks delimit the owned section.
+function operationalSections(text: string): { start: number; end: number }[] {
+  const sections: { start: number; end: number }[] = [];
+  let active: { start: number; end: number } | undefined;
+  let fence: { char: string; length: number } | undefined;
+  for (const match of text.matchAll(/[^\n]*(?:\n|$)/g)) {
+    const line = match[0].replace(/\r?\n$/, "");
+    const offset = match.index;
+    const fenced = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence) {
+      if (fenced?.[1]?.[0] === fence.char && fenced[1].length >= fence.length && !fenced[2]?.trim()) fence = undefined;
+      continue;
+    }
+    if (fenced?.[1] && (fenced[1][0] !== "`" || !fenced[2]?.includes("`"))) {
+      fence = { char: fenced[1][0]!, length: fenced[1].length };
+      continue;
+    }
+    const heading = line.match(/^ {0,3}(#{1,2})(?:[ \t]+(.*)|[ \t]*)$/);
+    if (!heading) continue;
+    if (active) { active.end = offset; active = undefined; }
+    if (heading[1] === "##" && heading[2]?.replace(/[ \t]+#+[ \t]*$/, "").trim() === "Operational notes") {
+      active = { start: offset, end: text.length };
+      sections.push(active);
+    }
+  }
+  return sections;
+}
+
+function guideWithoutFinalMarker(text: string): string {
+  return text.replace(/(^|\n)<!-- opl-init:fp \S+ -->[ \t]*(?:\r?\n)?$/, "$1");
+}
+
+function mergeOperationalNotes(generated: string, owned: string, marker: string): string {
+  let body = guideWithoutFinalMarker(generated);
+  // Discard generated versions: the existing user section is authoritative.
+  for (const section of operationalSections(body).reverse()) {
+    body = body.slice(0, section.start) + body.slice(section.end);
+  }
+  return `${body.trimEnd()}\n\n${owned}${owned.endsWith("\n") ? "" : "\n"}${marker}\n`;
+}
+
 // Named exports for fixture tests (tests/opl-init-*.test.mjs).
-export { crawl, fingerprint, evidencePacket, finalizeRefinedGuide, refineGuide };
+export { crawl, fingerprint, fingerprintGit, FP_LIMITS, evidencePacket, finalizeRefinedGuide, refineGuide };
 
 export default function (pi: ExtensionAPI) {
   pi.registerCommand("init", {
@@ -480,14 +661,34 @@ export default function (pi: ExtensionAPI) {
       }
 
       const marker = `<!-- opl-init:fp ${currentFp} -->`;
-      // Regenerating replaces the whole file, including hand-edited prose; the
-      // repository's version control is the recovery path.
+      let original: string | null;
+      let owned: string | undefined;
+      try {
+        original = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+        const body = guideWithoutFinalMarker(original ?? "");
+        const sections = operationalSections(body);
+        if (sections.length > 1) {
+          ctx.ui.notify("AGENTS.md has duplicate Operational notes sections; /init will not modify it.", "error");
+          return;
+        }
+        const section = sections[0];
+        if (section) owned = body.slice(section.start, section.end);
+      } catch (error: any) {
+        ctx.ui.notify(`Could not read AGENTS.md: ${error?.message || error}`, "error");
+        return;
+      }
       const crawlResult = crawl(root);
       const baseline = buildGuide(root, crawlResult, marker);
       const refined = await refineGuide(ctx, evidencePacket(root, baseline, crawlResult), marker);
 
       try {
-        writeFileSync(agentsPath, refined ?? baseline, "utf8");
+        const latest = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+        if (latest !== original) {
+          ctx.ui.notify("AGENTS.md changed during /init; update cancelled. Run /init again.", "error");
+          return;
+        }
+        const generated = refined ?? baseline;
+        writeFileSync(agentsPath, owned === undefined ? generated : mergeOperationalNotes(generated, owned, marker), "utf8");
       } catch (error: any) {
         ctx.ui.notify(`Could not write AGENTS.md: ${error?.message || error}`, "error");
         return;

package/extensions/opl-input/README.md

@@ -4,7 +4,7 @@ Replaces Pi's default chat editor with a mode-aware custom editor. Native editor
 
 ## Commands, flags, and shortcuts
 
-No commands, flags, or shortcuts. It replaces the standard editor at session start.
+No commands, flags, or shortcuts of its own. It replaces the standard editor at session start. Its settings are editable through the `/configurator` shell (Input tab, hotkey `i`); a save writes `opl-input.json` and reports that the change takes effect after `/reload`.
 
 ## Extension features
 
@@ -67,7 +67,7 @@ The companion requires at least 40 terminal columns and reserves three top-paddi
 
 Every color option accepts either:
 
-- **A Pi theme token** — one of the 45 tokens defined by Pi's `Theme`:
+- **A Pi theme token** — a color name from Pi's theme schema (56 names at pi 0.87.0 and 1.1.0, 7 of them `*Bg` fills). The ones that matter here:
   - Core: `accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`
   - Messages/content: `thinkingText`, `searchMatchText`, `userMessageText`, `customMessageText`, `customMessageLabel`
   - Tools: `toolTitle`, `toolOutput`, `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext`
@@ -75,7 +75,7 @@ Every color option accepts either:
   - Syntax: `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`
   - Thinking borders: `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `thinkingMax`
   - Special: `bashMode`
-- **A hex color** — `"#c07898"`, or the three-digit shorthand `"#abc"` (expanded to `#aabbcc`; rendered as ANSI truecolor, downgraded automatically on 256-color terminals).
+- **A hex color** — `"#c07898"`, or the three-digit shorthand `"#abc"` (expanded to `#aabbcc`). Hex values are emitted as ANSI truecolor (`38;2;r;g;b`); there is no 256-color downgrade in this extension, so on a 256-only terminal a hex color may render approximately or not at all, while a theme token renders correctly.
 
 Invalid theme tokens fall back to the theme's `border` token; invalid hex renders uncolored rather than crashing.
 - A mode `prefix` is clamped to one terminal cell (continuation lines reserve a single space), so a wide or multi-character `appearance.prefix` such as `👀` is truncated to one cell rather than pushing the box border past the editor width.
@@ -83,3 +83,17 @@ Invalid theme tokens fall back to the theme's `border` token; invalid hex render
 ## Architecture
 
 `index.ts` installs the editor integration and disposes companion render timers on editor replacement or session shutdown; `mode-style.ts` resolves Bash > published mode appearance > compiled fallback; `config.ts` loads editor and companion settings; and `utils.ts` handles color and rendering helpers. `opl-modes` is the sole publisher of active mode appearance through `globalThis.__agentMode`.
+
+Two couplings are worth knowing before editing this extension:
+
+- **pi-tui's text output.** Re-framing the editor means recognising its horizontal borders and
+  its scroll indicator, and pi-tui exposes neither as an API: they are the literal strings `─`
+  and `─── ↑ 3 more `. Those markers are collected in one place (`isSolidBorder`,
+  `scrollIndicatorText`, `isBorderLike` in `index.ts`) and
+  `tests/opl-input-pi-tui-markers.test.mjs` asserts the installed pi-tui still emits them. They
+  were byte-identical in pi-tui 0.87.0, 0.99.1 and 1.1.0; a failure there means the format
+  changed and the re-framing needs updating, not that the test is wrong.
+- **The bundle's idle heartbeat.** This component owns the only render timer, so the footer's
+  time-based cells advance because of it. Disabling `opl-input` freezes that clock; with
+  `companion.enabled: false` the tick slows to one repaint per `IDLE_REPAINT_MS` rather than
+  stopping.

package/extensions/opl-input/config.ts

@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export const DEFAULT_CONFIG = {
 	BOX_PAD_X: 1,
@@ -29,11 +29,65 @@ interface ChatInputUserConfig {
 	};
 }
 
-const CONFIG_PATH = join(homedir(), ".pi", "agent", "configs", "opl-input.json");
+/** Resolved per call so a custom `PI_AGENT_DIR` (pi's own agent dir) is honoured. */
+export function configPath(): string {
+	return join(getAgentDir(), "configs", "opl-input.json");
+}
+
+/** Subset of fields the configurator tab is allowed to edit. */
+export interface EditableInputConfig {
+	boxedView?: boolean;
+	companion?: {
+		enabled?: boolean;
+		type?: string;
+	};
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read the live config as a loose record ({} on absence or malformed), preserving unknown keys. */
+export function readInputConfig(): Record<string, unknown> {
+	try {
+		const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+		return isPlainObject(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+/** Merge only the editable fields into the live file. Returns false when nothing changed. */
+export function saveInputConfig(patch: EditableInputConfig): boolean {
+	const current = readInputConfig();
+	const next: Record<string, unknown> = { ...current };
+
+	if (typeof patch.boxedView === "boolean") next.boxedView = patch.boxedView;
+
+	if (patch.companion) {
+		const enabled = patch.companion.enabled;
+		const type = patch.companion.type;
+		const hasEnabled = typeof enabled === "boolean";
+		const hasType = typeof type === "string" && type.length > 0;
+		if (hasEnabled || hasType) {
+			const companion = isPlainObject(next.companion) ? { ...next.companion } : {};
+			if (hasEnabled) companion.enabled = enabled;
+			if (hasType) companion.type = type;
+			next.companion = companion;
+		}
+	}
+
+	if (JSON.stringify(next) === JSON.stringify(current)) return false;
+
+	const file = configPath();
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, JSON.stringify(next, null, 2) + "\n", "utf8");
+	return true;
+}
 
 function loadUserConfig(): ChatInputUserConfig {
 	try {
-		const raw = readFileSync(CONFIG_PATH, "utf8");
+		const raw = readFileSync(configPath(), "utf8");
 		return JSON.parse(raw) as ChatInputUserConfig;
 	} catch {
 		return {};

package/extensions/opl-input/configure.ts

@@ -0,0 +1,146 @@
+import type { ExtensionContext, KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { SettingsList, truncateToWidth, type SettingItem } from "@earendil-works/pi-tui";
+
+import { readInputConfig, saveInputConfig, type EditableInputConfig } from "./config.js";
+
+// The configurator seam. opl-configurator owns the /configurator command and reads this
+// globalThis array lazily; the entry shape is duplicated by hand on both sides because
+// install.sh copies one extension directory at a time.
+export const CONFIGURATOR_REGISTRY_KEY = "__oplConfiguratorTabs";
+
+/** What the configurator shell hands to each tab's factory. */
+export interface ConfiguratorTabApi {
+  ctx: ExtensionContext;
+  tui: { requestRender(): void };
+  theme: Theme;
+  keybindings: KeybindingsManager;
+  done: (result: void) => void;
+}
+
+export interface ConfiguratorTabComponent {
+  render(width: number): string[];
+  invalidate?(): void;
+  handleInput?(data: string): void;
+}
+
+interface ConfiguratorTab {
+  id: string;
+  hotkey: string;
+  label: string;
+  create: (api: ConfiguratorTabApi) => ConfiguratorTabComponent;
+}
+
+const BASE_COMPANION_TYPES = ["cat", "dog", "bunny"];
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function declaredCompanionTypes(companion: Record<string, unknown>): string[] {
+  const types = companion.types;
+  if (!Array.isArray(types)) return [];
+  return unique(
+    types
+      .filter((entry): entry is Record<string, unknown> => typeof entry === "object" && entry !== null)
+      .map((entry) => entry.typeName)
+      .filter((name): name is string => typeof name === "string" && name.length > 0),
+  );
+}
+
+function companionRecord(config: Record<string, unknown>): Record<string, unknown> {
+  return typeof config.companion === "object" && config.companion !== null && !Array.isArray(config.companion)
+    ? (config.companion as Record<string, unknown>)
+    : {};
+}
+
+/** Built-ins plus any declared typeName and the live selection, in that order, deduped. */
+export function companionTypeValues(config: Record<string, unknown>): string[] {
+  const companion = companionRecord(config);
+  const currentType = typeof companion.type === "string" && companion.type.length > 0 ? companion.type : "cat";
+  return unique([...BASE_COMPANION_TYPES, ...declaredCompanionTypes(companion), currentType]);
+}
+
+/** Map a setting item id to its write patch; null for an id the tab does not own. */
+export function inputFieldPatch(id: string, value: string): EditableInputConfig | null {
+  if (id === "boxedView") return { boxedView: value === "true" };
+  if (id === "companion.enabled") return { companion: { enabled: value === "true" } };
+  if (id === "companion.type") return { companion: { type: value } };
+  return null;
+}
+
+/** Publish the input settings screen as a tab, once per extension load. */
+export function registerInputConfiguratorTab(): void {
+  const tab: ConfiguratorTab = {
+    id: "opl-input",
+    hotkey: "i",
+    label: "Input",
+    create: (api) => createInputComponent(api),
+  };
+
+  const holder = globalThis as Record<string, unknown>;
+  const registry = holder[CONFIGURATOR_REGISTRY_KEY];
+  if (Array.isArray(registry)) {
+    const index = registry.findIndex((entry) => entry?.id === "opl-input");
+    if (index === -1) registry.push(tab);
+    else registry[index] = tab;
+  } else {
+    holder[CONFIGURATOR_REGISTRY_KEY] = [tab];
+  }
+}
+
+function createInputComponent(api: ConfiguratorTabApi): ConfiguratorTabComponent {
+  const { ctx, theme, done } = api;
+  let config = readInputConfig();
+  let settingsList: SettingsList | null = null;
+
+  const createSettingsList = (): SettingsList => {
+    const companion = companionRecord(config);
+    const boxedView = typeof config.boxedView === "boolean" ? config.boxedView : true;
+    const enabled = typeof companion.enabled === "boolean" ? companion.enabled : false;
+    const currentType = typeof companion.type === "string" && companion.type.length > 0 ? companion.type : "cat";
+
+    const typeValues = companionTypeValues(config);
+
+    const items: SettingItem[] = [
+      { id: "boxedView", label: "Boxed view", currentValue: boxedView ? "true" : "false", values: ["true", "false"] },
+      { id: "companion.enabled", label: "Companion", currentValue: enabled ? "true" : "false", values: ["true", "false"] },
+      { id: "companion.type", label: "Companion type", currentValue: currentType, values: typeValues },
+    ];
+
+    return new SettingsList(items, items.length, getSettingsListTheme(), save, () => done(undefined));
+  };
+
+  const save = (id: string, value: string) => {
+    const patch = inputFieldPatch(id, value);
+    if (!patch) return; // never misroute an unexpected id into companion.type
+
+    try {
+      const changed = saveInputConfig(patch);
+      if (changed) {
+        config = readInputConfig();
+        settingsList = createSettingsList();
+        settingsList.selectItem(id);
+        ctx.ui.notify("opl-input saved. Run /reload (or restart Pi) to apply.", "info");
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Could not save opl-input config: ${message}`, "error");
+      done(undefined);
+    }
+  };
+
+  settingsList = createSettingsList();
+
+  return {
+    render(width: number) {
+      return [
+        truncateToWidth(theme.bold("Configure OPL Input"), width),
+        truncateToWidth(theme.fg("dim", "Reload (/reload) is required for changes to apply"), width),
+        ...(settingsList ?? createSettingsList()).render(width),
+      ];
+    },
+    invalidate() { settingsList?.invalidate(); },
+    handleInput(data: string) { settingsList?.handleInput?.(data); },
+  };
+}