pi-crew 0.1.31 → 0.1.33

package/README.md

@@ -132,9 +132,12 @@ User config path:
 Project config path:
 
 ```text
-.pi/teams/config.json
+.crew/config.json            # default (new projects)
+.pi/teams/config.json        # legacy (when the repo already has .pi/)
 ```
 
+The project root is auto-detected by walking up from the current directory and stopping at any of: `.git`, `.pi`, `.crew`, `.hg`, `.svn`, `.factory`, `.omc`, or any common manifest file (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `composer.json`, `build.gradle[.kts]`). If the project already has a `.pi/` directory, pi-crew reuses it under `.pi/teams/` to avoid creating a parallel layout; otherwise it uses `.crew/`.
+
 Config merge priority:
 
 ```text
@@ -179,6 +182,11 @@ Supported config:
     "showModel": true,
     "showTokens": true,
     "showTools": true
+  },
+  "tools": {
+    "enableClaudeStyleAliases": true,
+    "enableSteer": true,
+    "terminateOnForeground": false
   }
 }
 ```
@@ -186,6 +194,7 @@ Supported config:
 Safety notes:
 
 - Foreground child-process runs continue in the Pi extension process and return control to chat immediately, so large workflows do not block the interactive session. They are interrupted on session shutdown. Use `async: true` only for intentionally detached runs that may survive the current session.
+- `tools.terminateOnForeground` is an opt-in power-user setting. When true, foreground `Agent`/`crew_agent` calls return with `terminate: true` after the child result is available, saving one follow-up LLM turn. Default is false so the assistant can still summarize raw worker output.
 
 UI notes:
 
@@ -454,12 +463,20 @@ User resources:
 ~/.pi/agent/workflows/*.workflow.md
 ```
 
-Project resources:
+Project resources (new default layout):
+
+```text
+.crew/agents/*.md
+.crew/teams/*.team.md
+.crew/workflows/*.workflow.md
+```
+
+Legacy layout (when `.pi/` already exists in the repo):
 
 ```text
-.pi/agents/*.md
-.pi/teams/*.team.md
-.pi/workflows/*.workflow.md
+.pi/teams/agents/*.md
+.pi/teams/teams/*.team.md
+.pi/teams/workflows/*.workflow.md
 ```
 
 Discovery priority:
@@ -525,33 +542,41 @@ review
 
 ## State layout
 
-Project-local state is preferred when the cwd has `.git` or `.pi`; otherwise user-global state is used.
+Project-local state is preferred when the cwd is inside a recognised project (any of the markers listed in the Config section above). Otherwise pi-crew falls back to user-global state.
 
-Typical project-local state:
+The project state root (`<crewRoot>` below) resolves to:
 
 ```text
-.pi/teams/state/runs/{runId}/manifest.json
-.pi/teams/state/runs/{runId}/tasks.json
-.pi/teams/state/runs/{runId}/events.jsonl
-.pi/teams/artifacts/{runId}/...
-.pi/teams/worktrees/{runId}/{taskId}
-.pi/teams/imports/{runId}/run-export.json
+<repoRoot>/.crew/             # default, used for new projects
+<repoRoot>/.pi/teams/         # legacy reuse when .pi/ already exists
+```
+
+Typical project-local state (`<crewRoot>` is one of the two paths above):
+
+```text
+<crewRoot>/state/runs/{runId}/manifest.json
+<crewRoot>/state/runs/{runId}/tasks.json
+<crewRoot>/state/runs/{runId}/events.jsonl
+<crewRoot>/artifacts/{runId}/...
+<crewRoot>/worktrees/{runId}/{taskId}
+<crewRoot>/imports/{runId}/run-export.json
 ```
 
 Mailbox state:
 
 ```text
-.pi/teams/state/runs/{runId}/mailbox/inbox.jsonl
-.pi/teams/state/runs/{runId}/mailbox/outbox.jsonl
-.pi/teams/state/runs/{runId}/mailbox/delivery.json
-.pi/teams/state/runs/{runId}/mailbox/tasks/{taskId}/inbox.jsonl
-.pi/teams/state/runs/{runId}/mailbox/tasks/{taskId}/outbox.jsonl
+<crewRoot>/state/runs/{runId}/mailbox/inbox.jsonl
+<crewRoot>/state/runs/{runId}/mailbox/outbox.jsonl
+<crewRoot>/state/runs/{runId}/mailbox/delivery.json
+<crewRoot>/state/runs/{runId}/mailbox/tasks/{taskId}/inbox.jsonl
+<crewRoot>/state/runs/{runId}/mailbox/tasks/{taskId}/outbox.jsonl
 ```
 
-User-global fallback:
+User-global fallback (shared with other Pi tools):
 
 ```text
-~/.pi/agent/extensions/pi-crew/runs/...
+~/.pi/agent/extensions/pi-crew/state/runs/...
+~/.pi/agent/extensions/pi-crew/artifacts/...
 ~/.pi/agent/extensions/pi-crew/imports/...
 ```
 
@@ -570,18 +595,34 @@ Optionally copy builtin resources:
 /team-init --copy-builtins --overwrite
 ```
 
-Created directories:
+Created directories (new projects):
 
 ```text
-.pi/agents/
-.pi/teams/
-.pi/workflows/
+.crew/agents/
+.crew/teams/
+.crew/workflows/
+.crew/imports/
+```
+
+If the project already has `.pi/`, the legacy layout is initialised instead:
+
+```text
+.pi/teams/agents/
+.pi/teams/teams/
+.pi/teams/workflows/
 .pi/teams/imports/
 ```
 
-`.gitignore` entries:
+`.gitignore` entries are written for whichever layout is active, e.g.:
 
 ```text
+# new layout
+.crew/state/
+.crew/artifacts/
+.crew/worktrees/
+.crew/imports/
+
+# legacy layout
 .pi/teams/state/
 .pi/teams/artifacts/
 .pi/teams/worktrees/
@@ -597,14 +638,26 @@ Export writes:
 {artifactsRoot}/export/run-export.md
 ```
 
-Import stores bundles under:
+Import stores bundles under (new layout):
+
+```text
+.crew/imports/{runId}/run-export.json
+.crew/imports/{runId}/README.md
+```
+
+or under the legacy layout when `.pi/` already exists:
 
 ```text
 .pi/teams/imports/{runId}/run-export.json
 .pi/teams/imports/{runId}/README.md
 ```
 
-or user-global imports with `--user`.
+or user-global imports with `--user`:
+
+```text
+~/.pi/agent/extensions/pi-crew/imports/{runId}/run-export.json
+~/.pi/agent/extensions/pi-crew/imports/{runId}/README.md
+```
 
 ## Doctor and validation
 

package/docs/architecture.md

@@ -12,12 +12,14 @@ Runtime layer
   team runner, task graph scheduler, child Pi process runner, async runner,
   model fallback, policy engine, worktree manager, live-session experimental path
 
-State layer
-  .pi/teams/state/runs/{runId}/manifest.json
-  .pi/teams/state/runs/{runId}/tasks.json
-  .pi/teams/state/runs/{runId}/events.jsonl
-  .pi/teams/state/runs/{runId}/agents/{taskId}/status.json
-  .pi/teams/artifacts/{runId}/...
+State layer (project root resolves to <crewRoot>:
+  - .crew/             when no .pi/ exists in the repo (default)
+  - .pi/teams/         when the repo already has .pi/ (legacy reuse))
+  <crewRoot>/state/runs/{runId}/manifest.json
+  <crewRoot>/state/runs/{runId}/tasks.json
+  <crewRoot>/state/runs/{runId}/events.jsonl
+  <crewRoot>/state/runs/{runId}/agents/{taskId}/status.json
+  <crewRoot>/artifacts/{runId}/...
 ```
 
 ## Run flow
@@ -104,10 +106,10 @@ Model choice is based on Pi's current configuration/model registry, not hardcode
 
 ## State layer
 
-Run state is under:
+Run state is under `<crewRoot>` (`.crew/` for new projects, or `.pi/teams/` when the repo already has `.pi/`):
 
 ```text
-.pi/teams/state/runs/{runId}/
+<crewRoot>/state/runs/{runId}/
   manifest.json        run metadata/status/artifacts/async pid
   tasks.json           task graph and per-task status
   events.jsonl         append-only run events
@@ -125,7 +127,7 @@ Run state is under:
 Artifacts are under:
 
 ```text
-.pi/teams/artifacts/{runId}/
+<crewRoot>/artifacts/{runId}/
   goal.md
   prompts/{taskId}.md
   results/{taskId}.txt
@@ -136,6 +138,13 @@ Artifacts are under:
   summary.md
 ```
 
+`<crewRoot>` resolution is centralised in `src/utils/paths.ts#projectCrewRoot()`:
+
+- if `<repoRoot>/.pi/` already exists, return `<repoRoot>/.pi/teams/` (legacy reuse, no parallel `.crew/`)
+- otherwise return `<repoRoot>/.crew/` (default for fresh projects)
+
+User-global fallback (when no project root is detected) lives under `~/.pi/agent/extensions/pi-crew/`.
+
 Atomic writes use temp-file replace with retry for transient Windows `EPERM`/`EBUSY`/`EACCES`. JSONL append paths are best-effort where used for observers/progress; write failures must not crash child output parsing.
 
 ## UI and observability

package/docs/refactor-tasks-phase3.md

@@ -278,7 +278,7 @@ export const MAX_PARALLEL_CONCURRENCY: number;
 **Source**: `source/pi-subagents/artifacts.ts` (hàm `cleanupOldArtifacts`)
 **Đích**: bổ sung vào `pi-crew/src/state/artifact-store.ts`
 
-**Lý do**: Pi-crew `.pi/teams/state/artifacts/` không có TTL → run cũ tích lũy mãi. Pattern subagents:
+**Lý do**: Pi-crew `<crewRoot>/state/artifacts/` (`<crewRoot>` = `.crew/` mới hoặc `.pi/teams/` legacy) không có TTL → run cũ tích lũy mãi. Pattern subagents:
 - File `.last-cleanup` chứa timestamp.
 - Nếu marker mới hơn 24h → skip (không scan dir lớn mỗi extension load).
 - Nếu cần scan: xoá file mtime > `maxAgeDays * 24h`.

package/docs/research-extension-examples.md

@@ -0,0 +1,297 @@
+# 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
+  },
+});
+```