pi-crew 0.1.51 → 0.2.0

package/docs/research-extension-examples.md

@@ -1,297 +0,0 @@
-# Research: Extension Examples & Patterns
-
-> Ngày: 2026-04-29 | Read-only research | Source: `source/pi-mono/packages/coding-agent/examples/extensions/`
-
-## 1. Example Catalog (86 files, 60+ extensions)
-
-### 1.1 Sorted by relevance to pi-crew
-
-| Priority | Example | Relevance |
-|---|---|---|
-| ⭐⭐⭐ | `subagent/` | Most similar to pi-crew: child Pi spawning, parallel, chain |
-| ⭐⭐⭐ | `custom-compaction.ts` | Hook compaction — useful for preserving run state |
-| ⭐⭐⭐ | `event-bus.ts` | Cross-extension communication pattern |
-| ⭐⭐⭐ | `plan-mode/` | State persistence, dynamic tools, widget management |
-| ⭐⭐⭐ | `structured-output.ts` | `terminate: true` — save LLM turns |
-| ⭐⭐ | `handoff.ts` | Context transfer to new session |
-| ⭐⭐ | `dynamic-tools.ts` | Register tools at runtime |
-| ⭐⭐ | `permission-gate.ts` | Gate dangerous operations |
-| ⭐⭐ | `trigger-compact.ts` | Proactive compaction monitoring |
-| ⭐⭐ | `send-user-message.ts` | sendUserMessage pattern |
-| ⭐ | `dirty-repo-guard.ts` | Guard against uncommitted changes |
-| ⭐ | `model-status.ts` | Model status in footer |
-| ⭐ | `confirm-destructive.ts` | Confirm destructive operations |
-
-## 2. Deep Analysis of Key Examples
-
-### 2.1 subagent/ — The Reference Implementation
-
-**Files:**
-- `index.ts` (~530 dòng): Main tool with execute + render
-- `agents.ts` (~130 dòng): Agent discovery (user/project scope)
-
-**Architecture:**
-```
-subagent tool
-  ├── Single: runSingleAgent() → spawn pi --mode json -p
-  ├── Parallel: mapWithConcurrencyLimit(tasks, 4, runSingleAgent)
-  └── Chain: sequential loop with {previous} placeholder
-```
-
-**Key patterns:**
-- Agent discovery: `discoverAgents(cwd, scope)` — scans `.md` files with YAML frontmatter
-- Child process: `getPiInvocation()` detects current runtime (node/bun/pi binary)
-- Streaming: `onUpdate` callback for partial results during execution
-- Render: `renderCall()` + `renderResult()` with collapsed/expanded views
-- Abort: AbortSignal propagated to child process
-
-**What pi-crew does better:**
-- Durable state (manifest, tasks, events) instead of in-memory only
-- Team/workflow abstraction instead of flat agent list
-- Task graph with DAG dependencies instead of linear chain
-- Async background runner with PID tracking
-- Policy engine for limits/retry/escalation
-- Mailbox for inter-task communication
-- Worktree isolation per task
-
-**What pi-crew could adopt from this:**
-- `terminate: true` on final results (not used in example either, but available)
-- `renderCall/Result` custom rendering patterns
-- `mapWithConcurrencyLimit` pattern (pi-crew already has similar)
-
-### 2.2 custom-compaction.ts — Custom Compaction
-
-**Pattern:**
-```typescript
-pi.on("session_before_compact", async (event, ctx) => {
-  // 1. Get preparation data
-  const { messagesToSummarize, turnPrefixMessages, tokensBefore, firstKeptEntryId } = event.preparation;
-
-  // 2. Use different model for summarization (cheaper)
-  const model = ctx.modelRegistry.find("google", "gemini-2.5-flash");
-
-  // 3. Custom prompt
-  const summary = await complete(model, { messages: [...] }, { apiKey, signal });
-
-  // 4. Return custom compaction result
-  return {
-    compaction: { summary, firstKeptEntryId, tokensBefore }
-  };
-});
-```
-
-**Relevance to pi-crew:**
-- Can use cheap model to summarize completed tasks
-- Can protect foreground runs from being compacted mid-execution
-- Can store structured artifact index in compaction `details`
-
-### 2.3 event-bus.ts — Cross-Extension Communication
-
-**Pattern:**
-```typescript
-// Extension A: emit events
-pi.events.emit("my:notification", { message: "hello", from: "ext-a" });
-
-// Extension B: listen
-pi.events.on("my:notification", (data) => {
-  currentCtx?.ui.notify(`Event from ${data.from}: ${data.message}`);
-});
-```
-
-**Relevance to pi-crew:**
-- Already used for internal events (`subagent.stuck-blocked`)
-- Could publish structured events for other extensions to consume:
-  - `pi-crew:run:completed`
-  - `pi-crew:subagent:completed`
-  - `pi-crew:run:failed`
-
-### 2.4 plan-mode/ — State Persistence + Dynamic Tools
-
-**Key patterns:**
-
-State persistence:
-```typescript
-// Save
-pi.appendEntry("plan-mode", { enabled, todos, executing });
-
-// Restore on session_start
-const entries = ctx.sessionManager.getEntries();
-const state = entries
-  .filter(e => e.type === "custom" && e.customType === "plan-mode")
-  .pop()?.data;
-```
-
-Dynamic tools:
-```typescript
-// Switch between tool sets
-if (planModeEnabled) {
-  pi.setActiveTools(["read", "bash", "grep", "find", "ls"]);
-} else {
-  pi.setActiveTools(["read", "bash", "edit", "write"]);
-}
-```
-
-Tool call gate:
-```typescript
-pi.on("tool_call", async (event) => {
-  if (planModeEnabled && event.toolName === "bash") {
-    if (!isSafeCommand(event.input.command)) {
-      return { block: true, reason: "..." };
-    }
-  }
-});
-```
-
-**Relevance to pi-crew:**
-- `pi.appendEntry` pattern for cross-session run awareness
-- `pi.setActiveTools` could be used to restrict tools during team runs
-- `tool_call` gate for destructive team actions
-
-### 2.5 structured-output.ts — terminate: true
-
-**Pattern:**
-```typescript
-async execute(_toolCallId, params) {
-  return {
-    content: [{ type: "text", text: "Done" }],
-    details: { headline, summary, actionItems },
-    terminate: true,  // ← No follow-up LLM turn needed
-  };
-}
-```
-
-**Relevance to pi-crew:**
-- `Agent` tool results could use `terminate: true` when background run queued
-- `get_subagent_result` could terminate when result is final
-- `team` tool status/list/recommend actions could terminate
-
-### 2.6 handoff.ts — Context Transfer to New Session
-
-**Pattern:**
-```typescript
-// 1. Extract conversation context
-const messages = ctx.sessionManager.getBranch()
-  .filter(e => e.type === "message")
-  .map(e => e.message);
-
-// 2. Generate focused prompt
-const prompt = await complete(model, { systemPrompt, messages }, { apiKey });
-
-// 3. Create new session with pre-filled editor
-await ctx.newSession({
-  parentSession: currentSessionFile,
-  withSession: async (replacementCtx) => {
-    replacementCtx.ui.setEditorText(prompt);
-  },
-});
-```
-
-**Relevance to pi-crew:**
-- When a task in a team run needs isolated context, could handoff to new session
-- Parent session tracking via `parentSession`
-
-### 2.7 permission-gate.ts — Dangerous Operation Gate
-
-**Pattern:**
-```typescript
-pi.on("tool_call", async (event, ctx) => {
-  if (event.toolName !== "bash") return;
-  if (isDangerousPattern(event.input.command)) {
-    const choice = await ctx.ui.select("Allow?", ["Yes", "No"]);
-    if (choice !== "Yes") {
-      return { block: true, reason: "Blocked by user" };
-    }
-  }
-});
-```
-
-**Relevance to pi-crew:**
-- Gate destructive team actions (delete, forget, prune)
-- Only allow with explicit `confirm: true` parameter
-
-### 2.8 trigger-compact.ts — Proactive Compaction
-
-**Pattern:**
-```typescript
-pi.on("turn_end", (_event, ctx) => {
-  const usage = ctx.getContextUsage();
-  if (usage?.tokens && usage.tokens > THRESHOLD) {
-    ctx.compact({ customInstructions: "..." });
-  }
-});
-```
-
-**Relevance to pi-crew:**
-- Monitor context during long team runs
-- Auto-compact before hitting overflow errors
-- Use compact's callback to track state
-
-## 3. Pattern Summary
-
-### 3.1 Patterns pi-crew already implements well
-
-| Pattern | pi-crew implementation |
-|---|---|
-| Child Pi spawning | `SubagentManager` + `spawn.ts` with full process management |
-| Parallel execution | `mapConcurrent` in team runner |
-| State persistence | Durable file-based (manifest, tasks, events, artifacts) |
-| Widget rendering | `CrewWidget`, `LiveRunSidebar`, `Powerbar` |
-| Lifecycle hooks | `session_start`, `session_before_switch`, `session_shutdown` |
-| Config merge | `loadConfig` with user/project priority |
-| Abort propagation | `AbortController` trees in foreground runs |
-
-### 3.2 Patterns pi-crew could adopt
-
-| Pattern | Current status | Recommendation |
-|---|---|---|
-| `terminate: true` | ❌ Not used | Add to Agent/get_subagent_result |
-| `session_before_compact` hook | ❌ Not hooked | Cancel compact during foreground runs |
-| Custom compaction model | ❌ Not used | Use Haiku/Gemini Flash for task summaries |
-| `pi.events` publish | ⚠️ Internal only | Add public structured events |
-| `pi.appendEntry` | ❌ Not used | Cross-session run references |
-| `tool_call` permission gate | ❌ Not gated | Gate destructive team actions |
-| Config-driven tool registration | ❌ Always all | Register tools per config |
-| Working indicator | ❌ Widget only | Use `ctx.ui.setWorkingIndicator` |
-| Session name auto-set | ❌ Manual only | Auto-name from team run context |
-| `ctx.compact()` proactive | ❌ No monitoring | Monitor + auto-compact at threshold |
-
-## 4. Example: Complete Tool with terminate + render
-
-This shows a hypothetical optimized pi-crew Agent tool:
-
-```typescript
-// OPTIMIZED Agent tool pattern
-const AgentTool = defineTool({
-  name: "Agent",
-  label: "Agent",
-  description: "Launch a real pi-crew subagent...",
-  parameters: Type.Object({
-    prompt: Type.String(),
-    description: Type.String(),
-    subagent_type: Type.String(),
-    run_in_background: Type.Optional(Type.Boolean()),
-  }),
-  async execute(_id, params, signal, _onUpdate, ctx) {
-    // ... spawn subagent ...
-    if (params.run_in_background) {
-      return {
-        content: [{ type: "text", text: `Agent queued. ID: ${record.id}` }],
-        details: { agentId: record.id, status: "queued" },
-        terminate: true,  // ← No need for LLM follow-up
-      };
-    }
-    await record.promise;
-    const output = readResult(record);
-    return {
-      content: [{ type: "text", text: output }],
-      details: { agentId: record.id, status: record.status },
-      terminate: true,  // ← Final result, save LLM turn
-    };
-  },
-  renderResult(result, { expanded }, theme) {
-    // Custom rendering with colored status icons
-    // Collapsed/expanded views
-    // Usage stats display
-  },
-});
-```

package/docs/research-extension-system.md

@@ -1,324 +0,0 @@
-# Research: Pi Extension System Deep Dive
-
-> Ngày: 2026-04-29 | Read-only research | Source: `source/pi-mono/packages/coding-agent/src/core/extensions/`
-
-## 1. Extension System Architecture
-
-Pi extension system là plugin framework cho coding agent. Extensions được viết bằng TypeScript,
-load qua jiti (JIT compiler), và có thể hook vào mọi phase của agent lifecycle.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    ExtensionAPI ("pi.*")                    │
-│  Event sub:   pi.on(event, handler)                        │
-│  Tools:       pi.registerTool(def)                         │
-│  Commands:    pi.registerCommand(name, opts)               │
-│  Shortcuts:   pi.registerShortcut(key, opts)               │
-│  Flags:       pi.registerFlag(name, opts)                  │
-│  Messages:    pi.sendMessage() / pi.sendUserMessage()      │
-│  State:       pi.appendEntry(customType, data)             │
-│  Provider:    pi.registerProvider(name, config)            │
-│  Event bus:   pi.events.emit/on()                          │
-│  Model:       pi.setModel() / getThinkingLevel()           │
-│  Tools mgmt:  pi.getActiveTools() / setActiveTools()       │
-├─────────────────────────────────────────────────────────────┤
-│               ExtensionFactory                              │
-│        (pi: ExtensionAPI) => void | Promise<void>          │
-├─────────────────────────────────────────────────────────────┤
-│  loader.ts ──► jiti → TypeScript module loading            │
-│  runner.ts ──► ExtensionRunner → lifecycle + event emit    │
-│  types.ts ───► 1545 dòng type definitions                  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 2. Extension Loading Flow
-
-```
-discoverAndLoadExtensions(cwd, agentDir, extensionPaths)
-  ├── Scan directories:
-  │     ├── ~/.pi/agent/extensions/**/index.ts  (user-global)
-  │     ├── .pi/extensions/**/index.ts           (project-local)
-  │     └── CLI --extension paths                (explicit)
-  ├── Create ExtensionRuntime (shared state + action stubs)
-  ├── For each extension file:
-  │     ├── jiti.import(path)                    # Load TS module
-  │     ├── Call default export: factory(pi)     # Register handlers/tools/commands
-  │     └── Collect into Extension object
-  └── Return LoadExtensionsResult
-
-ExtensionRunner.initialize(session, context, actions)
-  ├── Bind real action implementations to runtime
-  ├── Process queued provider registrations
-  └── Emit session_start event
-```
-
-### 2.1 Discovery priority
-
-Project-local > user-global. Extensions cùng tên: project override user.
-
-### 2.2 Runtime replacement (reload)
-
-Khi `/reload` hoặc session switch:
-1. `emitSessionShutdownEvent("reload")`
-2. Invalidate old ExtensionRuntime (throws if stale extension tries to act)
-3. Re-discover + re-load tất cả extensions
-4. Re-initialize ExtensionRunner
-
-## 3. Full Event Lifecycle
-
-### 3.1 Event model (23 event types)
-
-**Session events** — session-level lifecycle:
-```
-session_start              ← Khi session được tạo/load/reload
-resources_discover          ← Extension có thể inject thêm paths
-session_before_switch       ← Trước khi switch session (có thể cancel)
-session_before_fork         ← Trước khi fork session (có thể cancel)
-session_before_compact      ← Trước khi compaction (có thể cancel hoặc custom)
-session_compact             ← Sau khi compaction hoàn tất
-session_before_tree         ← Trước khi navigate tree (có thể cancel)
-session_tree                ← Sau khi navigate tree
-session_shutdown            ← Khi session bị hủy (quit/reload/new/resume/fork)
-```
-
-**Agent events** — per-prompt:
-```
-input                       ← Khi user input received (có thể transform/block)
-before_agent_start          ← Trước khi agent loop chạy (inject custom message / swap system prompt)
-context                     ← Transform messages trước khi gửi LLM
-before_provider_request     ← Thay đổi payload trước khi gửi provider
-after_provider_response     ← Quan sát response status/headers
-agent_start                 ← Agent loop bắt đầu
-agent_end                   ← Agent loop kết thúc
-```
-
-**Turn events** — per-turn:
-```
-turn_start                  ← Bắt đầu turn mới
-turn_end                    ← Kết thúc turn (có message + tool results)
-```
-
-**Message events** — per-message:
-```
-message_start               ← Message bắt đầu (user/assistant/toolResult)
-message_update              ← Streaming token-by-token update
-message_end                 ← Message hoàn tất
-```
-
-**Tool events** — per-tool:
-```
-tool_call                   ← Trước khi tool execute (có thể block/mutate args)
-tool_execution_start        ← Tool bắt đầu chạy
-tool_execution_update       ← Partial/streaming result
-tool_execution_end          ← Tool hoàn tất
-tool_result                 ← Sau khi tool execute (có thể modify result)
-```
-
-**Other:**
-```
-model_select                ← Khi model được chọn/thay đổi
-user_bash                   ← Khi user dùng ! prefix cho bash
-```
-
-### 3.2 Event result contracts
-
-Mỗi event có thể return result để ảnh hưởng đến behavior:
-
-| Event | Result type | Effect |
-|---|---|---|
-| `input` | `{ action: "continue" \| "transform" \| "handled" }` | Transform/block input |
-| `before_agent_start` | `{ message?, systemPrompt? }` | Inject custom message, swap system prompt |
-| `context` | `{ messages? }` | Replace context messages |
-| `before_provider_request` | `any` | Replace payload |
-| `tool_call` | `{ block?, reason? }` | Block tool execution |
-| `tool_result` | `{ content?, details?, isError? }` | Modify result |
-| `user_bash` | `{ operations?, result? }` | Custom bash execution |
-| `session_before_*` | `{ cancel? }` | Cancel session operation |
-| `session_before_compact` | `{ cancel?, compaction? }` | Cancel or custom compact |
-| `session_before_tree` | `{ cancel?, summary?, customInstructions? }` | Cancel or custom summary |
-| `resources_discover` | `{ skillPaths?, promptPaths?, themePaths? }` | Inject resource paths |
-
-## 4. Context Objects Available to Extensions
-
-### 4.1 ExtensionContext (`ctx.*`) — có sẵn trong mọi event handler
-
-```typescript
-interface ExtensionContext {
-  ui: ExtensionUIContext;         // UI methods (select, confirm, notify, widgets...)
-  hasUI: boolean;                 // false in print/RPC mode
-  cwd: string;                    // Current working directory
-  sessionManager: ReadonlySessionManager; // Session access (read-only)
-  modelRegistry: ModelRegistry;   // Auth + model discovery
-  model: Model<any> | undefined;  // Current model
-  isIdle(): boolean;              // Check if agent is streaming
-  signal: AbortSignal | undefined;// Current abort signal
-  abort(): void;                  // Abort current operation
-  hasPendingMessages(): boolean;  // Check message queue
-  shutdown(): void;               // Graceful shutdown
-  getContextUsage(): ContextUsage | undefined; // Token usage
-  compact(options?): void;        // Trigger compaction
-  getSystemPrompt(): string;      // Current system prompt
-}
-```
-
-### 4.2 ExtensionCommandContext — extends Context, chỉ trong command handler
-
-```typescript
-interface ExtensionCommandContext extends ExtensionContext {
-  waitForIdle(): Promise<void>;   // Wait for agent to finish
-  newSession(options?): Promise<{cancelled}>;
-  fork(entryId, options?): Promise<{cancelled}>;
-  navigateTree(targetId, options?): Promise<{cancelled}>;
-  switchSession(sessionPath, options?): Promise<{cancelled}>;
-  reload(): Promise<void>;
-}
-```
-
-### 4.3 ReplacedSessionContext — sau khi switch/new session
-
-```typescript
-interface ReplacedSessionContext extends ExtensionCommandContext {
-  sendMessage(message, options?): Promise<void>;
-  sendUserMessage(content, options?): Promise<void>;
-}
-```
-
-### 4.4 ExtensionUIContext (`ctx.ui.*`) — chỉ khi `hasUI=true`
-
-```typescript
-interface ExtensionUIContext {
-  select(title, options, opts?): Promise<string | undefined>;
-  confirm(title, message, opts?): Promise<boolean>;
-  input(title, placeholder?, opts?): Promise<string | undefined>;
-  notify(message, type?): void;
-  custom<T>(factory, options?): Promise<T>;   // Custom overlay component
-  setWidget(key, content, options?): void;     // Widget above/below editor
-  setFooter(factory): void;                    // Custom footer
-  setHeader(factory): void;                    // Custom header
-  setEditorComponent(factory): void;           // Custom editor
-  setStatus(key, text): void;                  // Status bar
-  setTitle(title): void;                       // Terminal title
-  setWorkingMessage(message?): void;           // Working loader text
-  setWorkingVisible(visible): void;            // Show/hide loader
-  setWorkingIndicator(options?): void;         // Custom loader animation
-  setHiddenThinkingLabel(label?): void;        // Thinking block label
-  onTerminalInput(handler): () => void;        // Raw terminal input
-  getToolsExpanded(): boolean;
-  setToolsExpanded(expanded): void;
-  theme: Theme;
-  getAllThemes(): {name, path}[];
-  getTheme(name): Theme | undefined;
-  setTheme(theme): {success, error?};
-}
-```
-
-## 5. ToolDefinition Contract
-
-```typescript
-interface ToolDefinition<TParams extends TSchema, TDetails = unknown, TState = any> {
-  name: string;                   // Unique tool name
-  label: string;                  // Human-readable for UI
-  description: string;            // For LLM
-  parameters: TParams;            // TypeBox schema
-  promptSnippet?: string;         // 1-line for system prompt "Available tools"
-  promptGuidelines?: string[];    // Bullets for system prompt "Guidelines"
-  renderShell?: "default" | "self"; // Who renders the outer frame
-  executionMode?: "sequential" | "parallel"; // Concurrency control
-  prepareArguments?: (args: unknown) => Static<TParams>;
-
-  // Core execution
-  execute(
-    toolCallId: string,
-    params: Static<TParams>,
-    signal: AbortSignal | undefined,
-    onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
-    ctx: ExtensionContext,
-  ): Promise<AgentToolResult<TDetails>>;
-
-  // Rendering (optional)
-  renderCall?(args, theme, context): Component;       // Custom call display
-  renderResult?(result, options, theme, context): Component; // Custom result display
-}
-```
-
-### 5.1 `terminate: true` pattern
-
-Tool có thể set `terminate: true` trong result để kết thúc turn ngay sau tool call,
-tiết kiệm 1 follow-up LLM turn:
-
-```typescript
-return {
-  content: [{ type: "text", text: "Done" }],
-  details: { ... },
-  terminate: true,  // ← Kết thúc turn, không cần LLM follow-up
-};
-```
-
-## 6. Provider Registration
-
-Extension có thể đăng ký provider tùy chỉnh:
-
-```typescript
-pi.registerProvider("my-provider", {
-  baseUrl: "https://api.example.com",
-  apiKey: "PROVIDER_API_KEY",
-  api: "anthropic-messages",
-  models: [{
-    id: "my-model",
-    name: "My Model",
-    reasoning: false,
-    input: ["text", "image"],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-    contextWindow: 200000,
-    maxTokens: 16384,
-  }],
-  // Optional OAuth:
-  oauth: {
-    name: "My Provider (SSO)",
-    async login(callbacks) { ... },
-    async refreshToken(credentials) { ... },
-    getApiKey(credentials) { return credentials.access; },
-  },
-});
-```
-
-Hiệu lực ngay lập tức sau `session_start` (không cần `/reload`).
-
-## 7. API Comparison: ExtensionAPI vs ExtensionContext
-
-| Capability | `pi.*` (ExtensionAPI) | `ctx.*` (ExtensionContext) |
-|---|---|---|
-| Subscribe events | ✅ `pi.on(...)` | ❌ |
-| Register tools | ✅ `pi.registerTool()` | ❌ |
-| Register commands | ✅ `pi.registerCommand()` | ❌ |
-| Register shortcuts | ✅ `pi.registerShortcut()` | ❌ |
-| Register flags | ✅ `pi.registerFlag()` | ❌ |
-| Register providers | ✅ `pi.registerProvider()` | ❌ |
-| Send messages | ✅ `pi.sendMessage()` | ❌ |
-| Send user messages | ✅ `pi.sendUserMessage()` | ❌ |
-| Append entries | ✅ `pi.appendEntry()` | ❌ |
-| Session name | ✅ `pi.setSessionName()` / `getSessionName()` | ❌ |
-| Event bus | ✅ `pi.events` | ❌ |
-| Get/set active tools | ✅ `pi.getActiveTools()` / `setActiveTools()` | ❌ |
-| Get model | ❌ (register-time only) | ✅ `ctx.model` |
-| Check idle | ❌ | ✅ `ctx.isIdle()` |
-| Abort | ❌ | ✅ `ctx.abort()` |
-| Trigger compaction | ❌ | ✅ `ctx.compact()` |
-| Context usage | ❌ | ✅ `ctx.getContextUsage()` |
-| System prompt | ❌ | ✅ `ctx.getSystemPrompt()` |
-| Session manager | ❌ | ✅ `ctx.sessionManager` |
-| UI interaction | ❌ | ✅ `ctx.ui` |
-| Session control | ❌ | ✅ `ctx.newSession()` / `fork()` (command ctx) |
-
-**Rule of thumb:**
-- `pi.*`: Registration-time API (trong factory function, `session_start`)
-- `ctx.*`: Runtime API (trong event handlers, command handlers)
-
-## 8. Key Design Decisions
-
-1. **No sandbox** — Extensions run in same Node.js process, full system access
-2. **jiti loader** — TypeScript extensions compiled JIT, no build step
-3. **Virtual modules** — For Bun compiled binary, built-in dependencies bundled
-4. **Throwing stubs** — Runtime actions start as stubs, real implementations bound by runner
-5. **Stale detection** — After reload, old extension instances throw on any API call
-6. **Event bus** — Separate from extension events, for cross-extension communication