@lsctech/polaris 0.1.0

package/dist/loop/adapters/terminal-cli.js

@@ -0,0 +1,403 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerminalCliAdapter = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const worker_instructions_js_1 = require("./worker-instructions.js");
+const worker_packet_js_1 = require("../worker-packet.js");
+const compact_return_js_1 = require("../compact-return.js");
+/** Expand $VAR and ${VAR} references from process.env. */
+function expandEnvVars(str) {
+    return str
+        .replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_, name) => process.env[name] ?? '')
+        .replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, name) => process.env[name] ?? '');
+}
+/** Substitute {{key}} template variables. Unknown keys are left as-is. */
+function substituteTemplates(str, vars) {
+    return str.replace(/\{\{([^}]+)\}\}/g, (original, key) => vars[key.trim()] ?? original);
+}
+/**
+ * Shell-quote a single argument for display purposes only.
+ * Not used for actual process spawning (which uses the args array directly).
+ */
+function shellQuote(arg) {
+    if (/^[a-zA-Z0-9@%+=:,./-]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+function formatCommandLine(command, args) {
+    return [command, ...args].map(shellQuote).join(' ');
+}
+/** Check whether a command is available on PATH or is an accessible file. */
+function resolveCommand(cmd) {
+    if (node_path_1.default.isAbsolute(cmd)) {
+        return node_fs_1.default.existsSync(cmd);
+    }
+    try {
+        (0, node_child_process_1.execFileSync)('which', [cmd], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+class TerminalCliAdapter {
+    config;
+    name = 'terminal-cli';
+    constructor(config) {
+        this.config = config;
+    }
+    getProvider(providerName) {
+        const providers = this.config.providers ?? {};
+        const cfg = providers[providerName];
+        if (!cfg) {
+            const available = Object.keys(providers);
+            const hint = available.length > 0
+                ? `Available providers: ${available.join(', ')}`
+                : 'No providers configured in polaris.config.json execution.providers';
+            throw new Error(`Unknown provider "${providerName}". ${hint}`);
+        }
+        return cfg;
+    }
+    buildCommand(providerCfg, packet, workerPrompt, packetFile) {
+        const templateVars = {
+            active_child: packet.active_child,
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            state_file: packet.state_file,
+            telemetry_file: packet.telemetry_file,
+            model: String(packet.context?.["model"] ?? ""),
+            packet_json: JSON.stringify(packet),
+            packet_file: packetFile,
+            worker_prompt: workerPrompt,
+        };
+        const rawCommand = providerCfg.command;
+        const command = expandEnvVars(substituteTemplates(rawCommand, templateVars));
+        // expandEnvVars resolves unset $VAR to '' — detect that case
+        if (!command.trim()) {
+            throw new Error(`Provider command "${rawCommand}" expanded to an empty string — ` +
+                `likely an unset environment variable. ` +
+                `Set the environment variable or use a literal command name.`);
+        }
+        const args = (providerCfg.args ?? []).map((arg) => expandEnvVars(substituteTemplates(arg, templateVars)));
+        return { command, args };
+    }
+    async probe(providerName) {
+        try {
+            const providerCfg = this.getProvider(providerName);
+            const expandedCommand = expandEnvVars(providerCfg.command);
+            if (!resolveCommand(expandedCommand.split(' ')[0] ?? expandedCommand)) {
+                return { ok: false, error: `Provider command "${providerCfg.command}" not found on PATH` };
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    async dispatch(packet, options) {
+        const primaryProvider = options.provider || "terminal-cli";
+        if ((0, worker_packet_js_1.isWorkerPacket)(packet) && packet.worker_role === "impl") {
+            const allowed = Array.isArray(packet.instructions?.allowed_scope) ? packet.instructions.allowed_scope : [];
+            if (allowed.length === 0) {
+                const blockedMsg = `Worker blocked: impl packet for ${packet.active_child} has empty allowed_scope. Foreman must provide scope or approve override.`;
+                return {
+                    exit_code: 1,
+                    provider_used: primaryProvider,
+                    command_run: `terminal-cli:${packet.active_child || "worker"}`,
+                    summary: JSON.stringify({
+                        child_id: packet.active_child,
+                        status: "blocked",
+                        validation_summary: blockedMsg,
+                        next_action: "escalate",
+                        warnings: ["empty-allowed-scope"],
+                    }),
+                    stderr: blockedMsg,
+                    pre_dispatch_failure: true,
+                };
+            }
+        }
+        // Validate primary provider eagerly — throws for unknown/misconfigured primary,
+        // preserving the pre-refactor contract for callers specifying invalid providers.
+        const primaryCfg = this.getProvider(primaryProvider);
+        // Build fallback chain from policy. Only append providers that are configured.
+        // Fallback is suppressed when providerPolicy.worker.noFallback is true.
+        const workerPolicy = this.config.providerPolicy?.['worker'];
+        const canFallback = !(workerPolicy?.noFallback === true);
+        const policyProviders = (canFallback && Array.isArray(workerPolicy?.providers))
+            ? workerPolicy.providers
+            : [];
+        const providersToTry = [
+            { name: primaryProvider, cfg: primaryCfg, isPrimary: true },
+        ];
+        if (canFallback) {
+            for (const p of policyProviders) {
+                if (p !== primaryProvider && p in (this.config.providers ?? {})) {
+                    try {
+                        providersToTry.push({ name: p, cfg: this.getProvider(p), isPrimary: false });
+                    }
+                    catch {
+                        // fallback provider not found — skip silently
+                    }
+                }
+            }
+        }
+        const workerPrompt = (0, worker_instructions_js_1.buildWorkerInstructions)(packet);
+        // Write packet to a named temp file so args can reference it via {{packet_file}}
+        const packetFile = node_path_1.default.join(node_os_1.default.tmpdir(), `polaris-packet-${packet.run_id}.json`);
+        node_fs_1.default.writeFileSync(packetFile, JSON.stringify(packet, null, 2), 'utf-8');
+        let lastResult;
+        try {
+            for (const { name: provider, cfg: providerCfg, isPrimary } of providersToTry) {
+                let command;
+                let args;
+                try {
+                    ({ command, args } = this.buildCommand(providerCfg, packet, workerPrompt, packetFile));
+                }
+                catch (err) {
+                    if (isPrimary)
+                        throw err; // primary build failures must propagate
+                    lastResult = {
+                        exit_code: 1,
+                        provider_used: provider,
+                        command_run: provider,
+                        stderr: err instanceof Error ? err.message : String(err),
+                    };
+                    continue;
+                }
+                const commandLine = formatCommandLine(command, args);
+                if (options.dryRun) {
+                    return this.dryRun(provider, command, args, commandLine, packet, packetFile, workerPrompt);
+                }
+                if (!resolveCommand(command)) {
+                    lastResult = {
+                        exit_code: 1,
+                        provider_used: provider,
+                        command_run: commandLine,
+                        stderr: `Provider command "${command}" not found on PATH. ` +
+                            `Install it or update the "command" field for provider "${provider}" in polaris.config.json.`,
+                    };
+                    continue;
+                }
+                const result = await this.runProcess(command, args, commandLine, packet, packetFile, provider, workerPrompt);
+                // Worker succeeded — return immediately.
+                if (result.exit_code === 0) {
+                    return result;
+                }
+                // If the worker wrote a result file it actually ran (and failed) — don't
+                // retry with another provider; that would double-dispatch the same child.
+                const resultFilePath = (0, worker_packet_js_1.isWorkerPacket)(packet) ? packet.result_file_contract?.result_file : undefined;
+                if (resultFilePath && node_fs_1.default.existsSync(resultFilePath)) {
+                    return result;
+                }
+                // Worker did not start (wrong args, command not found, etc.) — try next.
+                lastResult = result;
+            }
+            return lastResult ?? {
+                exit_code: 1,
+                provider_used: primaryProvider,
+                command_run: '',
+                stderr: 'All configured providers exhausted without starting a worker',
+            };
+        }
+        finally {
+            try {
+                node_fs_1.default.unlinkSync(packetFile);
+            }
+            catch {
+                // ignore cleanup errors
+            }
+        }
+    }
+    dryRun(provider, command, args, commandLine, packet, packetFile, workerPrompt) {
+        const lines = [
+            `[dry-run] Provider: ${provider}`,
+            `[dry-run] Command:  ${commandLine}`,
+            `[dry-run] Stdin:    <bootstrap packet JSON>`,
+            `[dry-run] Env vars set:`,
+            `            POLARIS_ACTIVE_CHILD=${packet.active_child}`,
+            `            POLARIS_RUN_ID=${packet.run_id}`,
+            `            POLARIS_CLUSTER_ID=${packet.cluster_id}`,
+            `            POLARIS_STATE_FILE=${packet.state_file}`,
+            `            POLARIS_TELEMETRY_FILE=${packet.telemetry_file}`,
+            `            POLARIS_PACKET_FILE=${packetFile}`,
+            `            POLARIS_PACKET_JSON=<json>`,
+            `            POLARIS_WORKER_PROMPT=<prompt>`,
+            `[dry-run] Worker prompt:`,
+            workerPrompt
+                .split('\n')
+                .map((l) => `            ${l}`)
+                .join('\n'),
+            `[dry-run] Bootstrap packet:`,
+            JSON.stringify(packet, null, 2)
+                .split('\n')
+                .map((l) => `            ${l}`)
+                .join('\n'),
+        ];
+        console.log(lines.join('\n'));
+        return {
+            exit_code: 0,
+            provider_used: provider,
+            command_run: commandLine,
+            summary: '[dry-run]',
+        };
+    }
+    runProcess(command, args, commandLine, packet, packetFile, provider, workerPrompt) {
+        return new Promise((resolve, reject) => {
+            const env = {
+                ...process.env,
+                POLARIS_ACTIVE_CHILD: packet.active_child,
+                POLARIS_RUN_ID: packet.run_id,
+                POLARIS_CLUSTER_ID: packet.cluster_id,
+                POLARIS_STATE_FILE: packet.state_file,
+                POLARIS_TELEMETRY_FILE: packet.telemetry_file,
+                POLARIS_PACKET_FILE: packetFile,
+                POLARIS_PACKET_JSON: JSON.stringify(packet),
+                POLARIS_WORKER_PROMPT: workerPrompt,
+            };
+            const child = (0, node_child_process_1.spawn)(command, args, {
+                env,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            // Deliver bootstrap packet to worker via stdin
+            child.stdin.write(JSON.stringify(packet), 'utf-8');
+            child.stdin.end();
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            child.stdout.on('data', (chunk) => {
+                stdoutChunks.push(chunk);
+            });
+            child.stderr.on('data', (chunk) => {
+                stderrChunks.push(chunk);
+            });
+            child.on('error', (err) => {
+                if (err.code === 'ENOENT') {
+                    reject(new Error(`Provider command "${command}" not found. ` +
+                        `Ensure it is installed and on PATH.`));
+                }
+                else {
+                    reject(err);
+                }
+            });
+            child.on('close', (exitCode) => {
+                const stdout = Buffer.concat(stdoutChunks).toString('utf-8').trim();
+                const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
+                const summary = extractSummary(stdout);
+                this.writeSealedResultIfNeeded(packet, summary, stdout, exitCode ?? 1);
+                resolve({
+                    exit_code: exitCode ?? 1,
+                    provider_used: provider,
+                    command_run: commandLine,
+                    stdout,
+                    summary,
+                    stderr: stderr || undefined,
+                });
+            });
+        });
+    }
+    writeSealedResultIfNeeded(packet, summary, stdout, exitCode) {
+        const resultFile = (0, worker_packet_js_1.isWorkerPacket)(packet) ? packet.result_file_contract?.result_file : undefined;
+        if (!resultFile || !summary) {
+            return;
+        }
+        try {
+            const parsed = JSON.parse(summary);
+            // Normalize legacy CompactReturn shapes before validation so that
+            // workers using pre-spec formats (status:"success", validation:{passed:[...]})
+            // are accepted rather than silently marked as failures.
+            const normalized = normalizeLegacyCompactReturn(parsed);
+            const compactReturnErrors = (0, compact_return_js_1.validateCompactReturn)(normalized);
+            const isValidCompactReturn = compactReturnErrors.length === 0;
+            // If the parsed result isn't a valid CompactReturn, treat it as a failure
+            // regardless of exit code — this prevents phantom successes from workers
+            // that return minimal status objects instead of proper CompactReturn structs.
+            const effectiveStatus = (exitCode === 0 && isValidCompactReturn) ? "success" : "failure";
+            const sealedResult = {
+                ...normalized,
+                run_id: packet.run_id,
+                child_id: String(normalized["child_id"] ?? packet.active_child),
+                status: effectiveStatus,
+                commit: typeof normalized["commit"] === "string"
+                    ? normalized["commit"]
+                    : typeof normalized["commit_hash"] === "string"
+                        ? normalized["commit_hash"]
+                        : undefined,
+                validation: normalized["validation"] ?? normalized["validation_summary"],
+                error_message: effectiveStatus === "failure"
+                    ? (!isValidCompactReturn
+                        ? `CompactReturn validation failed: ${compactReturnErrors.join("; ")}`
+                        : typeof normalized["error_message"] === "string"
+                            ? normalized["error_message"]
+                            : stdout || summary)
+                    : undefined,
+                ...(compactReturnErrors.length > 0 ? { compact_return_errors: compactReturnErrors } : {}),
+            };
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(resultFile), { recursive: true });
+            node_fs_1.default.writeFileSync(resultFile, JSON.stringify(sealedResult, null, 2), "utf-8");
+        }
+        catch {
+            // If the provider did not emit parseable compact JSON, leave the result
+            // file absent so the parent can surface the sealed-result read failure.
+        }
+    }
+}
+exports.TerminalCliAdapter = TerminalCliAdapter;
+/**
+ * Normalize a legacy CompactReturn shape to the current spec before validation.
+ * Handles pre-spec formats produced by older workers:
+ *   - status:"success"|"completed" → status:"done"
+ *   - validation:{passed:[...],failed:[...]} → validation:"passed"|"failed"|"skipped"
+ *   - missing boolean flags → false
+ */
+function normalizeLegacyCompactReturn(raw) {
+    const result = { ...raw };
+    if (result['status'] === 'success' || result['status'] === 'completed') {
+        result['status'] = 'done';
+    }
+    if (typeof result['validation'] === 'object' && result['validation'] !== null) {
+        const v = result['validation'];
+        if (Array.isArray(v['failed']) && v['failed'].length > 0) {
+            result['validation'] = 'failed';
+        }
+        else if (Array.isArray(v['passed']) && v['passed'].length > 0) {
+            result['validation'] = 'passed';
+        }
+        else {
+            result['validation'] = 'skipped';
+        }
+    }
+    for (const flag of ['tracker_updated', 'state_updated', 'telemetry_updated']) {
+        if (typeof result[flag] !== 'boolean') {
+            result[flag] = false;
+        }
+    }
+    return result;
+}
+/**
+ * Extract a worker summary from stdout.
+ * Looks for the last line that is valid JSON; falls back to the last 500 chars.
+ */
+function extractSummary(stdout) {
+    if (!stdout)
+        return undefined;
+    const lines = stdout.split('\n').reverse();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            JSON.parse(trimmed);
+            return trimmed;
+        }
+        catch {
+            // not JSON, keep looking
+        }
+    }
+    // fallback: last 500 characters
+    return stdout.length > 500 ? stdout.slice(-500) : stdout;
+}

package/dist/loop/adapters/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/loop/adapters/worker-instructions.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorkerInstructions = buildWorkerInstructions;
+exports.returnContractFor = returnContractFor;
+const worker_packet_js_1 = require("../worker-packet.js");
+/** Fallback return contract for legacy v1 BootstrapPackets. */
+const LEGACY_RETURN_CONTRACT = [
+    "child_id",
+    "status",
+    "commit_hash",
+    "validation_summary",
+    "next_action",
+    "warnings",
+];
+/** Lifecycle teardown preamble appended to every worker prompt. */
+const LIFECYCLE_TEARDOWN_NOTICE = [
+    `LIFECYCLE CONTRACT (mandatory):`,
+    `  - Execute ONLY the single child or task named in this packet.`,
+    `  - Your FINAL RESPONSE must be EXCLUSIVELY the compact return JSON object — a single JSON object on one line, nothing else.`,
+    `  - Do NOT include any preamble, explanation, narration, or text before or after the JSON in your final response.`,
+    `  - Do NOT summarize what you did. Do NOT say "Here is the compact return:". Output only the raw JSON.`,
+    `  - The foreman session receives only your final response. Keep it to the JSON alone so it cannot observe your work.`,
+    `  - Do NOT select, claim, or execute any other child.`,
+    `  - Do NOT continue looping after one child completes.`,
+    `  - One worker. One child. One commit. Then exit.`,
+].join("\n");
+/**
+ * Build instructions for a compiled WorkerPacket.
+ * Uses pre-baked steps from packet.instructions — no skill ingestion.
+ */
+function buildCompiledInstructions(packet) {
+    if (!(0, worker_packet_js_1.isWorkerPacket)(packet)) {
+        return buildLegacyInstructions(packet);
+    }
+    const { instructions, lifecycle, return_contract, worker_role, run_id, cluster_id } = packet;
+    const lines = [
+        `POLARIS WORKER — role: ${worker_role}`,
+        `Run: ${run_id} | Cluster: ${cluster_id}`,
+        ``,
+        `OBJECTIVE:`,
+        instructions.primary_goal,
+        ``,
+        `EXECUTION STEPS (pre-compiled — do not re-read skill files):`,
+        ...instructions.steps.map((s, i) => `  ${i + 1}. ${s}`),
+    ];
+    if (instructions.allowed_scope.length > 0) {
+        lines.push(``, `ALLOWED SCOPE:`, ...instructions.allowed_scope.map((s) => `  ${s}`));
+    }
+    if (instructions.validation_commands.length > 0) {
+        lines.push(``, `VALIDATION COMMANDS (run before returning):`, ...instructions.validation_commands.map((c) => `  ${c}`));
+    }
+    lines.push(``, `REQUIRED RETURN FIELDS: ${return_contract.join(", ")}`, `STATE FILE: ${packet.state_file}`, `TELEMETRY FILE: ${packet.telemetry_file}`, `SEALED RESULT FILE: ${packet.result_file_contract.result_file}`, `Write the sealed result file as a JSON object with EXACTLY this shape:`, `  { "run_id": "<run_id>", "child_id": "<child_id>", "status": "success" | "failure",`, `    "commit": "<full 40-char SHA>", "validation": { "passed": ["<cmd>", ...] },`, `    "error_message": "<string or omit if success>" }`, `commit MUST be the full 40-character git SHA (git rev-parse HEAD). Do NOT use a short hash.`, `Your final response MUST be ONLY the compact return JSON — a single JSON object, no other text.`, ``, LIFECYCLE_TEARDOWN_NOTICE, ``, `Session must terminate after max_concurrent=${lifecycle.max_concurrent} active workers.`, `cleanup_on_exit: ${lifecycle.cleanup_on_exit}`);
+    return lines.join("\n");
+}
+/**
+ * Build instructions for a legacy v1 BootstrapPacket.
+ * Kept for backward compat; generates generic instructions from packet metadata.
+ */
+function buildLegacyInstructions(packet) {
+    return [
+        `You are the dedicated Polaris worker subagent for exactly one child issue: ${packet.active_child}.`,
+        `Run id: ${packet.run_id}`,
+        `Parent cluster: ${packet.cluster_id}`,
+        `Execution mode: ephemeral agent subtask.`,
+        ``,
+        `Use the bootstrap packet below as the durable continuation boundary.`,
+        `Execute only ${packet.active_child}, update the state and telemetry files named in the packet, and return ONLY the compact JSON as your final response — no preamble, no narration, no other text.`,
+        `Do not include a transcript or continue to another child.`,
+        ``,
+        `Required return fields: ${LEGACY_RETURN_CONTRACT.join(", ")}`,
+        ``,
+        LIFECYCLE_TEARDOWN_NOTICE,
+        ``,
+        `Bootstrap packet:`,
+        JSON.stringify(packet, null, 2),
+    ].join("\n");
+}
+/** Build terminal/agent worker instructions for this packet. */
+function buildWorkerInstructions(packet) {
+    return buildCompiledInstructions(packet);
+}
+/** Returns the return contract for this packet (compiled or legacy). */
+function returnContractFor(packet) {
+    return (0, worker_packet_js_1.isWorkerPacket)(packet) ? packet.return_contract : LEGACY_RETURN_CONTRACT;
+}