pi-harness-runtime 0.10.11 → 0.10.12

package/packages/context-compiler/src/okf-loader.ts

@@ -0,0 +1,86 @@
+/**
+ * OKF Loader - Loads user knowledge from ~/.pi/okf/
+ *
+ * This module provides optional knowledge loading for context compilation.
+ * If the OKF directory doesn't exist, compilation proceeds without error.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join, basename } from "path";
+import { homedir } from "os";
+
+const DEFAULT_OKF_PATH = join(homedir(), ".pi", "okf");
+
+export interface OkfConcept {
+	id: string;
+	kind: "okf_concept";
+	source: string;
+	content: string;
+	required: false;
+	priority: 1;
+	updatedAt: string;
+	trust: "authoritative" | "generated" | "unverified";
+}
+
+/**
+ * Load OKF concepts from ~/.pi/okf/ directory.
+ *
+ * Each .md file becomes one OKF concept.
+ * If directory doesn't exist, returns empty array (graceful degradation).
+ */
+export function loadOkfConcepts(
+	okfPath: string = DEFAULT_OKF_PATH,
+): OkfConcept[] {
+	// Graceful: if directory doesn't exist, return empty
+	if (!existsSync(okfPath)) {
+		return [];
+	}
+
+	try {
+		const files = readdirSync(okfPath);
+		const concepts: OkfConcept[] = [];
+
+		for (const file of files) {
+			if (!file.endsWith(".md") && !file.endsWith(".txt")) {
+				continue;
+			}
+
+			const filePath = join(okfPath, file);
+			const content = readFileSync(filePath, "utf-8");
+			const id = basename(file, ".md").replace(/[^a-zA-Z0-9_-]/g, "_");
+
+			concepts.push({
+				id,
+				kind: "okf_concept",
+				source: filePath,
+				content,
+				required: false, // OKF is always optional
+				priority: 1,
+				updatedAt: new Date().toISOString(),
+				trust: "authoritative", // User's own OKF is authoritative
+			});
+		}
+
+		return concepts;
+	} catch (error) {
+		// Graceful: if read fails, log and continue
+		console.warn(`[OKF] Failed to load from ${okfPath}:`, error);
+		return [];
+	}
+}
+
+/**
+ * Check if OKF directory exists (for informational purposes).
+ */
+export function okfDirectoryExists(
+	okfPath: string = DEFAULT_OKF_PATH,
+): boolean {
+	return existsSync(okfPath);
+}
+
+/**
+ * Get the default OKF path.
+ */
+export function getOkfPath(): string {
+	return DEFAULT_OKF_PATH;
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Context Compiler - Scoring
+ *
+ * Scores optional candidates for inclusion priority.
+ * Required candidates bypass scoring.
+ * Deterministic: same inputs produce same scores.
+ */
+
+import type { ContextCandidate, ScoringWeights } from "./types.js";
+import { DEFAULT_SCORING_WEIGHTS } from "./types.js";
+
+/**
+ * Merge user weights with defaults.
+ */
+export function mergeWeights(user?: Partial<ScoringWeights>): ScoringWeights {
+	if (!user) return { ...DEFAULT_SCORING_WEIGHTS };
+	return {
+		priority: user.priority ?? DEFAULT_SCORING_WEIGHTS.priority,
+		directFileReference:
+			user.directFileReference ?? DEFAULT_SCORING_WEIGHTS.directFileReference,
+		recentFailureRelevance:
+			user.recentFailureRelevance ??
+			DEFAULT_SCORING_WEIGHTS.recentFailureRelevance,
+		dependencyRelevance:
+			user.dependencyRelevance ?? DEFAULT_SCORING_WEIGHTS.dependencyRelevance,
+		frameworkRelevance:
+			user.frameworkRelevance ?? DEFAULT_SCORING_WEIGHTS.frameworkRelevance,
+		stalePenalty: user.stalePenalty ?? DEFAULT_SCORING_WEIGHTS.stalePenalty,
+		duplicationPenalty:
+			user.duplicationPenalty ?? DEFAULT_SCORING_WEIGHTS.duplicationPenalty,
+	};
+}
+
+/**
+ * Score a candidate.
+ * Required candidates get MAX_SCORE (always included).
+ * Optional candidates get a weighted score.
+ *
+ * Score = priority * priority_weight
+ *       + direct_file_reference_bonus
+ *       + recent_failure_relevance
+ *       + dependency_relevance
+ *       + framework_relevance
+ *       - stale_penalty
+ *       - duplication_penalty
+ */
+export function scoreCandidate(
+	candidate: ContextCandidate,
+	weights: ScoringWeights,
+	context: ScoreContext,
+): number {
+	// Required items bypass scoring
+	if (candidate.required) return MAX_SCORE;
+
+	let score = 0;
+
+	// Base score from priority
+	score += candidate.priority * weights.priority;
+
+	// Direct file reference bonus
+	if (context.directFileReferences.has(candidate.source)) {
+		score += weights.directFileReference;
+	}
+
+	// Recent failure relevance
+	if (candidate.kind === "test_failure" && candidate.updatedAt) {
+		const age = Date.now() - new Date(candidate.updatedAt).getTime();
+		if (age < 24 * 60 * 60 * 1000) {
+			score += weights.recentFailureRelevance;
+		}
+	}
+
+	// Dependency relevance: candidates related to task dependencies score higher
+	if (context.taskDependencies.some((dep) => candidate.source.includes(dep))) {
+		score += weights.dependencyRelevance;
+	}
+
+	// Framework relevance: OKF concepts and framework files score higher
+	if (candidate.kind === "okf_concept" || candidate.kind === "project_rule") {
+		score += weights.frameworkRelevance;
+	}
+
+	// Stale penalty: items not updated recently
+	if (candidate.updatedAt) {
+		const age = Date.now() - new Date(candidate.updatedAt).getTime();
+		const staleDays = age / (24 * 60 * 60 * 1000);
+		score -= Math.min(
+			staleDays * weights.stalePenalty,
+			weights.stalePenalty * 3,
+		);
+	}
+
+	return score;
+}
+
+/**
+ * Score context for candidate evaluation.
+ */
+export interface ScoreContext {
+	directFileReferences: Set<string>;
+	taskDependencies: string[];
+}
+
+/**
+ * Maximum score — always included regardless of budget.
+ */
+export const MAX_SCORE = 9999;
+
+/**
+ * Sort candidates by score (descending), then by source (ascending) for determinism.
+ * Required candidates are always first.
+ */
+export function rankCandidates(
+	candidates: ContextCandidate[],
+	weights: ScoringWeights,
+	context: ScoreContext,
+): Array<{ candidate: ContextCandidate; score: number }> {
+	return [...candidates]
+		.map((c) => ({ candidate: c, score: scoreCandidate(c, weights, context) }))
+		.sort((a, b) => {
+			// Required candidates always first
+			if (a.candidate.required !== b.candidate.required) {
+				return a.candidate.required ? -1 : 1;
+			}
+			// Higher score first
+			if (a.score !== b.score) return b.score - a.score;
+			// Tiebreak: source alphabetically
+			return a.candidate.source.localeCompare(b.candidate.source);
+		});
+}

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

@@ -0,0 +1,246 @@
+/**
+ * Context Compiler - Types
+ *
+ * Type definitions for context compilation pipeline.
+ * Every selected item has a source reference; every omitted item has a reason.
+ */
+
+// --- Context candidate kinds -------------------------------------------
+
+/**
+ * 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";
+
+// --- Candidate --------------------------------------------------------
+
+/**
+ * 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[];
+}
+
+// --- Omission ---------------------------------------------------------
+
+/**
+ * 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;
+}
+
+// --- Compiled item ----------------------------------------------------
+
+/**
+ * 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[];
+}
+
+// --- Source graph -----------------------------------------------------
+
+/**
+ * An edge in the context source graph.
+ */
+export interface ContextSourceEdge {
+	from: string;
+	to: string;
+	label: string;
+	weight: number;
+}
+
+// --- Compiled context --------------------------------------------------
+
+/**
+ * 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 ---------------------------------------------------------
+
+/**
+ * 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 const DEFAULT_SCORING_WEIGHTS: ScoringWeights = {
+	priority: 10,
+	directFileReference: 5,
+	recentFailureRelevance: 3,
+	dependencyRelevance: 2,
+	frameworkRelevance: 2,
+	stalePenalty: 1,
+	duplicationPenalty: 8,
+};
+
+// --- Policy ---------------------------------------------------------
+
+/**
+ * Policy rules for context selection.
+ */
+export interface ContextPolicy {
+	deny: string[];
+	allowLargeFiles: boolean;
+	maxFileBytes: number;
+	trustThreshold?: ContextTrust;
+}
+
+export const DEFAULT_POLICY: ContextPolicy = {
+	deny: [
+		"**/.env",
+		"**/*.env*",
+		"**/.env.*",
+		"**/*.pem",
+		"**/*.key",
+		"**/credentials/**",
+		"**/secrets/**",
+		"**/id_rsa**",
+		"**/.npmrc",
+		"**/netrc",
+		"**/.netrc",
+		"**/galaxy.yml",
+		"**/.fleet.yaml",
+	],
+	allowLargeFiles: false,
+	maxFileBytes: 200_000,
+};
+
+// --- Compile request ------------------------------------------------
+
+/**
+ * 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>;
+}
+
+// --- Invalidation ---------------------------------------------------
+
+/**
+ * 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>;
+}
+
+// --- Error codes ----------------------------------------------------
+
+export type ContextCompileErrorCode =
+	| "MISSING_REQUIRED_SOURCE"
+	| "PARSING_FAILED"
+	| "BLACKBOARD_UNAVAILABLE"
+	| "ALL_SOURCES_FAILED";
+
+/**
+ * Context compilation error.
+ */
+export class ContextCompileError extends Error {
+	readonly code: ContextCompileErrorCode;
+	readonly details?: Record<string, unknown>;
+
+	constructor(
+		code: ContextCompileErrorCode,
+		message: string,
+		details?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = "ContextCompileError";
+		this.code = code;
+		this.details = details;
+	}
+}

package/packages/context-discovery/dist/src/discover.d.ts

@@ -0,0 +1,3 @@
+import type { ContextCandidate, DiscoveryOptions } from "./types.js";
+export declare function discoverContext(root: string, options?: Omit<DiscoveryOptions, "root">): ContextCandidate[];
+//# sourceMappingURL=discover.d.ts.map

package/packages/context-discovery/dist/src/discover.js

@@ -0,0 +1,42 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, extname } from "node:path";
+const CODE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java"]);
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function scanDir(dir, limit) {
+    const results = [];
+    try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (results.length >= limit)
+                break;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+                results.push(...scanDir(full, limit - results.length));
+            }
+            else if (entry.isFile() && CODE_EXTS.has(extname(entry.name))) {
+                try {
+                    const content = readFileSync(full, "utf8").slice(0, 8000);
+                    results.push({
+                        id: full,
+                        kind: "source",
+                        path: full,
+                        title: entry.name,
+                        content,
+                        tokens: estimateTokens(content),
+                        trust: "high",
+                        tags: [extname(entry.name).replace(".", "")],
+                    });
+                }
+                catch { /* skip unreadable */ }
+            }
+        }
+    }
+    catch { /* skip inaccessible */ }
+    return results;
+}
+export function discoverContext(root, options = {}) {
+    const limit = options.limit ?? 50;
+    return scanDir(root, limit);
+}
+//# sourceMappingURL=discover.js.map

package/packages/context-discovery/dist/src/discovery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Context Discovery — Orchestrates context collection
+ */
+interface DiscoveredContext {
+    intent: unknown;
+    workspace: unknown;
+    dependencies: unknown;
+    knowledge: unknown;
+    files: string[];
+    estimatedTokens: number;
+}
+interface DiscoveryOptions {
+    rootPath: string;
+    task: string;
+    intent?: unknown;
+    maximumTokens?: number;
+}
+interface DiscoveryResult {
+    context: DiscoveredContext;
+    discovered: unknown[];
+    omitted: unknown[];
+    estimatedTokens: number;
+}
+export declare class ContextDiscovery {
+    discover(options: DiscoveryOptions): Promise<DiscoveryResult>;
+}
+export {};
+//# sourceMappingURL=discovery.d.ts.map

package/packages/context-discovery/dist/src/discovery.js

@@ -0,0 +1,21 @@
+/**
+ * Context Discovery — Orchestrates context collection
+ */
+export class ContextDiscovery {
+    async discover(options) {
+        return {
+            context: {
+                intent: options.intent ?? null,
+                workspace: null,
+                dependencies: null,
+                knowledge: null,
+                files: [],
+                estimatedTokens: 0,
+            },
+            discovered: [],
+            omitted: [],
+            estimatedTokens: 0,
+        };
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/packages/context-discovery/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export type { ContextCandidate, DiscoveryOptions } from "./types.js";
+export { discoverContext } from "./discover.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/context-discovery/dist/src/index.js

@@ -0,0 +1,2 @@
+export { discoverContext } from "./discover.js";
+//# sourceMappingURL=index.js.map

package/packages/context-discovery/dist/src/types.d.ts

@@ -0,0 +1,16 @@
+export interface ContextCandidate {
+    id: string;
+    kind: "source" | "doc" | "okf" | "skill" | "test" | "config";
+    path: string;
+    title: string;
+    content: string;
+    tokens: number;
+    trust: "high" | "medium" | "low";
+    tags: string[];
+}
+export interface DiscoveryOptions {
+    root: string;
+    task?: string;
+    limit?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/context-discovery/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/packages/context-discovery/src/discover.ts

@@ -0,0 +1,42 @@
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join, extname } from "node:path";
+import type { ContextCandidate, DiscoveryOptions } from "./types.js";
+
+const CODE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java"]);
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+function scanDir(dir: string, limit: number): ContextCandidate[] {
+  const results: ContextCandidate[] = [];
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (results.length >= limit) break;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+        results.push(...scanDir(full, limit - results.length));
+      } else if (entry.isFile() && CODE_EXTS.has(extname(entry.name))) {
+        try {
+          const content = readFileSync(full, "utf8").slice(0, 8000);
+          results.push({
+            id: full,
+            kind: "source",
+            path: full,
+            title: entry.name,
+            content,
+            tokens: estimateTokens(content),
+            trust: "high",
+            tags: [extname(entry.name).replace(".", "")],
+          });
+        } catch { /* skip unreadable */ }
+      }
+    }
+  } catch { /* skip inaccessible */ }
+  return results;
+}
+
+export function discoverContext(root: string, options: Omit<DiscoveryOptions, "root"> = {}): ContextCandidate[] {
+  const limit = options.limit ?? 50;
+  return scanDir(root, limit);
+}

package/packages/context-discovery/src/discovery.ts

@@ -0,0 +1,44 @@
+/**
+ * Context Discovery — Orchestrates context collection
+ */
+
+interface DiscoveredContext {
+	intent: unknown;
+	workspace: unknown;
+	dependencies: unknown;
+	knowledge: unknown;
+	files: string[];
+	estimatedTokens: number;
+}
+
+interface DiscoveryOptions {
+	rootPath: string;
+	task: string;
+	intent?: unknown;
+	maximumTokens?: number;
+}
+
+interface DiscoveryResult {
+	context: DiscoveredContext;
+	discovered: unknown[];
+	omitted: unknown[];
+	estimatedTokens: number;
+}
+
+export class ContextDiscovery {
+	async discover(options: DiscoveryOptions): Promise<DiscoveryResult> {
+		return {
+			context: {
+				intent: options.intent ?? null,
+				workspace: null,
+				dependencies: null,
+				knowledge: null,
+				files: [],
+				estimatedTokens: 0,
+			},
+			discovered: [],
+			omitted: [],
+			estimatedTokens: 0,
+		};
+	}
+}

package/packages/context-discovery/src/index.ts

@@ -0,0 +1,2 @@
+export type { ContextCandidate, DiscoveryOptions } from "./types.js";
+export { discoverContext } from "./discover.js";

package/packages/context-discovery/src/types.ts

@@ -0,0 +1,15 @@
+export interface ContextCandidate {
+  id: string;
+  kind: "source" | "doc" | "okf" | "skill" | "test" | "config";
+  path: string;
+  title: string;
+  content: string;
+  tokens: number;
+  trust: "high" | "medium" | "low";
+  tags: string[];
+}
+export interface DiscoveryOptions {
+  root: string;
+  task?: string;
+  limit?: number;
+}