@rol1n/pi-kit 0.0.0-stage → 0.1.0

package/extensions/memory-log/ui/timeline.ts

@@ -0,0 +1,103 @@
+import type { Config } from "../config.ts";
+import {
+  entryIndexById,
+  foldLedger,
+  isObservationsRecordedEntry,
+  rawTokensAfterIndex,
+  rawTokensSinceObservationCoverage,
+  type Entry,
+} from "../ledger/index.ts";
+
+/** Glyphs for the timeline strip. */
+const GLYPH = {
+  consolidated: "▓", // observations promoted to .memory (long-term)
+  partial: "▚",      // chunk straddling the pool-target boundary (some obs promoted)
+  pool: "▒",         // observed, still in the short-term buffer
+  raw: "░",          // raw history not yet distilled into observations
+  cut: "┊",          // compaction cutoff (verbatim tail began here)
+  tip: "▶",          // live branch tip
+} as const;
+
+/** A committed observation chunk, in branch order. */
+type Chunk = { coversUpToIndex: number; timestamps: string[] };
+
+function fmtK(tokens: number): string {
+  if (tokens < 1000) return `${tokens}`;
+  return `${(tokens / 1000).toFixed(1)}k`;
+}
+
+function collectChunks(branch: Entry[]): Chunk[] {
+  const indexById = entryIndexById(branch);
+  const chunks: Chunk[] = [];
+  for (const entry of branch) {
+    if (!isObservationsRecordedEntry(entry)) continue;
+    const coversUpToIndex = indexById.get(entry.data.coversUpToId);
+    if (coversUpToIndex === undefined) continue;
+    chunks.push({ coversUpToIndex, timestamps: entry.data.observations.map((o) => o.timestamp) });
+  }
+  return chunks;
+}
+
+/** Branch indices of every compaction entry's `firstKeptEntryId` (the verbatim-tail cutoffs). */
+function compactionCutIndices(branch: Entry[]): number[] {
+  const indexById = entryIndexById(branch);
+  const cuts: number[] = [];
+  for (const entry of branch) {
+    if (entry.type !== "compaction") continue;
+    const idx = entry.firstKeptEntryId ? indexById.get(entry.firstKeptEntryId) : undefined;
+    if (idx !== undefined) cuts.push(idx);
+  }
+  return cuts;
+}
+
+function chunkGlyph(chunk: Chunk, dropped: Set<string>): string {
+  let droppedCount = 0;
+  for (const ts of chunk.timestamps) if (dropped.has(ts)) droppedCount++;
+  if (droppedCount === 0) return GLYPH.pool;
+  if (droppedCount === chunk.timestamps.length) return GLYPH.consolidated;
+  return GLYPH.partial;
+}
+
+function wrap(cells: string[], width: number): string {
+  if (cells.length === 0) return "";
+  const rows: string[] = [];
+  for (let i = 0; i < cells.length; i += width) rows.push(cells.slice(i, i + width).join(""));
+  return rows.join("\n");
+}
+
+/**
+ * Render the full session as a horizontal strip.
+ */
+export function renderTimeline(branch: Entry[], config: Config, width = 60): string {
+  const folded = foldLedger(branch);
+  const dropped = folded.droppedObservationTimestamps;
+  const chunks = collectChunks(branch);
+
+  const cells: string[] = chunks.map((chunk) => chunkGlyph(chunk, dropped));
+  const tailTokens = rawTokensSinceObservationCoverage(branch);
+  const tailCells = tailTokens > 0 ? Math.ceil(tailTokens / config.chunkTokens) : 0;
+  for (let i = 0; i < tailCells; i++) cells.push(GLYPH.raw);
+
+  const cutPositions = compactionCutIndices(branch)
+    .map((cutIdx) => {
+      let pos = 0;
+      for (const chunk of chunks) if (chunk.coversUpToIndex < cutIdx) pos++;
+      return Math.min(pos, cells.length);
+    })
+    .sort((a, b) => b - a);
+  for (const pos of cutPositions) cells.splice(pos, 0, GLYPH.cut);
+
+  const consolidatedChunks = chunks.filter((c) => chunkGlyph(c, dropped) === GLYPH.consolidated).length;
+  const poolChunks = chunks.filter((c) => chunkGlyph(c, dropped) === GLYPH.pool).length;
+  const rawTotal = rawTokensAfterIndex(branch, -1);
+  const compactions = cutPositions.length;
+
+  const strip = cells.length > 0 ? `${wrap(cells, width)}${GLYPH.tip}` : "(timeline empty)";
+
+  return [
+    `memory-log timeline · 1 cell ≈ ${fmtK(config.chunkTokens)} tok · cumulative ${fmtK(rawTotal)} raw · ${compactions} compaction${compactions === 1 ? "" : "s"}`,
+    strip,
+    ``,
+    `  ${GLYPH.consolidated} .memory (${consolidatedChunks})   ${GLYPH.pool} pool (${poolChunks})   ${GLYPH.raw} raw   ${GLYPH.cut} compaction cut   ${GLYPH.tip} tip`,
+  ].join("\n");
+}

package/extensions/model-vision/README.md

@@ -0,0 +1,28 @@
+# model-vision
+
+Analyze a local image or public image URL with a vision model. Registers the `model_vision` tool for OCR, UI inspection, and image questions.
+
+## Install
+
+```sh
+pi install npm:@rol1n/model-vision
+```
+
+Available independently; it is not enabled in the aggregate package by default. The extension entrypoint is `extensions/model-vision/index.ts`; `analysis.ts` coordinates image loading (`image.ts`), network validation (`network.ts`), and model requests (`requests.ts`).
+
+## Use
+
+```json
+{
+  "image": "./screenshots/error.png",
+  "prompt": "Read the error message and describe the relevant UI."
+}
+```
+
+Supported image formats are PNG, JPEG, WebP, GIF, and BMP. Local paths resolve from the working directory. Remote images must use public HTTP(S) addresses; private-network targets are rejected. Images are limited to 10 MiB and requests have a 90-second timeout.
+
+## Model configuration
+
+The current fallback chain is declared in `DEFAULT_VISION_MODELS` in `extensions/model-vision/models.ts`: Antigravity `gemini-3.8-flash` through Pi's native API, followed by SHUAI API `gpt-6-luna` through OpenAI completions. Change that source list to choose a different chain; there is currently no settings key or tool argument for choosing the vision model.
+
+Install and authenticate the provider integrations you select. Antigravity is an external integration; SHUAI registration is available in [custom-providers](https://github.com/RolinShmily/pi-kit/tree/main/extensions/custom-providers). The tool returns extracted text and the provider/model used.

package/extensions/multi-harness/README.md

@@ -0,0 +1,63 @@
+# Multi Harness
+
+A small delegation runtime with one tool, `multi_harness`. `pi`, `codex`, `claude`, and `opencode` are equal CLI peers. The original `subagent` extension remains a separate, lean Pi-only tool.
+
+The runtime accepts **one named worker and an existing cwd**. Those decisions belong to the caller. An independently installed `worktree-studio` skill can coordinate isolated implementations and their acceptance review.
+
+## Install
+
+```sh
+pi install npm:@rol1n/multi-harness
+```
+
+Also included in `@rol1n/pi-kit`. Enable one copy of the extension.
+
+## Use
+
+Load `extensions/multi-harness` through the aggregate package, or run from this repository:
+
+```sh
+pi --no-extensions -e ./extensions/multi-harness/index.ts
+```
+
+Example tool calls:
+
+```json
+{"action":"spawn","name":"reviewer","harness":"claude","cwd":"/existing/project","task":"Review error handling without changing files. Report concrete findings with file paths."}
+{"action":"spawn","name":"implementer","harness":"pi","cwd":"/existing/other-directory","task":"Implement the approved fix and run the specified checks.","model":"provider/model"}
+{"action":"spawn","name":"opencode-reviewer","harness":"opencode","cwd":"/existing/project","task":"Review the changes and report evidence without editing files."}
+{"action":"send","target":"reviewer","task":"Review the revised implementation in the same session."}
+{"action":"status"}
+{"action":"stop","target":"implementer"}
+{"action":"close","target":"reviewer"}
+```
+
+- `spawn` is the default action; `name`, `harness`, and `task` are required. `cwd` defaults to the parent directory and must already exist. Names are reserved for the session, including after closing.
+- `model` is optional and passed to the selected CLI. Pi defaults to the parent model; external CLIs use their installed defaults. Only the selected executable is checked on demand.
+- `spawn` and `send` return after dispatch. **Turn completion is pushed to the real parent Pi session via `pi.sendMessage`**, not by a background wrapper writing a log. Do not poll terminals or run waiting shell loops.
+- With tmux/Zellij, each worker runs its **native interactive TUI**. Turn settlement leaves the application open and idle. `send` continues that same application; `close` exits idle TUIs. `stop` terminates active work and its runtime, preserving files.
+- Without a supported mux, workers use silent child processes. `send` starts another invocation that resumes the same persisted CLI session. Set `PI_MULTI_HARNESS_BACKEND=process` to force this fallback. This is not a live TUI in headless mode.
+- Pi follow-ups use a file inbox and native `pi.sendUserMessage`. OpenCode uses a local server plugin, its native SDK inbox, and the same visible TUI session (no key injection). Codex uses its reported thread ID with `codex queue`; when no ID is available, mux input uses bracketed paste. Claude uses idle-only bracketed paste. Avoid simultaneous human typing and coordinator dispatch; startup trust/permission dialogs may require manual attention. Zellij input transport still requires validation with your installed Zellij/terminal build.
+
+## Notifications and state
+
+Artifacts live in `~/.pi/agent/multi-harness/<worker-id>/`: task prompts, CLI session data/IDs, console/event logs in process mode, completion records, and short TUI screen captures. Working files remain in the caller's `cwd`. No automatic Git report is generated.
+
+`harness-done "summary"` is injected into the worker PATH; `studio-done` is a compatibility alias. It records a proposed summary, **not an early completion event**. Native Codex/Claude hooks, OpenCode's root-session idle events, Pi's `agent_settled`, or the headless process exit publish the authoritative completion. This avoids racing a still-running CLI or notifying twice. Every dispatch has a task ID; stale and duplicate completions are ignored.
+
+The parent subscribes to directory `fs.watch` events, with no periodic terminal capture or completion polling. Screen capture happens once per completed turn. Watcher failures are surfaced rather than silently claiming delivery. A worker's final text is a claim: independently review its files and test results.
+
+Default turn timeout: 15 minutes (`maxMinutes`: 1–120). Headless workers are stopped on timeout. A native TUI stays open and cannot receive a new dispatch until it settles or is stopped. Timeouts do not cap tokens or spending; missing usage/pricing is not zero cost.
+
+Session entries record only worker artifact locations. On session restore/reload, the extension reattaches notification watchers for saved workers. A `controller.lock` prevents another session from controlling the same worker concurrently. After an unclean crash, verify the recorded owner PID is no longer running before manually removing that lock. Normal shutdown releases watchers/locks and stops active tasks; idle TUIs remain open and can be recovered by resuming the parent session.
+
+## Permissions and platform boundaries
+
+- This tool dispatches directly; user confirmation for expensive or risky workflows belongs to the caller/skill. It is not a sandbox.
+- Per the configured workflow, Codex runs with `--sandbox danger-full-access -a never`, and Claude with `--permission-mode bypassPermissions`. Workers have the invoking user's filesystem/network privileges. Headless Claude has a $0.50 CLI API budget; interactive mode does not impose that limit. Use only in trusted environments.
+- OpenCode uses `--auto`: automatically approve requests not explicitly denied by its configuration. Existing deny rules remain effective. Native mode injects the dependency-free local `opencode-plugin.mjs` through a merged `OPENCODE_CONFIG_CONTENT`; it never edits project/global config files or installs packages. Existing content must be valid JSON. Headless mode uses `opencode run --format json` and resumes by the exact reported `--session` ID. The adapter targets the OpenCode 1.x CLI/plugin API (source-checked against v1.19.3); 2.x API compatibility is not assumed. Install and authenticate the CLI yourself. DeepSeek Harness (`dsh`) is not integrated.
+- Pi's project-resource trust flags apply only to loading project resources, not filesystem access. A different cwd does not inherit the parent's project trust automatically.
+- Windows requires PowerShell 7 (`pwsh`) for external CLI invocation. Encoded PowerShell commands preserve Unicode, multiline tasks, JSON, and quoted paths. CLI hooks and `harness-done.cmd`/`.ps1` wrappers use the same native Windows Node installation. A mux must be available for visible TUIs; otherwise process fallback applies.
+- Existing worktrees, reports, and sessions created by the removed `worktree-studio` extension are left untouched. Its old `the_road_not_taken` tool and two-route manifests are not imported into this runtime. Synchronize platform resources/reload before using the new tool; old running workers should be finished before upgrading.
+
+Validation scripts are kept outside the repository. Check extension loading from this repository with `pi --no-extensions -e ./extensions/multi-harness/index.ts --list-models '<filter>'`.

package/extensions/multi-harness/adapters.mjs

@@ -0,0 +1,72 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const HARNESSES = Object.freeze(["pi", "codex", "claude", "opencode"]);
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+export const quotePs = (value) => `'${value.replaceAll("'", "''")}'`;
+const quoteSh = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+
+/** Avoid cmd/npm shim argument re-parsing and preserve Unicode and JSON on Windows. */
+export function commandSpec(argv, platform = process.platform) {
+  if (platform !== "win32") return { command: argv[0], args: argv.slice(1) };
+  const script = `$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); & ${argv.map(quotePs).join(" ")}; if ($null -eq $LASTEXITCODE) { exit 1 }; exit $LASTEXITCODE`;
+  return { command: "pwsh", args: ["-NoProfile", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")] };
+}
+
+/** Add a dependency-free local plugin for native OpenCode only; never rewrite user config. */
+export function buildEnv(config, inherited = process.env) {
+  if (config.harness !== "opencode" || !config.interactive) return inherited;
+  let content;
+  try { content = inherited.OPENCODE_CONFIG_CONTENT ? JSON.parse(inherited.OPENCODE_CONFIG_CONTENT) : {}; }
+  catch { throw new Error("OPENCODE_CONFIG_CONTENT must be valid JSON to append the multi-harness plugin."); }
+  if (!content || typeof content !== "object" || Array.isArray(content) || (content.plugin !== undefined && !Array.isArray(content.plugin))) {
+    throw new Error("OpenCode config must be an object with an optional plugin array.");
+  }
+  const plugin = pathToFileURL(join(extensionDir, "opencode-plugin.mjs")).href;
+  return { ...inherited, PI_MULTI_HARNESS_CWD: config.cwd,
+    OPENCODE_CONFIG_CONTENT: JSON.stringify({ ...content, plugin: [...(content.plugin ?? []).filter((item) => item !== plugin), plugin] }) };
+}
+
+export function buildArgs(config) {
+  const { harness, cwd, prompt, sessionFile, model, trusted, artifactDir, interactive, resume, sessionId } = config;
+  const modelArgs = model ? ["--model", model] : [];
+  switch (harness) {
+    case "pi":
+      return ["pi", ...(interactive ? ["--tui-mode", "regular", "-e", join(extensionDir, "worker-bridge.ts")] : ["--print"]),
+        trusted ? "--approve" : "--no-approve", "--session", sessionFile, ...modelArgs, prompt];
+    case "codex": {
+      const base = ["codex", "--sandbox", "danger-full-access", "-a", "never"];
+      if (interactive) {
+        const hook = JSON.stringify([process.execPath, join(extensionDir, "turn-hook.mjs"), artifactDir, "codex"]);
+        return [...base, "--cd", cwd, ...modelArgs, "-c", `notify=${hook}`, prompt];
+      }
+      return [...base, "exec", ...(resume ? ["resume", sessionId] : ["--cd", cwd]), "--skip-git-repo-check", "--json", ...modelArgs, "-"];
+    }
+    case "claude": {
+      const base = ["claude", "--permission-mode", "bypassPermissions", ...modelArgs];
+      if (interactive) {
+        const hook = (kind) => {
+          const args = [process.execPath, join(extensionDir, "turn-hook.mjs"), artifactDir, kind];
+          // Claude command hooks use a shell, not necessarily the interactive pane's shell.
+          if (process.platform === "win32") {
+            const script = `& ${args.map(quotePs).join(" ")}; exit $LASTEXITCODE`;
+            return `pwsh -NoProfile -EncodedCommand ${Buffer.from(script, "utf16le").toString("base64")}`;
+          }
+          return args.map(quoteSh).join(" ");
+        };
+        const settings = { hooks: {
+          UserPromptSubmit: [{ hooks: [{ type: "command", command: hook("claude-start"), timeout: 10 }] }],
+          Stop: [{ hooks: [{ type: "command", command: hook("claude"), timeout: 10 }] }],
+        } };
+        return [...base, "--session-id", sessionId, "--settings", JSON.stringify(settings), prompt];
+      }
+      return [...base, "-p", "--verbose", "--output-format", "stream-json", "--max-budget-usd", "0.50",
+        ...(resume ? ["--resume", sessionId] : ["--session-id", sessionId])];
+    }
+    case "opencode":
+      return interactive
+        ? ["opencode", cwd, "--auto", ...modelArgs, "--prompt", prompt]
+        : ["opencode", "run", "--dir", cwd, "--format", "json", "--auto", ...modelArgs, ...(resume ? ["--session", sessionId] : [])];
+    default: throw new Error(`Unsupported harness: ${harness}`);
+  }
+}

package/extensions/multi-harness/harness-done.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { join } from "node:path";
+import { readJson, writeJson } from "./ipc.mjs";
+
+const directory = process.env.PI_MULTI_HARNESS_DIR;
+if (!directory) throw new Error("harness-done must run inside a multi_harness worker.");
+const request = readJson(join(directory, "request.json"));
+if (!request) throw new Error("No task is assigned to this worker.");
+writeJson(join(directory, "proposal.json"), {
+  id: request.id,
+  summary: process.argv.slice(2).join(" ").trim() || "Task finished; inspect the artifacts for verification.",
+  at: Date.now(),
+});
+console.log("Summary recorded. The coordinator will be notified when this turn settles; keep the TUI open.");