pi-harness-runtime 0.10.13 → 0.10.14

package/harness/master-planner.js

@@ -0,0 +1,229 @@
+/**
+ * Master Planner — RFC-0017
+ *
+ * Converts a human requirement into an executable task graph.
+ * Uses a planning LLM to decompose the requirement into tasks with dependencies.
+ */
+const DEFAULT_SYSTEM_PROMPT = `You are a software project planner. Given a human requirement, decompose it into a clear task list.
+
+Rules:
+1. Each task should be atomic and independently testable
+2. Tasks must be ordered with proper dependencies
+3. Include acceptance criteria for each task
+4. Consider: analysis, implementation, testing, review phases
+5. Output ONLY valid JSON in the specified format
+
+Output format:
+{
+  "tasks": [
+    {
+      "id": "task-001",
+      "title": "Descriptive title",
+      "description": "What this task does",
+      "dependencies": [], // array of task IDs this depends on
+      "acceptanceCriteria": ["criterion 1", "criterion 2"]
+    }
+  ]
+}`;
+export class MasterPlanner {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Create a plan from a requirement
+     */
+    async createPlan(requirement, jobId, rootDir) {
+        try {
+            // Build the planning prompt
+            const userPrompt = `Human requirement:\n${requirement}\n\nMax tasks: ${this.options.maxTasks ?? 20}`;
+            let taskList;
+            if (this.options.planningProvider) {
+                // Use LLM to generate task list
+                const response = await this.options.planningProvider.call(userPrompt, DEFAULT_SYSTEM_PROMPT);
+                const parsed = this.parsePlanningResponse(response);
+                if (!parsed) {
+                    return { success: false, error: "Failed to parse planning response" };
+                }
+                taskList = parsed;
+            }
+            else {
+                // Use heuristic planner for simple requirements
+                taskList = this.heuristicPlan(requirement);
+            }
+            // Validate the task list
+            if (taskList.length === 0) {
+                return { success: false, error: "No tasks generated from requirement" };
+            }
+            // Validate dependencies (no cycles, all deps exist)
+            const taskIds = new Set(taskList.map((t) => t.id));
+            for (const task of taskList) {
+                for (const dep of task.dependencies) {
+                    if (!taskIds.has(dep)) {
+                        return {
+                            success: false,
+                            error: `Task ${task.id} has invalid dependency: ${dep}`,
+                        };
+                    }
+                }
+            }
+            // Create task graph
+            const graphManager = new TaskGraphManager({ jobId });
+            for (const task of taskList) {
+                graphManager.addTask(task.id, task.title, task.description, task.dependencies, task.acceptanceCriteria);
+            }
+            const graph = graphManager.getGraph();
+            // Save the graph
+            await graphManager.save(rootDir);
+            return { success: true, graph };
+        }
+        catch (error) {
+            return { success: false, error: String(error) };
+        }
+    }
+    /**
+     * Parse planning response from LLM
+     */
+    parsePlanningResponse(response) {
+        // Try to extract JSON from response
+        const jsonMatch = response.match(/```json\n([\s\S]*?)\n```/) ??
+            response.match(/\{[\s\S]*"tasks"[\s\S]*\}/);
+        if (!jsonMatch) {
+            console.error("Failed to extract JSON from planning response");
+            return null;
+        }
+        const jsonStr = jsonMatch[1] ?? jsonMatch[0];
+        try {
+            const parsed = JSON.parse(jsonStr);
+            return parsed.tasks ?? [];
+        }
+        catch {
+            console.error("Failed to parse JSON from planning response");
+            return null;
+        }
+    }
+    /**
+     * Heuristic planner for simple requirements
+     * Used when no LLM provider is available
+     */
+    heuristicPlan(requirement) {
+        const tasks = [];
+        const req = requirement.toLowerCase();
+        // Task 1: Analysis
+        tasks.push({
+            id: "task-001",
+            title: "Analyze requirements",
+            description: `Analyze and document the requirements: ${requirement}`,
+            dependencies: [],
+            acceptanceCriteria: [
+                "Requirements are clearly documented",
+                "All edge cases identified",
+                "Technical approach defined",
+            ],
+        });
+        // Task 2: Implementation
+        if (req.includes("api") ||
+            req.includes("endpoint") ||
+            req.includes("backend")) {
+            tasks.push({
+                id: "task-002",
+                title: "Implement API endpoints",
+                description: "Create API endpoints based on requirements",
+                dependencies: ["task-001"],
+                acceptanceCriteria: [
+                    "Endpoints return correct responses",
+                    "Error handling implemented",
+                    "Input validation in place",
+                ],
+            });
+        }
+        if (req.includes("database") ||
+            req.includes("model") ||
+            req.includes("schema")) {
+            tasks.push({
+                id: "task-003",
+                title: "Implement database schema",
+                description: "Create database models and migrations",
+                dependencies: ["task-001"],
+                acceptanceCriteria: [
+                    "Schema matches requirements",
+                    "Migrations run successfully",
+                    "Relationships defined correctly",
+                ],
+            });
+        }
+        if (req.includes("ui") ||
+            req.includes("frontend") ||
+            req.includes("page") ||
+            req.includes("component")) {
+            tasks.push({
+                id: "task-004",
+                title: "Implement UI components",
+                description: "Create frontend UI components",
+                dependencies: ["task-001"],
+                acceptanceCriteria: [
+                    "Components match design",
+                    "Responsive on all devices",
+                    "Accessible",
+                ],
+            });
+        }
+        // Task 5: Tests
+        const implDeps = tasks
+            .filter((t) => t.id.startsWith("task-00"))
+            .map((t) => t.id);
+        tasks.push({
+            id: "task-010",
+            title: "Write unit tests",
+            description: "Write unit tests for all implemented code",
+            dependencies: implDeps.length > 0 ? implDeps : ["task-001"],
+            acceptanceCriteria: [
+                "All new code has >80% test coverage",
+                "All tests pass",
+                "Edge cases covered",
+            ],
+        });
+        // Task 6: Integration
+        tasks.push({
+            id: "task-011",
+            title: "Integration testing",
+            description: "Run integration tests and verify end-to-end flow",
+            dependencies: ["task-010"],
+            acceptanceCriteria: [
+                "Integration tests pass",
+                "No regression in existing functionality",
+            ],
+        });
+        // Task 7: Review
+        tasks.push({
+            id: "task-012",
+            title: "Code review",
+            description: "Review code for quality, security, and best practices",
+            dependencies: ["task-011"],
+            acceptanceCriteria: [
+                "Code follows project style guide",
+                "No security vulnerabilities",
+                "Documentation updated",
+            ],
+        });
+        return tasks;
+    }
+    /**
+     * Generate a simple task ID
+     */
+    static generateTaskId(index) {
+        return `task-${String(index).padStart(3, "0")}`;
+    }
+}
+/**
+ * Parse a requirement into a basic task list (synchronous, no LLM)
+ */
+export function parseRequirementIntoTasks(requirement, jobId) {
+    const planner = new MasterPlanner();
+    const taskList = planner.heuristicPlan(requirement);
+    const graphManager = new TaskGraphManager({ jobId });
+    for (const task of taskList) {
+        graphManager.addTask(task.id, task.title, task.description, task.dependencies, task.acceptanceCriteria);
+    }
+    return graphManager;
+}

package/harness/notification-events.js

@@ -0,0 +1,233 @@
+/**
+ * Harness Notification Events — RFC-0022
+ *
+ * Integrates NotificationCenter with the harness runtime.
+ * Sends mobile alerts for all runtime events.
+ *
+ * Events:
+ *   JobStarted, TaskCompleted, TaskFailed, QuotaPaused,
+ *   ResumeScheduled, ContextCompacted, OutputLimitContinued,
+ *   E2EFailed, HumanReviewNeeded, ReadyForClient, JobCancelled, Error
+ */
+import { NotificationCenter } from "../packages/notification/notification-center.js";
+export class HarnessNotificationEvents {
+    center;
+    config;
+    machine = null;
+    graph = null;
+    constructor(config) {
+        this.config = config;
+        this.center = new NotificationCenter(config.notificationConfig);
+    }
+    /**
+     * Initialize the notification center
+     */
+    async initialize() {
+        await this.center.initialize();
+    }
+    /**
+     * Attach to job state machine to receive events
+     */
+    attachToMachine(machine) {
+        this.machine = machine;
+    }
+    /**
+     * Attach to task graph to get task info
+     */
+    attachToGraph(graph) {
+        this.graph = graph;
+    }
+    /**
+     * Check if notifications are configured
+     */
+    hasChannels() {
+        return this.center.hasChannels();
+    }
+    /**
+     * List configured channels
+     */
+    listChannels() {
+        return this.center.listChannels();
+    }
+    // --- Event Emitters ------------------------------------------------
+    /**
+     * Emit JobStarted event
+     */
+    async emitJobStarted() {
+        await this.emit("JobStarted");
+    }
+    /**
+     * Emit TaskCompleted event
+     */
+    async emitTaskCompleted(taskId, taskTitle) {
+        await this.emit("TaskCompleted", { taskId, taskTitle });
+    }
+    /**
+     * Emit TaskFailed event
+     */
+    async emitTaskFailed(taskId, taskTitle, error) {
+        await this.emit("TaskFailed", { taskId, taskTitle, error });
+    }
+    /**
+     * Emit QuotaPaused event
+     */
+    async emitQuotaPaused(resumeAt) {
+        await this.emit("QuotaPaused", {
+            error: resumeAt ? `Resumes at ${resumeAt}` : undefined,
+        });
+    }
+    /**
+     * Emit ResumeScheduled event
+     */
+    async emitResumeScheduled(resumeAt) {
+        await this.emit("ResumeScheduled", { error: resumeAt });
+    }
+    /**
+     * Emit ContextCompacted event
+     */
+    async emitContextCompacted(tokensCompacted) {
+        await this.emit("ContextCompacted", {
+            error: tokensCompacted
+                ? `Compacted ${tokensCompacted.toLocaleString()} tokens`
+                : undefined,
+        });
+    }
+    /**
+     * Emit OutputLimitContinued event
+     */
+    async emitOutputLimitContinued(attempt) {
+        await this.emit("OutputLimitContinued", {
+            error: `Attempt ${attempt}`,
+        });
+    }
+    /**
+     * Emit E2EFailed event
+     */
+    async emitE2EFailed(scenarioId) {
+        await this.emit("E2EFailed", {
+            error: scenarioId ? `Scenario: ${scenarioId}` : undefined,
+        });
+    }
+    /**
+     * Emit HumanReviewNeeded event
+     */
+    async emitHumanReviewNeeded(taskId, reason) {
+        await this.emit("HumanReviewNeeded", { taskId, error: reason });
+    }
+    /**
+     * Emit ReadyForClient event
+     */
+    async emitReadyForClient() {
+        await this.emit("ReadyForClient");
+    }
+    /**
+     * Emit JobCancelled event
+     */
+    async emitJobCancelled(reason) {
+        await this.emit("JobCancelled", { error: reason });
+    }
+    /**
+     * Emit Error event
+     */
+    async emitError(error) {
+        await this.emit("Error", { error });
+    }
+    // --- State Machine Event Listeners ---------------------------------
+    /**
+     * Wire up with JobStateMachine to emit events on transitions
+     */
+    wireWithStateMachine(machine) {
+        this.machine = machine;
+        // Listen to state machine events via polling or callback
+        // This would need the state machine to emit events
+    }
+    /**
+     * Check current state and emit appropriate events
+     */
+    async checkAndEmitStateChange(oldState, newState) {
+        // Map state machine states to notification events
+        const stateEventMap = {
+            paused_quota: "QuotaPaused",
+            waiting_human: "HumanReviewNeeded",
+            ready_for_client: "ReadyForClient",
+            cancelled: "JobCancelled",
+            planning: "JobStarted",
+        };
+        const event = stateEventMap[newState];
+        if (event) {
+            await this.emit(event);
+        }
+    }
+    // --- Private Methods -----------------------------------------------
+    async emit(event, extra) {
+        if (!this.center.hasChannels()) {
+            return; // No channels configured, skip
+        }
+        const context = {
+            jobId: this.config.jobId,
+            requirement: this.config.requirement,
+            ...extra,
+        };
+        try {
+            const results = await this.center.notify(event, context);
+            // Log results (but don't fail if notification fails)
+            for (const result of results) {
+                if (!result.success) {
+                    console.warn(`[NotificationEvents] Failed to send ${event} to ${result.channel}: ${result.error}`);
+                }
+            }
+        }
+        catch (error) {
+            // Never crash the runtime due to notification failure
+            console.error(`[NotificationEvents] Notification error: ${error}`);
+        }
+    }
+}
+/**
+ * Create notification config from environment variables
+ */
+export function createNotificationConfigFromEnv() {
+    const channels = [];
+    // Telegram
+    if (process.env.TELEGRAM_BOT_TOKEN && process.env.TELEGRAM_CHAT_ID) {
+        channels.push({
+            id: "telegram",
+            type: "telegram",
+            enabled: true,
+            config: {
+                botToken: process.env.TELEGRAM_BOT_TOKEN,
+                chatId: process.env.TELEGRAM_CHAT_ID,
+            },
+        });
+    }
+    // Ntfy
+    if (process.env.NTFY_TOPIC) {
+        channels.push({
+            id: "ntfy",
+            type: "ntfy",
+            enabled: true,
+            config: {
+                server: process.env.NTFY_SERVER ?? "https://ntfy.sh",
+                topic: process.env.NTFY_TOPIC,
+                authToken: process.env.NTFY_TOKEN,
+            },
+        });
+    }
+    // Webhook
+    if (process.env.NOTIFICATION_WEBHOOK_URL) {
+        channels.push({
+            id: "webhook",
+            type: "webhook",
+            enabled: true,
+            config: {
+                url: process.env.NOTIFICATION_WEBHOOK_URL,
+                method: process.env.NOTIFICATION_WEBHOOK_METHOD ?? "POST",
+                authToken: process.env.NOTIFICATION_WEBHOOK_TOKEN,
+            },
+        });
+    }
+    if (channels.length === 0) {
+        return undefined;
+    }
+    return { channels, enabled: true };
+}

package/harness/output-limit-handler.js

@@ -0,0 +1,233 @@
+/**
+ * Output Token Limit Handler — RFC-0020
+ *
+ * Handles model responses that stop because the maximum output token limit was reached.
+ * Coordinates with AutoCompactEngine (RFC-0019) and PartialRecovery (RFC-0021).
+ *
+ * Classification Matrix:
+ * | Failure Type       | Runtime Action           |
+ * |--------------------|--------------------------|
+ * | Quota exhausted    | pause until reset        |
+ * | Context full       | compact and resume       |
+ * | Output token limit | continue same task       |
+ * | Unknown error      | retry or escalate        |
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const OUTPUT_LIMIT_PATTERNS = [
+    /reached the maximum output token limit/i,
+    /output token limit/i,
+    /response may be incomplete/i,
+    /stop_reason.*length/i,
+    /finish_reason.*length/i,
+    /max_tokens.*exceeded/i,
+    /completion.*truncated/i,
+    /model.*stopped.*token/i,
+];
+export class OutputLimitHandler {
+    rootDir;
+    jobId;
+    taskId;
+    maxAttempts;
+    backoffMs;
+    requireValidation;
+    attempts = 0;
+    partials = [];
+    constructor(config) {
+        this.rootDir =
+            config.rootDir ??
+                join(homedir(), ".pi", "harness", config.jobId, "partial", config.taskId);
+        this.jobId = config.jobId;
+        this.taskId = config.taskId;
+        this.maxAttempts = config.maxContinueAttempts ?? 5;
+        this.backoffMs = config.continuationBackoffMs ?? 1000;
+        this.requireValidation = config.requireExpectedOutputValidation ?? true;
+        this.ensureDir();
+    }
+    /**
+     * Detect if an error or response indicates output limit was reached
+     */
+    detectOutputLimit(error, response) {
+        // Check error message
+        if (error) {
+            const errorStr = String(error).toLowerCase();
+            for (const pattern of OUTPUT_LIMIT_PATTERNS) {
+                if (pattern.test(errorStr)) {
+                    return true;
+                }
+            }
+        }
+        // Check finish reason
+        if (response?.finishReason === "length") {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Classify the type of failure for proper handling
+     */
+    classifyFailure(error, response) {
+        const errorStr = String(error ?? "").toLowerCase();
+        // Check for quota exhaustion
+        if (/error.*quota/i.test(errorStr) ||
+            /error.*2056/i.test(errorStr) ||
+            /error.*insufficient_quota/i.test(errorStr)) {
+            return "quota_exhausted";
+        }
+        // Check for context/sequence length
+        if (/error.*context.*length/i.test(errorStr) ||
+            /error.*too many tokens/i.test(errorStr) ||
+            /error.*maximum context/i.test(errorStr)) {
+            return "context_full";
+        }
+        // Check for output token limit
+        if (this.detectOutputLimit(error, response) ||
+            response?.finishReason === "length") {
+            return "output_limit";
+        }
+        return "unknown";
+    }
+    /**
+     * Handle output limit - save partial and prepare continuation
+     */
+    async handleOutputLimit(partialContent, finishReason = "length") {
+        this.attempts++;
+        const timestamp = new Date().toISOString();
+        // Save partial response
+        const partialPath = this.savePartial(partialContent, this.attempts);
+        this.partials.push(partialPath);
+        // Create event
+        const event = {
+            timestamp,
+            jobId: this.jobId,
+            taskId: this.taskId,
+            reason: "output_token_limit",
+            partialContent,
+            finishReason: finishReason,
+            attempts: this.attempts,
+        };
+        // Save event
+        this.saveEvent(event);
+        // Wait with backoff before continuing
+        await this.backoff();
+        return event;
+    }
+    /**
+     * Check if we should continue (respects max attempts)
+     */
+    shouldContinue() {
+        return this.attempts < this.maxAttempts;
+    }
+    /**
+     * Get current attempt count
+     */
+    getAttempts() {
+        return this.attempts;
+    }
+    /**
+     * Get all partial responses
+     */
+    getPartials() {
+        return [...this.partials];
+    }
+    /**
+     * Merge partial responses
+     */
+    mergePartials() {
+        const merged = [];
+        for (const partialPath of this.partials) {
+            if (existsSync(partialPath)) {
+                const content = readFileSync(partialPath, "utf-8");
+                merged.push(content);
+            }
+        }
+        // v0.1: simple concatenation as markdown sections
+        return merged
+            .map((p, i) => `## Partial ${i + 1}\n\n${p}`)
+            .join("\n\n---\n\n");
+    }
+    /**
+     * Build continue message for the next turn
+     */
+    buildContinueMessage(additionalContext) {
+        const merged = this.mergePartials();
+        const lines = [
+            "# Continue From Partial Response",
+            "",
+            "The previous response was truncated due to output token limit.",
+            "",
+            "## Merged Partial Content",
+            "",
+            merged,
+        ];
+        if (additionalContext) {
+            lines.push("", "## Additional Context");
+            lines.push("", additionalContext);
+        }
+        lines.push("", "## Instructions");
+        lines.push("");
+        lines.push("1. Review the partial content above");
+        lines.push("2. Continue from where the response was truncated");
+        lines.push("3. Do not repeat content that already appears above");
+        lines.push(`4. This is attempt ${this.attempts + 1} of ${this.maxAttempts}`);
+        return lines.join("\n");
+    }
+    /**
+     * Validate expected output if configured
+     */
+    validateOutput(content, expected) {
+        if (!this.requireValidation) {
+            return true;
+        }
+        if (expected.validate) {
+            return expected.validate(content);
+        }
+        // Basic validation: content should be longer than partial
+        return content.length > this.getPartials()[0]?.length ?? 0;
+    }
+    /**
+     * Reset for a new task
+     */
+    reset() {
+        this.attempts = 0;
+        this.partials = [];
+    }
+    /**
+     * Check if escalation is needed (max attempts reached)
+     */
+    shouldEscalate() {
+        return this.attempts >= this.maxAttempts;
+    }
+    // --- Private Methods ------------------------------------------------
+    ensureDir() {
+        if (!existsSync(this.rootDir)) {
+            mkdirSync(this.rootDir, { recursive: true });
+        }
+    }
+    savePartial(content, attempt) {
+        const filename = `partial_${String(attempt).padStart(3, "0")}.md`;
+        const path = join(this.rootDir, filename);
+        writeFileSync(path, content, "utf-8");
+        return path;
+    }
+    saveEvent(event) {
+        const eventsPath = join(this.rootDir, "events.jsonl");
+        writeFileSync(eventsPath, JSON.stringify(event) + "\n", "utf-8");
+        // Also save recovery status
+        const statusPath = join(this.rootDir, "recovery_status.json");
+        const status = {
+            taskId: this.taskId,
+            status: this.shouldContinue() ? "continuing" : "escalated",
+            partials: this.partials.map((p) => p.split("/").pop()),
+            mergedOutput: "merged.md",
+            attempts: this.attempts,
+            lastError: event.reason,
+        };
+        writeFileSync(statusPath, JSON.stringify(status, null, 2) + "\n", "utf-8");
+    }
+    async backoff() {
+        const delay = this.backoffMs * 2 ** (this.attempts - 1);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}