@workermill/agent 0.1.0

package/dist/planner.js

@@ -0,0 +1,268 @@
+/**
+ * Remote Agent Planner
+ *
+ * Fetches the planning prompt from the cloud API, runs it through
+ * Claude CLI locally (using the customer's Claude Max subscription),
+ * and posts the raw output back for server-side validation.
+ *
+ * Logs are streamed to the cloud dashboard in real-time so the user
+ * sees the same planning progress as cloud mode.
+ */
+import chalk from "chalk";
+import { spawn } from "child_process";
+import { findClaudePath } from "./config.js";
+import { api } from "./api.js";
+/** Timestamp prefix */
+function ts() {
+    return chalk.dim(new Date().toLocaleTimeString());
+}
+/**
+ * Post a log message to the cloud dashboard for real-time visibility.
+ */
+async function postLog(taskId, message, type = "system", severity = "info") {
+    try {
+        await api.post("/api/control-center/logs", {
+            taskId,
+            type,
+            message,
+            severity,
+        });
+    }
+    catch {
+        // Fire and forget — don't block planning on log failures
+    }
+}
+/**
+ * Post planning progress to the cloud API for SSE relay to the dashboard.
+ * This drives the animated progress bar (PlanningTerminalBar) in the frontend.
+ */
+async function postProgress(taskId, phase, elapsedSeconds, detail, charsGenerated, toolCallCount) {
+    try {
+        await api.post("/api/agent/planning-progress", {
+            taskId,
+            phase,
+            elapsedSeconds,
+            detail,
+            charsGenerated,
+            toolCallCount,
+        });
+    }
+    catch {
+        // Fire and forget
+    }
+}
+function phaseLabel(phase, elapsed) {
+    switch (phase) {
+        case "initializing": return "Starting planning agent...";
+        case "reading_repo": return "Reading repository structure...";
+        case "analyzing": return "Analyzing requirements...";
+        case "generating_plan": return `Generating execution plan... (${elapsed}s)`;
+        case "validating": return "Validating plan...";
+        case "complete": return "Planning complete";
+    }
+}
+/**
+ * Run Claude CLI with stream-json output, posting real-time phase milestones
+ * to the cloud dashboard — identical terminal experience to cloud planning.
+ */
+function runClaudeCli(claudePath, model, prompt, env, taskId, startTime) {
+    const taskLabel = chalk.cyan(taskId.slice(0, 8));
+    return new Promise((resolve, reject) => {
+        const proc = spawn(claudePath, [
+            "--print",
+            "--verbose",
+            "--output-format", "stream-json",
+            "--model", model,
+            "--permission-mode", "bypassPermissions",
+        ], {
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        proc.stdin.write(prompt);
+        proc.stdin.end();
+        let fullText = "";
+        let resultText = "";
+        let stderrOutput = "";
+        let charsReceived = 0;
+        let toolCallCount = 0;
+        // Phase detection state
+        let currentPhase = "initializing";
+        let firstTextSeen = false;
+        const milestoneSent = { started: true, reading: false, analyzing: false, generating: false };
+        // Post milestone when phase transitions (to dashboard terminal)
+        function transitionPhase(newPhase) {
+            if (newPhase === currentPhase)
+                return;
+            currentPhase = newPhase;
+            const elapsed = Math.round((Date.now() - startTime) / 1000);
+            const msg = phaseLabel(newPhase, elapsed);
+            postLog(taskId, msg);
+            console.log(`${ts()} ${taskLabel} ${chalk.dim(msg)}`);
+        }
+        // SSE progress updates every 2s — drives PlanningTerminalBar in dashboard
+        // (same cadence as local dev's progressInterval in planning-agent-local.ts)
+        const sseProgressInterval = setInterval(() => {
+            const elapsed = Math.round((Date.now() - startTime) / 1000);
+            postProgress(taskId, currentPhase, elapsed, phaseLabel(currentPhase, elapsed), charsReceived, toolCallCount);
+        }, 2_000);
+        // Phase transition logs + periodic DB logs (every 30s during generation)
+        let lastProgressLogAt = 0;
+        const progressInterval = setInterval(() => {
+            const elapsed = Math.round((Date.now() - startTime) / 1000);
+            // Time-based phase fallback (in case stream events are sparse)
+            if (currentPhase === "initializing" && elapsed >= 5) {
+                transitionPhase("reading_repo");
+            }
+            else if (currentPhase === "reading_repo" && elapsed >= 15 && !firstTextSeen) {
+                transitionPhase("analyzing");
+            }
+            // Periodic progress during generation
+            if (currentPhase === "generating_plan" && elapsed - lastProgressLogAt >= 30) {
+                lastProgressLogAt = elapsed;
+                const msg = `Generating execution plan... (${elapsed}s, ${charsReceived} chars, ${toolCallCount} tool calls)`;
+                postLog(taskId, msg);
+                console.log(`${ts()} ${taskLabel} ${chalk.dim(msg)}`);
+            }
+        }, 5_000);
+        // Parse streaming JSON lines from Claude CLI
+        let lineBuffer = "";
+        proc.stdout.on("data", (data) => {
+            lineBuffer += data.toString();
+            const lines = lineBuffer.split("\n");
+            lineBuffer = lines.pop() || "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const event = JSON.parse(trimmed);
+                    if (event.type === "content_block_delta" && event.delta?.text) {
+                        fullText += event.delta.text;
+                        charsReceived += event.delta.text.length;
+                        // Phase: first text after tool calls → analyzing
+                        if (!firstTextSeen) {
+                            firstTextSeen = true;
+                            if (toolCallCount > 0 && !milestoneSent.analyzing) {
+                                transitionPhase("analyzing");
+                                milestoneSent.analyzing = true;
+                            }
+                        }
+                        // Phase: substantial text → generating_plan
+                        if (charsReceived > 500 && !milestoneSent.generating) {
+                            transitionPhase("generating_plan");
+                            milestoneSent.generating = true;
+                            lastProgressLogAt = Math.round((Date.now() - startTime) / 1000);
+                        }
+                    }
+                    else if (event.type === "content_block_start" && event.content_block?.type === "tool_use") {
+                        toolCallCount++;
+                        if (!milestoneSent.reading) {
+                            transitionPhase("reading_repo");
+                            milestoneSent.reading = true;
+                        }
+                    }
+                    else if (event.type === "assistant" && event.message?.content) {
+                        const text = typeof event.message.content === "string" ? event.message.content : "";
+                        if (text) {
+                            fullText += text;
+                            charsReceived += text.length;
+                        }
+                    }
+                    else if (event.type === "result" && event.result) {
+                        resultText = typeof event.result === "string" ? event.result : "";
+                    }
+                }
+                catch {
+                    // Not valid JSON — raw text, accumulate
+                    fullText += trimmed + "\n";
+                    charsReceived += trimmed.length;
+                }
+            }
+        });
+        proc.stderr.on("data", (chunk) => {
+            stderrOutput += chunk.toString();
+        });
+        const timeout = setTimeout(() => {
+            clearInterval(progressInterval);
+            clearInterval(sseProgressInterval);
+            proc.kill("SIGTERM");
+            reject(new Error("Claude CLI timed out after 10 minutes"));
+        }, 600_000);
+        proc.on("exit", (code) => {
+            clearTimeout(timeout);
+            clearInterval(progressInterval);
+            clearInterval(sseProgressInterval);
+            // Emit final "validating" phase to dashboard
+            const elapsedAtClose = Math.round((Date.now() - startTime) / 1000);
+            postProgress(taskId, "validating", elapsedAtClose, "Validating plan...", charsReceived, toolCallCount);
+            if (code !== 0) {
+                reject(new Error(`Claude CLI failed (exit ${code}): ${stderrOutput.substring(0, 300)}`));
+            }
+            else {
+                // Prefer the result event's text (authoritative), fall back to accumulated deltas
+                resolve(resultText || fullText);
+            }
+        });
+        proc.on("error", (err) => {
+            clearTimeout(timeout);
+            clearInterval(progressInterval);
+            clearInterval(sseProgressInterval);
+            reject(err);
+        });
+    });
+}
+/**
+ * Run planning for a task: fetch prompt, execute Claude CLI, post result.
+ */
+export async function planTask(task, config) {
+    const taskLabel = chalk.cyan(task.id.slice(0, 8));
+    console.log(`${ts()} ${taskLabel} Fetching planning prompt...`);
+    await postLog(task.id, "Fetching planning prompt from cloud API...");
+    // 1. Fetch the assembled planning prompt from the cloud API
+    const promptResponse = await api.get("/api/agent/planning-prompt", {
+        params: { taskId: task.id },
+    });
+    const { prompt, model } = promptResponse.data;
+    const cliModel = model || "sonnet";
+    console.log(`${ts()} ${taskLabel} Running Claude CLI ${chalk.dim(`(model: ${chalk.yellow(cliModel)})`)}`);
+    await postLog(task.id, `Starting planning agent (model: ${cliModel})...`);
+    // 2. Run Claude CLI asynchronously with progress logging
+    const claudePath = process.env.CLAUDE_CLI_PATH || findClaudePath() || "claude";
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.CLAUDE_CODE_OAUTH_TOKEN;
+    const startTime = Date.now();
+    let rawOutput;
+    try {
+        rawOutput = await runClaudeCli(claudePath, cliModel, prompt, cleanEnv, task.id, startTime);
+    }
+    catch (error) {
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        const errMsg = error instanceof Error ? error.message : String(error);
+        console.error(`${ts()} ${taskLabel} ${chalk.red("✗")} Failed after ${elapsed}s: ${errMsg.substring(0, 100)}`);
+        await postLog(task.id, `Planning agent failed after ${elapsed}s: ${errMsg.substring(0, 200)}`, "error", "error");
+        return false;
+    }
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    console.log(`${ts()} ${taskLabel} ${chalk.green("✓")} Claude CLI done ${chalk.dim(`(${elapsed}s, ${rawOutput.length} chars)`)}`);
+    await postLog(task.id, `Planning complete (${elapsed}s, ${rawOutput.length} chars). Validating plan...`);
+    // 3. Post raw output back to cloud API for validation
+    try {
+        const result = await api.post("/api/agent/plan-result", {
+            taskId: task.id,
+            rawOutput,
+            agentId: config.agentId,
+        });
+        const storyCount = result.data.storyCount;
+        console.log(`${ts()} ${taskLabel} ${chalk.green("✓")} Plan validated: ${chalk.bold(storyCount)} stories → ${chalk.green("queued")}`);
+        await postLog(task.id, `Plan validated: ${storyCount} stories. Task queued for execution.`);
+        await postProgress(task.id, "complete", elapsed, "Planning complete", 0, 0);
+        return true;
+    }
+    catch (error) {
+        const err = error;
+        const detail = err.response?.data?.detail || String(error);
+        console.error(`${ts()} ${taskLabel} ${chalk.red("✗")} Validation failed: ${detail.substring(0, 100)}`);
+        await postLog(task.id, `Plan validation failed: ${detail.substring(0, 200)}`, "error", "error");
+        return false;
+    }
+}

package/dist/poller.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Remote Agent Poller
+ *
+ * Main poll loop: every N seconds, query the cloud API for tasks,
+ * dispatch to planner or spawner based on task status.
+ */
+import type { AgentConfig } from "./config.js";
+/**
+ * Start the poll loop.
+ */
+export declare function startPolling(config: AgentConfig): void;
+/**
+ * Start the heartbeat loop.
+ */
+export declare function startHeartbeat(config: AgentConfig): void;

package/dist/poller.js

@@ -0,0 +1,188 @@
+/**
+ * Remote Agent Poller
+ *
+ * Main poll loop: every N seconds, query the cloud API for tasks,
+ * dispatch to planner or spawner based on task status.
+ */
+import chalk from "chalk";
+import { api } from "./api.js";
+import { planTask } from "./planner.js";
+import { spawnWorker, getActiveCount, getActiveTaskIds, stopTask } from "./spawner.js";
+// Track tasks currently being planned (to avoid double-dispatching)
+const planningInProgress = new Set();
+// Cached org config
+let orgConfig = null;
+/** Timestamp prefix for log lines */
+function ts() {
+    return chalk.dim(new Date().toLocaleTimeString());
+}
+/**
+ * Fetch org config from the cloud API (cached).
+ */
+async function getOrgConfig() {
+    if (orgConfig)
+        return orgConfig;
+    try {
+        const response = await api.get("/api/agent/config");
+        orgConfig = response.data;
+        return orgConfig;
+    }
+    catch (error) {
+        console.error(`${ts()} ${chalk.red("✗")} Failed to fetch org config`);
+        return {};
+    }
+}
+/**
+ * Run a single poll iteration.
+ */
+async function pollOnce(config) {
+    try {
+        const response = await api.get("/api/agent/poll", {
+            params: { agentId: config.agentId },
+        });
+        const tasks = response.data.tasks;
+        if (tasks.length === 0)
+            return;
+        for (const task of tasks) {
+            if (task.status === "planning" && !planningInProgress.has(task.id)) {
+                // Claim and plan
+                await handlePlanningTask(task, config);
+            }
+            else if (task.status === "queued") {
+                // Claim and spawn
+                await handleQueuedTask(task, config);
+            }
+        }
+    }
+    catch (error) {
+        const err = error;
+        if (err.response?.status === 401) {
+            console.error(`${ts()} ${chalk.red("✗")} Authentication failed. Check your API key.`);
+        }
+        else {
+            console.error(`${ts()} ${chalk.red("✗")} Poll error: ${err.message || String(error)}`);
+        }
+    }
+}
+/**
+ * Handle a task in "planning" status.
+ */
+async function handlePlanningTask(task, config) {
+    // Claim the task
+    try {
+        const claimResponse = await api.post("/api/agent/claim", {
+            taskId: task.id,
+            agentId: config.agentId,
+        });
+        if (!claimResponse.data.claimed) {
+            return; // Another agent or cloud orchestrator claimed it
+        }
+    }
+    catch {
+        return;
+    }
+    const taskLabel = chalk.cyan(task.id.slice(0, 8));
+    console.log();
+    console.log(`${ts()} ${chalk.magenta("◆ PLANNING")} ${taskLabel} ${task.summary.substring(0, 60)}`);
+    planningInProgress.add(task.id);
+    // Run planning asynchronously (don't block the poll loop)
+    planTask(task, config)
+        .then((success) => {
+        if (success) {
+            console.log(`${ts()} ${chalk.green("✓")} Planning complete for ${taskLabel}`);
+        }
+        else {
+            console.log(`${ts()} ${chalk.red("✗")} Planning failed for ${taskLabel}`);
+        }
+    })
+        .catch((err) => console.error(`${ts()} ${chalk.red("✗")} Planning error for ${taskLabel}:`, err.message || err))
+        .finally(() => planningInProgress.delete(task.id));
+}
+/**
+ * Handle a task in "queued" status.
+ */
+async function handleQueuedTask(task, config) {
+    // Check concurrency limit
+    const activeCount = getActiveCount();
+    if (activeCount >= config.maxWorkers) {
+        return; // At capacity
+    }
+    // Claim the task
+    let claimData;
+    try {
+        const claimResponse = await api.post("/api/agent/claim", {
+            taskId: task.id,
+            agentId: config.agentId,
+        });
+        claimData = claimResponse.data;
+        if (!claimData.claimed) {
+            return;
+        }
+    }
+    catch {
+        return;
+    }
+    // Report started
+    try {
+        await api.post("/api/agent/started", {
+            taskId: task.id,
+            agentId: config.agentId,
+        });
+    }
+    catch (err) {
+        const taskLabel = chalk.cyan(task.id.slice(0, 8));
+        console.error(`${ts()} ${chalk.red("✗")} Failed to report started for ${taskLabel}`);
+    }
+    const taskLabel = chalk.cyan(task.id.slice(0, 8));
+    console.log();
+    console.log(`${ts()} ${chalk.blue("▶ EXECUTING")} ${taskLabel} ${task.summary.substring(0, 60)}`);
+    const oc = await getOrgConfig();
+    const spawnableTask = claimData.task || {
+        id: task.id,
+        summary: task.summary,
+        description: task.description,
+        jiraIssueKey: task.jiraIssueKey,
+        workerModel: task.workerModel,
+        githubRepo: task.githubRepo,
+        scmProvider: task.scmProvider,
+        skipManagerReview: task.skipManagerReview,
+        executionPlanV2: task.executionPlanV2,
+        jiraFields: task.jiraFields || {},
+    };
+    // Spawn asynchronously (don't block the poll loop)
+    spawnWorker(spawnableTask, config, oc).catch((err) => console.error(`${ts()} ${chalk.red("✗")} Spawn failed for ${taskLabel}:`, err.message || err));
+}
+/**
+ * Start the poll loop.
+ */
+export function startPolling(config) {
+    console.log(`  ${chalk.dim("Polling every")} ${config.pollIntervalMs / 1000}s ${chalk.dim("· waiting for tasks...")}`);
+    // Initial poll
+    pollOnce(config);
+    // Recurring poll
+    setInterval(() => pollOnce(config), config.pollIntervalMs);
+}
+/**
+ * Start the heartbeat loop.
+ */
+export function startHeartbeat(config) {
+    setInterval(async () => {
+        const activeTaskIds = getActiveTaskIds();
+        try {
+            const response = await api.post("/api/agent/heartbeat", {
+                agentId: config.agentId,
+                activeTasks: activeTaskIds,
+            });
+            // Stop containers for tasks cancelled via the cloud dashboard
+            const cancelledTasks = response.data?.cancelledTasks;
+            if (cancelledTasks && cancelledTasks.length > 0) {
+                for (const taskId of cancelledTasks) {
+                    stopTask(taskId);
+                }
+            }
+        }
+        catch {
+            // Heartbeat failures are non-critical
+        }
+    }, config.heartbeatIntervalMs);
+}

package/dist/spawner.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Remote Agent Spawner
+ *
+ * Spawns Docker worker containers that talk directly to the cloud WorkerMill API.
+ * Extracted from api/src/services/local-epic-spawner.ts with key differences:
+ *   - API_BASE_URL points to cloud (https://workermill.com)
+ *   - ORG_API_KEY is the real org API key
+ *   - Container logs stream to cloud dashboard via SSE
+ */
+import type { AgentConfig } from "./config.js";
+export interface SpawnableTask {
+    id: string;
+    summary: string;
+    description: string | null;
+    jiraIssueKey: string | null;
+    workerModel: string;
+    githubRepo: string;
+    scmProvider: string;
+    skipManagerReview?: boolean;
+    executionPlanV2: unknown;
+    jiraFields: Record<string, unknown>;
+}
+/**
+ * Spawn a Docker worker container for a task.
+ */
+export declare function spawnWorker(task: SpawnableTask, config: AgentConfig, orgConfig: Record<string, unknown>): Promise<void>;
+/**
+ * Get count of actively running containers.
+ */
+export declare function getActiveCount(): number;
+/**
+ * Get IDs of all active tasks.
+ */
+export declare function getActiveTaskIds(): string[];
+/**
+ * Stop a specific task's container by task ID.
+ */
+export declare function stopTask(taskId: string): void;
+/**
+ * Stop all running containers.
+ */
+export declare function stopAll(): Promise<void>;