pi-harness-runtime 0.10.11 → 0.10.12

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

@@ -0,0 +1,263 @@
+/**
+ * Prompt Compiler - Types
+ *
+ * Type definitions for prompt compilation pipeline.
+ */
+
+import type { CompiledRequirement } from "@pi-harness/requirement-compiler";
+import type { CompiledTask } from "@pi-harness/task-compiler";
+
+// --- Provider target ------------------------------------------------------
+
+/**
+ * Supported provider targets.
+ */
+export type ProviderTarget =
+	| "codex"
+	| "minimax"
+	| "glm"
+	| "openai"
+	| "anthropic"
+	| "gemini";
+
+// --- Provider prompt profile -----------------------------------------------
+
+/**
+ * Provider-specific formatting preferences.
+ */
+export interface ProviderPromptProfile {
+	id: ProviderTarget;
+	supportsSystemPrompt: boolean;
+	preferredInstructionStyle: "xml" | "markdown" | "plain";
+	maximumInputTokens: number;
+	reservedOutputTokens: number;
+	continuationMarker: string;
+}
+
+// --- Prompt sections ------------------------------------------------------
+
+/**
+ * A single section of the compiled prompt.
+ */
+export interface PromptSection {
+	id: string;
+	kind:
+		| "identity"
+		| "project_rules"
+		| "objective"
+		| "acceptance_criteria"
+		| "relevant_context"
+		| "known_constraints"
+		| "files_in_scope"
+		| "required_output"
+		| "tool_permissions"
+		| "continuation_instructions"
+		| "supplemental";
+	content: string;
+	required: boolean;
+	compactable: boolean;
+	sourceRefs: SourceRef[];
+}
+
+/**
+ * Lightweight source reference.
+ */
+export interface SourceRef {
+	source: string;
+	line?: number;
+	text: string;
+}
+
+// --- Continuation ---------------------------------------------------------
+
+/**
+ * Context for resuming a prompt that hit output limits.
+ */
+export interface ContinuationContext {
+	previousResponsePath: string;
+	completedItems: string[];
+	incompleteItems: string[];
+	instruction: "continue_without_repeating";
+}
+
+// --- Compiled context ----------------------------------------------------
+
+/**
+ * Compiled context from the Context Compiler (RFC-0042).
+ * Contains deduplicated, prioritized context entries.
+ */
+export interface CompiledContext {
+	entries: ContextEntry[];
+}
+
+export interface ContextEntry {
+	id: string;
+	content: string;
+	priority: number;
+	source: string;
+	tags?: string[];
+}
+
+function __contextEntryPriority(): void {
+	// Compactable priorities (higher = less important):
+	// 0 = critical (never compact)
+	// 1-3 = important
+	// 4-6 = useful
+	// 7+ = supplemental
+}
+
+// --- Redaction ------------------------------------------------------------
+
+/**
+ * Redaction rule patterns.
+ */
+export interface RedactionRule {
+	pattern: RegExp;
+	replacement: string;
+	description: string;
+}
+
+// --- Prompt package ------------------------------------------------------
+
+/**
+ * The output artifact of prompt compilation.
+ */
+export interface PromptPackage {
+	version: "1";
+	taskId: string;
+	provider: ProviderTarget;
+	system: string;
+	user: string;
+	sections: PromptSection[];
+	estimatedInputTokens: number;
+	sourceRefs: SourceRef[];
+	hash: string;
+	createdAt: string;
+}
+
+// --- Compile request ------------------------------------------------------
+
+/**
+ * Input to the prompt compiler.
+ */
+export interface PromptCompileRequest {
+	task: CompiledTask;
+	requirement: CompiledRequirement;
+	context: CompiledContext;
+	provider: ProviderTarget;
+	attempt: number;
+	continuation?: ContinuationContext;
+}
+
+// --- Error codes ---------------------------------------------------------
+
+export type PromptCompileErrorCode =
+	| "INVALID_TASK"
+	| "MISSING_OBJECTIVE"
+	| "MISSING_OUTPUT_CONTRACT"
+	| "UNRESOLVED_REQUIRED_SOURCE"
+	| "TOKEN_BUDGET_EXCEEDED"
+	| "POLICY_CONFLICT";
+
+/**
+ * Prompt compilation error.
+ */
+export class PromptCompileError extends Error {
+	readonly code: PromptCompileErrorCode;
+	readonly details?: Record<string, unknown>;
+
+	constructor(
+		code: PromptCompileErrorCode,
+		message: string,
+		details?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = "PromptCompileError";
+		this.code = code;
+		this.details = details;
+	}
+}
+
+// --- Provider profiles ----------------------------------------------------
+
+/**
+ * Built-in provider profiles.
+ */
+export const PROVIDER_PROFILES: Record<ProviderTarget, ProviderPromptProfile> =
+	{
+		codex: {
+			id: "codex",
+			supportsSystemPrompt: true,
+			preferredInstructionStyle: "markdown",
+			maximumInputTokens: 128_000,
+			reservedOutputTokens: 4_096,
+			continuationMarker: "<!-- CONTINUE -->",
+		},
+		minimax: {
+			id: "minimax",
+			supportsSystemPrompt: true,
+			preferredInstructionStyle: "markdown",
+			maximumInputTokens: 128_000,
+			reservedOutputTokens: 4_096,
+			continuationMarker: "<!-- CONTINUE -->",
+		},
+		glm: {
+			id: "glm",
+			supportsSystemPrompt: true,
+			preferredInstructionStyle: "markdown",
+			maximumInputTokens: 128_000,
+			reservedOutputTokens: 4_096,
+			continuationMarker: "<!-- CONTINUE -->",
+		},
+		openai: {
+			id: "openai",
+			supportsSystemPrompt: true,
+			preferredInstructionStyle: "markdown",
+			maximumInputTokens: 128_000,
+			reservedOutputTokens: 4_096,
+			continuationMarker: "<!-- CONTINUE -->",
+		},
+		anthropic: {
+			id: "anthropic",
+			supportsSystemPrompt: true,
+			preferredInstructionStyle: "xml",
+			maximumInputTokens: 200_000,
+			reservedOutputTokens: 4_096,
+			continuationMarker: "<!-- CONTINUE -->",
+		},
+		gemini: {
+			id: "gemini",
+			supportsSystemPrompt: true,
+			preferredInstructionStyle: "markdown",
+			maximumInputTokens: 1_000_000,
+			reservedOutputTokens: 8_192,
+			continuationMarker: "<!-- CONTINUE -->",
+		},
+	};
+
+// --- Section order --------------------------------------------------------
+
+/**
+ * Deterministic section ordering per RFC-0041.
+ */
+export const SECTION_ORDER: PromptSection["kind"][] = [
+	"identity",
+	"project_rules",
+	"objective",
+	"acceptance_criteria",
+	"relevant_context",
+	"known_constraints",
+	"files_in_scope",
+	"required_output",
+	"tool_permissions",
+	"continuation_instructions",
+	"supplemental",
+];
+
+// --- Compactable priority threshold ---------------------------------------
+
+/**
+ * Entries with priority >= this are eligible for compaction.
+ * Priority 0 = critical (never compact).
+ */
+export const COMPACTABLE_THRESHOLD = 1;

package/packages/prompt-compiler/src/validate.ts

@@ -0,0 +1,157 @@
+/**
+ * Prompt Compiler - Validation
+ *
+ * Validates compiled sections against the request.
+ * Fails fast on hard requirements.
+ */
+
+import type { NormalizedRequest } from "./normalize.js";
+import type {
+	PromptCompileErrorCode,
+	PromptSection,
+	ProviderPromptProfile,
+} from "./types.js";
+import { PromptCompileError } from "./types.js";
+
+/**
+ * Validation options.
+ */
+export interface ValidateOptions {
+	provider: ProviderPromptProfile;
+	maxRetries?: number;
+}
+
+/**
+ * Validate compiled sections.
+ *
+ * Throws PromptCompileError for:
+ * - Empty task ID
+ * - Empty objective
+ * - No expected outputs defined
+ * - Token budget exceeded
+ * - Required source unresolved
+ */
+export function validateSections(
+	sections: PromptSection[],
+	request: NormalizedRequest,
+	_options: ValidateOptions,
+): void {
+	const errors: Array<{ code: PromptCompileErrorCode; message: string }> = [];
+
+	// 1. Task ID must not be empty
+	if (!request.taskId.trim()) {
+		errors.push({
+			code: "INVALID_TASK",
+			message: "Task ID is empty",
+		});
+	}
+
+	// 2. Objective must not be empty
+	if (!request.objective.trim()) {
+		errors.push({
+			code: "MISSING_OBJECTIVE",
+			message: "Objective is empty",
+		});
+	}
+
+	// 3. At least one expected output required
+	if (request.expectedOutputs.length === 0) {
+		errors.push({
+			code: "MISSING_OUTPUT_CONTRACT",
+			message: "No expected outputs defined for task",
+		});
+	}
+
+	// 4. Check required sections exist
+	const requiredKinds = new Set(
+		sections.filter((s) => s.required).map((s) => s.kind),
+	);
+
+	if (!requiredKinds.has("objective")) {
+		errors.push({
+			code: "MISSING_OBJECTIVE",
+			message: "No objective section produced",
+		});
+	}
+
+	// 5. Check for unresolved required sources
+	for (const section of sections) {
+		if (section.required) {
+			for (const ref of section.sourceRefs) {
+				const refText =
+					typeof ref.text === "string" ? ref.text : String(ref.text ?? "");
+				if (!refText.trim()) {
+					errors.push({
+						code: "UNRESOLVED_REQUIRED_SOURCE",
+						message: `Required source "${ref.source}" has no content`,
+					});
+				}
+			}
+		}
+	}
+
+	// 6. Check tool permissions don't conflict with policy
+	for (const perm of request.toolPermissions) {
+		if (isProhibitedTool(perm)) {
+			errors.push({
+				code: "POLICY_CONFLICT",
+				message: `Tool permission "${perm}" is prohibited by policy`,
+			});
+		}
+	}
+
+	if (errors.length > 0) {
+		throw new PromptCompileError(errors[0]?.code, errors[0]?.message, {
+			errors,
+		});
+	}
+}
+
+/**
+ * Validate that the token budget is not exceeded.
+ */
+export function validateTokenBudget(
+	estimatedTokens: number,
+	profile: ProviderPromptProfile,
+): void {
+	const available = profile.maximumInputTokens - profile.reservedOutputTokens;
+	if (estimatedTokens > available) {
+		throw new PromptCompileError(
+			"TOKEN_BUDGET_EXCEEDED",
+			`Estimated ${estimatedTokens} tokens exceeds available budget ${available}`,
+			{
+				estimatedTokens,
+				availableTokens: available,
+				maximumTokens: profile.maximumInputTokens,
+				reservedOutput: profile.reservedOutputTokens,
+			},
+		);
+	}
+}
+
+/**
+ * List of tools/commands prohibited by default policy.
+ * These are never permitted without explicit override.
+ */
+const PROHIBITED_TOOLS = new Set([
+	"rm -rf /",
+	"DROP DATABASE",
+	"DELETE FROM",
+	"TRUNCATE",
+	"sudo rm",
+	"git push --force",
+	"bench --force",
+	"yarn build",
+	"npm run build",
+	"pnpm build",
+]);
+
+function isProhibitedTool(permission: string): boolean {
+	const normalized = permission.toLowerCase().trim();
+	for (const prohibited of PROHIBITED_TOOLS) {
+		if (normalized.includes(prohibited.toLowerCase())) {
+			return true;
+		}
+	}
+	return false;
+}

package/packages/prompt-versioning/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Prompt Versioning — Main Entry (RFC-0019)
+ */
+
+export { PromptVersioning } from "./versioning.js";
+export type * from "./types.js";

package/packages/prompt-versioning/src/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Prompt Versioning — Types (RFC-0019)
+ */
+
+export interface PromptVersion {
+	version: string;
+	prompt: string;
+	createdAt: string;
+	createdBy?: string;
+	tags?: string[];
+	metadata?: Record<string, string>;
+}
+
+export interface PromptRecord {
+	id: string;
+	name: string;
+	versions: PromptVersion[];
+	activeVersion: string;
+}
+
+export interface VersionDiff {
+	from: string;
+	to: string;
+	added: number;
+	removed: number;
+	addedLines: string[];
+	removedLines: string[];
+}
+
+export interface RollbackResult {
+	promptId: string;
+	rolledBackTo: string;
+	currentVersion: string;
+	previousVersion: string;
+}
+
+export interface PromptVersioningConfig {
+	maxVersions?: number;
+	allowDelete?: boolean;
+	onVersionCreated?: (v: PromptVersion) => void;
+}

package/packages/prompt-versioning/src/versioning.ts

@@ -0,0 +1,149 @@
+/**
+ * Prompt Versioning — Core (RFC-0019)
+ */
+
+import type {
+	PromptVersion,
+	PromptRecord,
+	VersionDiff,
+	RollbackResult,
+	PromptVersioningConfig,
+} from "./types.js";
+
+let _counter = 0;
+function nextId(): string {
+	return `pv-${Date.now()}-${++_counter}`;
+}
+
+export class PromptVersioning {
+	private prompts = new Map<string, PromptRecord>();
+	private config: Required<PromptVersioningConfig>;
+
+	constructor(config: PromptVersioningConfig = {}) {
+		this.config = {
+			maxVersions: config.maxVersions ?? 50,
+			allowDelete: config.allowDelete ?? false,
+			onVersionCreated: config.onVersionCreated ?? (() => {}),
+		};
+	}
+
+	createPrompt(name: string, initialPrompt: string, createdBy?: string): PromptRecord {
+		const v = this.makeVersion(initialPrompt, createdBy);
+		const record: PromptRecord = {
+			id: nextId(),
+			name,
+			versions: [v],
+			activeVersion: v.version,
+		};
+		this.prompts.set(record.id, record);
+		return record;
+	}
+
+	addVersion(promptId: string, prompt: string, createdBy?: string, tags?: string[]): PromptVersion {
+		const record = this.getOrThrow(promptId);
+		const v = this.makeVersion(prompt, createdBy, tags);
+		record.versions.push(v);
+		record.activeVersion = v.version;
+		this.enforceMaxVersions(record);
+		this.config.onVersionCreated(v);
+		return v;
+	}
+
+	getVersion(promptId: string, version?: string): PromptVersion | null {
+		const record = this.prompts.get(promptId);
+		if (!record) return null;
+		if (!version) {
+			return record.versions.find((v) => v.version === record.activeVersion) ?? null;
+		}
+		return record.versions.find((v) => v.version === version) ?? null;
+	}
+
+	listVersions(promptId: string): PromptVersion[] {
+		return this.get(promptId)?.versions ?? [];
+	}
+
+	diff(promptId: string, from: string, to: string): VersionDiff | null {
+		const record = this.prompts.get(promptId);
+		if (!record) return null;
+		const fromV = record.versions.find((v) => v.version === from);
+		const toV = record.versions.find((v) => v.version === to);
+		if (!fromV || !toV) return null;
+
+		const fromLines = fromV.prompt.split("\n");
+		const toLines = toV.prompt.split("\n");
+		const fromSet = new Set(fromLines);
+		const toSet = new Set(toLines);
+
+		const addedLines = toLines.filter((l) => !fromSet.has(l));
+		const removedLines = fromLines.filter((l) => !toSet.has(l));
+
+		return {
+			from,
+			to,
+			added: addedLines.length,
+			removed: removedLines.length,
+			addedLines: addedLines.slice(0, 20),
+			removedLines: removedLines.slice(0, 20),
+		};
+	}
+
+	rollback(promptId: string, targetVersion: string): RollbackResult | null {
+		const record = this.prompts.get(promptId);
+		if (!record) return null;
+		const target = record.versions.find((v) => v.version === targetVersion);
+		if (!target) return null;
+
+		const previous = record.activeVersion;
+		record.activeVersion = targetVersion;
+		return {
+			promptId,
+			rolledBackTo: targetVersion,
+			currentVersion: record.activeVersion,
+			previousVersion: previous,
+		};
+	}
+
+	delete(promptId: string): boolean {
+		if (!this.config.allowDelete) return false;
+		return this.prompts.delete(promptId);
+	}
+
+	listPrompts(): PromptRecord[] {
+		return [...this.prompts.values()];
+	}
+
+	getStats(promptId: string): { versionCount: number; activeVersion: string } | null {
+		const r = this.prompts.get(promptId);
+		return r ? { versionCount: r.versions.length, activeVersion: r.activeVersion } : null;
+	}
+
+	private makeVersion(prompt: string, createdBy?: string, tags?: string[]): PromptVersion {
+		const version = `v${Date.now()}-${++_counter}`;
+		const v: PromptVersion = {
+			version,
+			prompt,
+			createdAt: new Date().toISOString(),
+			createdBy,
+			tags,
+		};
+		return v;
+	}
+
+	private enforceMaxVersions(record: PromptRecord): void {
+		while (record.versions.length > this.config.maxVersions) {
+			const oldest = record.versions[0];
+			if (oldest.version === record.activeVersion) break;
+			record.versions.shift();
+		}
+	}
+
+	private get(promptId: string): PromptRecord | undefined {
+		return this.prompts.get(promptId);
+	}
+
+	private getOrThrow(promptId: string): PromptRecord {
+		const r = this.prompts.get(promptId);
+		if (!r) throw new Error(`Prompt not found: ${promptId}`);
+		return r;
+	}
+}