pi-crew 0.1.46 → 0.1.49

package/src/runtime/task-runner/progress.ts

@@ -1,119 +1,119 @@
-import type { UsageState } from "../../state/types.ts";
-import type { CrewAgentProgress } from "../crew-agent-runtime.ts";
-import { emptyCrewAgentProgress } from "../crew-agent-records.ts";
-import type { ProgressEventSummary } from "../progress-event-coalescer.ts";
-import type { TeamTaskState } from "../../state/types.ts";
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
-}
-
-function safeNum(v: number | undefined): number {
-	return Number.isFinite(v) ? v! : 0;
-}
-
-function textFromContent(content: unknown): string[] {
-	if (typeof content === "string") return [content];
-	if (!Array.isArray(content)) return [];
-	const text: string[] = [];
-	for (const part of content) {
-		const obj = asRecord(part);
-		if (!obj) continue;
-		if (obj.type === "text" && typeof obj.text === "string") text.push(obj.text);
-		else if (typeof obj.content === "string") text.push(obj.content);
-	}
-	return text;
-}
-
-function eventText(event: unknown): string[] {
-	const obj = asRecord(event);
-	if (!obj) return [];
-	const text: string[] = [];
-	if (typeof obj.text === "string") text.push(obj.text);
-	if (typeof obj.output === "string") text.push(obj.output);
-	text.push(...textFromContent(obj.content));
-	const message = asRecord(obj.message);
-	if (message) text.push(...textFromContent(message.content));
-	return text.filter((entry) => entry.trim());
-}
-
-function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
-	for (const key of keys) {
-		const value = obj[key];
-		if (typeof value === "number" && Number.isFinite(value)) return value;
-	}
-	return undefined;
-}
-
-function eventUsage(event: unknown): { input?: number; output?: number; turns?: number } | undefined {
-	const obj = asRecord(event);
-	if (!obj) return undefined;
-	const direct = { input: numberField(obj, ["input", "inputTokens", "input_tokens"]), output: numberField(obj, ["output", "outputTokens", "output_tokens"]), turns: numberField(obj, ["turns", "turnCount", "turn_count"]) };
-	if (Object.values(direct).some((value) => value !== undefined)) return direct;
-	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
-		const nested = eventUsage(obj[key]);
-		if (nested) return nested;
-	}
-	const message = asRecord(obj.message);
-	return message ? eventUsage(message.usage) : undefined;
-}
-
-function previewArgs(args: unknown): string | undefined {
-	if (!args) return undefined;
-	try {
-		const text = typeof args === "string" ? args : JSON.stringify(args);
-		return text.length > 240 ? `${text.slice(0, 240)}…` : text;
-	} catch {
-		return undefined;
-	}
-}
-
-export function applyUsageToProgress(progress: CrewAgentProgress | undefined, usage: UsageState | undefined): CrewAgentProgress | undefined {
-	if (!usage) return progress;
-	const base = progress ?? emptyCrewAgentProgress();
-	const tokens = safeNum(usage.input) + safeNum(usage.output) + safeNum(usage.cacheRead) + safeNum(usage.cacheWrite);
-	return { ...base, tokens, turns: usage.turns ?? base.turns };
-}
-
-export function shouldFlushProgressEvent(event: unknown): boolean {
-	const type = asRecord(event)?.type;
-	return type === "tool_execution_start" || type === "tool_execution_end" || type === "message_end" || type === "tool_result_end";
-}
-
-export function progressEventSummary(task: TeamTaskState, event: unknown): ProgressEventSummary {
-	const type = asRecord(event)?.type;
-	return { eventType: typeof type === "string" ? type : "event", currentTool: task.agentProgress?.currentTool, toolCount: task.agentProgress?.toolCount, tokens: task.agentProgress?.tokens, turns: task.agentProgress?.turns, activityState: task.agentProgress?.activityState, lastActivityAt: task.agentProgress?.lastActivityAt };
-}
-
-export function applyAgentProgressEvent(progress: CrewAgentProgress, event: unknown, startedAt: string | undefined): CrewAgentProgress {
-	const obj = asRecord(event);
-	const now = new Date().toISOString();
-	const next: CrewAgentProgress = { ...progress, recentTools: [...progress.recentTools], recentOutput: [...progress.recentOutput], lastActivityAt: now, activityState: "active" };
-	if (startedAt) {
-		const startMs = new Date(startedAt).getTime();
-		next.durationMs = Number.isFinite(startMs) ? Date.now() - startMs : undefined;
-	}
-	if (obj?.type === "tool_execution_start") {
-		next.toolCount += 1;
-		next.currentTool = typeof obj.toolName === "string" ? obj.toolName : typeof obj.name === "string" ? obj.name : "tool";
-		next.currentToolArgs = previewArgs(obj.args);
-		next.currentToolStartedAt = now;
-	}
-	if (obj?.type === "tool_execution_end") {
-		if (next.currentTool) next.recentTools.push({ tool: next.currentTool, args: next.currentToolArgs, endedAt: now });
-		next.currentTool = undefined;
-		next.currentToolArgs = undefined;
-		next.currentToolStartedAt = undefined;
-	}
-	if ((obj?.type === "tool_execution_error" || obj?.type === "tool_execution_failed") && next.currentTool) next.failedTool = next.currentTool;
-	const usage = eventUsage(event);
-	if (usage) {
-		next.tokens = safeNum(usage.input) + safeNum(usage.output);
-		next.turns = usage.turns ?? next.turns;
-	}
-	const text = eventText(event);
-	if (text.length > 0) next.recentOutput.push(...text.flatMap((entry) => entry.split(/\r?\n/)).filter(Boolean).slice(-10));
-	if (next.recentTools.length > 25) next.recentTools.splice(0, next.recentTools.length - 25);
-	if (next.recentOutput.length > 50) next.recentOutput.splice(0, next.recentOutput.length - 50);
-	return next;
-}
+import type { UsageState } from "../../state/types.ts";
+import type { CrewAgentProgress } from "../crew-agent-runtime.ts";
+import { emptyCrewAgentProgress } from "../crew-agent-records.ts";
+import type { ProgressEventSummary } from "../progress-event-coalescer.ts";
+import type { TeamTaskState } from "../../state/types.ts";
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function safeNum(v: number | undefined): number {
+	return Number.isFinite(v) ? v! : 0;
+}
+
+function textFromContent(content: unknown): string[] {
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+	const text: string[] = [];
+	for (const part of content) {
+		const obj = asRecord(part);
+		if (!obj) continue;
+		if (obj.type === "text" && typeof obj.text === "string") text.push(obj.text);
+		else if (typeof obj.content === "string") text.push(obj.content);
+	}
+	return text;
+}
+
+function eventText(event: unknown): string[] {
+	const obj = asRecord(event);
+	if (!obj) return [];
+	const text: string[] = [];
+	if (typeof obj.text === "string") text.push(obj.text);
+	if (typeof obj.output === "string") text.push(obj.output);
+	text.push(...textFromContent(obj.content));
+	const message = asRecord(obj.message);
+	if (message) text.push(...textFromContent(message.content));
+	return text.filter((entry) => entry.trim());
+}
+
+function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	}
+	return undefined;
+}
+
+function eventUsage(event: unknown): { input?: number; output?: number; turns?: number } | undefined {
+	const obj = asRecord(event);
+	if (!obj) return undefined;
+	const direct = { input: numberField(obj, ["input", "inputTokens", "input_tokens"]), output: numberField(obj, ["output", "outputTokens", "output_tokens"]), turns: numberField(obj, ["turns", "turnCount", "turn_count"]) };
+	if (Object.values(direct).some((value) => value !== undefined)) return direct;
+	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
+		const nested = eventUsage(obj[key]);
+		if (nested) return nested;
+	}
+	const message = asRecord(obj.message);
+	return message ? eventUsage(message.usage) : undefined;
+}
+
+function previewArgs(args: unknown): string | undefined {
+	if (!args) return undefined;
+	try {
+		const text = typeof args === "string" ? args : JSON.stringify(args);
+		return text.length > 240 ? `${text.slice(0, 240)}…` : text;
+	} catch {
+		return undefined;
+	}
+}
+
+export function applyUsageToProgress(progress: CrewAgentProgress | undefined, usage: UsageState | undefined): CrewAgentProgress | undefined {
+	if (!usage) return progress;
+	const base = progress ?? emptyCrewAgentProgress();
+	const tokens = safeNum(usage.input) + safeNum(usage.output) + safeNum(usage.cacheRead) + safeNum(usage.cacheWrite);
+	return { ...base, tokens, turns: usage.turns ?? base.turns };
+}
+
+export function shouldFlushProgressEvent(event: unknown): boolean {
+	const type = asRecord(event)?.type;
+	return type === "tool_execution_start" || type === "tool_execution_end" || type === "message_end" || type === "tool_result_end";
+}
+
+export function progressEventSummary(task: TeamTaskState, event: unknown): ProgressEventSummary {
+	const type = asRecord(event)?.type;
+	return { eventType: typeof type === "string" ? type : "event", currentTool: task.agentProgress?.currentTool, toolCount: task.agentProgress?.toolCount, tokens: task.agentProgress?.tokens, turns: task.agentProgress?.turns, activityState: task.agentProgress?.activityState, lastActivityAt: task.agentProgress?.lastActivityAt };
+}
+
+export function applyAgentProgressEvent(progress: CrewAgentProgress, event: unknown, startedAt: string | undefined): CrewAgentProgress {
+	const obj = asRecord(event);
+	const now = new Date().toISOString();
+	const next: CrewAgentProgress = { ...progress, recentTools: [...progress.recentTools], recentOutput: [...progress.recentOutput], lastActivityAt: now, activityState: "active" };
+	if (startedAt) {
+		const startMs = new Date(startedAt).getTime();
+		next.durationMs = Number.isFinite(startMs) ? Date.now() - startMs : undefined;
+	}
+	if (obj?.type === "tool_execution_start") {
+		next.toolCount += 1;
+		next.currentTool = typeof obj.toolName === "string" ? obj.toolName : typeof obj.name === "string" ? obj.name : "tool";
+		next.currentToolArgs = previewArgs(obj.args);
+		next.currentToolStartedAt = now;
+	}
+	if (obj?.type === "tool_execution_end") {
+		if (next.currentTool) next.recentTools.push({ tool: next.currentTool, args: next.currentToolArgs, endedAt: now });
+		next.currentTool = undefined;
+		next.currentToolArgs = undefined;
+		next.currentToolStartedAt = undefined;
+	}
+	if ((obj?.type === "tool_execution_error" || obj?.type === "tool_execution_failed") && next.currentTool) next.failedTool = next.currentTool;
+	const usage = eventUsage(event);
+	if (usage) {
+		next.tokens = safeNum(usage.input) + safeNum(usage.output);
+		next.turns = usage.turns ?? next.turns;
+	}
+	const text = eventText(event);
+	if (text.length > 0) next.recentOutput.push(...text.flatMap((entry) => entry.split(/\r?\n/)).filter(Boolean).slice(-10));
+	if (next.recentTools.length > 25) next.recentTools.splice(0, next.recentTools.length - 25);
+	if (next.recentOutput.length > 50) next.recentOutput.splice(0, next.recentOutput.length - 50);
+	return next;
+}

package/src/runtime/task-runner/prompt-builder.ts

@@ -1,9 +1,24 @@
 import type { AgentConfig } from "../../agents/agent-config.ts";
-import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import type { TeamRunManifest, TeamTaskState, TaskOutputSchema } from "../../state/types.ts";
 import type { WorkflowStep } from "../../workflows/workflow-config.ts";
 import { buildMemoryBlock } from "../agent-memory.ts";
 import { permissionForRole } from "../role-permission.ts";
 import { renderTaskPacket } from "../task-packet.ts";
+import { buildWorkspaceTree } from "../workspace-tree.ts";
+
+/**
+ * When loadMode is "lean", emit a tool guidance block that tells the worker
+ * which tools to prefer.  This is a prompt-level hint only — actual tool
+ * filtering at the Pi level is a future optimisation (Phase 3.2+).
+ */
+export function toolGuidanceBlock(agent?: AgentConfig): string {
+	if (!agent || agent.loadMode !== "lean" || !agent.defaultTools?.length) return "";
+	return [
+		"# Tool Guidance",
+		`This role uses a focused tool set. Preferred tools: ${agent.defaultTools.join(", ")}.`,
+		"Other tools are available but should only be used when explicitly needed for the task.",
+	].join("\n");
+}
 
 function readOnlyRoleInstructions(role: string): string {
 	if (permissionForRole(role) !== "read_only") return "";
@@ -36,9 +51,45 @@ function inputDependencyContext(task: TeamTaskState): string {
 	return (task as TeamTaskState & { dependencyContextText?: string }).dependencyContextText ?? "";
 }
 
-export function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: TeamTaskState, agent?: AgentConfig, skillBlock = ""): string {
+export function renderOutputSchemaBlock(outputSchema: TaskOutputSchema): string {
+	const lines: string[] = ["## Expected Output Format"];
+	lines.push(`Your final output must be ${outputSchema.format}.`);
+	if (outputSchema.description) {
+		lines.push(outputSchema.description);
+	}
+	if (outputSchema.format === "json" && outputSchema.schema) {
+		lines.push("The output must match this schema:");
+		lines.push("```json");
+		lines.push(JSON.stringify(outputSchema.schema, null, 2));
+		lines.push("```");
+	}
+	if (outputSchema.example) {
+		lines.push("Example output:");
+		lines.push("```");
+		lines.push(outputSchema.example);
+		lines.push("```");
+	}
+	return lines.join("\n");
+}
+
+export interface RenderedTaskPrompt {
+	/** Stable sections that rarely change between tasks of the same role/cwd. */
+	stablePrefix: string;
+	/** Dynamic sections that change per-task (goal, task packet, skills, dependency context). */
+	dynamicSuffix: string;
+	/** Full rendered prompt (stablePrefix + dynamicSuffix). */
+	full: string;
+}
+
+export async function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: TeamTaskState, agent?: AgentConfig, skillBlock = ""): Promise<RenderedTaskPrompt> {
 	const memoryBlock = agent?.memory ? buildMemoryBlock(agent.name, agent.memory, task.cwd, Boolean(agent.tools?.some((tool) => tool === "write" || tool === "edit"))) : "";
-	return [
+
+	// Build workspace tree for stable context
+	const tree = await buildWorkspaceTree(task.cwd);
+	const treeBlock = tree.rendered ? `# Workspace Structure\n${tree.rendered}` : "";
+
+	// Stable prefix: role instructions, coordination, workspace tree — rarely changes
+	const stablePrefix = [
 		"# pi-crew Worker Runtime Context",
 		`Run ID: ${manifest.runId}`,
 		`Team: ${manifest.team}`,
@@ -50,11 +101,6 @@ export function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep,
 		`Task cwd: ${task.cwd}`,
 		`Workspace mode: ${manifest.workspaceMode}`,
 		"",
-		`Goal:\n${manifest.goal}`,
-		"",
-		`Step: ${step.id}`,
-		`Role: ${step.role}`,
-		"",
 		"Protocol:",
 		"- Stay within the task scope unless the prompt explicitly says otherwise.",
 		"- Report blockers and verification evidence in the final result.",
@@ -65,13 +111,29 @@ export function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep,
 		"",
 		coordinationBridgeInstructions(task),
 		"",
+		treeBlock,
+		"",
+		toolGuidanceBlock(agent),
+	].filter(Boolean).join("\n");
+
+	// Dynamic suffix: goal, step, skills, task packet, dependency context, memory — changes per task
+	const dynamicSuffix = [
+		`Goal:\n${manifest.goal}`,
+		"",
+		`Step: ${step.id}`,
+		`Role: ${step.role}`,
+		"",
 		skillBlock,
 		"",
 		task.taskPacket ? renderTaskPacket(task.taskPacket) : "",
 		"",
 		(inputDependencyContext(task) || ""),
 		memoryBlock,
+		task.taskPacket?.outputSchema ? renderOutputSchemaBlock(task.taskPacket.outputSchema) : "",
 		"Task:",
 		step.task.replaceAll("{goal}", manifest.goal),
 	].join("\n");
+
+	const full = [stablePrefix, "", dynamicSuffix].join("\n");
+	return { stablePrefix, dynamicSuffix, full };
 }

package/src/runtime/task-runner/prompt-pipeline.ts

@@ -1,64 +1,64 @@
-import * as path from "node:path";
-import type { ArtifactDescriptor } from "../../state/types.ts";
-
-export type WorkerPromptPipelineStageName =
-	| "task-packet-built"
-	| "dependency-context-collected"
-	| "skills-rendered-or-disabled"
-	| "capability-inventory-recorded"
-	| "coordination-bridge-attached"
-	| "prompt-rendered"
-	| "prompt-artifact-written";
-
-export interface WorkerPromptPipelineStage {
-	name: WorkerPromptPipelineStageName;
-	references: string[];
-	details?: Record<string, string | number | boolean>;
-}
-
-export interface WorkerPromptPipelineArtifact {
-	schemaVersion: 1;
-	taskId: string;
-	stages: WorkerPromptPipelineStage[];
-}
-
-function artifactReference(artifactsRoot: string, artifact?: ArtifactDescriptor): string | undefined {
-	if (!artifact) return undefined;
-	const root = path.resolve(artifactsRoot);
-	const target = path.resolve(artifact.path);
-	const relative = path.relative(root, target);
-	if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return undefined;
-	return relative.replaceAll("\\", "/");
-}
-
-export interface BuildWorkerPromptPipelineInput {
-	artifactsRoot: string;
-	taskId: string;
-	promptArtifact: ArtifactDescriptor;
-	inputsArtifact: ArtifactDescriptor;
-	skillArtifact?: ArtifactDescriptor;
-	capabilityArtifact: ArtifactDescriptor;
-	coordinationArtifact: ArtifactDescriptor;
-	skillInstructionCount: number;
-	skillsDisabled: boolean;
-}
-
-export function buildWorkerPromptPipeline(input: BuildWorkerPromptPipelineInput): WorkerPromptPipelineArtifact {
-	return {
-		schemaVersion: 1,
-		taskId: input.taskId,
-		stages: [
-			{ name: "task-packet-built", references: [`metadata/${input.taskId}.task-packet.json`] },
-			{ name: "dependency-context-collected", references: [artifactReference(input.artifactsRoot, input.inputsArtifact) ?? `metadata/${input.taskId}.inputs.json`] },
-			{
-				name: "skills-rendered-or-disabled",
-				references: input.skillArtifact ? [artifactReference(input.artifactsRoot, input.skillArtifact) ?? `metadata/${input.taskId}.skills.md`] : [],
-				details: { disabled: input.skillsDisabled, skillInstructionCount: input.skillInstructionCount },
-			},
-			{ name: "capability-inventory-recorded", references: [artifactReference(input.artifactsRoot, input.capabilityArtifact) ?? `metadata/${input.taskId}.capabilities.json`] },
-			{ name: "coordination-bridge-attached", references: [artifactReference(input.artifactsRoot, input.coordinationArtifact) ?? `metadata/${input.taskId}.coordination-bridge.md`] },
-			{ name: "prompt-rendered", references: [] },
-			{ name: "prompt-artifact-written", references: [artifactReference(input.artifactsRoot, input.promptArtifact) ?? `prompts/${input.taskId}.md`] },
-		],
-	};
-}
+import * as path from "node:path";
+import type { ArtifactDescriptor } from "../../state/types.ts";
+
+export type WorkerPromptPipelineStageName =
+	| "task-packet-built"
+	| "dependency-context-collected"
+	| "skills-rendered-or-disabled"
+	| "capability-inventory-recorded"
+	| "coordination-bridge-attached"
+	| "prompt-rendered"
+	| "prompt-artifact-written";
+
+export interface WorkerPromptPipelineStage {
+	name: WorkerPromptPipelineStageName;
+	references: string[];
+	details?: Record<string, string | number | boolean>;
+}
+
+export interface WorkerPromptPipelineArtifact {
+	schemaVersion: 1;
+	taskId: string;
+	stages: WorkerPromptPipelineStage[];
+}
+
+function artifactReference(artifactsRoot: string, artifact?: ArtifactDescriptor): string | undefined {
+	if (!artifact) return undefined;
+	const root = path.resolve(artifactsRoot);
+	const target = path.resolve(artifact.path);
+	const relative = path.relative(root, target);
+	if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return undefined;
+	return relative.replaceAll("\\", "/");
+}
+
+export interface BuildWorkerPromptPipelineInput {
+	artifactsRoot: string;
+	taskId: string;
+	promptArtifact: ArtifactDescriptor;
+	inputsArtifact: ArtifactDescriptor;
+	skillArtifact?: ArtifactDescriptor;
+	capabilityArtifact: ArtifactDescriptor;
+	coordinationArtifact: ArtifactDescriptor;
+	skillInstructionCount: number;
+	skillsDisabled: boolean;
+}
+
+export function buildWorkerPromptPipeline(input: BuildWorkerPromptPipelineInput): WorkerPromptPipelineArtifact {
+	return {
+		schemaVersion: 1,
+		taskId: input.taskId,
+		stages: [
+			{ name: "task-packet-built", references: [`metadata/${input.taskId}.task-packet.json`] },
+			{ name: "dependency-context-collected", references: [artifactReference(input.artifactsRoot, input.inputsArtifact) ?? `metadata/${input.taskId}.inputs.json`] },
+			{
+				name: "skills-rendered-or-disabled",
+				references: input.skillArtifact ? [artifactReference(input.artifactsRoot, input.skillArtifact) ?? `metadata/${input.taskId}.skills.md`] : [],
+				details: { disabled: input.skillsDisabled, skillInstructionCount: input.skillInstructionCount },
+			},
+			{ name: "capability-inventory-recorded", references: [artifactReference(input.artifactsRoot, input.capabilityArtifact) ?? `metadata/${input.taskId}.capabilities.json`] },
+			{ name: "coordination-bridge-attached", references: [artifactReference(input.artifactsRoot, input.coordinationArtifact) ?? `metadata/${input.taskId}.coordination-bridge.md`] },
+			{ name: "prompt-rendered", references: [] },
+			{ name: "prompt-artifact-written", references: [artifactReference(input.artifactsRoot, input.promptArtifact) ?? `prompts/${input.taskId}.md`] },
+		],
+	};
+}

package/src/runtime/task-runner/result-utils.ts

@@ -1,14 +1,14 @@
-export function cleanResultText(text: string | undefined): string | undefined {
-	const trimmed = text?.trim();
-	if (!trimmed) return undefined;
-	const doneIndex = trimmed.lastIndexOf("\nDONE\n");
-	if (doneIndex >= 0) return trimmed.slice(doneIndex + 1).trim();
-	if (trimmed === "DONE" || trimmed.startsWith("DONE\n")) return trimmed;
-	const fencedPromptIndex = trimmed.lastIndexOf("</file>");
-	if (fencedPromptIndex >= 0 && fencedPromptIndex < trimmed.length - 7) return trimmed.slice(fencedPromptIndex + 7).trim() || trimmed;
-	return trimmed;
-}
-
-export function isFinalChildEvent(event: unknown): boolean {
-	return Boolean(event && typeof event === "object" && !Array.isArray(event) && (event as Record<string, unknown>).type === "message_end");
-}
+export function cleanResultText(text: string | undefined): string | undefined {
+	const trimmed = text?.trim();
+	if (!trimmed) return undefined;
+	const doneIndex = trimmed.lastIndexOf("\nDONE\n");
+	if (doneIndex >= 0) return trimmed.slice(doneIndex + 1).trim();
+	if (trimmed === "DONE" || trimmed.startsWith("DONE\n")) return trimmed;
+	const fencedPromptIndex = trimmed.lastIndexOf("</file>");
+	if (fencedPromptIndex >= 0 && fencedPromptIndex < trimmed.length - 7) return trimmed.slice(fencedPromptIndex + 7).trim() || trimmed;
+	return trimmed;
+}
+
+export function isFinalChildEvent(event: unknown): boolean {
+	return Boolean(event && typeof event === "object" && !Array.isArray(event) && (event as Record<string, unknown>).type === "message_end");
+}

package/src/runtime/task-runner/run-projection.ts

@@ -0,0 +1,104 @@
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import type { MailboxMessage } from "../../state/mailbox.ts";
+import type { ArtifactDescriptor } from "../../state/types.ts";
+
+export interface RunProjectionSource {
+	kind: "events" | "mailbox" | "artifacts" | "ui_metadata" | "runtime_metadata";
+	bounded: boolean;
+	reference?: string;
+}
+
+export interface RunProjectionResult {
+	sources: RunProjectionSource[];
+	summary: string;
+	injectedAsContext: boolean;
+}
+
+/**
+ * Transform run context before a worker starts.
+ * Builds a bounded projection of durable history that will be available
+ * to the worker as reference context, not as instructions.
+ *
+ * Rules:
+ * - Durable history retains events, mailbox, artifacts, UI/runtime metadata.
+ * - Worker prompt gets a bounded projection (truncated/summarized).
+ * - UI/runtime events are not prompt text unless explicitly selected.
+ */
+export function transformRunContextBeforeWorkerStart(input: {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	pendingMailbox: MailboxMessage[];
+	artifacts: ArtifactDescriptor[];
+	maxEvents?: number;
+	maxMailboxMessages?: number;
+	maxArtifactRefs?: number;
+}): RunProjectionResult {
+	const maxEvents = input.maxEvents ?? 20;
+	const maxMailbox = input.maxMailboxMessages ?? 10;
+	const maxArtifacts = input.maxArtifactRefs ?? 15;
+
+	const sources: RunProjectionSource[] = [];
+	const lines: string[] = [];
+
+	// Project a bounded slice of task history
+	const completedTasks = input.tasks.filter((t) => t.status === "completed" || t.status === "failed");
+	if (completedTasks.length > 0) {
+		const tasks = completedTasks.slice(0, maxEvents);
+		sources.push({ kind: "events", bounded: true, reference: `tasks:${tasks.length}/${completedTasks.length}` });
+		lines.push(`Previous tasks (${tasks.length}/${completedTasks.length}):`);
+		for (const task of tasks) {
+			lines.push(`- ${task.id}: ${task.status}${task.error ? ` (${task.error})` : ""}`);
+		}
+	}
+
+	// Project pending mailbox that is relevant to this worker
+	if (input.pendingMailbox.length > 0) {
+		const messages = input.pendingMailbox.slice(0, maxMailbox);
+		sources.push({ kind: "mailbox", bounded: true, reference: `mailbox:${messages.length}/${input.pendingMailbox.length}` });
+		lines.push(`Pending messages (${messages.length}/${input.pendingMailbox.length}):`);
+		for (const msg of messages) {
+			lines.push(`- ${msg.kind ?? "message"}: ${msg.body.slice(0, 100)}`);
+		}
+	}
+
+	// Project artifact references (not content)
+	if (input.artifacts.length > 0) {
+		const artifacts = input.artifacts.slice(0, maxArtifacts);
+		sources.push({ kind: "artifacts", bounded: true, reference: `artifacts:${artifacts.length}/${input.artifacts.length}` });
+		lines.push(`Available artifacts (${artifacts.length}/${input.artifacts.length}):`);
+		for (const art of artifacts) {
+			lines.push(`- ${art.kind} (${art.producer})`);
+		}
+	}
+
+	// Metadata markers — not injected as prompt instructions
+	sources.push({ kind: "ui_metadata", bounded: false, reference: "excluded_from_prompt" });
+	sources.push({ kind: "runtime_metadata", bounded: false, reference: "excluded_from_prompt" });
+
+	return {
+		sources,
+		summary: lines.join("\n"),
+		injectedAsContext: true,
+	};
+}
+
+/**
+ * Convert run history to a bounded worker prompt section.
+ * Same logic as transformRunContextBeforeWorkerStart but returns
+ * the prompt text directly for embedding in the worker prompt.
+ */
+export function convertRunHistoryToWorkerPrompt(input: {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	pendingMailbox: MailboxMessage[];
+	artifacts: ArtifactDescriptor[];
+}): string {
+	const projection = transformRunContextBeforeWorkerStart(input);
+	if (!projection.summary) return "";
+	return [
+		"## Run Context (bounded projection)",
+		projection.summary,
+		"",
+		`Projection sources: ${projection.sources.map((s) => s.kind).join(", ")}`,
+	].join("\n");
+}