pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/prompt-compiler/src/section-builder.ts

@@ -0,0 +1,279 @@
+/**
+ * Prompt Compiler - Section Builder
+ *
+ * Assembles prompt sections from a normalized request.
+ * Each section is built independently for testability.
+ */
+
+import type { NormalizedContinuation, NormalizedRequest } from "./normalize.js";
+import type { PromptSection } from "./types.js";
+
+/**
+ * Build all prompt sections from a normalized request.
+ * Section order is deterministic per RFC-0041.
+ */
+export function buildSections(
+	normalized: NormalizedRequest,
+	projectRules: string[],
+): PromptSection[] {
+	const sections: PromptSection[] = [];
+
+	// 1. Runtime identity
+	sections.push(buildIdentitySection(normalized));
+
+	// 2. Project rules
+	if (projectRules.length > 0) {
+		sections.push(buildProjectRulesSection(projectRules));
+	}
+
+	// 3. Objective
+	sections.push(buildObjectiveSection(normalized));
+
+	// 4. Acceptance criteria
+	if (normalized.acceptanceCriteria.length > 0) {
+		sections.push(buildAcceptanceCriteriaSection(normalized));
+	}
+
+	// 5. Relevant context
+	if (normalized.contextEntries.length > 0) {
+		sections.push(buildContextSection(normalized));
+	}
+
+	// 6. Known constraints
+	if (normalized.constraints.length > 0) {
+		sections.push(buildConstraintsSection(normalized));
+	}
+
+	// 7. Files in scope
+	if (normalized.filesInScope.length > 0) {
+		sections.push(buildFilesInScopeSection(normalized));
+	}
+
+	// 8. Required output
+	if (normalized.expectedOutputs.length > 0) {
+		sections.push(buildRequiredOutputSection(normalized));
+	}
+
+	// 9. Tool permissions
+	if (normalized.toolPermissions.length > 0) {
+		sections.push(buildToolPermissionsSection(normalized));
+	}
+
+	// 10. Continuation instructions
+	if (normalized.continuation) {
+		sections.push(buildContinuationSection(normalized));
+	}
+
+	return sections;
+}
+
+// ─── Section builders ───────────────────────────────────────────────────
+
+function buildIdentitySection(req: NormalizedRequest): PromptSection {
+	const lines = [
+		"# Task Identity",
+		"",
+		`Task ID: ${req.taskId}`,
+		`Requirement: ${req.requirementId}`,
+		`Provider: ${req.provider}`,
+		`Attempt: ${req.attempt}`,
+	];
+
+	return {
+		id: "identity",
+		kind: "identity",
+		content: lines.join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: [],
+	};
+}
+
+function buildProjectRulesSection(rules: string[]): PromptSection {
+	return {
+		id: "project_rules",
+		kind: "project_rules",
+		content: [
+			"# Project Rules",
+			"",
+			...rules.map((rule, i) => `${i + 1}. ${rule}`),
+		].join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: [],
+	};
+}
+
+function buildObjectiveSection(req: NormalizedRequest): PromptSection {
+	return {
+		id: "objective",
+		kind: "objective",
+		content: [
+			"# Objective",
+			"",
+			req.objective || "(no objective provided)",
+		].join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: [],
+	};
+}
+
+function buildAcceptanceCriteriaSection(req: NormalizedRequest): PromptSection {
+	return {
+		id: "acceptance_criteria",
+		kind: "acceptance_criteria",
+		content: [
+			"# Acceptance Criteria",
+			"",
+			...req.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`),
+		].join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: [],
+	};
+}
+
+function buildContextSection(req: NormalizedRequest): PromptSection {
+	const lines = ["# Relevant Context", ""];
+
+	for (const entry of req.contextEntries) {
+		const priorityLabel =
+			entry.priority === 0
+				? "[CRITICAL]"
+				: entry.priority <= 3
+					? "[IMPORTANT]"
+					: entry.priority <= 6
+						? "[USEFUL]"
+						: "[SUPPLEMENTAL]";
+
+		lines.push(`## ${priorityLabel} ${entry.source}`);
+		lines.push(entry.content);
+		lines.push("");
+	}
+
+	return {
+		id: "relevant_context",
+		kind: "relevant_context",
+		content: lines.join("\n"),
+		required: false,
+		compactable: true,
+		sourceRefs: req.contextEntries.map((e) => ({
+			source: e.source,
+			text: e.content.slice(0, 200),
+		})),
+	};
+}
+
+function buildConstraintsSection(req: NormalizedRequest): PromptSection {
+	return {
+		id: "known_constraints",
+		kind: "known_constraints",
+		content: [
+			"# Known Constraints",
+			"",
+			...req.constraints.map((c, i) => `${i + 1}. ${c}`),
+		].join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: [],
+	};
+}
+
+function buildFilesInScopeSection(req: NormalizedRequest): PromptSection {
+	return {
+		id: "files_in_scope",
+		kind: "files_in_scope",
+		content: [
+			"# Files in Scope",
+			"",
+			"Only modify or create files listed below:",
+			"",
+			...req.filesInScope.map((f) => `- ${f}`),
+			"",
+			"Do NOT modify any other files unless explicitly required.",
+		].join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: req.filesInScope.map((f) => ({ source: f, text: f })),
+	};
+}
+
+function buildRequiredOutputSection(req: NormalizedRequest): PromptSection {
+	return {
+		id: "required_output",
+		kind: "required_output",
+		content: [
+			"# Required Output",
+			"",
+			"Produce the following outputs to mark this task complete:",
+			"",
+			...req.expectedOutputs.map((o) => `- ${o}`),
+			"",
+			"Each output must be verified before marking the task done.",
+		].join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: [],
+	};
+}
+
+function buildToolPermissionsSection(req: NormalizedRequest): PromptSection {
+	return {
+		id: "tool_permissions",
+		kind: "tool_permissions",
+		content: [
+			"# Tool Permissions",
+			"",
+			"You may use the following tools:",
+			"",
+			...req.toolPermissions.map((t) => `- ${t}`),
+			"",
+			"Do NOT run any other commands without explicit approval.",
+		].join("\n"),
+		required: false,
+		compactable: true,
+		sourceRefs: [],
+	};
+}
+
+function buildContinuationSection(req: NormalizedRequest): PromptSection {
+	const cont = req.continuation as NormalizedContinuation;
+	const completedLines =
+		cont.completedItems.length > 0
+			? [
+					"",
+					"## Completed (do not repeat)",
+					"",
+					...cont.completedItems.map((item) => `- ~~${item}~~ [DONE]`),
+				]
+			: [];
+
+	const incompleteLines =
+		cont.incompleteItems.length > 0
+			? [
+					"",
+					"## Incomplete (continue these)",
+					"",
+					...cont.incompleteItems.map((item) => `- ${item}`),
+				]
+			: [];
+
+	return {
+		id: "continuation_instructions",
+		kind: "continuation_instructions",
+		content: [
+			"# Continuation",
+			"",
+			"Continue from where the previous attempt stopped.",
+			"Do not repeat completed work.",
+			...completedLines,
+			...incompleteLines,
+		].join("\n"),
+		required: true,
+		compactable: false,
+		sourceRefs: [
+			{ source: cont.previousResponsePath, text: "[Previous response]" },
+		],
+	};
+}

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;
+}