pi-harness-runtime 0.2.0 → 0.3.1

package/harness/blackboard.ts

@@ -0,0 +1,291 @@
+/**
+ * Shared Blackboard — RFC-0011
+ *
+ * Durable file-based coordination so agents communicate without the human
+ * acting as message bus.
+ *
+ * Layout:
+ *   harness/blackboard/
+ *     status.json
+ *     next_action.json
+ *     tasks.json
+ *     agent_registry.json
+ *     locks/
+ *     reports/
+ *     context/
+ *     events.jsonl
+ */
+
+import type {
+	BlackboardRecord,
+	NextAction,
+	AgentRegistry,
+	AgentReport,
+	LockInfo,
+	RuntimeEvent,
+	TaskGraph,
+} from "../packages/types/src/runtime-types.ts";
+import { writeJson, readJson, appendJsonl, ensureUsageDir } from "../cli.ts";
+// @ts-expect-error - Bun has built-in Node.js types
+import { join, dirname } from "node:path";
+
+export class SharedBlackboard {
+	private readonly jobDir: string;
+	private record: BlackboardRecord | null = null;
+
+	constructor(jobId: string, rootDir: string) {
+		this.jobDir = join(rootDir, "jobs", jobId, "blackboard");
+	}
+
+	/**
+	 * Initialize a new blackboard for a job
+	 */
+	init(jobId: string, taskGraph: TaskGraph): void {
+		const now = new Date().toISOString();
+		this.record = {
+			jobId,
+			status: "created",
+			nextAction: undefined,
+			tasks: taskGraph,
+			agentRegistry: { agents: {} },
+			reports: {},
+			locks: {},
+			updatedAt: now,
+		};
+		this.save();
+	}
+
+	/**
+	 * Load blackboard from disk
+	 */
+	load(): BlackboardRecord | null {
+		const path = join(this.jobDir, "status.json");
+		this.record = readJson(path) as BlackboardRecord | null;
+		return this.record;
+	}
+
+	/**
+	 * Save blackboard to disk
+	 */
+	save(): void {
+		if (!this.record) return;
+		this.record.updatedAt = new Date().toISOString();
+		ensureUsageDir();
+		const path = join(this.jobDir, "status.json");
+		writeJson(path, this.record);
+	}
+
+	/**
+	 * Update job status
+	 */
+	updateStatus(status: BlackboardRecord["status"]): void {
+		if (!this.record) return;
+		this.record.status = status;
+		this.save();
+		this.appendEvent("StatusUpdated", { status });
+	}
+
+	/**
+	 * Set the next action for agents to pick up
+	 */
+	setNextAction(action: NextAction): void {
+		if (!this.record) return;
+		this.record.nextAction = action;
+		this.save();
+		this.appendEvent("NextActionUpdated", {
+			taskId: action.taskId,
+			agentId: action.agentId,
+			priority: action.priority,
+		});
+	}
+
+	/**
+	 * Clear the next action (after agent picks it up)
+	 */
+	clearNextAction(): void {
+		if (!this.record) return;
+		this.record.nextAction = undefined;
+		this.save();
+	}
+
+	/**
+	 * Register an agent
+	 */
+	registerAgent(
+		agentId: string,
+		name: string,
+		provider: string,
+		model?: string,
+	): void {
+		if (!this.record) return;
+		this.record.agentRegistry.agents[agentId] = {
+			id: agentId,
+			name,
+			provider,
+			model,
+			status: "idle",
+			startedAt: new Date().toISOString(),
+		};
+		this.save();
+	}
+
+	/**
+	 * Update agent status
+	 */
+	updateAgentStatus(
+		agentId: string,
+		status: AgentRegistry["agents"][string]["status"],
+		currentTaskId?: string,
+	): void {
+		if (!this.record) return;
+		const agent = this.record.agentRegistry.agents[agentId];
+		if (!agent) return;
+		agent.status = status;
+		agent.currentTaskId = currentTaskId;
+		agent.lastHeartbeat = new Date().toISOString();
+		this.save();
+	}
+
+	/**
+	 * Unregister an agent
+	 */
+	unregisterAgent(agentId: string): void {
+		if (!this.record) return;
+		delete this.record.agentRegistry.agents[agentId];
+		this.save();
+	}
+
+	/**
+	 * Write an agent report
+	 */
+	writeReport(report: AgentReport): void {
+		if (!this.record) return;
+		this.record.reports[report.agentId] = report;
+		this.save();
+		this.appendEvent("AgentReportWritten", {
+			agentId: report.agentId,
+			taskId: report.taskId,
+			status: report.status,
+		});
+	}
+
+	/**
+	 * Acquire a lock on a task
+	 */
+	acquireLock(taskId: string, agentId: string): boolean {
+		if (!this.record) return false;
+		if (this.record.locks[taskId]) {
+			return false; // Already locked
+		}
+		this.record.locks[taskId] = {
+			taskId,
+			agentId,
+			acquiredAt: new Date().toISOString(),
+		};
+		this.save();
+		this.appendEvent("LockAcquired", { taskId, agentId });
+		return true;
+	}
+
+	/**
+	 * Release a lock on a task
+	 */
+	releaseLock(taskId: string, agentId: string): boolean {
+		if (!this.record) return false;
+		const lock = this.record.locks[taskId];
+		if (!lock || lock.agentId !== agentId) {
+			return false; // Not locked by this agent
+		}
+		delete this.record.locks[taskId];
+		this.save();
+		this.appendEvent("LockReleased", { taskId, agentId });
+		return true;
+	}
+
+	/**
+	 * Check if a task is locked
+	 */
+	isLocked(taskId: string): boolean {
+		return !!this.record?.locks[taskId];
+	}
+
+	/**
+	 * Get lock info for a task
+	 */
+	getLock(taskId: string): LockInfo | null {
+		return this.record?.locks[taskId] ?? null;
+	}
+
+	/**
+	 * Get the current record
+	 */
+	getRecord(): BlackboardRecord | null {
+		return this.record;
+	}
+
+	/**
+	 * Get active agents
+	 */
+	getActiveAgents(): AgentRegistry["agents"][string][] {
+		if (!this.record) return [];
+		return Object.values(this.record.agentRegistry.agents);
+	}
+
+	/**
+	 * Check for stale agents (no heartbeat in N minutes)
+	 */
+	getStaleAgents(
+		maxAgeMinutes: number = 10,
+	): AgentRegistry["agents"][string][] {
+		if (!this.record) return [];
+		const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
+		return Object.values(this.record.agentRegistry.agents).filter((a) => {
+			if (!a.lastHeartbeat) return false;
+			return Date.parse(a.lastHeartbeat) < cutoff;
+		});
+	}
+
+	/**
+	 * Append an event to the event log
+	 */
+	private appendEvent(type: string, data?: Record<string, unknown>): void {
+		if (!this.record) return;
+		const event: RuntimeEvent = {
+			ts: new Date().toISOString(),
+			jobId: this.record.jobId,
+			type,
+			message: `Blackboard event: ${type}`,
+			data,
+		};
+		const path = join(this.jobDir, "events.jsonl");
+		ensureUsageDir();
+		appendJsonl(path, event);
+	}
+
+	/**
+	 * Export full blackboard state
+	 */
+	export(): string {
+		return JSON.stringify(this.record, null, 2);
+	}
+
+	/**
+	 * Get blackboard directory path
+	 */
+	getPath(): string {
+		return this.jobDir;
+	}
+}
+
+/**
+ * Create and initialize a blackboard for a job
+ */
+export function createBlackboard(
+	jobId: string,
+	rootDir: string,
+	taskGraph: TaskGraph,
+): SharedBlackboard {
+	const blackboard = new SharedBlackboard(jobId, rootDir);
+	blackboard.init(jobId, taskGraph);
+	return blackboard;
+}

package/harness/context-window-manager.ts

@@ -0,0 +1,210 @@
+/**
+ * Context Window Manager — RFC-0010
+ *
+ * Manages context window usage across providers.
+ * Tracks utilization and suggests strategies when approaching limits.
+ */
+
+import type {
+	ContextWindowStats,
+	ContextWindowConfig,
+	ProviderMessage,
+} from "../packages/types/src/runtime-types.ts";
+
+export interface ContextWindowUpdate {
+	provider: string;
+	model: string;
+	maxTokens: number;
+	usedTokens: number;
+}
+
+export class ContextWindowManager {
+	private stats: Map<string, ContextWindowStats> = new Map();
+	private configs: Map<string, ContextWindowConfig> = new Map();
+
+	constructor(defaultConfigs?: Record<string, ContextWindowConfig>) {
+		// Initialize with defaults
+		const defaults: Record<string, ContextWindowConfig> = {
+			minimax: {
+				warningThreshold: 0.8,
+				criticalThreshold: 0.95,
+				strategy: "truncate",
+			},
+			anthropic: {
+				warningThreshold: 0.85,
+				criticalThreshold: 0.97,
+				strategy: "truncate",
+			},
+			openai: {
+				warningThreshold: 0.8,
+				criticalThreshold: 0.95,
+				strategy: "truncate",
+			},
+			...defaultConfigs,
+		};
+
+		for (const [provider, config] of Object.entries(defaults)) {
+			this.configs.set(provider, config);
+		}
+	}
+
+	/**
+	 * Update context window stats after a request
+	 */
+	updateStats(update: ContextWindowUpdate): ContextWindowStats {
+		const { provider, model, maxTokens, usedTokens } = update;
+		const stats: ContextWindowStats = {
+			provider,
+			model,
+			maxTokens,
+			usedTokens,
+			availableTokens: maxTokens - usedTokens,
+			utilizationPct: usedTokens / maxTokens,
+		};
+		this.stats.set(`${provider}:${model}`, stats);
+		return stats;
+	}
+
+	/**
+	 * Get stats for a provider/model
+	 */
+	getStats(provider: string, model: string): ContextWindowStats | null {
+		return this.stats.get(`${provider}:${model}`) ?? null;
+	}
+
+	/**
+	 * Get all stats
+	 */
+	getAllStats(): ContextWindowStats[] {
+		return Array.from(this.stats.values());
+	}
+
+	/**
+	 * Check utilization status
+	 */
+	getUtilizationStatus(
+		provider: string,
+		model: string,
+	): "ok" | "warning" | "critical" | "unknown" {
+		const stats = this.getStats(provider, model);
+		if (!stats) return "unknown";
+
+		const config = this.configs.get(provider);
+		if (!config) return "ok";
+
+		const pct = stats.utilizationPct;
+		if (pct >= config.criticalThreshold) return "critical";
+		if (pct >= config.warningThreshold) return "warning";
+		return "ok";
+	}
+
+	/**
+	 * Estimate remaining capacity
+	 */
+	estimateRemainingRequests(
+		provider: string,
+		model: string,
+		avgTokensPerRequest: number,
+	): number | null {
+		const stats = this.getStats(provider, model);
+		if (!stats) return null;
+		return Math.floor(stats.availableTokens / avgTokensPerRequest);
+	}
+
+	/**
+	 * Prepare messages for a request (truncation/summarization strategy)
+	 */
+	prepareMessages(
+		messages: ProviderMessage[],
+		maxTokens: number,
+		strategy: "truncate" | "summarize" | "split" = "truncate",
+	): ProviderMessage[] {
+		const estimateTokens = (text: string) => Math.ceil(text.length / 4);
+		let totalTokens = messages.reduce(
+			(sum, m) => sum + estimateTokens(m.content),
+			0,
+		);
+
+		if (totalTokens <= maxTokens) {
+			return messages;
+		}
+
+		switch (strategy) {
+			case "truncate": {
+				// Remove oldest messages first
+				const truncated = [...messages];
+				while (totalTokens > maxTokens && truncated.length > 1) {
+					const removed = truncated.shift();
+					if (removed) {
+						totalTokens -= estimateTokens(removed.content);
+					}
+				}
+				return truncated;
+			}
+
+			case "summarize":
+				// In a real implementation, this would use a summarization LLM
+				// For now, fall back to truncate
+				return this.prepareMessages(messages, maxTokens, "truncate");
+
+			case "split":
+				// Split into multiple requests if possible
+				// Return first portion
+				return this.prepareMessages(messages, maxTokens, "truncate");
+
+			default:
+				return messages;
+		}
+	}
+
+	/**
+	 * Set config for a provider
+	 */
+	setConfig(provider: string, config: ContextWindowConfig): void {
+		this.configs.set(provider, config);
+	}
+
+	/**
+	 * Get config for a provider
+	 */
+	getConfig(provider: string): ContextWindowConfig | undefined {
+		return this.configs.get(provider);
+	}
+
+	/**
+	 * Generate utilization report
+	 */
+	generateReport(): string {
+		const lines = ["Context Window Utilization Report", "=".repeat(40), ""];
+
+		for (const [key, stats] of this.stats.entries()) {
+			const config = this.configs.get(stats.provider);
+			const bar = this.renderBar(stats.utilizationPct);
+			const status = this.getUtilizationStatus(stats.provider, stats.model);
+
+			lines.push(`${stats.provider}/${stats.model}`);
+			lines.push(`  ${bar} ${(stats.utilizationPct * 100).toFixed(1)}%`);
+			lines.push(
+				`  Used: ${stats.usedTokens.toLocaleString()} / ${stats.maxTokens.toLocaleString()} tokens`,
+			);
+			lines.push(
+				`  Available: ${stats.availableTokens.toLocaleString()} tokens`,
+			);
+			lines.push(`  Status: ${status.toUpperCase()}`);
+			if (config) {
+				lines.push(
+					`  Thresholds: warning=${(config.warningThreshold * 100).toFixed(0)}%, critical=${(config.criticalThreshold * 100).toFixed(0)}%`,
+				);
+			}
+			lines.push("");
+		}
+
+		return lines.join("\n");
+	}
+
+	private renderBar(pct: number, width: number = 20): string {
+		const filled = Math.round(pct * width);
+		const empty = width - filled;
+		return "[" + "█".repeat(filled) + "░".repeat(empty) + "]";
+	}
+}