@lsctech/polaris 0.1.0

package/dist/loop/worker.js

@@ -0,0 +1,498 @@
+"use strict";
+/**
+ * Polaris worker entry point.
+ *
+ * A worker process is spawned by the parent loop to execute exactly ONE child
+ * task. The worker:
+ *   1. Reads the bootstrap packet (from POLARIS_BOOTSTRAP_PACKET env var or
+ *      --bootstrap CLI flag).
+ *   2. Executes the single child specified in the packet.
+ *   3. Updates current-state.json (child completion fields).
+ *   4. Appends telemetry JSONL events.
+ *   5. Writes a CompactReturn JSON to stdout.
+ *   6. Exits.
+ *
+ * The worker MUST NOT continue to the next child under any circumstances.
+ * Calling runWorker() will call process.exit() when done.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBootstrapPacket = readBootstrapPacket;
+exports.executeOneChild = executeOneChild;
+exports.runWorker = runWorker;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const checkpoint_js_1 = require("./checkpoint.js");
+const monotonic_timestamp_js_1 = require("../utils/monotonic-timestamp.js");
+const index_js_1 = require("../cognition/index.js");
+// ────────────────────────────────────────────────────────────────────────────
+// Bootstrap packet reading
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Parse CLI args looking for --bootstrap <path>.
+ */
+function bootstrapPathFromArgs(argv) {
+    const idx = argv.indexOf("--bootstrap");
+    if (idx !== -1 && idx + 1 < argv.length) {
+        return argv[idx + 1] ?? null;
+    }
+    return null;
+}
+/**
+ * Read and parse the bootstrap packet.
+ * Resolution order:
+ *   1. --bootstrap <path> CLI argument
+ *   2. POLARIS_BOOTSTRAP_PACKET env var (path to file)
+ *   3. POLARIS_PACKET_FILE env var (path to file)
+ *   4. POLARIS_PACKET_JSON env var (raw JSON)
+ */
+function readBootstrapPacket(argv = process.argv) {
+    // 1. CLI arg
+    const cliPath = bootstrapPathFromArgs(argv);
+    if (cliPath) {
+        return JSON.parse((0, node_fs_1.readFileSync)(cliPath, "utf-8"));
+    }
+    // 2. POLARIS_BOOTSTRAP_PACKET env var (file path)
+    const envPath = process.env["POLARIS_BOOTSTRAP_PACKET"];
+    if (envPath) {
+        return JSON.parse((0, node_fs_1.readFileSync)(envPath, "utf-8"));
+    }
+    // 3. POLARIS_PACKET_FILE env var (file path)
+    const packetFile = process.env["POLARIS_PACKET_FILE"];
+    if (packetFile) {
+        return JSON.parse((0, node_fs_1.readFileSync)(packetFile, "utf-8"));
+    }
+    // 4. POLARIS_PACKET_JSON env var (raw JSON string)
+    const packetJson = process.env["POLARIS_PACKET_JSON"];
+    if (packetJson) {
+        return JSON.parse(packetJson);
+    }
+    throw new Error("No bootstrap packet found. Provide --bootstrap <path>, " +
+        "POLARIS_BOOTSTRAP_PACKET, POLARIS_PACKET_FILE, or POLARIS_PACKET_JSON.");
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Telemetry helpers
+// ────────────────────────────────────────────────────────────────────────────
+function appendTelemetry(telemetryFile, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Git helpers
+// ────────────────────────────────────────────────────────────────────────────
+function getHeadShort(cwd) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--short", "HEAD"], {
+            cwd,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Work note helpers
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Determine the primary folder (folder_slug) from touched files.
+ * Returns the folder containing the most changed files, normalized to lowercase with / → -.
+ */
+function determineFolderSlug(touchedFiles) {
+    if (touchedFiles.length === 0) {
+        return "root";
+    }
+    // Count files by folder depth, preferring the shallowest common folder
+    const folderCounts = {};
+    for (const file of touchedFiles) {
+        const parts = file.split("/");
+        // Try each folder level from root down
+        for (let i = 1; i <= parts.length; i++) {
+            const folder = parts.slice(0, i).join("/");
+            folderCounts[folder] = (folderCounts[folder] ?? 0) + 1;
+        }
+    }
+    // Find the folder with the most files (deepest common folder)
+    let maxFolder = "root";
+    let maxCount = 0;
+    for (const [folder, count] of Object.entries(folderCounts)) {
+        if (count > maxCount) {
+            maxCount = count;
+            maxFolder = folder;
+        }
+    }
+    // Normalize: replace / with -, handle edge cases
+    if (maxFolder === "root" || maxFolder === "") {
+        return "root";
+    }
+    return maxFolder.replace(/\//g, "-").toLowerCase();
+}
+/**
+ * Determine docs_impact based on cognition delta results.
+ * Returns one of: none, polaris-update, summary-update, both, archive-only
+ */
+function determineDocsImpact(cognitionDelta, summaryDelta) {
+    const polarisUpdate = cognitionDelta?.updateWarranted ?? false;
+    const summaryUpdate = summaryDelta?.updateWarranted ?? false;
+    if (polarisUpdate && summaryUpdate) {
+        return "both";
+    }
+    else if (polarisUpdate) {
+        return "polaris-update";
+    }
+    else if (summaryUpdate) {
+        return "summary-update";
+    }
+    return "none";
+}
+/**
+ * Write a work note to .polaris/cognition/pending/<folder-slug>/<run-id>-<child-id>.md
+ * Returns the repo-relative path to the written note.
+ */
+function writeWorkNote(repoRoot, runId, childId, issueId, folderSlug, touchedFiles, docsImpact, commit, validationPerformed) {
+    const timestamp = new Date().toISOString();
+    const primaryFolder = folderSlug === "root" ? "" : folderSlug.replace(/-/g, "/");
+    // Build frontmatter
+    const frontmatter = [
+        "---",
+        `run_id: ${runId}`,
+        `child_id: ${childId}`,
+        `issue_id: ${issueId}`,
+        `folder: ${primaryFolder || "."}`,
+        `folder_slug: ${folderSlug}`,
+        "affected_files:",
+        ...touchedFiles.map((f) => `  - ${f}`),
+        `validation_performed: ${validationPerformed}`,
+        `docs_impact: ${docsImpact}`,
+        `commit: ${commit}`,
+        `timestamp: ${timestamp}`,
+        "---",
+    ];
+    // Build prose body (minimal, ≤150 words)
+    const proseBody = `Completed task ${childId} (${issueId}). Implementation changes applied, validation passed. ${docsImpact !== "none" ? `Cognition surfaces require update (${docsImpact}).` : "No cognition surface updates needed."}`;
+    // Combine
+    const noteContent = [...frontmatter, "", proseBody].join("\n");
+    // Write to file
+    const notePath = (0, node_path_1.resolve)(repoRoot, ".polaris/cognition/pending", folderSlug, `${runId}-${childId}.md`);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(notePath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(notePath, noteContent, "utf-8");
+    // Return repo-relative path
+    return notePath.replace(repoRoot + "/", "");
+}
+/**
+ * Build a CompactReturn for an error case without touching durable state.
+ */
+function blockedReturn(childId, _reason) {
+    return {
+        child_id: childId,
+        status: 'blocked',
+        commit: null,
+        validation: 'skipped',
+        tracker_updated: false,
+        state_updated: false,
+        telemetry_updated: false,
+        next_recommended_action: 'stop',
+        result_data: {},
+    };
+}
+/**
+ * Execute one child task, update all durable state, and return a CompactReturn.
+ *
+ * This function does NOT call process.exit(). The caller (runWorker) does.
+ */
+async function executeOneChild(packet, options = {}) {
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const childId = packet.active_child;
+    const stateFile = (0, node_path_1.isAbsolute)(packet.state_file)
+        ? packet.state_file
+        : (0, node_path_1.resolve)(repoRoot, packet.state_file);
+    const telemetryFile = (0, node_path_1.isAbsolute)(packet.telemetry_file)
+        ? packet.telemetry_file
+        : (0, node_path_1.resolve)(repoRoot, packet.telemetry_file);
+    const now = monotonic_timestamp_js_1.getMonotonicTimestamp;
+    let stateUpdated = false;
+    let telemetryUpdated = false;
+    let commit = null;
+    let validation = 'skipped';
+    let cognitionDelta = null;
+    let summaryDelta = null;
+    // Create a new packet with absolute paths for child execution
+    const newPacket = {
+        ...packet,
+        state_file: stateFile,
+        telemetry_file: telemetryFile,
+    };
+    // ── Step 03b: Emit worker-acknowledged event ────────────────────────────
+    // Must be emitted after packet read and SHA computation, before any work
+    // output (telemetry spec §5.1). Acknowledges receipt of the dispatch packet.
+    {
+        let packetSha = "";
+        if (options.packetPath) {
+            try {
+                const raw = (0, node_fs_1.readFileSync)(options.packetPath, "utf-8");
+                packetSha = (0, node_crypto_1.createHash)("sha256").update(raw, "utf-8").digest("hex");
+            }
+            catch {
+                // SHA computation failure is non-fatal; emit empty string
+            }
+        }
+        else if (options.packetRawJson) {
+            packetSha = (0, node_crypto_1.createHash)("sha256").update(options.packetRawJson, "utf-8").digest("hex");
+        }
+        appendTelemetry(telemetryFile, {
+            event: "worker-acknowledged",
+            event_id: (0, node_crypto_1.randomUUID)(),
+            run_id: packet.run_id,
+            child_id: childId,
+            dispatch_id: packet.dispatch_id ?? "",
+            worker_id: packet.worker_id ?? "",
+            packet_sha: packetSha,
+            timestamp: now(),
+        });
+        telemetryUpdated = true;
+    }
+    // ── Step 04: Execute child ──────────────────────────────────────────────
+    try {
+        if (options.executeChild) {
+            options.executeChild(childId, newPacket);
+        }
+        // If no executeChild hook is provided, the worker is acting as a thin
+        // wrapper — real child work was done in the agent session itself before
+        // calling runWorker(). This is the standard usage pattern.
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        appendTelemetry(telemetryFile, {
+            event: "child-execution-error",
+            run_id: packet.run_id,
+            child_id: childId,
+            error: msg,
+            timestamp: now(),
+        });
+        return {
+            child_id: childId,
+            status: 'failed',
+            commit: null,
+            validation: 'failed',
+            tracker_updated: false,
+            state_updated: false,
+            telemetry_updated: true,
+            next_recommended_action: 'investigate',
+            result_data: {},
+        };
+    }
+    // ── Step 05: Validate child ─────────────────────────────────────────────
+    // Validation is treated as passed when child execution succeeds.
+    // A real implementation would run `npm run build && npm test` here.
+    validation = 'passed';
+    // ── Step 05b: Route cognition delta ─────────────────────────────────────
+    // Inspect touched files and determine whether route-local POLARIS.md /
+    // SUMMARY.md surfaces need updating. Bounded by locality — no repo-wide
+    // regeneration. Parent runtime is never involved in cognition reconciliation.
+    const touchedFiles = options.touchedFiles ?? [];
+    if (touchedFiles.length > 0) {
+        try {
+            cognitionDelta = (0, index_js_1.applyRouteCognitionDelta)({
+                repoRoot,
+                touchedFiles,
+                skipRoot: true,
+            });
+            summaryDelta = (0, index_js_1.applySummaryDelta)({
+                repoRoot,
+                touchedFiles,
+                skipRoot: true,
+            });
+            appendTelemetry(telemetryFile, {
+                event: "cognition-delta",
+                run_id: packet.run_id,
+                child_id: childId,
+                polaris_update_warranted: cognitionDelta.updateWarranted,
+                polaris_reasons: cognitionDelta.reasons,
+                polaris_targets: cognitionDelta.routeLocalTargets,
+                polaris_missing: cognitionDelta.missingCognitionSurfaces,
+                summary_update_warranted: summaryDelta.updateWarranted,
+                summary_reasons: summaryDelta.reasons,
+                summary_targets: summaryDelta.summaryTargets,
+                summary_missing: summaryDelta.missingSummaries,
+                timestamp: now(),
+            });
+            telemetryUpdated = true;
+        }
+        catch {
+            // Cognition delta failure is non-fatal — implementation already done
+        }
+    }
+    // ── Step 06: Commit ─────────────────────────────────────────────────────
+    commit = getHeadShort(repoRoot);
+    // ── Update current-state.json ───────────────────────────────────────────
+    try {
+        const state = (0, checkpoint_js_1.readState)(stateFile);
+        const remaining = state.open_children.filter((c) => c !== childId);
+        const completed = [...state.completed_children, childId];
+        const updatedState = {
+            ...state,
+            active_child: "",
+            open_children: remaining,
+            completed_children: completed,
+            next_open_child: remaining[0] ?? null,
+            step_cursor: "checkpoint",
+            status: remaining.length > 0 ? "running" : "cluster-complete",
+            last_commit: commit ?? state.last_commit,
+            context_budget: {
+                ...state.context_budget,
+                children_completed: completed.length,
+            },
+            updated_at: now(),
+        };
+        (0, checkpoint_js_1.writeStateAtomic)(stateFile, updatedState);
+        stateUpdated = true;
+    }
+    catch (err) {
+        // State persistence failure is critical — return error status
+        const msg = err instanceof Error ? err.message : String(err);
+        appendTelemetry(telemetryFile, {
+            event: "state-update-error",
+            run_id: packet.run_id,
+            child_id: childId,
+            error: msg,
+            timestamp: now(),
+        });
+        return {
+            child_id: childId,
+            status: 'failed',
+            commit,
+            validation,
+            tracker_updated: false,
+            state_updated: false,
+            telemetry_updated: telemetryUpdated,
+            next_recommended_action: 'investigate',
+            result_data: {},
+        };
+    }
+    // Linear tracker update is intentionally skipped by the worker:
+    // the spec says "Do NOT mark POL-69 as Done in Linear (parent handles Linear updates)".
+    // tracker_updated is therefore always false from the worker's perspective.
+    const trackerUpdated = false;
+    // ── Step 07: Write work note ────────────────────────────────────────────
+    let workNotePaths = [];
+    try {
+        const folderSlug = determineFolderSlug(touchedFiles);
+        const docsImpact = determineDocsImpact(cognitionDelta, summaryDelta);
+        const validationPerformed = "child execution and validation completed";
+        const notePath = writeWorkNote(repoRoot, packet.run_id, childId, childId, folderSlug, touchedFiles, docsImpact, commit, validationPerformed);
+        workNotePaths = [notePath];
+        appendTelemetry(telemetryFile, {
+            event: "work-note-written",
+            run_id: packet.run_id,
+            child_id: childId,
+            note_path: notePath,
+            folder_slug: folderSlug,
+            docs_impact: docsImpact,
+            timestamp: now(),
+        });
+        telemetryUpdated = true;
+    }
+    catch (err) {
+        // Work note failure is non-fatal — implementation already done
+        // Log but don't block CompactReturn
+        const msg = err instanceof Error ? err.message : String(err);
+        appendTelemetry(telemetryFile, {
+            event: "work-note-error",
+            run_id: packet.run_id,
+            child_id: childId,
+            error: msg,
+            timestamp: now(),
+        });
+        telemetryUpdated = true;
+    }
+    return {
+        child_id: childId,
+        status: 'done',
+        commit,
+        validation,
+        tracker_updated: trackerUpdated,
+        state_updated: stateUpdated,
+        telemetry_updated: telemetryUpdated,
+        next_recommended_action: 'continue',
+        result_data: {},
+        work_note_paths: workNotePaths.length > 0 ? workNotePaths : undefined,
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// CLI entry point
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Main worker entry point. Reads the bootstrap packet, executes one child,
+ * writes a CompactReturn JSON line to stdout, and calls process.exit(0).
+ *
+ * MUST NOT continue to the next child.
+ */
+async function runWorker(options = {}) {
+    let packet;
+    let resolvedPacketPath = options.packetPath;
+    let resolvedPacketRawJson = options.packetRawJson;
+    try {
+        if (options.packetPath) {
+            packet = JSON.parse((0, node_fs_1.readFileSync)(options.packetPath, "utf-8"));
+        }
+        else {
+            // Capture raw JSON from env var sources for SHA computation
+            const cliPath = (() => {
+                const idx = process.argv.indexOf("--bootstrap");
+                return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : null;
+            })();
+            if (cliPath) {
+                resolvedPacketPath = cliPath;
+            }
+            else {
+                const envPath = process.env["POLARIS_BOOTSTRAP_PACKET"] ?? process.env["POLARIS_PACKET_FILE"];
+                if (envPath) {
+                    resolvedPacketPath = envPath;
+                }
+                else {
+                    const packetJson = process.env["POLARIS_PACKET_JSON"];
+                    if (packetJson) {
+                        resolvedPacketRawJson = packetJson;
+                    }
+                }
+            }
+            packet = readBootstrapPacket(process.argv);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const ret = {
+            child_id: "",
+            status: 'failed',
+            commit: null,
+            validation: 'skipped',
+            tracker_updated: false,
+            state_updated: false,
+            telemetry_updated: false,
+            next_recommended_action: 'investigate',
+            result_data: {},
+        };
+        process.stdout.write(JSON.stringify(ret) + "\n");
+        process.stderr.write(`[polaris-worker] Failed to read bootstrap packet: ${msg}\n`);
+        process.exit(1);
+        return;
+    }
+    let result;
+    try {
+        result = await executeOneChild(packet, {
+            ...options,
+            packetPath: resolvedPacketPath,
+            packetRawJson: resolvedPacketRawJson,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result = blockedReturn(packet.active_child, msg);
+        process.stderr.write(`[polaris-worker] Unexpected error: ${msg}\n`);
+    }
+    // Write compact return as the last (and only) JSON line to stdout, then exit.
+    // No continuation to the next child — process.exit() ensures this.
+    process.stdout.write(JSON.stringify(result) + "\n");
+    process.exit(result.status === 'done' ? 0 : 1);
+}