pi-config/extensions/pi-crew/docs/research-oh-my-pi-distillation.md

oh-my-pi Distillation for pi-crew

Date: 2026-05-05 Source repo: Source/oh-my-pi at 1d898a7fe chore: bump version to 14.5.3.

Scope Read

Read-only exploration covered four source areas:

• Agent/provider runtime: packages/agent, packages/ai.
• Main CLI/session/task implementation: packages/coding-agent.
• TUI, extensions, hooks, skills, marketplace, rulebook docs and implementation.
• Native/Rust reliability/performance/release docs and implementation.

Representative files and docs inspected:

• packages/agent/src/agent-loop.ts, packages/agent/src/agent.ts, packages/agent/src/types.ts.
• packages/ai/src/stream.ts, packages/ai/src/model-manager.ts, packages/ai/src/utils/{abort,retry,event-stream,overflow}.ts, provider adapters.
• packages/coding-agent/src/session/*, src/extensibility/{hooks,slash-commands,skills,plugins}/*, src/task/*, src/edit/*, prompts.
• packages/tui/src/tui.ts, docs/tui*.md, docs/extensions.md, docs/hooks.md, docs/skills.md, docs/marketplace.md, docs/rulebook-matching-pipeline.md.
• crates/pi-natives/src/{task,shell,pty,fs_cache,glob,fd,grep}.rs, natives docs, install/release scripts.

This document rewrites the useful ideas as pi-crew-native patterns. It does not vendor or copy source code.

High-Value Patterns to Adopt

1. Separate durable run history from provider/model context

oh-my-pi keeps rich internal session messages separate from LLM-compatible provider messages. Custom events, UI messages, hook entries, and branch/compaction entries can live in durable history, while a conversion layer decides what reaches the model.

pi-crew application:

• Keep TeamRunManifest, task records, mailbox messages, artifacts, worker events, and review/verification notes as durable run history.
• Add a projection/conversion step before worker prompt/model invocation:
  • transformRunContextBeforeWorkerStart(...) for pruning/context injection.
  • convertRunHistoryToWorkerPrompt(...) for provider/child-Pi compatible text.
• Avoid treating UI/runtime events as prompt text by default.

Benefit: safer compaction, mailbox summarization, and artifact hygiene without losing durable audit history.

2. Distinguish steering from follow-up

oh-my-pi's agent runtime distinguishes interrupting current work (steer) from continuing after the agent would otherwise stop (followUp).

pi-crew application:

• Model leader/operator messages as two queues:
  • steeringQueue: urgent cancellation, nudge, priority change, user answer while worker is active.
  • followUpQueue: review/verification/documentation after a task reaches a natural stop.
• Default to one-at-a-time delivery to reduce context shock.
• Persist queue entries and delivery status in task mailbox/state.

Benefit: clearer interactive semantics than a single generic respond/resume path.

3. Preserve invariants on cancellation and abort

oh-my-pi propagates AbortSignal through model streaming and tool execution, distinguishes caller abort from provider-local watchdog abort, and emits synthetic tool results when abort happens after tool calls were started.

pi-crew application:

• Use structured cancel reasons:
  • caller_cancelled
  • leader_interrupted
  • provider_timeout
  • worker_timeout
  • tool_timeout
  • shutdown
• If a worker/tool/action has started but is cancelled, emit a terminal synthetic event/result so task history has no dangling operation.
• Add non-abortable cleanup/finalize phases for artifact preservation and state unlock.

Benefit: fewer stuck running tasks and clearer recovery after cancellation.

4. Batch-aware execution with shared vs exclusive operations

oh-my-pi marks tools with concurrency semantics: shared tools can run concurrently, exclusive tools serialize around shared/exclusive peers, and queued tools can be skipped when steering arrives.

pi-crew application:

• Classify worker subtasks or internal operations:
  • shared: read-only exploration, status, grep, artifact reads.
  • exclusive: edits, package manifests, lockfiles, migration/schema updates, worktree merge.
• Attach batchId, index, total, and conflictKey metadata to task execution.
• On new steering, skip not-yet-started low-priority operations with explicit skip reason.

Benefit: safer parallelism and more auditable conflict handling.

5. Intent tracing for destructive/tool actions

oh-my-pi optionally injects an intent field into tool schemas, strips it before execution, and keeps it for auditability.

pi-crew application:

• Add optional _intent/intent metadata to worker tool/action events.
• Require intent for destructive actions: cancel, delete, prune, force cleanup, edits, package publish, worktree removal.
• Store intent in events/artifacts but never pass it to low-level execution APIs if not needed.

Benefit: reviewable why/what for high-risk actions without changing execution payloads.

6. Event-first UI with tiny component contract and coalesced rendering

oh-my-pi TUI uses small components (render(width), handleInput, invalidate) and event-driven, coalesced rendering. Components must be width-safe and lifecycle-clean.

pi-crew application:

• Keep dashboards/widgets as projections from snapshot/event state, not direct filesystem scanners.
• Continue using render scheduler/coalescing; add width-safety tests for all dashboard panes/widgets.
• Components should expose dispose() for timers/theme subscriptions.
• UI event stream should be semantic (task_started, worker_status, mailbox_updated) rather than raw file polling.

Benefit: avoids UI freezes and makes live views predictable.

7. Two-phase extension lifecycle

oh-my-pi extensions have a registration phase where side-effecting runtime methods are unavailable, followed by an initialized phase with real context/actions.

pi-crew application:

• If pi-crew grows plugin/extension support, split APIs into:
  • registerCrewExtension(api): declare teams, workflows, hooks, commands, renderers.
  • initializeCrewExtension(context): subscribe to events, perform side effects.
• In headless mode, UI APIs should be explicit no-ops or unavailable via hasUI.
• Loader should collect extension errors without breaking builtin teams.

Benefit: fewer load-time side effects and safer third-party extensibility.

8. Unified capability inventory/control center

oh-my-pi normalizes extensions, skills, rules, tools, hooks, MCPs, prompts, and slash commands into a shared dashboard model with active/disabled/shadowed states.

pi-crew application:

• Extend /team-settings or add /team-control to show a unified inventory:
  • teams, workflows, agents, skills, hooks/policies, tools, runtime providers.
• Normalize each item to:
  • id, kind, name, description, source, path, state, disabledReason, shadowedBy, raw.
• Persist disables by stable capability ID, not file path.

Benefit: better operator experience for complex multi-resource setups.

9. Hooks as typed lifecycle gates, not ad-hoc shell glue

oh-my-pi hooks cover session lifecycle, before-agent-start, tool-call gates, tool-result transforms, and compaction events. Blocking hooks are scoped; non-blocking hook errors are captured but do not crash streaming.

pi-crew application:

• Define typed crew hooks:
  • before_run_start
  • before_task_start
  • task_result
  • before_cancel
  • before_publish
  • session_before_switch
  • run_recovery
• Mark hooks as blocking or non-blocking.
• Capture hook errors into diagnostics/status, not uncontrolled exceptions.

Benefit: safer customization for policy/security/release gates.

10. Prompt pipeline should be explicit

oh-my-pi applies slash/custom commands, templates, compaction, file mentions, hook injection, and model validation in a clear order before calling the agent.

pi-crew application:

Define a worker prompt pipeline:

1. Parse orchestration command/control intent.
2. Expand prompt templates/task packet.
3. Attach selected context/artifact/mailbox summaries.
4. Run before_worker_start hooks.
5. Persist exact task packet/artifacts.
6. Launch worker.

Benefit: reproducible worker prompts and easier debugging of context injection.

11. Session/run history as append-only tree

oh-my-pi persists session entries with parent relationships. Branching/forking moves the current leaf rather than rewriting past history.

pi-crew application:

• Keep events.jsonl append-only and add optional parentEventId / attemptId / branchId fields for retries/forks.
• Represent retry attempts as child branches from the original task prompt/result.
• Preserve old failed attempts instead of overwriting task state only.

Benefit: better auditability and replay/debug of retries.

12. Cooperative cancellation token for long loops

oh-my-pi native code uses cancel tokens with deadlines, abort signals, heartbeat(), and async wait. Long loops over external-size input must heartbeat at bounded cadence.

pi-crew application:

• Add a TS CancellationToken utility for internal long-running loops:
  • heartbeat(stage?: string)
  • throwIfCancelled()
  • wait()
  • abort(reason)
• Require it in scanners over runs, artifacts, mailboxes, worktrees, and event logs.

Benefit: bounded shutdown/cancel latency and easier stuck-loop diagnostics.

13. Process lifecycle: graceful cancel, forced kill, then non-reuse

oh-my-pi shell/PTY runtime cancels gracefully, waits a grace window, forces abort/kill, drains output for bounded windows, and discards persistent sessions after cancellation/errors.

pi-crew application:

• For child Pi workers:
  • send graceful abort/TERM;
  • wait graceMs;
  • force-kill process tree;
  • drain stdout/stderr for bounded time;
  • mark session non-reusable after timeout/protocol error/cancel.
• Return typed status { exitCode, cancelled, timedOut, killed, cleanupErrors }.

Benefit: more deterministic worker cleanup and fewer zombie/stale runs.

14. Reserve control channel before async worker start

oh-my-pi PTY reserves its control channel before async process start, rejects duplicate starts, and always clears state in completion.

pi-crew application:

• Install a WorkerRunCore/controller synchronously before spawn returns.
• Expose cancel/steer immediately, even while startup is still in progress.
• Clear controller in finally and persist terminal state.

Benefit: closes race windows where operator cannot cancel a starting worker.

15. Cache scan entries, not final query results

oh-my-pi native search caches directory entries and applies query-specific filters/scoring later. Empty stale caches trigger rescan; ordering is deterministic.

pi-crew application:

• For run/artifact/mailbox discovery, cache raw entries/stats rather than final UI results.
• Apply active-status/mailbox/health filters after cache retrieval.
• Invalidate cache after state mutation.
• Use deterministic sort keys for dashboards and summaries.

Benefit: faster UI/status with fewer stale semantic bugs.

16. Blob artifacts and bounded file access

oh-my-pi blob-artifact design uses content addressing, metadata sidecars, streaming writes, size budgets, manifest GC, and path whitelisting.

pi-crew application:

• Introduce content-addressed large artifacts for worker transcripts/screenshots/log chunks.
• Persist metadata sidecars with MIME, source, redaction, run/task IDs, size, hash.
• Keep task prompts/results small by referencing artifact IDs.
• Add GC tied to run retention.

Benefit: avoids bloating task JSON/events and improves artifact security.

17. Native/release verification checklist mindset

oh-my-pi release scripts emphasize multi-platform build artifacts, install smoke tests, spoofed-version checks, and runtime loader fallback diagnostics.

pi-crew application:

• For npm releases, keep a release checklist with:
  • typecheck;
  • unit/integration tests;
  • npm pack --dry-run;
  • install from packed tarball in temp project;
  • Pi extension load smoke;
  • version/tag/npm consistency check.

Benefit: fewer broken published packages.

Skill/Rulebook Ideas to Port

oh-my-pi's skills/rulebook ecosystem suggests additional pi-crew resources:

1. worker-prompt-pipeline skill: prompt assembly, context projection, before-worker hooks, artifact references.
2. typed-hook-design skill: lifecycle gates, blocking vs non-blocking hooks, diagnostics.
3. process-cancellation-contract skill: graceful/force kill, synthetic terminal results, non-reuse.
4. capability-inventory-ux skill: normalized resource inventory and disable/shadow semantics.
5. append-only-run-history skill: event tree, branch/retry provenance.

Prioritized Backlog for pi-crew

P0 / High confidence

• Fix current runtime review findings first: waiting final status, respond semantics, no-registry model routing.
• Add structured cancellation reason and terminal synthetic result/event for cancelled workers.
• Centralize worker prompt pipeline and persist exact prompt packets.
• Add width-safety tests for dashboard/widget lines.

P1 / Medium-term architecture

• Add steering vs follow-up mailbox queues.
• Add typed hook lifecycle for before_task_start, task_result, before_cancel, session_before_switch.
• Add capability inventory model for teams/workflows/agents/skills/hooks/tools.
• Add CancellationToken for long internal loops and scans.

P2 / Larger subsystem work

• Append-only run-history tree with attempt/branch parentage.
• Content-addressed blob artifact store with metadata sidecars and GC.
• Worker process controller installed before spawn; process non-reuse after cancel/protocol error.
• Raw scan-entry cache shared by dashboard/status/artifact lookup.

Anti-Patterns to Avoid

• Building prompts from scattered inline string concatenation without a traceable pipeline.
• Treating UI render as a place to perform heavy filesystem scans.
• Auto-opening modal/right-sidebar UI by default when a compact widget/status line would suffice.
• Dropping queued user-facing results just because session generation changed.
• Cancelling a task without writing a terminal event/result.
• Caching semantic query results that should be recomputed from raw state.
• Letting one bad extension/resource prevent builtin operation.

Immediate Review Questions for Future Implementation

• Should pi-crew project-local skills be allowed to shadow builtin safety skills by default, or require explicit project: namespace?
• Should respond enqueue durable work or only deliver to live workers? Current semantics need to become explicit.
• What is the stable capability ID scheme for teams/workflows/agents/skills/hooks?
• Which hook events should be blocking by default and which should be diagnostic-only?
• What artifact size threshold should trigger blob storage instead of embedding content in task/events JSON?