pi-harness-runtime 0.10.11 → 0.10.13

package/packages/context-compiler/dist/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Context Compiler - Types
+ *
+ * Type definitions for context compilation pipeline.
+ * Every selected item has a source reference; every omitted item has a reason.
+ */
+/**
+ * Kinds of context that can be collected.
+ */
+export type ContextKind = "project_rule" | "okf_concept" | "source_file" | "git_diff" | "test_failure" | "agent_report" | "blackboard_state";
+/**
+ * Trust level of a context item.
+ */
+export type ContextTrust = "authoritative" | "generated" | "unverified";
+/**
+ * A raw context candidate from a source collector.
+ */
+export interface ContextCandidate {
+    id: string;
+    kind: ContextKind;
+    content: string;
+    source: string;
+    priority: 0 | 1 | 2 | 3;
+    required: boolean;
+    updatedAt?: string;
+    trust: ContextTrust;
+    /** Content hash for cache invalidation */
+    contentHash?: string;
+    /** For source files: file path */
+    filePath?: string;
+    /** For source files: line range */
+    startLine?: number;
+    endLine?: number;
+    /** For source files: matched symbols */
+    symbols?: string[];
+}
+/**
+ * Reasons why a candidate was omitted.
+ */
+export type OmissionReason = "duplicate" | "out_of_scope" | "stale" | "budget" | "policy_denied" | "parsing_failed" | "source_unavailable";
+/**
+ * An item that was considered but not included in the final context.
+ */
+export interface OmittedItem {
+    id: string;
+    kind: ContextKind;
+    reason: OmissionReason;
+    reasonDetail?: string;
+    estimatedTokens: number;
+    /** For policy_denied: the rule that denied this item */
+    deniedBy?: string;
+}
+/**
+ * An item that made it into the final compiled context.
+ */
+export interface CompiledContextItem {
+    id: string;
+    kind: ContextKind;
+    content: string;
+    source: string;
+    priority: 0 | 1 | 2 | 3;
+    required: boolean;
+    trust: ContextTrust;
+    estimatedTokens: number;
+    contentHash?: string;
+    filePath?: string;
+    startLine?: number;
+    endLine?: number;
+    symbols?: string[];
+}
+/**
+ * An edge in the context source graph.
+ */
+export interface ContextSourceEdge {
+    from: string;
+    to: string;
+    label: string;
+    weight: number;
+}
+/**
+ * The final compiled context output.
+ */
+export interface CompiledContext {
+    taskId: string;
+    items: CompiledContextItem[];
+    omitted: OmittedItem[];
+    estimatedTokens: number;
+    sourceGraph: ContextSourceEdge[];
+    generatedAt: string;
+    /** Maps original candidate ID to compiled item ID */
+    mapping: Record<string, string>;
+}
+/**
+ * Scoring weights for context candidates.
+ * Configurable via ContextCompilerConfig.
+ */
+export interface ScoringWeights {
+    priority: number;
+    directFileReference: number;
+    recentFailureRelevance: number;
+    dependencyRelevance: number;
+    frameworkRelevance: number;
+    stalePenalty: number;
+    duplicationPenalty: number;
+}
+export declare const DEFAULT_SCORING_WEIGHTS: ScoringWeights;
+/**
+ * Policy rules for context selection.
+ */
+export interface ContextPolicy {
+    deny: string[];
+    allowLargeFiles: boolean;
+    maxFileBytes: number;
+    trustThreshold?: ContextTrust;
+}
+export declare const DEFAULT_POLICY: ContextPolicy;
+/**
+ * Input to the context compiler.
+ */
+export interface ContextCompileRequest {
+    jobId: string;
+    taskId: string;
+    taskObjective: string;
+    maximumTokens: number;
+    worktreePath: string;
+    candidates: ContextCandidate[];
+    scoringWeights?: Partial<ScoringWeights>;
+    policy?: Partial<ContextPolicy>;
+}
+/**
+ * Reasons for context invalidation.
+ */
+export type InvalidationReason = "source_hash_changed" | "project_rule_changed" | "required_okf_changed" | "task_objective_changed" | "test_failure_superseded" | "worktree_branch_changed";
+export interface ContextInvalidation {
+    reason: InvalidationReason;
+    taskId: string;
+    details?: Record<string, unknown>;
+}
+export type ContextCompileErrorCode = "MISSING_REQUIRED_SOURCE" | "PARSING_FAILED" | "BLACKBOARD_UNAVAILABLE" | "ALL_SOURCES_FAILED";
+/**
+ * Context compilation error.
+ */
+export declare class ContextCompileError extends Error {
+    readonly code: ContextCompileErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ContextCompileErrorCode, message: string, details?: Record<string, unknown>);
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/context-compiler/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/packages/context-compiler/dist/types.js

@@ -0,0 +1,48 @@
+/**
+ * Context Compiler - Types
+ *
+ * Type definitions for context compilation pipeline.
+ * Every selected item has a source reference; every omitted item has a reason.
+ */
+export const DEFAULT_SCORING_WEIGHTS = {
+    priority: 10,
+    directFileReference: 5,
+    recentFailureRelevance: 3,
+    dependencyRelevance: 2,
+    frameworkRelevance: 2,
+    stalePenalty: 1,
+    duplicationPenalty: 8,
+};
+export const DEFAULT_POLICY = {
+    deny: [
+        "**/.env",
+        "**/*.env*",
+        "**/.env.*",
+        "**/*.pem",
+        "**/*.key",
+        "**/credentials/**",
+        "**/secrets/**",
+        "**/id_rsa**",
+        "**/.npmrc",
+        "**/netrc",
+        "**/.netrc",
+        "**/galaxy.yml",
+        "**/.fleet.yaml",
+    ],
+    allowLargeFiles: false,
+    maxFileBytes: 200_000,
+};
+/**
+ * Context compilation error.
+ */
+export class ContextCompileError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ContextCompileError";
+        this.code = code;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=types.js.map

package/packages/context-compiler/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0IH,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACtD,QAAQ,EAAE,EAAE;IACZ,mBAAmB,EAAE,CAAC;IACtB,sBAAsB,EAAE,CAAC;IACzB,mBAAmB,EAAE,CAAC;IACtB,kBAAkB,EAAE,CAAC;IACrB,YAAY,EAAE,CAAC;IACf,kBAAkB,EAAE,CAAC;CACrB,CAAC;AAcF,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC5C,IAAI,EAAE;QACL,SAAS;QACT,WAAW;QACX,WAAW;QACX,UAAU;QACV,UAAU;QACV,mBAAmB;QACnB,eAAe;QACf,aAAa;QACb,WAAW;QACX,UAAU;QACV,WAAW;QACX,eAAe;QACf,gBAAgB;KAChB;IACD,eAAe,EAAE,KAAK;IACtB,YAAY,EAAE,OAAO;CACrB,CAAC;AA6CF;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACpC,IAAI,CAA0B;IAC9B,OAAO,CAA2B;IAE3C,YACC,IAA6B,EAC7B,OAAe,EACf,OAAiC;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD"}

package/packages/context-compiler/src/budget.ts

@@ -0,0 +1,122 @@
+/**
+ * Context Compiler - Token Budget Fitting
+ *
+ * Fits optional candidates into the available token budget.
+ * Required candidates always fit first.
+ * Uses the RFC-0041 character-based estimation (1 token ≈ 4 characters).
+ */
+
+import type {
+	CompiledContextItem,
+	ContextCandidate,
+	OmittedItem,
+} from "./types.js";
+
+/**
+ * Result of budget fitting.
+ */
+export interface BudgetFitResult {
+	included: ContextCandidate[];
+	omitted: OmittedItem[];
+	estimatedTokens: number;
+}
+
+/**
+ * Estimate tokens from content using 4 chars/token approximation.
+ */
+export function estimateTokens(content: string): number {
+	if (!content || content.trim() === "") return 0;
+	return Math.ceil(content.length / 4);
+}
+
+/**
+ * Fit candidates into the token budget.
+ *
+ * Algorithm:
+ * 1. Always include required candidates
+ * 2. Sort optional by score (descending)
+ * 3. Greedily add optional until budget exhausted
+ * 4. Record all omitted with reason "budget"
+ *
+ * @param candidates - Ranked candidates (highest score first)
+ * @param maximumTokens - Available budget
+ * @returns Candidates to include and items to omit
+ */
+export function fitToBudget(
+	candidates: Array<{ candidate: ContextCandidate; score: number }>,
+	maximumTokens: number,
+): BudgetFitResult {
+	const included: ContextCandidate[] = [];
+	const omitted: OmittedItem[] = [];
+
+	let usedTokens = 0;
+
+	for (const { candidate } of candidates) {
+		const tokens = estimateTokens(candidate.content);
+
+		// Optional items with no content are omitted (broken/unavailable)
+		if (
+			!candidate.required &&
+			(!candidate.content || candidate.content.trim() === "")
+		) {
+			omitted.push({
+				id: candidate.id,
+				kind: candidate.kind,
+				reason: "source_unavailable",
+				reasonDetail: "no content",
+				estimatedTokens: 0,
+			});
+			continue;
+		}
+
+		if (candidate.required) {
+			// Required: always include
+			included.push(candidate);
+			usedTokens += tokens;
+			continue;
+		}
+
+		// Optional: check budget
+		if (usedTokens + tokens <= maximumTokens) {
+			included.push(candidate);
+			usedTokens += tokens;
+		} else {
+			omitted.push({
+				id: candidate.id,
+				kind: candidate.kind,
+				reason: "budget",
+				reasonDetail: `estimated ${tokens} tokens, only ${maximumTokens - usedTokens} remaining`,
+				estimatedTokens: tokens,
+			});
+		}
+	}
+
+	return {
+		included,
+		omitted,
+		estimatedTokens: usedTokens,
+	};
+}
+
+/**
+ * Convert included candidates to compiled items.
+ */
+export function toCompiledItems(
+	candidates: ContextCandidate[],
+): CompiledContextItem[] {
+	return candidates.map((c) => ({
+		id: c.id,
+		kind: c.kind,
+		content: c.content,
+		source: c.source,
+		priority: c.priority,
+		required: c.required,
+		trust: c.trust,
+		estimatedTokens: estimateTokens(c.content),
+		contentHash: c.contentHash,
+		filePath: c.filePath,
+		startLine: c.startLine,
+		endLine: c.endLine,
+		symbols: c.symbols,
+	}));
+}

package/packages/context-compiler/src/cache.ts

@@ -0,0 +1,134 @@
+/**
+ * Context Compiler - Cache & Invalidation
+ *
+ * Generates deterministic cache keys from selected source hashes.
+ * Tracks invalidation triggers.
+ */
+
+import type {
+	CompiledContext,
+	CompiledContextItem,
+	ContextInvalidation,
+} from "./types.js";
+
+/**
+ * Generate a deterministic cache key from compiled context items.
+ * Includes source file hashes for content invalidation.
+ */
+export function generateCacheKey(
+	taskId: string,
+	items: CompiledContextItem[],
+	taskObjective: string,
+): string {
+	// Sort by source path for determinism
+	const hashes = items
+		.filter((item) => item.contentHash)
+		.map((item) => `${item.source}:${item.contentHash}`)
+		.sort();
+
+	const objectiveHash = simpleHash(taskObjective);
+	const combined = `${taskId}:${objectiveHash}:${hashes.join(",")}`;
+
+	return `ctx:${simpleHash(combined)}`;
+}
+
+/**
+ * Check if a compiled context should be invalidated.
+ *
+ * Invalidation triggers:
+ * - A selected source file hash changed
+ * - A project rule changed
+ * - A required OKF concept changed
+ * - The task objective changed
+ * - A test failure superseded an old one
+ * - Worktree branch/HEAD changed
+ */
+export function shouldInvalidate(
+	previous: CompiledContext,
+	invalidation: ContextInvalidation,
+	currentItemHashes: Map<string, string>,
+): boolean {
+	switch (invalidation.reason) {
+		case "source_hash_changed": {
+			const changed = invalidation.details?.sourcePath as string | undefined;
+			if (!changed) return true;
+			const item = previous.items.find((i) => i.source === changed);
+			if (!item) return false;
+			const currentHash = currentItemHashes.get(changed);
+			return currentHash !== item.contentHash;
+		}
+
+		case "project_rule_changed": {
+			const rulePath = invalidation.details?.rulePath as string | undefined;
+			const ruleItem = previous.items.find(
+				(i) =>
+					i.kind === "project_rule" &&
+					(i.source === rulePath || i.filePath === rulePath),
+			);
+			return ruleItem !== undefined;
+		}
+
+		case "required_okf_changed": {
+			const okfId = invalidation.details?.okfId as string | undefined;
+			return (
+				previous.items.find(
+					(i) => i.kind === "okf_concept" && i.id === okfId && i.required,
+				) !== undefined
+			);
+		}
+
+		case "task_objective_changed": {
+			return true; // Always invalidate on objective change
+		}
+
+		case "test_failure_superseded": {
+			const oldFailure = invalidation.details?.oldFailureId as
+				| string
+				| undefined;
+			if (!oldFailure) return false;
+			const existingFailure = previous.items.find(
+				(i) => i.kind === "test_failure" && i.id === oldFailure,
+			);
+			return existingFailure !== undefined;
+		}
+
+		case "worktree_branch_changed": {
+			const oldBranch = invalidation.details?.oldBranch as string | undefined;
+			const newBranch = invalidation.details?.newBranch as string | undefined;
+			// Invalidate if any source file changed or if branch changed
+			return oldBranch !== newBranch;
+		}
+
+		default:
+			return false;
+	}
+}
+
+/**
+ * Generate current item hashes from a compiled context.
+ */
+export function extractItemHashes(
+	items: CompiledContextItem[],
+): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const item of items) {
+		if (item.contentHash) {
+			map.set(item.source, item.contentHash);
+		}
+	}
+	return map;
+}
+
+/**
+ * Simple deterministic hash for strings.
+ * Used for cache keys when crypto is unavailable.
+ */
+export function simpleHash(text: string): string {
+	let hash = 0;
+	for (let i = 0; i < text.length; i++) {
+		const char = text.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash |= 0;
+	}
+	return Math.abs(hash).toString(16).padStart(8, "0");
+}