pi-crew 0.9.12 → 0.9.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/config/defaults.ts

@@ -15,7 +15,9 @@ export const DEFAULT_CHILD_PI: Readonly<{
 	// Child workers can spend more than a few seconds in provider calls or long-running tools without emitting stdout.
 	// Keep this as a coarse stuck-worker guard rather than a short per-message latency budget.
 	responseTimeoutMs: 5 * 60_000,
-	maxCaptureBytes: 256 * 1024,
+	// #3 unresponsive worker hardening: increased from 256KB to 512KB so critical
+	// diagnostic stderr is less likely to be silently truncated during hang analysis.
+	maxCaptureBytes: 512 * 1024,
 	// L4 output-handling: thresholds sized from real worker-output data
 	// (27 result artifacts measured: max 9226 bytes, median 8272, 100% < 16KB).
 	// Previous values (8192/1024/4096) truncated 62% of real results.

package/src/extension/knowledge-injection.ts

@@ -9,6 +9,16 @@
  * Philosophy (Round 6 stress-test): radically downsized. Just a Markdown
  * file the user can edit, surfaced into every run. No vector DB, no
  * embeddings, no graph. Simple = trustworthy.
+ *
+ * B2 section-aware injection (2026-06-28): knowledge.md splits cleanly into
+ * CONVENTIONS (always-relevant: Code Style, Environment, Architecture,
+ * Testing, Release Process — ~2.5KB) and SESSION-LOG (per-version post-
+ * mortems, incidents, fix detail — ~29KB, rarely relevant). Conventions
+ * are ALWAYS injected; session-log sections are injected on-demand via
+ * header-token IDF scoring against the task/goal, capped at
+ * MAX_SESSION_LOG_BYTES. Non-matched session-log is summarized as a section
+ * index with a `read` path-hint so the worker can recover any omitted topic.
+ * Design doc: research-findings/b2-section-aware-design.md.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -17,20 +27,179 @@ import { projectCrewRoot } from "../utils/paths.ts";
 
 /** The knowledge file, relative to the project crew root. */
 export const KNOWLEDGE_FILENAME = "knowledge.md";
-/** Cap injected knowledge to avoid unbounded system-prompt growth. */
-const MAX_KNOWLEDGE_BYTES = 16_000;
+
+/**
+ * Session-log injection cap (B2). Conventions are always injected in full;
+ * matched session-log sections are capped here to bound total prompt size.
+ * Sized so 2-3 typical sections (~1-2.5KB each) fit, while the largest single
+ * outlier (v0.9.10 IN PROGRESS, ~7KB) is excluded from a full-match scenario.
+ */
+const MAX_SESSION_LOG_BYTES = 5_000;
+
+/**
+ * Relevance context for section-aware injection. When omitted (or when goal/
+ * taskText are both absent), injection falls back to conventions-only — no
+ * IDF computation, no session-log body. This keeps callers without query
+ * context (main-session hook, legacy tests) stable.
+ */
+export interface KnowledgeQuery {
+	/** The team run goal (broad topic signal). */
+	goal?: string;
+	/** The step/task instruction text (narrow topic signal). */
+	taskText?: string;
+	/** The worker role (reserved for future role-floor/boost; not scored yet). */
+	role?: string;
+}
+
+/**
+ * Headers of sections always treated as CONVENTIONS (universal project rules).
+ * Anything NOT matching these (after the convention run) is SESSION-LOG.
+ * Header-matching is prefix + case-insensitive against the H2 title.
+ */
+const CONVENTION_HEADERS = ["Code Style", "Environment", "Architecture", "Testing", "Release Process"];
 
 /** Resolve the knowledge file path for a cwd (may not exist yet). */
 export function knowledgePath(cwd: string): string {
 	return path.join(projectCrewRoot(cwd), KNOWLEDGE_FILENAME);
 }
 
-/** Read knowledge content, truncated to a safe size. "" if absent/empty. */
-export function readKnowledge(cwd: string): string {
+interface KnowledgeSection {
+	/** H2 header text (without leading `## `). */
+	header: string;
+	/** Full section body including the `## ` header line. */
+	body: string;
+	/** Header tokens (lowercased, stopword-filtered) for IDF scoring. */
+	headerTokens: Set<string>;
+}
+
+const STOPWORDS = new Set([
+	"the", "a", "an", "is", "are", "of", "to", "in", "for", "and", "or", "not",
+	"with", "this", "that", "it", "be", "on", "at", "by", "do", "does", "how",
+	"what", "when", "from", "fix", "fixes", "fixed", "v0", "v1", "released",
+	"progress", "uncommitted", "not", "pushed", "published", "session", "post",
+]);
+
+/** Tokenize header text into a Set of lowercased non-stopword tokens. */
+function tokenizeHeader(header: string): Set<string> {
+	const tokens = new Set<string>();
+	for (const raw of header.toLowerCase().split(/[^a-z0-9.]+/)) {
+		// keep dot-paths (e.g. "run.lock", "config.ts") and alphanumerics >= 2 chars
+		const t = raw.replace(/^\.+|\.+$/g, "");
+		if (t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t)) tokens.add(t);
+	}
+	return tokens;
+}
+
+/** Parse knowledge.md into (conventions, sessionLog) sections by H2 header. */
+function parseKnowledgeSections(content: string): { conventions: KnowledgeSection[]; sessionLog: KnowledgeSection[] } {
+	const lines = content.split(/\r?\n/);
+	const sections: KnowledgeSection[] = [];
+	let current: { header: string; lines: string[] } | null = null;
+	for (const line of lines) {
+		const m = /^##\s+(.+?)\s*$/.exec(line);
+		if (m) {
+			if (current) sections.push({ header: current.header, body: current.lines.join("\n"), headerTokens: tokenizeHeader(current.header) });
+			current = { header: m[1]!, lines: [line] };
+		} else if (current) {
+			current.lines.push(line);
+		}
+	}
+	if (current) sections.push({ header: current.header, body: current.lines.join("\n"), headerTokens: tokenizeHeader(current.header) });
+
+	// Classify: a section is a CONVENTION if its header starts-with one of the
+	// known convention titles. Once we leave the convention run (first non-
+	// matching H2 after conventions), everything else is SESSION-LOG. This is
+	// self-healing: if knowledge.md is restructured, the classifier adapts.
+	const conventions: KnowledgeSection[] = [];
+	const sessionLog: KnowledgeSection[] = [];
+	let leftConventionRun = false;
+	for (const sec of sections) {
+		const isConvention = !leftConventionRun && CONVENTION_HEADERS.some((c) => sec.header.toLowerCase().startsWith(c.toLowerCase()));
+		if (isConvention) conventions.push(sec);
+		else {
+			leftConventionRun = true;
+			sessionLog.push(sec);
+		}
+	}
+	return { conventions, sessionLog };
+}
+
+/** Compute IDF (inverse document frequency) over session-log header tokens. */
+function computeIdf(sections: KnowledgeSection[]): Map<string, number> {
+	const N = sections.length;
+	const df = new Map<string, number>();
+	for (const s of sections) for (const token of s.headerTokens) df.set(token, (df.get(token) ?? 0) + 1);
+	const idf = new Map<string, number>();
+	for (const [token, freq] of df) idf.set(token, Math.log(N / freq)); // standard IDF; freq >= 1
+	return idf;
+}
+
+/** Tokenize a free-form query (goal/taskText) the same way as headers. */
+function tokenizeQuery(query: string): Set<string> {
+	const tokens = new Set<string>();
+	for (const raw of query.toLowerCase().split(/[^a-z0-9.]+/)) {
+		const t = raw.replace(/^\.+|\.+$/g, "");
+		if (t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t)) tokens.add(t);
+	}
+	return tokens;
+}
+
+/** Score a section by summed IDF of query tokens present in its header. */
+function scoreSection(queryTokens: Set<string>, headerTokens: Set<string>, idf: Map<string, number>): number {
+	let score = 0;
+	for (const token of queryTokens) if (headerTokens.has(token)) score += idf.get(token) ?? 0;
+	return score;
+}
+
+/**
+ * Select session-log sections relevant to the query, capped at budgetBytes.
+ * Greedy by descending score (then original order), drop-whole policy with a
+ * head-slice fallback for the single best match if nothing else fits (so a
+ * matched query never returns zero bytes).
+ */
+function selectSessionLog(query: string, sessionLog: KnowledgeSection[], budgetBytes: number): KnowledgeSection[] {
+	if (sessionLog.length === 0 || !query.trim()) return [];
+	const idf = computeIdf(sessionLog);
+	const queryTokens = tokenizeQuery(query);
+	// Match = ANY header-token overlap with the query. IDF still drives RANKING
+	// (rarer overlap ranks first), but a token that happens to appear in every
+	// section (IDF=0) must still count as a match — otherwise a query for a
+	// common-but-relevant keyword (e.g. "redaction") would return nothing.
+	const scored = sessionLog
+		.map((sec, idx) => {
+			const overlap = [...queryTokens].filter((t) => sec.headerTokens.has(t));
+			return { sec, score: overlap.reduce((sum, t) => sum + (idf.get(t) ?? 0), 0), idx, hasOverlap: overlap.length > 0 };
+		})
+		.filter((x) => x.hasOverlap);
+	if (scored.length === 0) return [];
+	scored.sort((a, b) => b.score - a.score || a.idx - b.idx);
+
+	const selected: KnowledgeSection[] = [];
+	let used = 0;
+	let bestMatch: { sec: KnowledgeSection; score: number } | undefined;
+	for (const { sec, score } of scored) {
+		if (score > (bestMatch?.score ?? -1)) bestMatch = { sec, score };
+		if (used + sec.body.length <= budgetBytes) {
+			selected.push(sec);
+			used += sec.body.length;
+		}
+	}
+	// Head-slice fallback: if the best match didn't fit (or nothing fit), inject
+	// a head-sliced copy of the single best match so the query isn't empty.
+	if (selected.length === 0 && bestMatch) {
+		const sliced = bestMatch.sec.body.slice(0, Math.max(0, budgetBytes));
+		selected.push({ ...bestMatch.sec, body: `${sliced}\n\n<!-- section truncated (session-log budget ${budgetBytes} bytes). Full file: use \`read\`. -->` });
+	}
+	return selected;
+}
+
+/** Read knowledge content. "" if absent/empty. */
+export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 	try {
 		const p = knowledgePath(cwd);
 		const stat = tryStat(p);
 		if (!stat) {
+			sectionCache.delete(p);
 			knowledgeCache.delete(p);
 			return "";
 		}
@@ -39,14 +208,46 @@ export function readKnowledge(cwd: string): string {
 		// For a run with N workers this is N redundant readFileSync of the same
 		// file. Cache by (mtimeMs, size) and only re-read when the file changes.
 		const cacheKey = `${stat.mtimeMs}:${stat.size}`;
-		const cached = knowledgeCache.get(p);
-		if (cached && cached.key === cacheKey) return cached.content;
-		let content = fs.readFileSync(p, "utf8").trim();
-		if (content.length > MAX_KNOWLEDGE_BYTES) {
-			content = `${content.slice(0, MAX_KNOWLEDGE_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_BYTES} bytes -->`;
+
+		// B2: when no query context is provided (main-session hook, legacy
+		// callers, tests), keep the simple head-only path. This preserves the
+		// 4 existing unit tests exactly (they call readKnowledge(cwd)).
+		if (!query || (!query.goal && !query.taskText)) {
+			const cached = knowledgeCache.get(p);
+			if (cached && cached.key === cacheKey) return cached.content;
+			let content = fs.readFileSync(p, "utf8").trim();
+			if (content.length > MAX_KNOWLEDGE_HEAD_BYTES) {
+				content = `${content.slice(0, MAX_KNOWLEDGE_HEAD_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_HEAD_BYTES} bytes (head shown). Full file: ${p} — use the \`read\` tool if you need sections beyond the head. -->`;
+			}
+			knowledgeCache.set(p, { key: cacheKey, content });
+			return content;
+		}
+
+		// Section-aware path: cache parsed sections, select per-query.
+		const cachedSections = sectionCache.get(p);
+		let parsed: { conventions: KnowledgeSection[]; sessionLog: KnowledgeSection[] };
+		if (cachedSections && cachedSections.key === cacheKey) {
+			parsed = { conventions: cachedSections.conventions, sessionLog: cachedSections.sessionLog };
+		} else {
+			const content = fs.readFileSync(p, "utf8").trim();
+			parsed = parseKnowledgeSections(content);
+			sectionCache.set(p, { key: cacheKey, conventions: parsed.conventions, sessionLog: parsed.sessionLog });
+		}
+
+		const queryText = [query.goal, query.taskText].filter(Boolean).join(" \n ");
+		const matchedSessionLog = selectSessionLog(queryText, parsed.sessionLog, MAX_SESSION_LOG_BYTES);
+
+		const parts: string[] = [];
+		// Conventions: always full.
+		for (const sec of parsed.conventions) parts.push(sec.body);
+		// Matched session-log (drop-whole, budget-capped).
+		for (const sec of matchedSessionLog) parts.push(sec.body);
+		// Always: section-index of ALL session-log headers (recovery safety net).
+		if (parsed.sessionLog.length > 0) {
+			const indexLines = parsed.sessionLog.map((s) => `  - ${s.header}`);
+			parts.push(`<!-- Session-log sections in knowledge.md (not injected unless matched above — use \`read\` for detail):\n${indexLines.join("\n")}\nFull file: ${p} -->`);
 		}
-		knowledgeCache.set(p, { key: cacheKey, content });
-		return content;
+		return parts.join("\n").trim();
 	} catch {
 		return "";
 	}
@@ -68,9 +269,19 @@ interface CachedKnowledge {
 }
 const knowledgeCache = new Map<string, CachedKnowledge>();
 
+interface CachedSections {
+	key: string;
+	conventions: KnowledgeSection[];
+	sessionLog: KnowledgeSection[];
+}
+const sectionCache = new Map<string, CachedSections>();
+
+/** Head cap for the no-query (legacy / main-session) path. */
+const MAX_KNOWLEDGE_HEAD_BYTES = 2_000;
+
 /** Build the injected prompt fragment (empty if no knowledge). */
-export function buildKnowledgeFragment(cwd: string): string {
-	const content = readKnowledge(cwd);
+export function buildKnowledgeFragment(cwd: string, query?: KnowledgeQuery): string {
+	const content = readKnowledge(cwd, query);
 	if (!content) return "";
 	return [
 		"",
@@ -85,8 +296,18 @@ export function buildKnowledgeFragment(cwd: string): string {
 
 /**
  * Register the knowledge-injection hook. Appends project knowledge to the
- * system prompt on every agent start (main session + each crew worker,
- * since workers are child Pi processes that also fire before_agent_start).
+ * MAIN session's system prompt on `before_agent_start`. This hook does NOT
+ * fire for crew workers: they are spawned with `--no-extensions`, so the
+ * extension layer (and this hook) never loads in their process. Workers
+ * instead receive knowledge via `buildKnowledgeFragment(task.cwd)` injected
+ * into their prompt stablePrefix by `prompt-builder.ts`. Do NOT "fix" this
+ * perceived gap by making the hook reach workers — it would cause
+ * double-injection. (Verified by research workflow 2026-06-28.)
+ *
+ * The hook calls buildKnowledgeFragment(cwd) with NO query — so the main
+ * session gets conventions-only (no session-log noise), which is the right
+ * default for an interactive session that doesn't have a single task focus.
+ * Workers (which DO have a task) use the section-aware path via prompt-builder.
  */
 export function registerKnowledgeInjection(pi: ExtensionAPI): void {
 	pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {

package/src/extension/pi-api.ts

@@ -44,4 +44,4 @@ export { defineTool, createBashTool } from "@earendil-works/pi-coding-agent";
  * and to surface version-drift if Pi upgrades introduce breaking changes.
  * Update this when bumping the pi-coding-agent dependency.
  */
-export const BUILT_AGAINST_PI_VERSION = "0.79.3";
+export const BUILT_AGAINST_PI_VERSION = "0.77.0";

package/src/extension/team-tool/chain-dispatch.ts

@@ -0,0 +1,103 @@
+/**
+ * Team-tool entry point for the `chain` feature.
+ *
+ * Dispatched from `handleRun` (run.ts) via an early-return guard:
+ *   if (params.chain) → handleChainRun(params, ctx, handleRun)
+ *
+ * `handleRun` is passed by reference (NOT imported) to break the
+ * run.ts ↔ chain-dispatch.ts import cycle. This file imports only
+ * chain-runner, handoff-manager, chain-executor, and the shared
+ * tool-result helpers — none of which import run.ts.
+ *
+ * @see src/extension/team-tool/chain-executor.ts (ChainTeamRunExecutor)
+ * @see src/runtime/chain-runner.ts (ChainRunner.runChain, parseChainString)
+ */
+
+import { ChainRunner, parseChainString } from "../../runtime/chain-runner.ts";
+import { HandoffManager } from "../../runtime/handoff-manager.ts";
+import { ChainTeamRunExecutor, type HandleRunFn } from "./chain-executor.ts";
+import { result, type TeamContext } from "./context.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+
+/**
+ * Execute a chain expression (`"a -> b -> c"`). Each step runs a real team run
+ * via the injected `handleRun`, with handoff context passed forward through the
+ * goal text. Returns a multi-line summary plus structured `data` for the TUI.
+ *
+ * @param params  - Must contain `chain`. `team`/`workflow`/`model` are forwarded
+ *                  as per-step overrides when a step does not declare its own.
+ * @param ctx     - The team tool context (cwd is used to load run manifests).
+ * @param handleRun - The run.ts `handleRun` function reference (injected).
+ */
+export async function handleChainRun(
+	params: TeamToolParamsValue,
+	ctx: TeamContext,
+	handleRun: HandleRunFn,
+): Promise<PiTeamsToolResult> {
+	const chainString = params.chain;
+	if (!chainString || chainString.trim().length === 0) {
+		return result("Chain expression is empty.", { action: "run", status: "error" }, true);
+	}
+
+	const spec = parseChainString(chainString);
+	if (spec.steps.length === 0) {
+		return result(
+			"Chain must contain at least one step. Use the form: \"step1 -> step2 -> step3\".",
+			{ action: "run", status: "error" },
+			true,
+		);
+	}
+
+	// Construct the concrete executor with per-step overrides forwarded from the
+	// chain invocation (overridden by any step that parsed to a @team reference).
+	const executor = new ChainTeamRunExecutor({
+		handleRun,
+		ctx,
+		overrides: {
+			team: params.team,
+			workflow: params.workflow,
+			model: params.model,
+		},
+	});
+
+	// Surface the global continueOnError from the parsed spec (e.g. --continue-on-error=true).
+	const runner = new ChainRunner(executor, new HandoffManager());
+	const chainResult = await runner.runChain(spec, {}, undefined);
+
+	// Build a readable multi-line summary.
+	const lines: string[] = [
+		`Chain ${chainResult.success ? "completed" : "ended"}: ${spec.steps.length} step(s), ${chainResult.totalHandoffs.length} handoff(s).`,
+		"",
+	];
+	for (const s of chainResult.steps) {
+		const runId = executor.stepRunIds[s.step - 1];
+		const tag =
+			s.outcome === "success" ? "✓"
+			: s.outcome === "failure" ? "✗"
+			: s.outcome === "partial" ? "≈"
+			: "⊘";
+		lines.push(
+			`${tag} Step ${s.step} [${s.name}]: ${s.outcome} (${s.duration}ms)${runId ? ` runId=${runId}` : ""}${s.error ? ` | ${s.error}` : ""}`,
+		);
+	}
+	lines.push("");
+	lines.push(
+		`Total: ${chainResult.totalDuration}ms${chainResult.totalTokens !== undefined ? `, ${chainResult.totalTokens} tokens` : ""}`,
+	);
+
+	return result(
+		lines.join("\n"),
+		{
+			action: "run",
+			status: chainResult.success ? "ok" : "error",
+			data: {
+				chain: true,
+				steps: chainResult.steps.length,
+				totalTokens: chainResult.totalTokens,
+				runIds: executor.stepRunIds,
+			},
+		},
+		!chainResult.success,
+	);
+}