@tt-a1i/openpi 0.1.0

package/extensions/workflows/worktree-handoff.ts

@@ -0,0 +1,216 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Worktree, WorktreeCleanup } from "../shared/worktree.ts";
+import { writeFileAtomic } from "./serialization.ts";
+
+export const WORKTREE_HANDOFF_VERSION = 1;
+const PATCH_MAX_BYTES = 512 * 1024;
+const MANIFEST_MAX_BYTES = 1024 * 1024;
+const GIT_MAX_BUFFER = PATCH_MAX_BYTES + 64 * 1024;
+const HANDOFF_GIT_TIMEOUT_MS = 5_000;
+
+export interface WorktreeHandoffManifest {
+  readonly version: typeof WORKTREE_HANDOFF_VERSION;
+  readonly runId: string;
+  readonly agentIndex: number;
+  readonly agentLabel: string;
+  readonly repository: string;
+  readonly worktree: string;
+  readonly baseSha: string;
+  readonly headSha: string;
+  readonly branch?: string;
+  readonly detached: boolean;
+  readonly patch: {
+    readonly format: "git-diff-binary";
+    readonly content: string;
+  };
+  readonly numstat: string;
+  readonly nameStatus: string;
+  /** Names only. Their contents are not claimed to be captured by the patch. */
+  readonly untracked: readonly string[];
+  /** Names only. Their contents are not claimed to be captured by the patch. */
+  readonly ignored: readonly string[];
+  readonly cleanup?: WorktreeCleanup;
+}
+
+export type WorktreeHandoffPreparation =
+  | {
+      readonly ok: true;
+      readonly artifact: string;
+      readonly absolutePath: string;
+      readonly manifest: WorktreeHandoffManifest;
+    }
+  | { readonly ok: false; readonly reason: string };
+
+function boundedGit(cwd: string, args: readonly string[], deadline: number) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new Error("Git handoff deadline exceeded");
+  const output = execFileSync("git", ["-c", "core.fsmonitor=false", ...args], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: GIT_MAX_BUFFER,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: Math.min(remaining, HANDOFF_GIT_TIMEOUT_MS),
+  });
+  if (output.includes("\uFFFD")) {
+    throw new Error("Git handoff output is not valid UTF-8");
+  }
+  return output;
+}
+
+function nulPaths(value: string) {
+  if (value.includes("\uFFFD")) {
+    throw new Error("Git path inventory is not valid UTF-8");
+  }
+  return value.split("\0").filter(Boolean).sort();
+}
+
+function boundedError(error: unknown) {
+  const text = error instanceof Error ? error.message : String(error);
+  return text.slice(0, 4096);
+}
+
+function serializeCompleteManifest(manifest: WorktreeHandoffManifest) {
+  const serialized = JSON.stringify(manifest, null, 2);
+  const bytes = Buffer.byteLength(serialized, "utf8");
+  if (bytes > MANIFEST_MAX_BYTES) {
+    throw new Error(
+      `worktree handoff manifest exceeded ${MANIFEST_MAX_BYTES} bytes`,
+    );
+  }
+  return serialized;
+}
+
+/**
+ * Persist the complete tracked Git handoff before cleanup is allowed. A failure
+ * returns `ok:false`; callers must preserve the checkout instead of guessing.
+ */
+export function prepareWorktreeHandoff(options: {
+  runDir: string;
+  runId: string;
+  agentIndex: number;
+  agentLabel: string;
+  repoCwd: string;
+  worktree: Worktree;
+}): WorktreeHandoffPreparation {
+  const deadline = Date.now() + HANDOFF_GIT_TIMEOUT_MS;
+  const git = (cwd: string, args: readonly string[]) =>
+    boundedGit(cwd, args, deadline);
+  try {
+    if (!options.worktree.baseSha) {
+      return { ok: false, reason: "worktree creation baseline is unknown" };
+    }
+    const repository = fs.realpathSync.native(
+      git(options.repoCwd, ["rev-parse", "--show-toplevel"]).trim(),
+    );
+    const worktree = fs.realpathSync.native(options.worktree.path);
+    const common = fs.realpathSync.native(
+      path.resolve(
+        options.repoCwd,
+        git(options.repoCwd, ["rev-parse", "--git-common-dir"]).trim(),
+      ),
+    );
+    if (worktree !== common && !worktree.startsWith(`${common}${path.sep}`)) {
+      return {
+        ok: false,
+        reason: "worktree path escaped the repository Git directory",
+      };
+    }
+
+    const headSha = git(worktree, ["rev-parse", "--verify", "HEAD"]).trim();
+    let branch = "";
+    try {
+      branch = git(worktree, [
+        "symbolic-ref",
+        "--quiet",
+        "--short",
+        "HEAD",
+      ]).trim();
+    } catch {
+      // A detached HEAD is valid, but cleanup will preserve productive ones.
+    }
+    const detached = !branch;
+    let patch: string;
+    try {
+      patch = git(worktree, [
+        "diff",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--binary",
+        options.worktree.baseSha,
+        "--",
+      ]);
+    } catch (error) {
+      return {
+        ok: false,
+        reason: `could not capture bounded binary patch: ${boundedError(error)}`,
+      };
+    }
+    if (Buffer.byteLength(patch, "utf8") > PATCH_MAX_BYTES) {
+      return {
+        ok: false,
+        reason: `binary patch exceeded ${PATCH_MAX_BYTES} bytes`,
+      };
+    }
+
+    const manifest: WorktreeHandoffManifest = {
+      version: WORKTREE_HANDOFF_VERSION,
+      runId: options.runId,
+      agentIndex: options.agentIndex,
+      agentLabel: options.agentLabel,
+      repository,
+      worktree,
+      baseSha: options.worktree.baseSha,
+      headSha,
+      ...(branch ? { branch } : {}),
+      detached,
+      patch: { format: "git-diff-binary", content: patch },
+      numstat: git(worktree, [
+        "diff",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--numstat",
+        options.worktree.baseSha,
+        "--",
+      ]),
+      nameStatus: git(worktree, [
+        "diff",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--name-status",
+        options.worktree.baseSha,
+        "--",
+      ]),
+      untracked: nulPaths(
+        git(worktree, ["ls-files", "--others", "--exclude-standard", "-z"]),
+      ),
+      ignored: nulPaths(
+        git(worktree, [
+          "ls-files",
+          "--others",
+          "--ignored",
+          "--exclude-standard",
+          "-z",
+        ]),
+      ),
+    };
+    // An inventory is not a content backup. Cleanup will preserve these trees,
+    // and the manifest says exactly what was not captured.
+    const artifact = path.join("worktrees", `agent-${options.agentIndex}.json`);
+    const absolutePath = path.join(options.runDir, artifact);
+    writeFileAtomic(absolutePath, serializeCompleteManifest(manifest));
+    return { ok: true, artifact, absolutePath, manifest };
+  } catch (error) {
+    return { ok: false, reason: boundedError(error) };
+  }
+}
+
+export function finalizeWorktreeHandoff(
+  prepared: Extract<WorktreeHandoffPreparation, { ok: true }>,
+  cleanup: WorktreeCleanup,
+) {
+  const manifest = { ...prepared.manifest, cleanup };
+  writeFileAtomic(prepared.absolutePath, serializeCompleteManifest(manifest));
+  return manifest;
+}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@tt-a1i/openpi",
+  "version": "0.1.0",
+  "description": "OpenPI — a Pi-native multi-agent workbench with background execution, isolated subagents, replay-safe workflows, goals, tasks, and observable TUI",
+  "license": "UNLICENSED",
+  "author": "tt-a1i",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "multi-agent",
+    "subagents",
+    "workflows"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tt-a1i/my-pi-setup.git"
+  },
+  "homepage": "https://github.com/tt-a1i/my-pi-setup#readme",
+  "bugs": {
+    "url": "https://github.com/tt-a1i/my-pi-setup/issues"
+  },
+  "files": [
+    "extensions",
+    "!extensions/**/*.test.ts",
+    "!extensions/**/*.spec.ts",
+    "!extensions/**/tsconfig.json",
+    "!extensions/*/docs",
+    "skills",
+    "themes",
+    "assets",
+    "scripts/prepare-effect-tsgo.mjs",
+    "README.md",
+    "SETUP.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "themes": [
+      "./themes"
+    ],
+    "image": "https://raw.githubusercontent.com/tt-a1i/my-pi-setup/main/assets/openpi-package.png"
+  },
+  "dependencies": {
+    "@effect/platform-node": "^4.0.0-beta.99",
+    "acorn": "^8.17.0",
+    "effect": "^4.0.0-beta.99"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
+    "@effect/tsgo": "^0.24.2",
+    "@effect/vitest": "^4.0.0-beta.99",
+    "@types/node": "^26.1.1",
+    "prettier": "^3.9.5",
+    "typebox": "^1.3.6",
+    "typescript": "^7.0.2",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run format:check && npm run check && npm test",
+    "check": "tsc --noEmit",
+    "prepare": "node scripts/prepare-effect-tsgo.mjs",
+    "format": "prettier --write \"extensions/**/*.{ts,cjs}\" \"scripts/**/*.{js,mjs,cjs,ts}\" \".github/**/*.{yml,yaml}\" \"*.json\"",
+    "format:check": "prettier --check \"extensions/**/*.{ts,cjs}\" \"scripts/**/*.{js,mjs,cjs,ts}\" \".github/**/*.{yml,yaml}\" \"*.json\"",
+    "test": "node --test --experimental-strip-types extensions/*/*.test.ts && vitest run extensions/file-search/index.spec.ts"
+  }
+}

package/scripts/prepare-effect-tsgo.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+let cli;
+try {
+  cli = fileURLToPath(import.meta.resolve("@effect/tsgo/dist/effect-tsgo.js"));
+} catch (error) {
+  if (error?.code === "ERR_MODULE_NOT_FOUND") process.exit(0);
+  throw error;
+}
+
+const result = spawnSync(process.execPath, [cli, "patch"], {
+  stdio: "inherit",
+});
+if (result.error) throw result.error;
+process.exit(result.status ?? 1);

package/skills/background-terminals/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: background-terminals
+description: Run and manage long-lived shell commands in background terminals. Use for dev servers, watchers, streaming builds, and other commands that should keep running while the agent continues working.
+---
+
+# Background Terminals
+
+Use `bg_start` for long-running commands; use regular `bash` for quick commands.
+
+## Start
+
+Call `bg_start` with:
+
+- `command`: shell command to run
+- `title`: short recognizable label
+- `working_dir`: project directory when different from the current directory
+- `timeout_seconds`: optional deadline for finite work such as builds, tests, or migrations; omit for servers and watchers
+
+Background commands receive no stdin. Never use them for interactive prompts.
+
+After starting, continue useful work instead of polling. The terminal sends one completion message when it exits or times out.
+
+## Inspect and stop
+
+- Use `bg_status` only when current output or status is needed.
+- Use `bg_list` to inventory all tracked terminals.
+- Use `bg_kill` when a process is no longer needed or is stuck; termination continues even if the tool wait is aborted.
+- Tell the user they can open `/ps` to inspect live output and kill terminals interactively.
+
+Prefer meaningful titles and avoid starting duplicate servers or watchers. Full output is captured to spill files; tool and completion output shows a concise tail. Terminals are session-scoped and are stopped during shutdown or reload.

package/skills/subagents/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: subagents
+description: Invoke this skill when the user asks to use subagents or when a substantial, self-contained task can run independently in the background.
+---
+
+# Subagents
+
+The tool definitions are canonical for parameters, limits, model syntax, isolation, and lifecycle commands. This skill governs delegation decisions only.
+
+- Delegate substantial independent work, not a lookup or edit the parent can do directly.
+- Give the child a standalone prompt with paths, constraints, relevant context, and the expected report; it cannot see the parent conversation or ask the user.
+- Inherit the parent model and thinking level by default. Override them only for an explicit user request or concrete task requirement.
+- Prefer a matching agent type when one exists; its tool restriction is enforced. An explicit spawn model or reasoning effort wins, otherwise use the type default then inherit the parent. Types live in `~/.pi/agent/agents/*.md` and, for trusted projects, `.pi/agents/*.md`; see `extensions/subagents/docs/agent-types.md`.
+- Isolate concurrent writers in worktrees according to the `subagent_spawn` schema so they cannot overwrite one checkout or git index. While Plan Mode is active, use only read-only exploration types (or no type); worktree isolation and types narrowed by Plan Mode are rejected.
+- After spawning, continue useful parent work. Let automatic result delivery drive the next turn; block only when the immediate next step truly depends on that result.

package/themes/github-dark-default.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "github-dark-default",
+  "vars": {
+    "bg": "#0d1117",
+    "panel": "#010409",
+    "surface": "#161b22",
+    "border": "#30363d",
+    "borderMuted": "#21262d",
+    "accent": "#2f81f7",
+    "focus": "#1f6feb",
+    "text": "#e6edf3",
+    "muted": "#7d8590",
+    "dim": "#6e7681",
+    "green": "#3fb950",
+    "red": "#f85149",
+    "yellow": "#d29922",
+    "purple": "#d2a8ff",
+    "orange": "#ffa657",
+    "cyan": "#79c0ff",
+    "string": "#a5d6ff",
+    "softGreen": "#7ee787",
+    "softRed": "#ff7b72"
+  },
+  "colors": {
+    "accent": "accent",
+    "border": "border",
+    "borderAccent": "focus",
+    "borderMuted": "borderMuted",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "muted",
+    "dim": "dim",
+    "text": "text",
+    "thinkingText": "muted",
+
+    "selectedBg": "#13233a",
+    "userMessageBg": "surface",
+    "userMessageText": "text",
+    "customMessageBg": "surface",
+    "customMessageText": "text",
+    "customMessageLabel": "accent",
+    "toolPendingBg": "surface",
+    "toolSuccessBg": "surface",
+    "toolErrorBg": "#2b1618",
+    "toolTitle": "accent",
+    "toolOutput": "muted",
+
+    "mdHeading": "cyan",
+    "mdLink": "accent",
+    "mdLinkUrl": "muted",
+    "mdCode": "cyan",
+    "mdCodeBlock": "text",
+    "mdCodeBlockBorder": "border",
+    "mdQuote": "muted",
+    "mdQuoteBorder": "border",
+    "mdHr": "borderMuted",
+    "mdListBullet": "orange",
+
+    "toolDiffAdded": "green",
+    "toolDiffRemoved": "red",
+    "toolDiffContext": "muted",
+
+    "syntaxComment": "#8b949e",
+    "syntaxKeyword": "softRed",
+    "syntaxFunction": "purple",
+    "syntaxVariable": "orange",
+    "syntaxString": "string",
+    "syntaxNumber": "cyan",
+    "syntaxType": "softGreen",
+    "syntaxOperator": "text",
+    "syntaxPunctuation": "dim",
+
+    "thinkingOff": "dim",
+    "thinkingMinimal": "muted",
+    "thinkingLow": "accent",
+    "thinkingMedium": "cyan",
+    "thinkingHigh": "purple",
+    "thinkingXhigh": "softRed",
+
+    "bashMode": "green"
+  },
+  "export": {
+    "pageBg": "bg",
+    "cardBg": "panel",
+    "infoBg": "surface"
+  }
+}