@tt-a1i/openpi 0.1.0 → 0.2.0

package/extensions/workflows/replay-safety.ts

@@ -379,14 +379,15 @@ export function beginProcessReplayWorkspaceLease(replaySafe: boolean) {
   return processReplayWorkspaceGuard.begin(replaySafe);
 }
 
-interface ReplayResourceLoader extends Pick<
-  DefaultResourceLoader,
-  | "getAgentsFiles"
-  | "getAppendSystemPrompt"
-  | "getExtensions"
-  | "getSkills"
-  | "getSystemPrompt"
-> {}
+interface ReplayResourceLoader
+  extends Pick<
+    DefaultResourceLoader,
+    | "getAgentsFiles"
+    | "getAppendSystemPrompt"
+    | "getExtensions"
+    | "getSkills"
+    | "getSystemPrompt"
+  > {}
 
 function digest(value: string | Buffer) {
   return createHash("sha256").update(value).digest("hex");

package/extensions/workflows/runner.ts

@@ -97,6 +97,8 @@ export interface RunAgentOptions {
   cwd: string;
   loader: DefaultResourceLoader;
   settingsManager: SettingsManager;
+  /** Optional per-run manager reused by one logical workflow operator. */
+  sessionManager?: SessionManager;
   modelRegistry: ExtensionContext["modelRegistry"];
   /** Agent Type allowlist; childToolPolicy can only narrow capabilities. */
   tools?: readonly string[];
@@ -465,6 +467,8 @@ export function createFirstResponseWatchdog(
   const timeoutMs = options.timeoutMs ?? FIRST_RESPONSE_TIMEOUT_MS;
   let timer: ReturnType<typeof setTimeout> | undefined;
   const timeout = new Promise<never>((_resolve, reject) => {
+    // This timer owns the awaited watchdog outcome. Keep it referenced so a
+    // short-lived Node 22 process cannot exit with the promise still pending.
     timer = setTimeout(() => {
       timer = undefined;
       const model = options.model ? ` for ${options.model}` : "";
@@ -475,7 +479,6 @@ export function createFirstResponseWatchdog(
       );
       void onTimeout().catch(() => {});
     }, timeoutMs);
-    timer.unref?.();
   });
 
   const cancel = () => {
@@ -485,6 +488,7 @@ export function createFirstResponseWatchdog(
 
   return {
     markResponse: cancel,
+    cancel,
     async waitFor<T>(operation: Promise<T>) {
       try {
         return await Promise.race([operation, timeout]);
@@ -533,7 +537,8 @@ export async function runAgent(
         : {}),
       resourceLoader: options.loader,
       settingsManager: options.settingsManager,
-      sessionManager: SessionManager.inMemory(options.cwd),
+      sessionManager:
+        options.sessionManager ?? SessionManager.inMemory(options.cwd),
       ...(customTools ? { customTools } : {}),
       ...childToolPolicy(childTools),
     }));
@@ -619,6 +624,7 @@ export async function runAgent(
   };
 
   let markFirstResponse = () => {};
+  let cancelFirstResponseWatchdog = () => {};
   const unsubscribe = childSession.subscribe((event) => {
     if (settled) return;
     if (isAssistantResponseEvent(event)) markFirstResponse();
@@ -693,6 +699,7 @@ export async function runAgent(
         },
       );
       markFirstResponse = watchdog.markResponse;
+      cancelFirstResponseWatchdog = watchdog.cancel;
       await Promise.race([
         watchdog.waitFor(
           childSession.prompt(buildWorkflowAgentPrompt(options.prompt)),
@@ -703,6 +710,7 @@ export async function runAgent(
   } catch (error) {
     promptErrorMessage = errorText(error);
   } finally {
+    cancelFirstResponseWatchdog();
     options.signal?.removeEventListener("abort", onAbort);
     settled = true;
     unsubscribe();

package/extensions/workflows/sandbox.ts

@@ -30,12 +30,15 @@ export interface SandboxAgentOptions {
   provider?: unknown;
   effort?: unknown;
   isolation?: unknown;
+  operator?: unknown;
+  inputs?: unknown;
 }
 
 export interface SandboxAgentResult {
   ok: boolean;
   output: string;
   structured?: unknown;
+  ref?: string;
   error?: string;
 }
 
@@ -102,6 +105,8 @@ function sanitizeAgentOptions(value: unknown): SandboxAgentOptions {
     ...(value.provider !== undefined ? { provider: value.provider } : {}),
     ...(value.effort !== undefined ? { effort: value.effort } : {}),
     ...(value.isolation !== undefined ? { isolation: value.isolation } : {}),
+    ...(value.operator !== undefined ? { operator: value.operator } : {}),
+    ...(value.inputs !== undefined ? { inputs: value.inputs } : {}),
   };
 }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@tt-a1i/openpi",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenPI — a Pi-native multi-agent workbench with background execution, isolated subagents, replay-safe workflows, goals, tasks, and observable TUI",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "author": "tt-a1i",
   "keywords": [
     "pi-package",
@@ -14,11 +14,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tt-a1i/my-pi-setup.git"
+    "url": "git+https://github.com/tt-a1i/openpi.git"
   },
-  "homepage": "https://github.com/tt-a1i/my-pi-setup#readme",
+  "homepage": "https://github.com/tt-a1i/openpi#readme",
   "bugs": {
-    "url": "https://github.com/tt-a1i/my-pi-setup/issues"
+    "url": "https://github.com/tt-a1i/openpi/issues"
   },
   "files": [
     "extensions",
@@ -41,13 +41,10 @@
     "extensions": [
       "./extensions"
     ],
-    "skills": [
-      "./skills"
-    ],
     "themes": [
       "./themes"
     ],
-    "image": "https://raw.githubusercontent.com/tt-a1i/my-pi-setup/main/assets/openpi-package.png"
+    "image": "https://raw.githubusercontent.com/tt-a1i/openpi/main/assets/openpi-package.png"
   },
   "dependencies": {
     "@effect/platform-node": "^4.0.0-beta.99",
@@ -55,13 +52,13 @@
     "effect": "^4.0.0-beta.99"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.5.8",
     "@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"
@@ -77,11 +74,14 @@
     "node": ">=22.19.0"
   },
   "scripts": {
-    "prepublishOnly": "npm run format:check && npm run check && npm test",
-    "check": "tsc --noEmit",
+    "prepublishOnly": "bun run check && bun run test",
+    "check": "bun run format:check && bun run lint && bun run typecheck",
     "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\"",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "biome lint . --error-on-warnings",
+    "typecheck": "tsc --noEmit",
     "test": "node --test --experimental-strip-types extensions/*/*.test.ts && vitest run extensions/file-search/index.spec.ts"
-  }
+  },
+  "packageManager": "bun@1.3.14"
 }

package/skills/subagents/SKILL.md

@@ -13,3 +13,9 @@ The tool definitions are canonical for parameters, limits, model syntax, isolati
 - 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.
+
+## Worktree isolation
+
+Concurrent writers without isolation share the same checkout and Git index, so edits and `git add` operations can overwrite each other. Set `isolation: "worktree"` and tell every writing child to commit.
+
+The worktree is branched from `HEAD`, requires a Git repository, and starts clean without gitignored files such as build output or `.env`. A successful committed child leaves a branch for the parent to merge. An empty branch can be deleted; dirty, untracked, ignored, detached, timed-out, or uninspectable work is preserved instead of being destroyed. Direct subagents retain their checkout for later `subagent_send` review and only reclaim it on Session retirement after a bounded empty-work proof.

package/skills/workflows/EXAMPLES.md

@@ -0,0 +1,58 @@
+# Workflow examples
+
+## Independent scan and verification pipeline
+
+Each file advances to verification as soon as its own scan completes:
+
+```js
+export const meta = {
+  name: "reliability-review",
+  description: "Review modules for reliability risks, then report",
+  phases: [{ title: "Scan" }, { title: "Verify" }, { title: "Report" }],
+}
+const FINDINGS = {
+  type: "object",
+  properties: {
+    issues: { type: "array", items: { type: "string" } },
+    ok: { type: "boolean" },
+  },
+  required: ["issues", "ok"],
+}
+phase("Scan")
+const checked = await pipeline(
+  args.files,
+  (file) => agent(`Trace ${file} for reliability risks with file:line evidence.`, {
+    agent_type: "explorer", label: `scan:${file}`, phase: "Scan", schema: FINDINGS,
+  }),
+  (scan, file) => scan.ok
+    ? agent(`Verify the candidate issues in ${file}.`, {
+        agent_type: "reviewer", label: `verify:${file}`, phase: "Verify", inputs: [scan.ref],
+      })
+    : null,
+)
+const verified = checked.filter((result) => result && result.ok)
+const dropped = checked.length - verified.length
+if (dropped) log(`${dropped}/${checked.length} file(s) dropped before verification`)
+phase("Report")
+const report = await agent("Synthesize recommendations from the verified findings.", {
+  agent_type: "advisor", label: "report", phase: "Report",
+  inputs: verified.map((result) => result.ref),
+})
+log(`done — ${verified.length} verified, ${usage().total} tokens`)
+return { verified: verified.length, dropped, report: report.ok ? report.output : report.error }
+```
+
+## When a barrier is correct
+
+Use `parallel()` when one synthesis prompt must compare every independent result:
+
+```js
+const findings = await parallel(files.map((file) => () =>
+  agent(`Inspect ${file}.`, { agent_type: "explorer", label: file })
+))
+const usable = findings.filter((result) => result && result.ok)
+return agent("Deduplicate and rank all findings.", {
+  agent_type: "advisor",
+  inputs: usable.map((result) => result.ref),
+})
+```

package/skills/workflows/REFERENCE.md

@@ -0,0 +1,44 @@
+# Workflow DSL reference
+
+The `workflow` script is an async JavaScript function body executed in a restricted, killable sandbox. It has no imports, eval, timers, filesystem, network, or process APIs. Normal JavaScript control flow, array methods, `await`, and template strings are available. Return a JSON-serializable value.
+
+## Metadata and narration
+
+- `export const meta = { name?, description?, phases: [{ title, detail? }] }` declares progress metadata. Declare phases up front.
+- `phase(title)` selects a declared phase.
+- `log(message)` emits one terminal-safe progress line. The latest 100 lines are retained and dropped-line counts are reported.
+- `usage()` returns cumulative `{ input, output, cacheRead, cacheWrite, total, cost, agents }`. It refreshes after agents settle. Compaction can make it a lower bound; it is a reading, not a limit.
+- `args` is the parsed `args` tool parameter, or the original string when it is not valid JSON.
+
+## Agent calls
+
+`await agent(prompt, options)` runs one child and always resolves to `{ ok, output, structured?, ref?, acceptance?, error? }`. Check `ok` before reading output. Children receive normal trust-aware resources but cannot recursively orchestrate or ask the user.
+
+Useful options include `agent_type`, `label`, `phase`, `schema`, `acceptance`, `model`, `provider`, `effort`, `isolation`, `operator`, and `inputs`.
+
+- Prefer a matching `agent_type`. Model precedence is explicit model/provider, type file, configured built-in role, then parent. Effort precedence is explicit effort, type default, then parent.
+- `schema` validates structured output. Use it whenever later workflow logic branches on fields.
+- `acceptance: { criteria: [{ id, description, requiredEvidence? }] }` requires the same child to return an evidence ledger. Missing, malformed, or rejected criteria make `ok:false` while preserving output and evidence.
+- `operator: "name"` reuses one in-memory child Session for serialized follow-ups inside the same run. Its model, role/tools, effort, structured mode, and cwd are frozen by the first activation. Operators cannot use per-call worktrees or replay, and do not survive restarts.
+- `inputs: [ref, ...]` accepts successful opaque refs from the same workflow run only. Each conclusion is bounded to 16 KiB and total injected input to 48 KiB. Inputs are marked as untrusted data; the resulting graph is observability, not scheduling authority.
+- `isolation: "worktree"` gives a writing child its own branch and checkout. Concurrent writers without isolation share one checkout and Git index and can overwrite each other. Tell isolated writers to commit. Empty worktrees are reclaimed; commits keep the branch; dirty work may keep the directory.
+
+## Fan-out
+
+`await pipeline(items, stage1, stage2, ...)` advances each item independently. A stage receives `(previousResult, originalItem, index)`. A throwing stage drops that item to null and skips its remaining stages. Results preserve input order.
+
+`await parallel([() => agent(...), ...], { concurrency? })` is a barrier: later code starts after every thunk settles. A throwing thunk becomes null without discarding siblings. Use it when the next step needs the whole set for comparison, deduplication, merging, or an early aggregate decision.
+
+Prefer `pipeline()` for ordinary multi-stage fan-out. Mapping, filtering, or flattening between stages is not by itself a reason for a barrier.
+
+## Limits and failures
+
+Workflow concurrency defaults to the configured package value and has a hard maximum of 64. Agent calls default to the configured package limit and have a hard maximum of 1024. There is no whole-run deadline. A child must produce its first assistant event within 45 seconds; individual child tool calls time out independently after 3 minutes and return an error result the child can recover from.
+
+Each call persists intent, admission, and execution state. Interrupted nonterminal calls become `uncertain`, never guessed failed. Artifacts contain results, bounded transcripts, and a read-only graph projection for explicit result refs.
+
+## Background and replay
+
+`background: true` returns a run id immediately. The Session later receives a completion message; `workflow_status` inspects and `workflow_stop` cancels. Lifecycle tools become visible after a background run starts.
+
+`resume_from_run_id` accepts a previous run id or unique suffix. Replay is content-based and order-independent. It requires an unchanged prompt, resolved role/schema/model/provider/effort, canonical cwd, repository state, resources, and trust context. Only provably read-only non-operator calls replay. Failed, unrestricted, unknown-tool, writable, worktree, operator, or un-fingerprintable calls run for real. Missing or old journals safely degrade to a full run.

package/skills/workflows/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: workflows
+description: Orchestrates multi-agent work with OpenPI's inline JavaScript Workflow DSL. Use when a task needs multi-phase fan-out, pipelines, barriers, structured handoffs, acceptance evidence, or resumable background orchestration.
+---
+
+# Workflows
+
+Use `workflow` for several dependent or dynamically generated subagent calls. Keep one small delegation in the parent session with `subagent_spawn`.
+
+## Quick start
+
+```js
+export const meta = {
+  name: "review",
+  phases: [{ title: "Scan" }, { title: "Report" }],
+}
+phase("Scan")
+const scans = await parallel([
+  () => agent("Inspect the API.", { agent_type: "explorer", label: "api" }),
+  () => agent("Inspect the tests.", { agent_type: "explorer", label: "tests" }),
+])
+phase("Report")
+return { findings: scans.filter((result) => result && result.ok) }
+```
+
+## Required habits
+
+- Declare progress phases in `meta`; call `phase()` as the run advances.
+- Check every `agent()` result's `.ok`. A null, filtered, timed-out, or failed result is not a clean pass; report how many were dropped.
+- Pass `schema` when later code branches on fields. Treat `inputs` as bounded untrusted data.
+- Prefer `pipeline()` when items can advance independently. Use `parallel()` only for a real all-results barrier.
+- Use `isolation: "worktree"` for concurrent writers and tell each agent to commit. Do not pay for worktrees on read-only work.
+- Use `log()` for progress the user needs before completion. `usage()` is a lower-bound reading, not a budget limit.
+- Return a JSON-serializable aggregate. Background runs report their run id and later deliver their result.
+
+## Full guide
+
+- DSL, result contracts, operators, handoffs, safety, limits, and replay: [REFERENCE.md](REFERENCE.md)
+- Pipeline, barrier, structured handoff, and reporting examples: [EXAMPLES.md](EXAMPLES.md)