@flumecode/runner 0.0.1

package/dist/cli.js

@@ -0,0 +1,820 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var CONFIG_DIR = join(homedir(), ".flume");
+var configPath = join(CONFIG_DIR, "config.json");
+function readConfig() {
+  if (!existsSync(configPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    if (!parsed.serverUrl || !parsed.token) return null;
+    return { serverUrl: parsed.serverUrl, token: parsed.token };
+  } catch {
+    return null;
+  }
+}
+function writeConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 384 });
+}
+
+// src/version.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { fileURLToPath } from "node:url";
+function readVersion() {
+  try {
+    const path = fileURLToPath(new URL("../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync2(path, "utf8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+var RUNNER_VERSION = readVersion();
+var RUNNER_VERSION_HEADER = "x-flumecode-runner-version";
+
+// src/api.ts
+async function claimJob(config) {
+  const res = await fetch(`${config.serverUrl}/api/runner/jobs/claim`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      [RUNNER_VERSION_HEADER]: RUNNER_VERSION
+    }
+  });
+  if (res.status === 204) return null;
+  if (res.status === 401) {
+    throw new Error("Runner token rejected (401). Re-run `login` with a fresh token.");
+  }
+  if (!res.ok) throw new Error(`claim failed: ${res.status} ${await safeText(res)}`);
+  return await res.json();
+}
+async function reportJob(config, jobId, result) {
+  const res = await fetch(`${config.serverUrl}/api/runner/jobs/${jobId}/complete`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      "content-type": "application/json",
+      [RUNNER_VERSION_HEADER]: RUNNER_VERSION
+    },
+    body: JSON.stringify(result)
+  });
+  if (!res.ok) throw new Error(`complete failed: ${res.status} ${await safeText(res)}`);
+}
+async function reportHeartbeat(config, claudeCode) {
+  const res = await fetch(`${config.serverUrl}/api/runner/heartbeat`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      "content-type": "application/json",
+      [RUNNER_VERSION_HEADER]: RUNNER_VERSION
+    },
+    body: JSON.stringify({ claudeCode })
+  });
+  if (!res.ok) throw new Error(`heartbeat failed: ${res.status} ${await safeText(res)}`);
+}
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+// src/executor.ts
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+// src/widgets.ts
+import { randomUUID } from "node:crypto";
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+var SERVER_NAME = "flume_widgets";
+var SINGLE_SELECT = "single_select";
+var MULTI_SELECT = "multi_select";
+var WIDGET_TOOL_NAMES = [
+  `mcp__${SERVER_NAME}__${SINGLE_SELECT}`,
+  `mcp__${SERVER_NAME}__${MULTI_SELECT}`
+];
+var optionsSchema = z.array(z.string().min(1)).min(2).max(8).describe("2\u20138 short, distinct choices for the user to pick from.");
+var TAIL = "Do NOT add an 'Other' or 'None of these' catch-all \u2014 the UI always offers an 'Other' free-text option automatically. After calling this, END YOUR TURN and wait: the user's answer arrives as their next message and starts a fresh run.";
+function createWidgetTooling() {
+  const collected = [];
+  const singleSelect = tool(
+    SINGLE_SELECT,
+    "Ask the user a single-select (radio-button) question \u2014 exactly one answer. Use this for a genuine either/or choice (competing approaches, scope decisions, yes/no) instead of writing the options as prose. " + TAIL,
+    {
+      question: z.string().min(1).describe("The question to ask the user."),
+      options: optionsSchema
+    },
+    async (args) => {
+      collected.push({
+        id: randomUUID(),
+        type: "single_select",
+        question: args.question,
+        options: args.options.map((label) => ({ id: randomUUID(), label })),
+        selectedOptionId: null,
+        customAnswer: null
+      });
+      return widgetPosted("single-select");
+    }
+  );
+  const multiSelect = tool(
+    MULTI_SELECT,
+    "Ask the user a multi-select (checkbox) question \u2014 they may pick any number of options, including none of the presets if they use 'Other'. Use this for 'select all that apply' questions (which features to include, which files to touch). " + TAIL,
+    {
+      question: z.string().min(1).describe("The question to ask the user."),
+      options: optionsSchema
+    },
+    async (args) => {
+      collected.push({
+        id: randomUUID(),
+        type: "multi_select",
+        question: args.question,
+        options: args.options.map((label) => ({ id: randomUUID(), label })),
+        selectedOptionIds: null,
+        customAnswer: null
+      });
+      return widgetPosted("multi-select");
+    }
+  );
+  const mcpServer = createSdkMcpServer({
+    name: SERVER_NAME,
+    tools: [singleSelect, multiSelect]
+  });
+  return { mcpServer, collected };
+}
+function widgetPosted(kind) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Question posted to the user as a ${kind} widget. End your turn now and wait \u2014 their answer will arrive as their next message.`
+      }
+    ]
+  };
+}
+
+// src/plan.ts
+import { createSdkMcpServer as createSdkMcpServer2, tool as tool2 } from "@anthropic-ai/claude-agent-sdk";
+import { z as z2 } from "zod";
+var SERVER_NAME2 = "flume_plan";
+var SUBMIT_PLAN = "submit_plan";
+var PLAN_TOOL_NAME = `mcp__${SERVER_NAME2}__${SUBMIT_PLAN}`;
+var PLAN_MARKER = "<!-- flumecode:end-of-plan -->";
+var stepSchema = z2.object({
+  change: z2.string().min(1).describe("What changes, with concrete file references."),
+  why: z2.string().min(1).describe("The reason for this step."),
+  files: z2.array(z2.string()).optional().describe("Affected file paths.")
+});
+var planInputSchema = {
+  scope: z2.enum(["feat", "fix", "chore", "docs", "test", "refactor"]).describe("The primary intent of the change."),
+  goal: z2.string().min(1).describe("One or two sentences stating the outcome."),
+  assumptions: z2.array(z2.string()).describe("Anything decided during planning, including unanswered defaults."),
+  steps: z2.array(stepSchema).min(1).describe("Ordered list of changes. Each step says what and why, with file references."),
+  acceptanceCriteria: z2.array(z2.string().min(1)).min(2).describe(
+    "Observable conditions that together define done. Each must be checkable \u2014 a behavior, test, or state you could verify \u2014 not a restatement of a step. At least 2 required."
+  ),
+  risks: z2.array(z2.string()).describe("Anything that could change the approach."),
+  outOfScope: z2.array(z2.string()).describe("What is deliberately not being done.")
+};
+var planSchema = z2.object(planInputSchema);
+function renderPlan(plan) {
+  const lines = [];
+  lines.push(`**Scope** \u2014 \`${plan.scope}\``);
+  lines.push("");
+  lines.push(`**Goal** \u2014 ${plan.goal}`);
+  if (plan.assumptions.length > 0) {
+    lines.push("");
+    lines.push("**Assumptions**");
+    for (const assumption of plan.assumptions) {
+      lines.push(`- ${assumption}`);
+    }
+  }
+  lines.push("");
+  lines.push("**Steps**");
+  for (const [i, step] of plan.steps.entries()) {
+    lines.push(`${i + 1}. **${step.change}** \u2014 ${step.why}`);
+    if (step.files && step.files.length > 0) {
+      for (const file of step.files) {
+        lines.push(`   - \`${file}\``);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("## Acceptance criteria");
+  for (const criterion of plan.acceptanceCriteria) {
+    lines.push(`- [ ] ${criterion}`);
+  }
+  if (plan.risks.length > 0) {
+    lines.push("");
+    lines.push("**Risks / open questions**");
+    for (const risk of plan.risks) {
+      lines.push(`- ${risk}`);
+    }
+  }
+  if (plan.outOfScope.length > 0) {
+    lines.push("");
+    lines.push("**Out of scope**");
+    for (const item of plan.outOfScope) {
+      lines.push(`- ${item}`);
+    }
+  }
+  lines.push("");
+  lines.push(PLAN_MARKER);
+  return lines.join("\n");
+}
+function createPlanTooling() {
+  let renderedPlan = null;
+  const submitPlan = tool2(
+    SUBMIT_PLAN,
+    "Submit the finished plan. Call this \u2014 and only this \u2014 when the plan is complete and ready to post. The runner renders your structured fields into the canonical plan markdown and posts it as your comment. acceptanceCriteria is required and must contain at least 2 observable, verifiable conditions (behaviors, tests, or states you could check) that together define 'done'. After calling this, end your turn.",
+    planInputSchema,
+    async (args) => {
+      renderedPlan = renderPlan(planSchema.parse(args));
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Plan submitted. The runner will render and post it as your comment. End your turn now."
+          }
+        ]
+      };
+    }
+  );
+  const mcpServer = createSdkMcpServer2({
+    name: SERVER_NAME2,
+    tools: [submitPlan]
+  });
+  return { mcpServer, getPlan: () => renderedPlan };
+}
+
+// src/executor.ts
+var FLUME_PLUGIN_DIR = fileURLToPath2(new URL("../skills-plugin", import.meta.url));
+async function runClaudeCode(opts) {
+  let finalText = "";
+  const { mcpServer, collected } = createWidgetTooling();
+  const { mcpServer: planServer, getPlan } = createPlanTooling();
+  for await (const message of query({
+    prompt: opts.prompt,
+    options: {
+      cwd: opts.cwd,
+      permissionMode: opts.permissionMode,
+      allowDangerouslySkipPermissions: opts.permissionMode === "bypassPermissions",
+      ...opts.model ? { model: opts.model } : {},
+      maxTurns: opts.maxTurns ?? 40,
+      // Hermetic: ignore ALL config from the checked-out repo (CLAUDE.md,
+      // .claude/settings.json, .claude/skills, …) and the runner owner's
+      // ~/.claude. Only our plugin's skills are exposed to the agent. Auto-memory
+      // is disabled separately via CLAUDE_CODE_DISABLE_AUTO_MEMORY (see cli.ts).
+      settingSources: [],
+      plugins: [{ type: "local", path: FLUME_PLUGIN_DIR }],
+      // Pre-approve the widget, plan, and Task tools so they run without a
+      // permission prompt in headless mode (allow-listing pre-approves them; it
+      // does NOT restrict anything else). Task lets the implement-plan
+      // orchestrator spawn its subagents; without pre-approval the spawn could
+      // stall waiting for an approval no one can give.
+      mcpServers: { flume_widgets: mcpServer, flume_plan: planServer },
+      allowedTools: [...WIDGET_TOOL_NAMES, PLAN_TOOL_NAME, "Task"]
+    }
+  })) {
+    if (message.type === "assistant") {
+      const content = message.message?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block && block.type === "text" && typeof block.text === "string") {
+            process.stdout.write(block.text);
+          }
+        }
+      }
+    } else if (message.type === "result") {
+      finalText = message.result ?? "";
+    }
+  }
+  process.stdout.write("\n");
+  return { text: finalText, widgets: collected, plan: getPlan() };
+}
+
+// src/health.ts
+import { query as query2 } from "@anthropic-ai/claude-agent-sdk";
+var PROBE_TIMEOUT_MS = 6e4;
+async function checkClaudeCode() {
+  try {
+    let sawResult = false;
+    const run = (async () => {
+      for await (const message of query2({
+        prompt: "Reply with the single word: ok",
+        options: { permissionMode: "bypassPermissions", maxTurns: 1 }
+      })) {
+        if (message.type === "result") {
+          sawResult = true;
+          const isError = message.is_error === true;
+          const subtype = message.subtype;
+          if (isError)
+            throw new Error(
+              subtype ? `Claude Code error: ${subtype}` : "Claude Code returned an error"
+            );
+        }
+      }
+    })();
+    await withTimeout(run, PROBE_TIMEOUT_MS, "Claude Code did not respond in time");
+    if (!sawResult) return { ready: false, error: "Claude Code produced no result" };
+    return { ready: true };
+  } catch (err) {
+    return { ready: false, error: errorMessage(err) };
+  }
+}
+function withTimeout(p, ms, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/rules.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { join as join2 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+var RULES_DIR = fileURLToPath3(new URL("../skills-plugin/rules", import.meta.url));
+function loadRule(name) {
+  const raw = readFileSync3(join2(RULES_DIR, `${name}.md`), "utf8");
+  return stripFrontMatter(raw).trim();
+}
+function stripFrontMatter(raw) {
+  const match = raw.match(/^---\n.*?\n---\n/s);
+  return match ? raw.slice(match[0].length) : raw;
+}
+
+// src/prompt.ts
+function buildPrompt(ctx) {
+  const task = ctx.permissionMode === "plan" ? `Use the \`flumecode:request-to-plan\` skill to handle this request. You are read-only and cannot modify files \u2014 clarify any ambiguity with the user first, then produce a concrete, actionable plan (the specific changes you would make and why). Cite the relevant files. Do NOT call ExitPlanMode or write the plan to a file. When the plan is ready, call the \`submit_plan\` tool with the structured plan fields; the runner renders it into the canonical plan markdown and posts it as your comment.` : `Use the \`flumecode:implement-plan\` skill to handle this request. You are the ORCHESTRATOR: do not implement, review, or write the report yourself \u2014 follow the skill to delegate each phase to subagents via the Task tool, picking the right model for each. Do not commit or push \u2014 the runner handles that.`;
+  const orient = `Before investigating raw source, check for a FlumeCode wiki at \`.flumecode/wiki/\`. If it exists, read \`.flumecode/wiki/README.md\` first \u2014 it is the index \u2014 and follow its links to the pages and source paths relevant to this request. If there is no wiki, work from the code directly.`;
+  const widgets = `When you need the user to choose, ask it as a widget rather than writing the options as prose: call \`single_select\` for a one-of-N choice (radio buttons) or \`multi_select\` for a "select all that apply" choice (checkboxes). Don't add your own "Other" option \u2014 the UI always provides one. After calling a widget tool, end your turn \u2014 the user's answer comes back as their next message and starts a fresh run.`;
+  const lines = [
+    `You are "${ctx.agentName}", an autonomous coding agent working inside a FlumeCode request.`,
+    `The repository ${ctx.repo.fullName} is checked out in your current working directory on branch "${ctx.repo.checkoutBranch}" at commit ${ctx.repo.checkoutSha.slice(0, 7)}.`,
+    task,
+    orient,
+    widgets
+  ];
+  if (ctx.permissionMode !== "plan") {
+    lines.push(
+      "",
+      "These coding guidelines apply to all code produced in this run:",
+      "",
+      loadRule("coding-guideline")
+    );
+  }
+  lines.push("", `# Request: ${ctx.request?.title ?? ""}`);
+  if (ctx.request?.body) {
+    lines.push("", ctx.request.body);
+  }
+  if (ctx.thread && ctx.thread.length > 0) {
+    lines.push("", "# Conversation so far");
+    for (const turn of ctx.thread) {
+      lines.push("", `## ${turn.role === "agent" ? ctx.agentName : "User"}`, turn.content);
+    }
+  }
+  lines.push(
+    "",
+    ctx.permissionMode === "plan" ? "Your final reply is posted verbatim as your comment in the thread \u2014 if you called `submit_plan`, the rendered plan is posted automatically; for clarifying questions, your reply text is posted as-is." : "Your final reply is posted verbatim as your comment in the thread \u2014 make it the implementation report your report subagent produced, with nothing added. The runner appends the pull-request link."
+  );
+  return lines.join("\n");
+}
+function buildDocumentPrompt(ctx) {
+  const lines = [
+    `You are "${ctx.agentName}" maintaining the repository wiki for ${ctx.repo.fullName}.`,
+    `An implementation just ran in this working directory to satisfy the request below; its changes are uncommitted in the working tree.`,
+    `Use the \`flumecode:document\` skill to bring the wiki in sync with those changes. Only edit files under \`.flumecode/wiki/\` \u2014 do not touch application code. The runner commits the wiki alongside the implementation in the same pull request.`,
+    "",
+    `# Request: ${ctx.request?.title ?? ""}`
+  ];
+  if (ctx.request?.body) {
+    lines.push("", ctx.request.body);
+  }
+  if (ctx.thread && ctx.thread.length > 0) {
+    lines.push("", "# Conversation so far");
+    for (const turn of ctx.thread) {
+      lines.push("", `## ${turn.role === "agent" ? ctx.agentName : "User"}`, turn.content);
+    }
+  }
+  lines.push("", "When done, reply with a one- or two-line summary of the wiki changes you made.");
+  return lines.join("\n");
+}
+function buildInitPrompt(ctx) {
+  return [
+    `You are "${ctx.agentName}" initializing FlumeCode for the repository ${ctx.repo.fullName}, checked out in your current working directory.`,
+    `Use the \`flumecode:document\` skill to create the initial repository wiki under \`.flumecode/wiki/\`. The wiki does not exist yet, so the skill will bootstrap it: survey the codebase and produce a high-level overview plus per-component pages. Only create files under \`.flumecode/\` \u2014 do not modify application code. The runner commits the result and opens a pull request.`,
+    "",
+    "When done, reply with a one- or two-line summary of the wiki you created."
+  ].join("\n");
+}
+
+// src/types.ts
+function jobTitle(ctx) {
+  return ctx.kind === "init" ? "Initialize FlumeCode wiki" : ctx.request?.title ?? "request";
+}
+
+// src/workspace.ts
+import { execFile } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join3 } from "node:path";
+import { promisify } from "node:util";
+var exec = promisify(execFile);
+var WORKSPACE_PREFIX = "flume-runner-";
+var MAX_BUFFER = 1 << 24;
+async function git(args) {
+  return exec("git", args, { maxBuffer: MAX_BUFFER });
+}
+function cloneUrl(ctx) {
+  const { owner, name, cloneToken } = ctx.repo;
+  return `https://x-access-token:${cloneToken}@github.com/${owner}/${name}.git`;
+}
+function detectPackageManager(dir) {
+  if (!existsSync2(join3(dir, "package.json"))) return null;
+  if (existsSync2(join3(dir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync2(join3(dir, "yarn.lock"))) return "yarn";
+  if (existsSync2(join3(dir, "package-lock.json"))) return "npm";
+  if (existsSync2(join3(dir, "bun.lockb"))) return "bun";
+  return "npm";
+}
+async function installDependencies(dir) {
+  const manager = detectPackageManager(dir);
+  if (manager === null) return { status: "skipped" };
+  const env = { ...process.env, CI: "1", ADBLOCK: "1", DISABLE_OPENCOLLECTIVE: "1" };
+  try {
+    await exec(manager, ["install"], { cwd: dir, maxBuffer: MAX_BUFFER, env, timeout: 5 * 6e4 });
+    return { status: "installed", manager };
+  } catch (err) {
+    return { status: "failed", manager, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+async function makeWorkspace() {
+  return mkdtemp(join3(tmpdir(), WORKSPACE_PREFIX));
+}
+async function sweepWorkspaces() {
+  const base = tmpdir();
+  let entries;
+  try {
+    entries = await readdir(base);
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.startsWith(WORKSPACE_PREFIX)) continue;
+    try {
+      await rm(join3(base, entry), { recursive: true, force: true });
+      removed++;
+    } catch {
+    }
+  }
+  return removed;
+}
+async function cloneAtSha(ctx, dir) {
+  await git(["clone", "--quiet", cloneUrl(ctx), dir]);
+  await git(["-C", dir, "checkout", "-B", ctx.repo.checkoutBranch, ctx.repo.checkoutSha]);
+}
+async function hasChanges(dir) {
+  await git(["-C", dir, "add", "-A"]);
+  const { stdout: stdout2 } = await git(["-C", dir, "status", "--porcelain"]);
+  return stdout2.trim().length > 0;
+}
+async function commitAndPush(ctx, dir) {
+  if (!await hasChanges(dir)) return false;
+  await git([
+    "-C",
+    dir,
+    "-c",
+    "user.email=runner@flumecode.local",
+    "-c",
+    "user.name=FlumeCode Runner",
+    "commit",
+    "--quiet",
+    "-m",
+    `FlumeCode: ${jobTitle(ctx)}`
+  ]);
+  await git(["-C", dir, "push", "--quiet", "-u", "origin", ctx.repo.checkoutBranch]);
+  return true;
+}
+async function openPullRequest(ctx) {
+  const { owner, name, cloneToken, checkoutBranch, mergeBranch } = ctx.repo;
+  if (!mergeBranch) return null;
+  const apiBase = `https://api.github.com/repos/${owner}/${name}`;
+  const headers = {
+    authorization: `Bearer ${cloneToken}`,
+    accept: "application/vnd.github+json",
+    "x-github-api-version": "2022-11-28",
+    "content-type": "application/json"
+  };
+  const title = jobTitle(ctx);
+  const body = ctx.kind === "init" ? "Bootstraps the `.flumecode/` wiki for this repository. Opened by the FlumeCode runner." : `Opened by the FlumeCode runner for request "${title}".`;
+  const res = await fetch(`${apiBase}/pulls`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      title: `FlumeCode: ${title}`,
+      head: checkoutBranch,
+      base: mergeBranch,
+      body
+    })
+  });
+  if (res.status === 201) {
+    const data = await res.json();
+    return { number: data.number, url: data.html_url };
+  }
+  if (res.status === 422) {
+    const list = await fetch(
+      `${apiBase}/pulls?state=open&head=${owner}:${checkoutBranch}&base=${mergeBranch}`,
+      { headers }
+    );
+    if (list.ok) {
+      const open = await list.json();
+      if (open[0]) return { number: open[0].number, url: open[0].html_url };
+    }
+    return null;
+  }
+  throw new Error(`PR creation failed: ${res.status} ${await res.text()}`);
+}
+async function cleanup(dir) {
+  await rm(dir, { recursive: true, force: true });
+}
+
+// src/run.ts
+var IDLE_MS = 5e3;
+var ORCHESTRATOR_MODEL = "sonnet";
+var ORCHESTRATOR_MAX_TURNS = 80;
+var INIT_MAX_TURNS = 200;
+var DOCUMENT_MAX_TURNS = 120;
+var HEARTBEAT_MS = 5 * 6e4;
+async function pushAndOpenPr(ctx, dir) {
+  const pushed = await commitAndPush(ctx, dir);
+  if (!pushed) return { kind: "none" };
+  const pr = await openPullRequest(ctx);
+  return pr ? { kind: "pr", pr } : { kind: "pushed" };
+}
+function outcomeBanner(outcome, opts) {
+  const wikiNote = opts.documented ? " (with wiki updates)" : "";
+  switch (outcome.kind) {
+    case "pr":
+      return `
+
+---
+\u2705 Opened pull request from \`${opts.branch}\`${wikiNote} \xB7 [View pull request](${outcome.pr.url})`;
+    case "pushed":
+      return `
+
+---
+\u26A0\uFE0F Pushed \`${opts.branch}\`${wikiNote}, but couldn't open a pull request (no diff against the base branch, or one is already open).`;
+    case "none":
+      return `
+
+---
+\u2139\uFE0F **No code changes were made** \u2014 ${opts.noChange ?? "there was nothing to open a pull request for."}`;
+  }
+}
+async function processJob(ctx) {
+  const dir = await makeWorkspace();
+  try {
+    if (ctx.kind === "init") return await processInitJob(ctx, dir);
+    if (ctx.kind === "implement") return await processImplementJob(ctx, dir);
+    return await processChatJob(ctx, dir);
+  } finally {
+    await cleanup(dir);
+  }
+}
+async function processInitJob(ctx, dir) {
+  console.log(`
+\u25B6 Init ${ctx.jobId} \u2014 ${ctx.repo.fullName} on ${ctx.repo.checkoutBranch}`);
+  await cloneAtSha(ctx, dir);
+  const summary = (await runClaudeCode({
+    cwd: dir,
+    prompt: buildInitPrompt(ctx),
+    permissionMode: ctx.permissionMode,
+    maxTurns: INIT_MAX_TURNS
+  })).text.trim();
+  let reply = summary || "(the agent produced no summary)";
+  const outcome = await pushAndOpenPr(ctx, dir);
+  reply += outcomeBanner(outcome, {
+    branch: ctx.repo.checkoutBranch,
+    noChange: "no files were generated; the wiki may already exist."
+  });
+  return { text: reply, widgets: [] };
+}
+async function processChatJob(ctx, dir) {
+  console.log(`
+\u25B6 Job ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
+  await cloneAtSha(ctx, dir);
+  const orchestrating = ctx.permissionMode !== "plan";
+  const installResult = orchestrating ? await installDependencies(dir) : null;
+  const result = await runClaudeCode({
+    cwd: dir,
+    prompt: buildPrompt(ctx),
+    permissionMode: ctx.permissionMode,
+    ...orchestrating ? { model: ORCHESTRATOR_MODEL, maxTurns: ORCHESTRATOR_MAX_TURNS } : {}
+  });
+  const summary = result.text.trim();
+  let reply = summary || "(the agent produced no summary)";
+  if (result.plan) {
+    reply = result.plan;
+  }
+  if (installResult?.status === "failed") {
+    reply += `
+
+> \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
+  }
+  if (result.widgets.length > 0) {
+    console.log(`  \u2026job ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
+    return { text: reply, widgets: result.widgets };
+  }
+  let documented = false;
+  if (ctx.permissionMode !== "plan" && await hasChanges(dir)) {
+    try {
+      console.log(`  \u2026updating wiki for job ${ctx.jobId}`);
+      await runClaudeCode({
+        cwd: dir,
+        prompt: buildDocumentPrompt(ctx),
+        permissionMode: ctx.permissionMode,
+        maxTurns: DOCUMENT_MAX_TURNS
+      });
+      documented = true;
+    } catch (err) {
+      console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
+    }
+  }
+  const outcome = await pushAndOpenPr(ctx, dir);
+  reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
+  return { text: reply, widgets: [] };
+}
+async function processImplementJob(ctx, dir) {
+  console.log(`
+\u25B6 Implement ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
+  await cloneAtSha(ctx, dir);
+  const installResult = await installDependencies(dir);
+  const result = await runClaudeCode({
+    cwd: dir,
+    prompt: buildPrompt(ctx),
+    permissionMode: ctx.permissionMode,
+    model: ORCHESTRATOR_MODEL,
+    maxTurns: ORCHESTRATOR_MAX_TURNS
+  });
+  let reply = result.text.trim() || "(the agent produced no report)";
+  if (installResult.status === "failed") {
+    reply += `
+
+> \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
+  }
+  let documented = false;
+  if (await hasChanges(dir)) {
+    try {
+      console.log(`  \u2026updating wiki for implement ${ctx.jobId}`);
+      await runClaudeCode({
+        cwd: dir,
+        prompt: buildDocumentPrompt(ctx),
+        permissionMode: ctx.permissionMode,
+        maxTurns: DOCUMENT_MAX_TURNS
+      });
+      documented = true;
+    } catch (err) {
+      console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
+    }
+  }
+  const outcome = await pushAndOpenPr(ctx, dir);
+  reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
+  return { text: reply, widgets: [], ...outcome.kind === "pr" ? { pr: outcome.pr } : {} };
+}
+async function heartbeat(config) {
+  const health = await checkClaudeCode();
+  if (health.ready) {
+    console.log("\u2665 Claude Code auth verified \u2014 ready for jobs.");
+  } else {
+    console.warn(`\u2665 Claude Code not ready: ${health.error ?? "unknown reason"}`);
+  }
+  try {
+    await reportHeartbeat(config, health);
+  } catch (err) {
+    console.error(`Heartbeat report failed: ${errorMessage2(err)}`);
+  }
+}
+async function pollLoop(config) {
+  console.log(`FlumeCode runner connected to ${config.serverUrl}. Polling for jobs\u2026`);
+  const swept = await sweepWorkspaces();
+  if (swept > 0) console.log(`Cleared ${swept} stale workspace${swept === 1 ? "" : "s"}.`);
+  await heartbeat(config);
+  let nextHeartbeatAt = Date.now() + HEARTBEAT_MS;
+  for (; ; ) {
+    if (Date.now() >= nextHeartbeatAt) {
+      await heartbeat(config);
+      nextHeartbeatAt = Date.now() + HEARTBEAT_MS;
+    }
+    let ctx = null;
+    try {
+      ctx = await claimJob(config);
+    } catch (err) {
+      console.error(`Claim error: ${errorMessage2(err)}`);
+      await sleep(IDLE_MS);
+      continue;
+    }
+    if (!ctx) {
+      await sleep(IDLE_MS);
+      continue;
+    }
+    try {
+      const { text, widgets, pr } = await processJob(ctx);
+      await reportJob(config, ctx.jobId, { status: "done", text, widgets, pr });
+      console.log(`\u2713 Job ${ctx.jobId} done`);
+    } catch (err) {
+      const message = errorMessage2(err);
+      console.error(`\u2717 Job ${ctx.jobId} failed: ${message}`);
+      try {
+        await reportJob(config, ctx.jobId, { status: "error", error: message });
+      } catch (reportErr) {
+        console.error(`  (also failed to report the error: ${errorMessage2(reportErr)})`);
+      }
+    }
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function errorMessage2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/cli.ts
+var DEFAULT_SERVER = process.env.FLUME_SERVER || "http://localhost:3000";
+async function login(args) {
+  const flags = parseFlags(args);
+  let serverUrl = flags.server;
+  let token = flags.token;
+  if (!serverUrl || !token) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    if (!serverUrl) {
+      const answer = (await rl.question(`Server URL [${DEFAULT_SERVER}]: `)).trim();
+      serverUrl = answer || DEFAULT_SERVER;
+    }
+    if (!token) {
+      token = (await rl.question("Runner token (flrun_\u2026): ")).trim();
+    }
+    rl.close();
+  }
+  serverUrl = serverUrl.replace(/\/+$/, "");
+  if (!token) {
+    console.error("A runner token is required. Create one in the web app under Runners.");
+    process.exit(1);
+  }
+  writeConfig({ serverUrl, token });
+  console.log(`Saved runner config to ${configPath}.`);
+  console.log("Start the runner with: flumecode start");
+}
+async function start() {
+  process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
+  const config = readConfig();
+  if (!config) {
+    console.error("Not logged in. Run: flumecode login");
+    process.exit(1);
+  }
+  await pollLoop(config);
+}
+function parseFlags(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--server") out.server = args[i + 1];
+    else if (args[i] === "--token") out.token = args[i + 1];
+  }
+  return out;
+}
+var command = process.argv[2];
+var rest = process.argv.slice(3);
+if (command === "login") {
+  void login(rest);
+} else if (command === "start") {
+  void start();
+} else {
+  console.log("FlumeCode runner");
+  console.log("Usage:");
+  console.log("  flumecode login   # save server URL + token");
+  console.log("  flumecode start   # poll for and run jobs");
+  process.exit(command ? 1 : 0);
+}