pi-crew 0.1.51 → 0.2.1

package/docs/research/OH-MY-PI-DEEP-RESEARCH-v14.7.6.md

@@ -1,266 +0,0 @@
-# oh-my-pi Deep Research — v14.7.6 (2026-05-08)
-
-**Pull**: `df07e8a5a..7632117de` (55 files, +906/-249 lines)
-**Scope**: Phân tích toàn diện tất cả modules, đặc biệt new features
-
----
-
-## 🔴 CRITICAL: oh-my-pi là IN-PROCESS, không phải child process
-
-```typescript
-// executor.ts line 961
-const { session } = await createAgentSession({ ... });
-await session.prompt(task, { attribution: "agent" });
-// → Subagent chạy TRONG CÙNG PROCESS với parent!
-// → Parent chết → child chết ngay lập tức (OS guarantee)
-// → KHÔNG cần sentinel, watchdog, hay parent-guard gì cả
-```
-
-**Đây là lý do oh-my-pi không cần orphan cleanup:**
-- oh-my-pi: `Agent` objects in-process → process.exit() = all dead
-- pi-crew: Worker processes separate → need parent-guard
-
-**pi-crew KHÔNG THỂ** đổi sang in-process vì:
-- Extension-based architecture (cannot embed in Pi's process)
-- pi-crew is a Pi extension, not a built-in
-- Must remain child-process for isolation
-
-→ **parent-guard.ts là giải pháp ĐÚNG cho pi-crew**
-
----
-
-## 📦 New Features trong v14.7.x
-
-### 1. `agentsMdSearch` + `workspaceTree` Passthrough
-```typescript
-// sdk.ts - Subagents inherit pre-scanned workspace data
-createAgentSession({
-  agentsMdSearch: resolvedAgentsMdSearch,  // skip re-scan
-  workspaceTree: resolvedWorkspaceTree,     // skip re-scan
-});
-```
-- **Lợi ích**: Subagent startup nhanh hơn (không scan lại filesystem)
-- **pi-crew cần**: Pass `AGENTS.md` content + workspace tree qua env/args
-
-### 2. `loop-limit.ts` — Iteration/Duration Limits
-```typescript
-// /loop 10 hoặc /loop 10m
-parseLoopLimitArgs("10m")  // → { kind: "duration", durationMs: 600_000 }
-parseLoopLimitArgs("3")    // → { kind: "iterations", iterations: 3 }
-
-consumeLoopLimitIteration(limit);  // returns false when exhausted
-isLoopDurationExpired(limit);     // checks duration deadline
-```
-- **Auto-submit**: 800ms delay after each turn, Esc cancels iteration
-- **pi-crew có thể dùng**: Giới hạn số lần agent auto-repeat
-
-### 3. `hideThinkingSummary` trong provider config
-```typescript
-// sdk.ts line 1655
-hideThinkingSummary: settings.get("hideThinkingBlock"),
-```
-- **pi-crew cần**: Pass qua `modelConfig.hideThinkingSummary`
-
-### 4. `rewriteStaticImports()` — ESM trong Code Eval
-```typescript
-// context-manager.ts - Tự động rewrite:
-import { foo } from "bar";  // → const { foo } = await import("bar");
-import * as ns from "x";    // → const ns = await import("x");
-import default from "y";   // → const default = (await import("y")).default;
-```
-- User có thể paste ESM imports verbatim trong code eval
-- **pi-crew chưa có**: JS executor cần integrate
-
-### 5. `openai-completions-compat.ts` — 30+ Provider Handling
-- Handles: Cerebras, Zai, Kilo, DeepSeek V4, Alibaba, Qwen, GitHub Copilot, Zenmux
-- `detectOpenAICompat()` — auto-detect strict mode support
-- `detectStrictModeSupport()` — provider + URL matching
-- **pi-crew nên**: Học cách detect model capabilities từ provider
-
-### 6. `scrubProcessEnv()` — macOS malloc fix
-```typescript
-// procmgr.ts
-export function scrubProcessEnv(): void {
-  delete process.env.MallocStackLogging;
-  delete process.env.MallocStackLoggingNoCompact;
-}
-```
-- Fixes stderr spam từ macOS debug-attach shells
-- **pi-crew nên**: Add vào `child-pi.ts` hoặc `background-runner.ts`
-
-### 7. Fetch URL line selector syntax change
-```
-# TRƯỚC: https://example.com:L50
-# SAU:  https://example.com/:50
-# hoặc:  https://example.com/:50-100
-# hoặc:  https://example.com/:raw
-```
-- **pi-crew nên**: Cập nhật fetch tool để hỗ trợ `:50` thay vì `L50`
-
-### 8. Abort race optimization
-```typescript
-// agent-loop.ts - Single abort race per event
-const abortRacePromise = new Promise<void>(resolve => {
-  abortSignal.addEventListener("abort", () => resolve(), { once: true });
-});
-await Promise.race([iterator.next(), abortRacePromise]);
-```
-- Thay vì add/remove listener cho mỗi event → dùng 1 race promise
-- **pi-crew nên**: Học pattern này cho AbortSignal handling
-
----
-
-## 🎯 Architecture Patterns từ oh-my-pi
-
-### 1. Async Job Delivery (pi-crew đang làm G4)
-```typescript
-// sdk.ts line 938
-await session.sendCustomMessage(
-  { customType: "async-result", content: message, ... },
-  { deliverAs: "followUp", triggerTurn: true }
-);
-```
-- ✅ pi-crew đã làm tương tự trong G4 (`sendCustomMessage` với `deliverAs: "followUp"`)
-
-### 2. Yield Enforcement
-```typescript
-// executor.ts - toolChoice to force yield
-await session.prompt(reminder, {
-  toolChoice: buildNamedToolChoice(["yield"])
-});
-```
-- ✅ pi-crew đã làm trong G6 (setActiveToolsByName trước reminder)
-
-### 3. Semaphore Pattern
-```typescript
-// parallel.ts
-const semaphore = new Semaphore(maxConcurrency);
-await semaphore.acquire();
-// ... do work
-semaphore.release();
-```
-- ✅ pi-crew đã implement trong Phase 6
-
-### 4. mapWithConcurrencyLimit Fail-Fast
-```typescript
-// parallel.ts
-mapWithConcurrencyLimit(tasks, max, runTask, signal);
-```
-- On first error → abort all workers via internal AbortController
-- ✅ pi-crew đã implement fail-fast trong Phase 6
-
-### 5. Session Disposal Timeout
-```typescript
-// executor.ts
-untilAborted(AbortSignal.timeout(5000), () => session.dispose());
-```
-- Drain with timeout → force dispose
-- **pi-crew cần**: Thêm timeout cho session disposal
-
----
-
-## 📊 Parity Update
-
-| Feature | oh-my-pi | pi-crew | Status |
-|---------|----------|---------|--------|
-| In-process execution | ✅ | ❌ (child processes) | pi-crew cần parent-guard |
-| agentsMdSearch passthrough | ✅ | ❌ | Ghi nhớ |
-| workspaceTree passthrough | ✅ | ❌ | Ghi nhớ |
-| Loop limit (/loop) | ✅ | ❌ | Low priority |
-| rewriteStaticImports | ✅ | ❌ | JS executor |
-| hideThinkingSummary | ✅ | ❌ | Model config |
-| Async job delivery | ✅ | ✅ | Done (G4) |
-| Yield enforcement | ✅ | ✅ | Done (G6) |
-| Semaphore fail-fast | ✅ | ✅ | Done (Phase 6) |
-| scrubProcessEnv | ✅ | ❌ | Nice to have |
-| Abort race optimization | ✅ | Partial | Low priority |
-
----
-
-## 🎯 Action Items từ Research Mới
-
-### P0 (Highest Priority)
-1. ✅ **parent-guard.ts** — ĐÃ LÀM, đúng design
-2. ✅ **purgeStaleActiveRunIndex** — ĐÃ LÀM, đúng design
-
-### P1 (High Value)
-3. **scrubProcessEnv()** — Add vào background-runner.ts
-   ```typescript
-   // Remove macOS malloc vars
-   delete process.env.MallocStackLogging;
-   delete process.env.MallocStackLoggingNoCompact;
-   ```
-
-### P2 (Medium Value)
-4. **Fetch URL syntax** — Cập nhật `:50` thay vì `L50`
-5. **rewriteStaticImports** — JS executor enhancement
-
-### P3 (Nice to Have)
-6. **Abort race optimization** — Đã có trong abort-controller
-7. **Loop limit** — Low priority cho pi-crew
-
----
-
-## 🔍 Chi Tiết Kỹ Thuật
-
-### oh-my-pi's Session Architecture (7500-line class!)
-- `#handleAgentEvent` — single handler for all events
-- TTSR (Time-Traveling Stream Rules) — pattern abort + inject
-- Auto-compaction on `agent_end` when context > threshold
-- Auto-retry với exponential backoff + model fallback
-- Streaming edit abort for auto-generated files
-- `#cancelPostPromptTasks()` — cleanup background tasks
-
-### TaskTool Dispatch Flow
-```
-TaskTool.execute(tasks, signal, onUpdate)
-  → discoverAgents(cwd, scope)
-  → resolveIsolationBackend(worktree/fuse/projfs)
-  → for each task:
-     → ensureWorktree/ensureFuseOverlay/ensureProjfsOverlay
-     → createAgentSession()
-     → session.prompt(task, { attribution: "agent" })
-     → waitForIdle()
-     → check yieldCalled → retry up to 3x
-     → finalization (truncation, schema validation)
-     → cleanup isolation dir (finally block)
-```
-
-### Async Job Lifecycle
-```
-register(type, label, run, options)
-  → AbortController + Job ID
-  → run() with signal + reportProgress
-  → on complete: job.status = "completed"
-  → delivery: sendCustomMessage({ deliverAs: "followUp" })
-  → eviction timer after retentionMs
-```
-
----
-
-## 📝 Files Changed trong v14.7.x (New)
-
-| File | Description |
-|------|-------------|
-| `modes/loop-limit.ts` | NEW — iteration/duration limits |
-| `eval/js/context-manager.ts` | rewriteStaticImports, buildRequire |
-| `tools/fetch.ts` | URL line range syntax change |
-| `sdk.ts` | agentsMdSearch + workspaceTree passthrough |
-| `agent.ts` | hideThinkingSummary |
-| `providers/openai-completions-compat.ts` | 30+ provider compatibility |
-| `providers/openai-completions.ts` | tool strict mode handling |
-| `system-prompt.ts` | ordered systemPrompt arrays |
-| `procmgr.ts` | scrubProcessEnv() |
-| `interactive-mode.ts` | loop mode integration |
-
----
-
-## ✅ Confirmation: pi-crew Design đúng
-
-1. **parent-guard.ts**: ĐÚNG — vì pi-crew dùng child processes, không thể in-process
-2. **purgeStaleActiveRunIndex**: ĐÚNG — cleanup file-level state
-3. **G4 Async IRC**: ĐÚNG — sendCustomMessage deliverAs pattern
-4. **G6 Yield Enforcement**: ĐÚNG — toolChoice workaround
-5. **Phase 6 Semaphore**: ĐÚNG — fail-fast pattern
-
-**Không có gì phải thay đổi trong design hiện tại.**

package/docs/research/REMAINING-GAPS-PLAN.md

@@ -1,363 +0,0 @@
-# Remaining Gaps Plan — pi-crew Live-Session → Production Parity
-
-> **Ngày tạo**: 2026-05-08
-> **Prerequisite**: Phases 0-8 đã hoàn thành (991/994 tests pass, typecheck clean)
-> **Mục tiêu**: Đóng 6 gap còn lại để đạt **≥90% parity** với oh-my-pi
-
----
-
-## Gap Analysis Summary
-
-| # | Gap | Parity | Effort | Priority | Status |
-|---|-----|--------|--------|----------|--------|
-| G1 | Custom Tool Injection (Yield + IRC) | **100%** | 3-4d | P0 | ✅ Done |
-| G2 | MCP Proxy (functional) | **70%** | 3-5d | P1 | ✅ Done |
-| G3 | AJV Schema Validation | **100%** | 2d | P2 | ✅ Done |
-| G4 | respondAsBackground (non-blocking IRC) | **70%** | 5-7d | P3 | ✅ Done |
-| G5 | Extension Runner Integration Test | **90%** | 2-3d | P2 | ✅ Done |
-| G6 | toolChoice enforcement for yield | **80%** | 1-2d | P3 | ✅ Done |
-
----
-
-## G1: Custom Tool Injection (Yield + IRC as real tools)
-
-### Vấn đề
-- Workers chạy live-session **không thấy** `submit_result` tool hay `irc` tool
-- oh-my-pi inject các tools này qua `createAgentSession({ customTools: [...] })`
-- Pi SDK **có hỗ trợ**: `createAgentSession({ customTools: ToolDefinition[] })`
-
-### Pi SDK API đã xác nhận
-```typescript
-// node_modules/@mariozechner/pi-coding-agent/dist/core/extensions/types.d.ts
-interface ToolDefinition<TParams, TDetails, TState> {
-    name: string;
-    label: string;
-    description: string;
-    parameters: TSchema;  // TypeBox schema
-    execute(toolCallId: string, params, signal, onUpdate, ctx): Promise<AgentToolResult>;
-    promptSnippet?: string;
-    promptGuidelines?: string[];
-}
-
-// Usage:
-const session = await createAgentSession({
-    cwd,
-    customTools: [yieldTool, ircTool],  // ← This is what oh-my-pi does
-});
-```
-
-### Implementation Plan
-
-#### Bước 1: Tạo `src/runtime/custom-tools/submit-result-tool.ts`
-- Dùng `defineTool()` từ Pi SDK để tạo `submit_result` tool
-- `parameters`: TypeBox schema `{ summary: string, artifacts?: Record<string,string>, structuredData?: object }`
-- `execute()`: Lưu result vào callback/store, return success
-- `promptSnippet`: "Submit your final result using submit_result"
-- `promptGuidelines`: ["Always call submit_result when your task is complete"]
-
-```typescript
-import { defineTool } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";  // already in SDK
-
-export function createSubmitResultTool(onYield: (result: YieldResult) => void) {
-    return defineTool({
-        name: "submit_result",
-        label: "Submit Result",
-        description: "Submit your final result...",
-        parameters: Type.Object({
-            summary: Type.String({ description: "Summary of your work" }),
-            artifacts: Type.Optional(Type.Record(Type.String(), Type.String())),
-            structuredData: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-        }),
-        async execute(toolCallId, params, _signal, _onUpdate, _ctx) {
-            onYield({ summary: params.summary, artifacts: params.artifacts, structuredData: params.structuredData, toolCallId });
-            return { content: [{ type: "text", text: "Result submitted successfully." }] };
-        },
-        promptSnippet: "Submit your task result when done",
-        promptGuidelines: ["Always call submit_result when your task is complete"],
-    });
-}
-```
-
-#### Bước 2: Tạo `src/runtime/custom-tools/irc-tool.ts`
-- `parameters`: TypeBox schema `{ op: "send"|"list", to?: string, message?: string, awaitReply?: boolean }`
-- `execute()`:
-  - `op=list` → trả về danh sách live agents (từ `listLiveAgents()`)
-  - `op=send` → route qua `sendIrcMessage()` / `broadcastIrcMessage()`
-- `promptSnippet`: "Send messages to other live agents"
-
-#### Bước 3: Update `live-session-runtime.ts`
-- Import custom tools, inject qua `createAgentSession({ customTools: [...] })`
-- Khi `submit_result` execute → set `yieldResult` + resolve promise
-- Giảm yield enforcement loop vì `submit_result` là tool thật → model sẽ gọi nó
-
-#### Bước 4: Update yield enforcement
-- Thay vì detect `isYieldEvent()` từ JSON events → dùng callback từ `submit_result` tool
-- Vẫn giữ reminder loop như fallback
-
-### Files cần thay đổi
-| File | Action |
-|------|--------|
-| `src/runtime/custom-tools/submit-result-tool.ts` | **NEW** |
-| `src/runtime/custom-tools/irc-tool.ts` | **NEW** |
-| `src/runtime/live-session-runtime.ts` | Update: inject customTools |
-| `src/runtime/yield-handler.ts` | Update: callback-based yield detection |
-
-### Test strategy
-- Unit test `createSubmitResultTool` → verify onYield callback
-- Unit test `createIrcTool` → verify routing
-- Integration test: `PI_CREW_MOCK_LIVE_SESSION` mock phải work với custom tools
-
----
-
-## G2: MCP Proxy (Functional)
-
-### Vấn đề
-- `mcp-proxy.ts` hiện tại chỉ là placeholder → `discoverMcpToolsForProxy()` return `[]`
-- oh-my-pi dùng `mcpManager.getTools()` + `createMCPProxyTools()` → inject as custom tools
-- Pi SDK **không expose** `MCPManager` trực tiếp, nhưng có MCP tools trong session
-
-### Probe cần làm
-1. Kiểm tra xem Pi SDK session có MCP tools sau `bindExtensions()` không
-2. Nếu có → dùng `session.getActiveToolNames()` + `getToolDefinition()` để discover
-3. Nếu không → cần tạo proxy tools với connection sharing
-
-### Implementation Plan
-
-#### Bước 1: Probe MCP availability
-```typescript
-// Sau session.bindExtensions()
-const activeTools = session.getActiveToolNames();
-const mcpTools = activeTools.filter(n => n.startsWith("mcp__") || n.includes("__"));
-```
-
-#### Bước 2: Nếu MCP tools đã available
-- Chỉ cần `enableMCP: true` (hoặc không set) trong `createAgentSession`
-- MCP proxy không cần thiết → session tự discover
-
-#### Bước 3: Nếu MCP tools không available
-- Tạo proxy tools dùng `session.sendCustomMessage()` hoặc direct MCP call
-- Inject qua `customTools` array
-
-#### Bước 4: Connection sharing (nếu cần)
-- Parse parent's `.pi/mcp.json` config
-- Tạo MCP client connections trong parent process
-- Share qua custom tool wrappers
-
-### Files cần thay đổi
-| File | Action |
-|------|--------|
-| `src/runtime/mcp-proxy.ts` | **REWRITE** — functional discovery |
-| `src/runtime/live-session-runtime.ts` | Update: use real MCP proxy |
-
----
-
-## G3: AJV Schema Validation
-
-### Vấn đề
-- `validateYieldData()` hiện tại chỉ check basic types + required fields
-- oh-my-pi dùng AJV (`ajv = new Ajv({ allErrors: true, strict: false })`) + `jtdToJsonSchema()`
-- Thiếu: nested properties, pattern, enum, min/max, additionalProperties
-
-### Implementation Plan
-
-#### Bước 1: Thêm AJV dependency
-```bash
-cd pi-crew && npm install ajv
-```
-
-#### Bước 2: Update `validateYieldData()` trong `yield-handler.ts`
-```typescript
-import Ajv from "ajv";
-
-const ajv = new Ajv({ allErrors: true, strict: false, logger: false });
-
-export function validateYieldData(data: unknown, schema: unknown): SchemaValidationResult {
-    if (!schema) return { valid: true };
-    try {
-        const validate = ajv.compile(schema as object);
-        const valid = validate(data);
-        if (!valid) {
-            return { valid: false, error: ajv.errorsText(validate.errors) };
-        }
-        return { valid: true };
-    } catch {
-        // Fallback to lightweight validation
-        return lightweightValidate(data, schema);
-    }
-}
-```
-
-#### Bước 3: JTD → JSON Schema conversion (optional)
-- Port `jtdToJsonSchema()` từ oh-my-pi nếu output schema dùng JTD format
-- Hoặc yêu cầu caller pass JSON Schema trực tiếp
-
-### Files cần thay đổi
-| File | Action |
-|------|--------|
-| `src/runtime/yield-handler.ts` | Update: AJV validation |
-| `package.json` | Add: ajv dependency |
-
----
-
-## G4: respondAsBackground (Non-blocking IRC)
-
-### Vấn đề
-- oh-my-pi dùng `session.respondAsBackground()` → gửi tin nhắn mà **không block** recipient
-- pi-crew hiện tại dùng `session.prompt()` → **có thể block** nếu recipient đang streaming
-- Pi SDK có `sendCustomMessage({ deliverAs: "followUp" })` và `sendUserMessage({ deliverAs: "steer" })`
-
-### Pi SDK API đã xác nhận
-```typescript
-// ExtensionContext
-sendMessage(message, options?: { triggerTurn?, deliverAs?: "steer" | "followUp" | "nextTurn" }): void;
-sendUserMessage(content, options?: { deliverAs?: "steer" | "followUp" }): void;
-```
-
-### Implementation Plan
-
-#### Bước 1: Thử `deliverAs` option
-```typescript
-// Non-blocking message injection
-session.sendCustomMessage?.(
-    { customType: "irc", content: `[DM from ${from}] ${message}` },
-    { deliverAs: "followUp", triggerTurn: false }
-);
-```
-
-#### Bước 2: Fallback chain
-1. `sendCustomMessage({ deliverAs: "followUp" })` — ideal
-2. `sendUserMessage({ deliverAs: "steer" })` — less ideal, interrupts streaming
-3. `session.steer(message)` — basic, waits for current turn
-4. `session.prompt(message)` — blocking, last resort
-
-#### Bước 3: Reply-waiting
-- Nếu `awaitReply=true`:
-  - Inject message (non-blocking)
-  - Subscribe to events, filter for reply from target
-  - Timeout after configurable period
-
-### Files cần thay đổi
-| File | Action |
-|------|--------|
-| `src/runtime/live-agent-manager.ts` | Update: non-blocking delivery |
-| `src/runtime/live-irc.ts` | Update: reply-waiting logic |
-
----
-
-## G5: Extension Runner Integration Verification
-
-### Vấn đề
-- `live-extension-bridge.ts` đã build API bridge nhưng chưa test với SDK thật
-- Cần verify: `extensionRunner.initialize(apis, host)` có hoạt động không
-- Cần verify: event emission lifecycle
-
-### Implementation Plan
-
-#### Bước 1: Tạo integration test
-```typescript
-// test/integration/live-extension-bridge.test.ts
-import { createAgentSession } from "@mariozechner/pi-coding-agent";
-
-test("extension bridge initializes with real session", async () => {
-    const session = await createAgentSession({ cwd: tmpdir() });
-    // Probe extensionRunner
-    const runner = (session as any).extensionRunner;
-    // Verify bridge APIs match
-});
-```
-
-#### Bước 2: Fix bridge APIs based on actual SDK shape
-- `session.sessionManager` → check methods
-- `session.model` → check getter
-- `session.getContextUsage()` → check return type
-
-#### Bước 3: Add extension lifecycle tests
-- `session_start` event
-- Tool registration via extension
-- `session_shutdown` event
-
-### Files cần thay đổi
-| File | Action |
-|------|--------|
-| `src/runtime/live-extension-bridge.ts` | Fix: match actual SDK API |
-| `test/integration/` | **NEW**: integration tests |
-
----
-
-## G6: toolChoice Enforcement for Yield
-
-### Vấn đề
-- oh-my-pi dùng `buildNamedToolChoice("yield")` → ép model gọi yield tool
-- Pi SDK `prompt()` **không có** `toolChoice` option
-- Giải pháp thay thế: sử dụng system prompt + reminder
-
-### Probe cần làm
-1. Check nếu Pi SDK thêm `toolChoice` trong tương lai
-2. Check `session.setActiveToolsByName(["submit_result"])` trước reminder prompt
-
-### Implementation Plan
-
-#### Workaround: Constrained tool set
-```typescript
-// Trước khi gửi yield reminder:
-const prevTools = session.getActiveToolNames();
-session.setActiveToolsByName(["submit_result"]);  // Chỉ cho tool này
-await session.prompt(reminder, { source: "api" });
-session.setActiveToolsByName(prevTools);  // Restore
-```
-
-#### Future: Khi SDK hỗ trợ toolChoice
-```typescript
-await session.prompt(reminder, {
-    source: "api",
-    toolChoice: { type: "tool", name: "submit_result" }
-});
-```
-
-### Files cần thay đổi
-| File | Action |
-|------|--------|
-| `src/runtime/live-session-runtime.ts` | Update: constrained tool set before reminder |
-
----
-
-## Execution Order
-
-```
-Week 1: G1 (Custom Tool Injection)     ← P0, unblocks G2+G4+G6
-Week 1: G3 (AJV Schema Validation)     ← P2, independent, quick
-Week 2: G2 (MCP Proxy)                 ← P1, depends on G1's customTools pattern
-Week 2: G6 (toolChoice Workaround)     ← P3, depends on G1's submit_result tool
-Week 2: G5 (Extension Runner Verify)   ← P2, independent
-Week 3: G4 (respondAsBackground)       ← P3, depends on G1's IRC tool + G5's bridge
-```
-
-### Dependency Graph
-```
-G1 ──► G2 (customTools pattern)
-G1 ──► G4 (IRC tool delivery)
-G1 ──► G6 (submit_result constraining)
-G3 ──► (independent)
-G5 ──► G4 (bridge APIs for sendCustomMessage)
-```
-
-### Expected Outcome After All Gaps
-- **Parity**: ~90-95% với oh-my-pi
-- **Yield**: 100% (real tool + AJV validation + toolChoice workaround)
-- **IRC**: ~85% (real tool, delivery qua sendCustomMessage, reply-waiting)
-- **MCP**: ~80% (proxy injection, connection sharing needs upstream)
-- **Extensions**: ~90% (verified bridge, lifecycle tested)
-- **Core unique**: 100% (fault isolation, file state, health monitoring, workflow DAG)
-
----
-
-## Risks & Mitigations
-
-| Risk | Probability | Impact | Mitigation |
-|------|------------|--------|------------|
-| Pi SDK `customTools` TypeBox import không compatible | Medium | High | Test ngay bước đầu; fallback: inline schema object |
-| AJV bundle size | Low | Low | Tree-shake; AJV ~30KB gzipped |
-| `sendCustomMessage` không hoạt động ở background | Medium | Medium | Fallback sang `steer()` |
-| ExtensionRunner không expose cho live-session | Medium | Medium | Graceful degradation, keep bridge as framework |
-| `defineTool` signature thay đổi trong SDK update | Low | High | Pin SDK version, test trước khi upgrade |