pi-crew 0.5.25 → 0.6.1

package/src/runtime/child-pi.ts

@@ -424,7 +424,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			return { exitCode: 1, stdout: "", stderr: "Mock mode requires PI_CREW_ALLOW_MOCK=1" };
 		}
 		// SECURITY: Log mock mode activation prominently for audit trail
-		console.warn(`Mock mode active: ${mock} — NOT running real agents!`);
+		logInternalError("child-pi.mock", new Error(`Mock mode active: ${mock}`), "NOT running real agents");
 		if (mock === "success") {
 			const stdout = `[MOCK] Success for ${input.agent.name}\n`;
 			observeStdoutChunk(input, stdout);

package/src/runtime/crew-agent-records.ts

@@ -249,8 +249,8 @@ export function writeCrewAgentStatusCoalesced(manifest: TeamRunManifest, record:
 	atomicWriteJsonCoalesced(agentStatusPath(manifest, record.taskId), redactSecrets(record), AGENT_COALESCE_MS);
 }
 
-/** Flush all coalesced agent writes synchronously. Hook into cleanup paths. */
-export function flushPendingAgentWrites(): void {
+/** @internal Flush all coalesced agent writes synchronously. Hook into cleanup paths. */
+function flushPendingAgentWrites(): void {
 	flushPendingAtomicWrites();
 }
 
@@ -353,7 +353,8 @@ export interface CrewAgentEventCursorOptions {
 	limit?: number;
 }
 
-export function readCrewAgentEvents(manifest: TeamRunManifest, taskId: string): unknown[] {
+/** @internal Convenience wrapper around readCrewAgentEventsCursor. */
+function readCrewAgentEvents(manifest: TeamRunManifest, taskId: string): unknown[] {
 	return readCrewAgentEventsCursor(manifest, taskId).events;
 }
 

package/src/runtime/cross-extension-rpc.ts

@@ -29,15 +29,19 @@ function handleRpc<P extends { requestId: string }>(
 ): () => void {
 	return events.on(channel, async (raw: unknown) => {
 		const params = raw as P;
+		// SECURITY: Validate requestId format to prevent channel injection.
+		if (!/^[a-zA-Z0-9_-]+$/.test(params.requestId)) {
+			throw new Error("Security: invalid requestId format");
+		}
 		try {
 			const data = await fn(params);
 			const reply: { success: true; data?: unknown } = { success: true };
 			if (data !== undefined) reply.data = data;
 			events.emit(`${channel}:reply:${params.requestId}`, reply);
-		} catch (err: any) {
+		} catch (err: unknown) {
 			events.emit(`${channel}:reply:${params.requestId}`, {
 				success: false,
-				error: err?.message ?? String(err),
+				error: err instanceof Error ? err.message : String(err),
 			});
 		}
 	});
@@ -50,21 +54,43 @@ export function registerCrewRpcHandlers(deps: RpcDeps): RpcHandle {
 		return { version: PROTOCOL_VERSION };
 	});
 
-	const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: Record<string, unknown> }>(
+	// SECURITY TRUST BOUNDARY: crew:rpc:spawn and crew:rpc:stop are privileged
+	// operations that create or terminate child processes. Any subscriber on
+	// the shared event bus can emit these events. In a multi-extension
+	// environment, this means a malicious extension could spawn/stop agents.
+	// Mitigation: validate that the caller is the pi-crew extension by checking
+	// the request includes a known extension identifier. Log all invocations
+	// for audit. A full fix requires event-bus-level origin signing.
+	const CREW_RPC_SOURCE = "pi-crew";
+
+	function validateRpcSource(params: { requestId: string; source?: string }): boolean {
+		if (!params.source || params.source !== CREW_RPC_SOURCE) {
+			console.warn(
+				`[pi-crew SECURITY] RPC invocation from unexpected source: ${params.source ?? "(none)"}. ` +
+				`Expected '${CREW_RPC_SOURCE}'. Request may be from an untrusted extension.`,
+			);
+			return false;
+		}
+		return true;
+	}
+
+	const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: Record<string, unknown>; source?: string }>(
 		events,
 		"crew:rpc:spawn",
-		({ type, prompt, options }) => {
+		(params) => {
+			if (!validateRpcSource(params)) throw new Error("Unauthorized: RPC spawn requires source='pi-crew'");
 			const ctx = getCtx();
 			if (!ctx) throw new Error("No active session");
-			return { id: spawn(type, prompt, options ?? {}) };
+			return { id: spawn(params.type, params.prompt, params.options ?? {}) };
 		},
 	);
 
-	const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
+	const unsubStop = handleRpc<{ requestId: string; agentId: string; source?: string }>(
 		events,
 		"crew:rpc:stop",
-		({ agentId }) => {
-			if (!abort(agentId)) throw new Error("Agent not found");
+		(params) => {
+			if (!validateRpcSource(params)) throw new Error("Unauthorized: RPC stop requires source='pi-crew'");
+			if (!abort(params.agentId)) throw new Error("Agent not found");
 		},
 	);
 

package/src/runtime/diagnostic-export.ts

@@ -9,9 +9,9 @@ import { loadRunManifestById } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { summarizeHeartbeats, type HeartbeatSummary } from "../ui/heartbeat-aggregator.ts";
 import type { RunUiSnapshot } from "../ui/snapshot-types.ts";
-import { redactSecrets } from "../utils/redaction.ts";
+import { redactSecrets, isSecretKey } from "../utils/redaction.ts";
 import { buildRecoveryLedger, type RecoveryLedgerEntry } from "./recovery-recipes.ts";
-export { redactSecrets } from "../utils/redaction.ts";
+export { redactSecrets, isSecretKey } from "../utils/redaction.ts";
 
 export interface DiagnosticReport {
 	schemaVersion?: number;
@@ -37,13 +37,12 @@ export interface DiagnosticReport {
 	recoveryLedger: RecoveryLedgerEntry[];
 }
 
-const SECRET_KEY_PATTERN = /(token|key|password|secret|credential|auth)/i;
 const ENV_DEBUG_ALLOWLIST = /^(PI_CREW_|PI_TEAMS_|PI_.*HOME|NODE_ENV|NODE_VERSION|OS|PROCESSOR|TERM|LANG|HOME|USERPROFILE|APPDATA|PLATFORM|ARCH|WIN32|DOCKER|CI|VERBOSE|DEBUG|NO_COLOR|FORCE_COLOR|NPM_CONFIG|npm_)/i;
 
 function envRedacted(): Record<string, string> {
 	const output: Record<string, string> = {};
 	for (const [key, value] of Object.entries(process.env)) {
-		if (SECRET_KEY_PATTERN.test(key)) output[key] = "***";
+		if (isSecretKey(key)) output[key] = "***";
 		else if (typeof value === "string" && ENV_DEBUG_ALLOWLIST.test(key)) output[key] = value;
 		// All other env vars are omitted to prevent leaking sensitive paths or system topology.
 	}

package/src/runtime/dynamic-script-runner.ts

@@ -484,11 +484,11 @@ export function createScriptRunner(options?: DynamicScriptOptions): DynamicScrip
 /**
  * @internal TEST ONLY — do not use in production code.
  * Exposes DynamicScriptRunner.executeUnchecked for unit testing.
+ * Returns undefined in non-test environments to prevent production use.
  */
-export function __test_executeUnchecked(
-	runner: DynamicScriptRunner,
-	code: string,
-	timeout?: number,
-): ScriptExecutionResult {
-	return (runner as unknown as { executeUnchecked: (code: string, timeout?: number) => ScriptExecutionResult }).executeUnchecked(code, timeout);
-}
+export const __test_executeUnchecked: ((runner: DynamicScriptRunner, code: string, timeout?: number) => ScriptExecutionResult) | undefined =
+	process.env.NODE_ENV === "test"
+		? (runner: DynamicScriptRunner, code: string, timeout?: number): ScriptExecutionResult => {
+			return (runner as unknown as { executeUnchecked: (code: string, timeout?: number) => ScriptExecutionResult }).executeUnchecked(code, timeout);
+		}
+		: undefined;

package/src/runtime/foreground-watchdog.ts

@@ -41,8 +41,8 @@ export function stopWatchdog(runId: string): void {
 	}
 }
 
-/** Stop all active watchdogs. Called on session shutdown. */
-export function stopAllWatchdogs(): void {
+/** @internal Stop all active watchdogs. Called on session shutdown. */
+function stopAllWatchdogs(): void {
 	for (const [runId, timer] of activeWatchdogs) {
 		clearTimeout(timer);
 	}

package/src/runtime/intercom-bridge.ts

@@ -0,0 +1,178 @@
+/**
+ * Intercom bridge — workers can escalate questions to the orchestrator.
+ *
+ * Pattern origin: pi-subagents/src/intercom-bridge.ts — contact_supervisor tool
+ * for child agents to escalate decisions, report progress, or ask questions.
+ *
+ * This module provides the message queue and correlation logic.
+ * The actual tool registration happens in task-runner.ts.
+ */
+
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type IntercomUrgency = "low" | "medium" | "high" | "critical";
+export type IntercomType = "question" | "escalation" | "progress" | "block";
+
+export interface IntercomMessage {
+	type: IntercomType;
+	taskStepId: string;
+	content: string;
+	urgency: IntercomUrgency;
+	timestamp: number;
+	timeout?: number; // ms to wait for response
+}
+
+export interface IntercomResponse {
+	answer: string;
+	source: "orchestrator" | "human" | "timeout";
+	timestamp: number;
+	messageId: string;
+}
+
+// ── Message Queue ────────────────────────────────────────────────────────
+
+interface PendingMessage {
+	message: IntercomMessage;
+	id: string;
+	resolve: (response: IntercomResponse) => void;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+const MAX_QUEUE_SIZE = 100;
+
+/**
+ * In-process intercom queue for worker→orchestrator communication.
+ *
+ * Each message gets a unique ID. Callers await a response via a Promise.
+ * If no response arrives within the timeout, resolves with source="timeout".
+ */
+export class IntercomQueue {
+	private pending = new Map<string, PendingMessage>();
+	private queue: IntercomMessage[] = [];
+
+	/**
+	 * Enqueue a message and return a promise that resolves when the
+	 * orchestrator responds (or times out).
+	 */
+	enqueue(message: IntercomMessage): Promise<IntercomResponse> {
+		if (this.pending.size >= MAX_QUEUE_SIZE) {
+			// Evict oldest
+			const firstKey = this.pending.keys().next().value;
+			if (firstKey) this.evict(firstKey, "queue_full");
+		}
+
+		const id = `icm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+
+		return new Promise<IntercomResponse>((resolve) => {
+			const entry: PendingMessage = { message, id, resolve };
+
+			// Set timeout if specified
+			if (message.timeout && message.timeout > 0) {
+				entry.timer = setTimeout(() => {
+					resolve({
+						answer: "No response received within timeout",
+						source: "timeout",
+						timestamp: Date.now(),
+						messageId: id,
+					});
+					this.pending.delete(id);
+				}, message.timeout);
+			}
+
+			this.pending.set(id, entry);
+			this.queue.push({ ...message });
+		});
+	}
+
+	/**
+	 * Respond to a pending message by ID.
+	 */
+	respond(messageId: string, answer: string, source: "orchestrator" | "human" = "orchestrator"): boolean {
+		const entry = this.pending.get(messageId);
+		if (!entry) return false;
+
+		if (entry.timer) clearTimeout(entry.timer);
+
+		entry.resolve({
+			answer,
+			source,
+			timestamp: Date.now(),
+			messageId,
+		});
+
+		this.pending.delete(messageId);
+		return true;
+	}
+
+	/**
+	 * Get all pending messages (for orchestrator to process).
+	 */
+	getPending(): Array<IntercomMessage & { id: string }> {
+		return [...this.pending.entries()].map(([id, entry]) => ({
+			...entry.message,
+			id,
+		}));
+	}
+
+	/**
+	 * Number of pending messages awaiting response.
+	 */
+	get pendingCount(): number {
+		return this.pending.size;
+	}
+
+	/**
+	 * Clean up all pending messages (e.g., on run completion).
+	 */
+	clear(): void {
+		for (const [id, entry] of this.pending) {
+			this.evict(id, "run_complete");
+		}
+		this.queue = [];
+	}
+
+	private evict(id: string, reason: string): void {
+		const entry = this.pending.get(id);
+		if (!entry) return;
+
+		if (entry.timer) clearTimeout(entry.timer);
+
+		entry.resolve({
+			answer: `Message evicted: ${reason}`,
+			source: "timeout",
+			timestamp: Date.now(),
+			messageId: id,
+		});
+
+		this.pending.delete(id);
+	}
+}
+
+// ── Singleton per run ────────────────────────────────────────────────────
+
+const queues = new Map<string, IntercomQueue>();
+
+/**
+ * Get or create an intercom queue for a run.
+ */
+export function getIntercomQueue(runId: string): IntercomQueue {
+	let queue = queues.get(runId);
+	if (!queue) {
+		queue = new IntercomQueue();
+		queues.set(runId, queue);
+	}
+	return queue;
+}
+
+/**
+ * Clean up intercom queue for a completed run.
+ */
+export function cleanupIntercomQueue(runId: string): void {
+	const queue = queues.get(runId);
+	if (queue) {
+		queue.clear();
+		queues.delete(runId);
+	}
+}

package/src/runtime/live-agent-manager.ts

@@ -81,7 +81,8 @@ export function listLiveAgentsByWorkspace(workspaceId: string): LiveAgentHandle[
 /**
  * List only active agents (running/queued/waiting) for a specific workspace.
  */
-export function listActiveLiveAgentsByWorkspace(workspaceId: string): LiveAgentHandle[] {
+/** @internal */
+function listActiveLiveAgentsByWorkspace(workspaceId: string): LiveAgentHandle[] {
 	return listActiveLiveAgents().filter((a) => a.workspaceId === workspaceId);
 }
 
@@ -150,7 +151,8 @@ function safeDisposeLiveSession(handle: LiveAgentHandle): void {
 	}
 }
 
-export function removeLiveAgentHandle(agentId: string): LiveAgentHandle | undefined {
+/** @internal */
+function removeLiveAgentHandle(agentId: string): LiveAgentHandle | undefined {
 	const handle = liveAgents.get(agentId);
 	if (!handle) return undefined;
 	liveAgents.delete(agentId);
@@ -406,7 +408,8 @@ export function broadcastIrcMessage(fromAgentId: string, message: IrcMessage): s
 }
 
 /** Phase 7: Get pending IRC messages for an agent (and clear them). */
-export function drainIrcMessages(agentIdOrTaskId: string): IrcMessage[] {
+/** @internal */
+function drainIrcMessages(agentIdOrTaskId: string): IrcMessage[] {
 	const handle = getLiveAgent(agentIdOrTaskId);
 	if (!handle) return [];
 	const messages = [...handle.pendingMessages];

package/src/runtime/live-irc.ts

@@ -51,7 +51,8 @@ export function renderIrcPeerRoster(selfId: string, peers: Array<{ agentId: stri
 /**
  * Build the IRC system prompt section for a live-session worker.
  */
-export function buildIrcSystemSection(selfId: string, peers: Array<{ agentId: string; status: string }>): string {
+/** @internal */
+function buildIrcSystemSection(selfId: string, peers: Array<{ agentId: string; status: string }>): string {
 	const roster = renderIrcPeerRoster(selfId, peers);
 	return [
 		"## Inter-Agent Communication",
@@ -66,7 +67,8 @@ export function buildIrcSystemSection(selfId: string, peers: Array<{ agentId: st
  * Route an IRC message to the appropriate agent(s).
  * Returns the list of agent IDs that received the message.
  */
-export function routeIrcMessage(
+/** @internal */
+function routeIrcMessage(
 	message: IrcSendMessage,
 	selfId: string,
 	routing: {

package/src/runtime/parallel-utils.ts

@@ -63,7 +63,8 @@ export async function mapConcurrent<T, R>(items: T[], limit: number, fn: (item:
  * On abort: returns partial results (may contain undefined entries).
  * On error: throws immediately (fail-fast) and cancels remaining work.
  */
-export async function mapConcurrentWithSignal<T, R>(
+/** @internal */
+async function mapConcurrentWithSignal<T, R>(
 	items: T[],
 	limit: number,
 	fn: (item: T, i: number, signal: AbortSignal) => Promise<R>,

package/src/runtime/plan-templates.ts

@@ -0,0 +1,200 @@
+/**
+ * Structured planning engine — template-based plan generation with verification.
+ *
+ * Pattern origin: plannotator/ — plan templates with task decomposition,
+ * verification constraints, and pre-execution plan verification.
+ *
+ * Templates provide reusable plan structures that can be specialized
+ * for different project types, replacing pure LLM-generated plans with
+ * deterministic scaffolding + LLM refinement.
+ */
+
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface PlanTemplate {
+	/** Template name (e.g., "standard-review", "full-implementation") */
+	name: string;
+	/** One-line description */
+	description: string;
+	/** Template phases */
+	phases: PlanPhase[];
+	/** Verification commands per phase (phaseName → command) */
+	verificationCommands: Record<string, string>;
+}
+
+export interface PlanPhase {
+	/** Phase name (e.g., "explore", "plan", "execute", "verify") */
+	name: string;
+	/** Agent role for this phase */
+	role: string;
+	/** Task description template — {{variables}} are substituted */
+	taskTemplate: string;
+	/** Maximum number of tasks in this phase */
+	maxTasks: number;
+	/** Dependencies on other phases */
+	dependsOn: string[];
+	/** Optional verification command */
+	verificationCommand?: string;
+}
+
+export interface RenderedPlan {
+	templateName: string;
+	phases: RenderedPhase[];
+	variables: Record<string, string>;
+}
+
+export interface RenderedPhase {
+	name: string;
+	role: string;
+	task: string;
+	dependsOn: string[];
+	verificationCommand?: string;
+}
+
+// ── Template Registry ────────────────────────────────────────────────────
+
+const templates = new Map<string, PlanTemplate>();
+
+/**
+ * Register a plan template.
+ */
+export function registerPlanTemplate(template: PlanTemplate): void {
+	templates.set(template.name, template);
+}
+
+/**
+ * Get a registered template by name.
+ */
+export function getPlanTemplate(name: string): PlanTemplate | undefined {
+	return templates.get(name);
+}
+
+/**
+ * List all registered template names.
+ */
+export function listPlanTemplates(): string[] {
+	return [...templates.keys()];
+}
+
+// ── Rendering ────────────────────────────────────────────────────────────
+
+/**
+ * Render a plan template with variable substitution.
+ *
+ * Variables in task templates use {{variableName}} syntax.
+ *
+ * @param templateName - Name of the registered template
+ * @param variables - Key-value pairs for substitution
+ * @returns Rendered plan, or undefined if template not found
+ */
+export function renderPlanTemplate(
+	templateName: string,
+	variables: Record<string, string>,
+): RenderedPlan | undefined {
+	const template = templates.get(templateName);
+	if (!template) {
+		logInternalError("plan-templates", new Error(`Template not found: ${templateName}`));
+		return undefined;
+	}
+
+	const phases: RenderedPhase[] = template.phases.map((phase) => ({
+		name: phase.name,
+		role: phase.role,
+		task: substituteVariables(phase.taskTemplate, variables),
+		dependsOn: phase.dependsOn,
+		verificationCommand: phase.verificationCommand ?? template.verificationCommands[phase.name],
+	}));
+
+	return { templateName, phases, variables };
+}
+
+/**
+ * Substitute {{variable}} placeholders in a template string.
+ */
+function substituteVariables(template: string, variables: Record<string, string>): string {
+	return template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
+		return variables[key] ?? match;
+	});
+}
+
+// ── Built-in Templates ───────────────────────────────────────────────────
+
+registerPlanTemplate({
+	name: "standard-review",
+	description: "Standard code review workflow: explore → review → verify",
+	phases: [
+		{
+			name: "explore",
+			role: "explorer",
+			taskTemplate: "Map the codebase and identify the key files related to: {{goal}}. Focus on: {{focusAreas}}.",
+			maxTasks: 1,
+			dependsOn: [],
+		},
+		{
+			name: "review",
+			role: "reviewer",
+			taskTemplate: "Review the code identified in the explore phase for: {{goal}}. Check correctness, maintainability, and security.",
+			maxTasks: 1,
+			dependsOn: ["explore"],
+		},
+		{
+			name: "verify",
+			role: "verifier",
+			taskTemplate: "Verify that all review findings are addressed. Run tests if applicable. Confirm: {{goal}} is achieved.",
+			maxTasks: 1,
+			dependsOn: ["review"],
+			verificationCommand: "npm test",
+		},
+	],
+	verificationCommands: {
+		verify: "npm test",
+	},
+});
+
+registerPlanTemplate({
+	name: "full-implementation",
+	description: "Full implementation workflow: explore → plan → execute → review → verify",
+	phases: [
+		{
+			name: "explore",
+			role: "explorer",
+			taskTemplate: "Explore the codebase to understand the current state relevant to: {{goal}}. Identify affected files and patterns.",
+			maxTasks: 1,
+			dependsOn: [],
+		},
+		{
+			name: "plan",
+			role: "planner",
+			taskTemplate: "Create a detailed implementation plan for: {{goal}}. Break down into concrete steps with file-level changes.",
+			maxTasks: 1,
+			dependsOn: ["explore"],
+		},
+		{
+			name: "execute",
+			role: "executor",
+			taskTemplate: "Implement the plan for: {{goal}}. Make all planned changes, write tests, and ensure TypeScript compiles.",
+			maxTasks: 3,
+			dependsOn: ["plan"],
+		},
+		{
+			name: "review",
+			role: "reviewer",
+			taskTemplate: "Review the implementation of: {{goal}}. Check for correctness, security, performance, and code quality.",
+			maxTasks: 1,
+			dependsOn: ["execute"],
+		},
+		{
+			name: "verify",
+			role: "verifier",
+			taskTemplate: "Verify the complete implementation of: {{goal}}. Run tests, check types, validate all acceptance criteria.",
+			maxTasks: 1,
+			dependsOn: ["review"],
+			verificationCommand: "npm test && npx tsc --noEmit",
+		},
+	],
+	verificationCommands: {
+		verify: "npm test && npx tsc --noEmit",
+	},
+});

package/src/runtime/post-checks.ts

@@ -5,6 +5,7 @@
  * Distilled from pi-autoresearch's post-check / backpressure pattern.
  */
 import { execFileSync } from "node:child_process";
+import * as path from "node:path";
 import { resolveShellForScript } from "../utils/resolve-shell.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 
@@ -56,9 +57,8 @@ function resolveScriptPath(config: PostCheckConfig): string | undefined {
  * If no script path is available (neither config nor env var), the check
  * passes by default with a note.
  *
- * **Security note:** The script path is user-configurable (config or env var)
- * and executed with minimal environment (PATH, HOME, USER, LANG). Only use with trusted script
- * paths. No path containment validation is performed.
+ * **Security note:** The script path is validated to stay within `cwd`.
+ * Scripts that escape the working directory are rejected.
  *
  * @param config - Post-check configuration (script path and timeout)
  * @param cwd - Working directory for script execution
@@ -77,6 +77,13 @@ export async function runPostCheck(config: PostCheckConfig, cwd: string): Promis
 		};
 	}
 
+	// M1: Validate that the script path is contained within cwd to prevent arbitrary file execution
+	const resolved = path.resolve(cwd, scriptPath);
+	const resolvedCwd = path.resolve(cwd);
+	if (!resolved.startsWith(resolvedCwd + path.sep) && resolved !== resolvedCwd) {
+		throw new Error(`Security: PI_CREW_POST_CHECK_SCRIPT escapes cwd: ${scriptPath}`);
+	}
+
 	const startTime = Date.now();
 
 	return new Promise<PostCheckResult>((resolve) => {