pi-crew 0.1.45 → 0.1.49

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

@@ -0,0 +1,266 @@
+# 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

@@ -0,0 +1,363 @@
+# 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 |