pi-crew 0.9.50 → 0.9.52

package/src/runtime/tool-output-pruner.ts

@@ -1,333 +0,0 @@
-/**
- * Staleness-aware tool output pruning.
- *
- * Identifies tool results that have been superseded by a later result for the
- * same target (same file read again, same search re-run) or invalidated by a
- * later successful edit/write to a covered file, and replaces the stale
- * content with a compact digest notice. Protect-window and minimum-savings
- * hysteresis ensure recent results are preserved and pruning only fires when
- * the savings justify it.
- *
- * Ported and adapted from gajae-code's compaction/pruning.ts to pi-crew's
- * data shapes. Pi-crew delegates conversation management to child Pi
- * processes, so this module operates on a generic {@link ToolResultEntry}
- * sequence rather than SessionEntry[]. The primary integration point is
- * task-output-context.ts (dependency output context injected into worker
- * prompts), but the module is designed to be reusable for any in-process
- * tool-result sequence.
- */
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * A single tool result in a sequence (oldest → newest).
- * Adapted to pi-crew's shapes — does not depend on gajae-code's SessionEntry.
- */
-export interface ToolResultEntry {
-	/** Stable identifier for deduplication and correlation. */
-	id: string;
-	/** Tool name: "read", "bash", "grep", "search", "edit", "write", etc. */
-	toolName: string;
-	/**
-	 * Target identity: file path for read/edit/write, search pattern for
-	 * grep/search, or undefined for tools without a natural target key.
-	 */
-	target?: string;
-	/** The tool result content text. */
-	content: string;
-	/** Whether the tool result represents an error. */
-	isError?: boolean;
-}
-
-/** A file mutation event (edit/write) that can invalidate earlier reads. */
-export interface FileEditEvent {
-	/** The file path that was mutated. */
-	target: string;
-	/**
-	 * Sequence index of this edit relative to tool results. A read at index
-	 * `i` is stale if an edit at index `j > i` touches the same file.
-	 */
-	index: number;
-}
-
-export interface PruneConfig {
-	/** Keep the most recent tool output tokens intact (protect window). */
-	protectTokens: number;
-	/** Only prune if total savings meets this threshold (hysteresis). */
-	minimumSavings: number;
-	/** Tool names that should never be pruned. */
-	protectedTools: string[];
-	/**
-	 * Tools in `protectedTools` whose protection is waived once the result is
-	 * superseded (a later result for the same target, or a later successful
-	 * edit/write to the covered file). The most recent result per target is
-	 * never considered superseded. Optional; defaults to none.
-	 */
-	staleOverridableTools?: string[];
-}
-
-export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
-	protectTokens: 40_000,
-	minimumSavings: 20_000,
-	protectedTools: ["read"],
-	staleOverridableTools: ["read"],
-};
-
-export interface PruneResult {
-	/** Number of entries pruned. */
-	prunedCount: number;
-	/** Estimated tokens saved. */
-	tokensSaved: number;
-	/** The pruned result entries (same length as input, content replaced for pruned). */
-	results: ToolResultEntry[];
-	/** IDs of entries that were pruned. */
-	prunedIds: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Token estimation (rough char/4 heuristic, matching gajae-code)
-// ---------------------------------------------------------------------------
-
-import { countTokens } from "../utils/token-counter.ts";
-
-function estimateTokens(text: string): number {
-	return countTokens(text);
-}
-
-// ---------------------------------------------------------------------------
-// Digest notice generation
-// ---------------------------------------------------------------------------
-
-const DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER = 1.25;
-
-function firstErrorLine(text: string): string | undefined {
-	return text
-		.split(/\r?\n/)
-		.find((line) => /error|failed|exception|panic/i.test(line))
-		?.trim();
-}
-
-function truncateField(value: string, maxLength: number): string {
-	if (value.length <= maxLength) return value;
-	if (maxLength <= 1) return "…";
-	return `${value.slice(0, maxLength - 1)}…`;
-}
-
-/**
- * Generate a compact digest of a tool result for the digest notice.
- * Supports bash (exit code + tail line), grep/search (match/file counts),
- * and falls back to undefined for tools without a known digest format.
- */
-export function resultDigest(toolName: string, content: string, isError?: boolean): string | undefined {
-	const name = toolName.toLowerCase();
-	const text = content ?? "";
-	if (name === "bash") {
-		const exitCode = isError ? 1 : 0;
-		const tail = text.trim().split(/\r?\n/).filter(Boolean).at(-1) ?? "";
-		const error = firstErrorLine(text);
-		return [`exit=${exitCode}`, tail ? `tail=${tail}` : undefined, error ? `error=${error}` : undefined]
-			.filter((part): part is string => part !== undefined)
-			.join("; ");
-	}
-	if (name === "search" || name === "grep") {
-		const match = text.match(/(\d+)\s+matches?/i) ?? text.match(/totalMatches["']?:\s*(\d+)/i);
-		const files = text.match(/(\d+)\s+files?/i) ?? text.match(/filesWithMatches["']?:\s*(\d+)/i);
-		const error = firstErrorLine(text);
-		return (
-			[match ? `matches=${match[1]}` : undefined, files ? `files=${files[1]}` : undefined, error ? `error=${error}` : undefined]
-				.filter((part): part is string => part !== undefined)
-				.join("; ") || "search digest unavailable"
-		);
-	}
-	return undefined;
-}
-
-function createPrunedNotice(tokens: number, entry: ToolResultEntry): string {
-	const generic = `[Output pruned — ${tokens} tokens]`;
-	const digest = resultDigest(entry.toolName, entry.content, entry.isError);
-	if (!digest) return generic;
-	const genericTokens = countTokens(generic);
-	const maxTokens = Math.max(genericTokens, Math.floor(genericTokens * DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER));
-	const prefix = `[Output pruned — ${tokens} tokens; `;
-	const suffix = "]";
-	const maxChars = Math.max(0, maxTokens * 4 - prefix.length - suffix.length);
-	return `${prefix}${truncateField(digest, maxChars)}${suffix}`;
-}
-
-// ---------------------------------------------------------------------------
-// Target key resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Trailing read selectors (`:50`, `:50-200`, `:50+150`, `:5-16,960-973`,
- * `:raw`, `:conflicts`), possibly stacked. Stripped to resolve the
- * underlying file for edit invalidation.
- */
-const READ_SELECTOR_SUFFIX = /:(?:raw|conflicts|\d+(?:[-+]\d+)?(?:,\d+(?:[-+]\d+)?)*)$/;
-
-/** Base file path of a read target with any line/mode selectors stripped. */
-function readBasePath(filePath: string): string {
-	let base = filePath;
-	while (READ_SELECTOR_SUFFIX.test(base)) {
-		base = base.replace(READ_SELECTOR_SUFFIX, "");
-	}
-	return base;
-}
-
-/**
- * Stable identity for "the same logical lookup": same tool re-targeting the
- * same subject. A later result with the same key supersedes earlier ones.
- */
-function toolTargetKey(entry: ToolResultEntry): string | undefined {
-	if (!entry.target || entry.target.length === 0) return undefined;
-	return JSON.stringify([entry.toolName, entry.target]);
-}
-
-// ---------------------------------------------------------------------------
-// Staleness index
-// ---------------------------------------------------------------------------
-
-export interface StalenessIndex {
-	/** Indices of tool results superseded by a later same-target result or edit. */
-	staleIndices: Set<number>;
-}
-
-/**
- * Build a staleness index over a sequence of tool results (oldest → newest):
- * - a tool result is stale when a later non-error result shares its target key;
- * - a `read` result is stale when a later edit event touches its file.
- * The most recent result per target is never stale.
- *
- * @param toolResults  Ordered tool result entries (oldest first).
- * @param fileEdits    Optional file mutation events with sequence indices.
- */
-export function buildStalenessIndex(toolResults: ToolResultEntry[], fileEdits: FileEditEvent[] = []): StalenessIndex {
-	// Map target key → last result index that has it.
-	const lastResultIndexByKey = new Map<string, number>();
-	for (let i = 0; i < toolResults.length; i++) {
-		const entry = toolResults[i]!;
-		if (entry.isError) continue;
-		const key = toolTargetKey(entry);
-		if (key !== undefined) lastResultIndexByKey.set(key, i);
-	}
-
-	// Map file path → last edit index.
-	const lastEditIndexByPath = new Map<string, number>();
-	for (const edit of fileEdits) {
-		lastEditIndexByPath.set(edit.target, edit.index);
-	}
-
-	const staleIndices = new Set<number>();
-	for (let i = 0; i < toolResults.length; i++) {
-		const entry = toolResults[i]!;
-		// Check superseded by same-target re-read.
-		const key = toolTargetKey(entry);
-		if (key !== undefined) {
-			const lastIndex = lastResultIndexByKey.get(key);
-			if (lastIndex !== undefined && lastIndex > i) {
-				staleIndices.add(i);
-				continue;
-			}
-		}
-		// Check invalidated by later file edit (read-specific).
-		if (entry.toolName.toLowerCase() === "read" && entry.target) {
-			const basePath = readBasePath(entry.target);
-			const editIndex = lastEditIndexByPath.get(basePath);
-			if (editIndex !== undefined && editIndex > i) {
-				staleIndices.add(i);
-			}
-		}
-	}
-
-	return { staleIndices };
-}
-
-// ---------------------------------------------------------------------------
-// Pruning
-// ---------------------------------------------------------------------------
-
-/**
- * Prune stale tool outputs from a sequence, replacing superseded content with
- * compact digest notices. Protect-window, protected-tools immunity, and
- * minimum-savings hysteresis are all respected.
- *
- * OPT-IN by default: {@link DEFAULT_PRUNE_CONFIG} protects recent results via
- * a generous `protectTokens` window. Only results outside the window AND not
- * protected AND stale (or old enough) are pruned.
- *
- * @param results  Ordered tool result entries (oldest first).
- * @param config   Prune configuration. Defaults to {@link DEFAULT_PRUNE_CONFIG}.
- */
-export function pruneToolOutputs(results: ToolResultEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
-	const { staleIndices } = buildStalenessIndex(results);
-	const staleOverridable = new Set(config.staleOverridableTools ?? []);
-
-	let accumulatedTokens = 0;
-	let tokensSaved = 0;
-	let prunedCount = 0;
-
-	interface Candidate {
-		index: number;
-		entry: ToolResultEntry;
-		tokens: number;
-		notice: string;
-		savings: number;
-	}
-	const candidates: Candidate[] = [];
-	const prunedIds: string[] = [];
-
-	// Iterate newest → oldest to accumulate the protect window from the tail.
-	for (let i = results.length - 1; i >= 0; i--) {
-		const entry = results[i]!;
-		const tokens = estimateTokens(entry.content);
-		const isStale = staleIndices.has(i);
-
-		// Staleness waives protected-tool immunity for overridable tools
-		// (e.g. a superseded `read`); the most recent result per target is
-		// never stale, so the latest read of each file stays protected.
-		const isProtected = config.protectedTools.includes(entry.toolName) && !(isStale && staleOverridable.has(entry.toolName));
-
-		// Stale results are prunable even inside the recency protect window —
-		// they are superseded, so recency no longer implies relevance. They
-		// still count toward window accounting so non-stale protection is
-		// unchanged.
-		const insideProtectWindow = accumulatedTokens < config.protectTokens;
-		if ((insideProtectWindow && !isStale) || isProtected) {
-			accumulatedTokens += tokens;
-			continue;
-		}
-
-		const notice = createPrunedNotice(tokens, entry);
-		candidates.push({
-			index: i,
-			entry,
-			tokens,
-			notice,
-			savings: Math.max(0, tokens - countTokens(notice)),
-		});
-		accumulatedTokens += tokens;
-	}
-
-	for (const candidate of candidates) {
-		tokensSaved += candidate.savings;
-	}
-
-	// Hysteresis: only prune if savings meet the threshold.
-	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
-		return { prunedCount: 0, tokensSaved: 0, results, prunedIds: [] };
-	}
-
-	const prunedResults = [...results];
-	for (const candidate of candidates) {
-		prunedResults[candidate.index] = {
-			...candidate.entry,
-			content: candidate.notice,
-		};
-		prunedIds.push(candidate.entry.id);
-		prunedCount++;
-	}
-
-	return { prunedCount, tokensSaved, results: prunedResults, prunedIds };
-}

package/src/runtime/tool-progress.ts

@@ -1,278 +0,0 @@
-/**
- * Tool Progress Event System
- *
- * Provides real-time visibility into tool execution within child Pi workers.
- *
- * Event flow:
- * 1. Child Pi emits JSON events on stdout (tool_execution_start, tool_execution_end, etc.)
- * 2. child-pi.ts parses these events and passes them to onJsonEvent callback
- * 3. task-runner.ts calls applyAgentProgressEvent() to update task state
- * 4. This module provides structured types and utilities for the event system
- */
-
-import type { CrewAgentProgress } from "../state/types.ts";
-
-// ── Event Types ─────────────────────────────────────────────────────────
-
-export interface ToolExecutionStartEvent {
-	type: "tool_execution_start";
-	toolName: string;
-	toolCallId: string;
-	args?: Record<string, unknown>;
-	timestamp: number;
-}
-
-export interface ToolExecutionEndEvent {
-	type: "tool_execution_end";
-	toolName: string;
-	toolCallId: string;
-	result?: unknown;
-	timestamp: number;
-}
-
-export interface ToolExecutionUpdateEvent {
-	type: "tool_execution_update";
-	toolName: string;
-	toolCallId: string;
-	partialResult?: unknown;
-	timestamp: number;
-}
-
-export interface ToolExecutionErrorEvent {
-	type: "tool_execution_error" | "tool_execution_failed";
-	toolName: string;
-	toolCallId: string;
-	error?: string;
-	timestamp: number;
-}
-
-export interface MessageEndEvent {
-	type: "message_end";
-	message: {
-		role: "assistant" | "user" | "system";
-		content?: unknown[];
-		usage?: UsageStats;
-		model?: string;
-		stopReason?: string;
-	};
-	timestamp: number;
-}
-
-export interface UsageStats {
-	input: number;
-	output: number;
-	cacheRead?: number;
-	cacheWrite?: number;
-	cost?: { total: number };
-	turns?: number;
-	totalTokens?: number;
-}
-
-// Union type of all tool progress events
-export type ToolProgressEvent =
-	| ToolExecutionStartEvent
-	| ToolExecutionEndEvent
-	| ToolExecutionUpdateEvent
-	| ToolExecutionErrorEvent
-	| MessageEndEvent;
-
-// ── Event Utilities ───────────────────────────────────────────────────────
-
-/**
- * Extract tool name from any event type
- */
-export function getToolName(event: ToolProgressEvent): string | undefined {
-	if ("toolName" in event) return event.toolName;
-	return undefined;
-}
-
-/**
- * Check if event indicates tool is running
- */
-export function isToolRunning(event: ToolProgressEvent): boolean {
-	return event.type === "tool_execution_start";
-}
-
-/**
- * Check if event indicates tool completed
- */
-export function isToolComplete(event: ToolProgressEvent): boolean {
-	return event.type === "tool_execution_end";
-}
-
-/**
- * Check if event indicates tool failed
- */
-export function isToolError(event: ToolProgressEvent): boolean {
-	return event.type === "tool_execution_error" || event.type === "tool_execution_failed";
-}
-
-/**
- * Get usage stats from message_end event
- */
-export function getUsage(event: ToolProgressEvent): UsageStats | undefined {
-	if (event.type === "message_end" && event.message?.usage) {
-		return event.message.usage as UsageStats;
-	}
-	return undefined;
-}
-
-// ── Progress Display ──────────────────────────────────────────────────────
-
-export interface ToolProgressDisplay {
-	/** Current/last tool being executed */
-	currentTool?: string;
-	/** Preview of tool arguments (truncated) */
-	currentToolArgs?: string;
-	/** When tool started */
-	currentToolStartedAt?: string;
-	/** All recent tools with their args */
-	recentTools: Array<{
-		tool: string;
-		args?: string;
-		startedAt?: string;
-		endedAt?: string;
-		status: "running" | "done" | "error";
-	}>;
-	/** Token usage snapshot */
-	tokens?: number;
-	/** Context window usage percentage */
-	contextPercent?: number;
-	/** Total tool count */
-	toolCount: number;
-	/** Last activity timestamp */
-	lastActivityAt?: string;
-	/** Activity state */
-	activityState: "active" | "idle" | "done";
-}
-
-/**
- * Format tool progress for display
- */
-export function formatToolProgress(progress: CrewAgentProgress, maxContextTokens = 128000): ToolProgressDisplay {
-	const recentTools: Array<{
-		tool: string;
-		args?: string;
-		startedAt?: string;
-		endedAt?: string;
-		status: "running" | "done" | "error";
-	}> = progress.recentTools.map((t) => ({
-		tool: t.tool,
-		args: t.args,
-		startedAt: t.startedAt,
-		endedAt: t.endedAt,
-		status: t.endedAt ? ("done" as const) : ("running" as const),
-	}));
-
-	// If there's a currentTool but no endedAt, it's still running
-	const currentRunning = progress.recentTools.find((t) => !t.endedAt && t.tool === progress.currentTool);
-	if (currentRunning && progress.currentTool) {
-		recentTools.push({
-			tool: progress.currentTool,
-			args: progress.currentToolArgs,
-			startedAt: progress.currentToolStartedAt,
-			endedAt: undefined as string | undefined,
-			status: "running" as const,
-		});
-	}
-
-	const tokens = progress.tokens ?? 0;
-	const contextPercent = maxContextTokens > 0 ? Math.round((tokens / maxContextTokens) * 100) : 0;
-
-	return {
-		currentTool: progress.currentTool,
-		currentToolArgs: progress.currentToolArgs,
-		currentToolStartedAt: progress.currentToolStartedAt,
-		recentTools,
-		tokens,
-		contextPercent,
-		toolCount: progress.toolCount,
-		lastActivityAt: progress.lastActivityAt,
-		activityState: progress.activityState as "active" | "idle" | "done",
-	};
-}
-
-/**
- * Format a single line summary of current tool
- */
-export function formatCurrentToolLine(progress: CrewAgentProgress): string {
-	if (!progress.currentTool) return "";
-
-	const args = progress.currentToolArgs
-		? ` ${progress.currentToolArgs.slice(0, 50)}${progress.currentToolArgs.length > 50 ? "..." : ""}`
-		: "";
-
-	const toolCount = progress.toolCount > 0 ? ` (${progress.toolCount})` : "";
-
-	return `${progress.currentTool}${args}${toolCount}`;
-}
-
-/**
- * Format token usage for display
- */
-export function formatTokenUsage(progress: CrewAgentProgress, maxTokens = 128000): string {
-	const tokens = progress.tokens ?? 0;
-	const percent = maxTokens > 0 ? Math.round((tokens / maxTokens) * 100) : 0;
-	return `${tokens.toLocaleString()} / ${maxTokens.toLocaleString()} (${percent}%)`;
-}
-
-// ── Progress Bar Rendering ────────────────────────────────────────────────
-
-export interface ProgressBarOptions {
-	width?: number;
-	showPercent?: boolean;
-	showCount?: boolean;
-}
-
-/**
- * Render a progress bar for tool execution
- */
-export function renderProgressBar(progress: CrewAgentProgress, options: ProgressBarOptions = {}): string {
-	const width = options.width ?? 20;
-	const showPercent = options.showPercent ?? true;
-	const showCount = options.showCount ?? true;
-
-	// Calculate based on recent tools (max 10)
-	const recentCount = Math.min(progress.recentTools.length, 10);
-	const filled = Math.round((recentCount / 10) * width);
-	const empty = width - filled;
-
-	const bar = "█".repeat(filled) + "░".repeat(empty);
-	const percent = showPercent ? ` ${progress.toolCount} tools` : "";
-	const tokens = progress.tokens ? ` | ${(progress.tokens / 1000).toFixed(1)}k tokens` : "";
-
-	return `[${bar}]${percent}${tokens}`;
-}
-
-// ── Event Filtering ──────────────────────────────────────────────────────
-
-/**
- * Filter events to only tool execution events
- */
-export function filterToolEvents(events: ToolProgressEvent[]): ToolProgressEvent[] {
-	return events.filter(
-		(e) =>
-			e.type === "tool_execution_start" ||
-			e.type === "tool_execution_end" ||
-			e.type === "tool_execution_update" ||
-			e.type === "tool_execution_error" ||
-			e.type === "tool_execution_failed",
-	);
-}
-
-/**
- * Get events for a specific tool
- */
-export function getEventsForTool(events: ToolProgressEvent[], toolName: string): ToolProgressEvent[] {
-	return events.filter((e) => {
-		if ("toolName" in e) return e.toolName === toolName;
-		return false;
-	});
-}
-
-/**
- * Check if any event indicates an error
- */
-export function hasError(events: ToolProgressEvent[]): boolean {
-	return events.some(isToolError);
-}

package/src/runtime/usage-tracker.ts

@@ -1,73 +0,0 @@
-import type { TeamRunManifest, TeamTaskState, UsageState } from "../state/types.ts";
-
-export interface LifetimeUsage {
-	input: number;
-	output: number;
-	cacheWrite: number;
-}
-
-export function emptyLifetimeUsage(): LifetimeUsage {
-	return { input: 0, output: 0, cacheWrite: 0 };
-}
-
-export function addUsage(into: LifetimeUsage, delta: { input?: number; output?: number; cacheWrite?: number }): void {
-	if (typeof delta.input === "number") into.input += delta.input;
-	if (typeof delta.output === "number") into.output += delta.output;
-	if (typeof delta.cacheWrite === "number") into.cacheWrite += delta.cacheWrite;
-}
-
-/** @internal */
-function lifetimeUsageFromState(state: UsageState | undefined): LifetimeUsage {
-	if (!state) return emptyLifetimeUsage();
-	return {
-		input: state.input ?? 0,
-		output: state.output ?? 0,
-		cacheWrite: state.cacheWrite ?? 0,
-	};
-}
-
-export function usageStateFromLifetime(lifetime: LifetimeUsage): UsageState {
-	return {
-		input: lifetime.input,
-		output: lifetime.output,
-		cacheWrite: lifetime.cacheWrite,
-		cacheRead: 0,
-	};
-}
-
-const taskUsageMap = new Map<string, LifetimeUsage>();
-
-export function trackTaskUsage(taskId: string, delta: { input?: number; output?: number; cacheWrite?: number }): void {
-	const existing = taskUsageMap.get(taskId) ?? emptyLifetimeUsage();
-	addUsage(existing, delta);
-	taskUsageMap.set(taskId, existing);
-}
-
-export function getTrackedTaskUsage(taskId: string): LifetimeUsage {
-	return taskUsageMap.get(taskId) ?? emptyLifetimeUsage();
-}
-
-export function clearTrackedTaskUsage(taskId: string): void {
-	taskUsageMap.delete(taskId);
-}
-
-export function clearAllTrackedTaskUsage(): void {
-	taskUsageMap.clear();
-}
-
-// Aliases for public API
-export const getTaskUsage = getTrackedTaskUsage;
-export const getRunUsage = getTrackedTaskUsage;
-export const clearAllTaskUsage = clearAllTrackedTaskUsage;
-
-/** @internal */
-function aggregateTrackedUsageForRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): UsageState {
-	const total = emptyLifetimeUsage();
-	for (const task of tasks) {
-		const tracked = getTrackedTaskUsage(task.id);
-		addUsage(total, tracked);
-		// Also add any usage already stored on the task
-		if (task.usage) addUsage(total, task.usage);
-	}
-	return usageStateFromLifetime(total);
-}