flowviant 0.6.0

package/bin/lib/live.mjs

@@ -0,0 +1,483 @@
+/**
+ * Live mode (phase 2, opt-in via FLOWVIANT_LIVE=1). Instead of one-shot
+ * `claude -p` turns + sentinels, each task runs a PERSISTENT Agent-SDK session:
+ * the daemon claims, seeds the session with the brief, mirrors the model's
+ * streamed reply into the task channel (stream_turn), injects human @-messages
+ * as new turns, and bridges blockers (the session idle-parks; the daemon polls
+ * the human's answer and injects it to resume in place). Same session = the
+ * iterating loop, hosted through Flowviant.
+ *
+ * Auth invariant: the SDK runs the user's own Claude Code (subscription), never
+ * the API — we strip ANTHROPIC_API_KEY from the session env so a key in the
+ * user's shell can't silently divert to API billing.
+ *
+ * NOTE: the SDK mechanics here (streaming-input continuity, tool_use visibility,
+ * one result per turn) are validated by spikes; the end-to-end task loop needs a
+ * live fleet + repo to shake out. Old (poll/sentinel) mode is untouched.
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import {
+  MCP_URL,
+  SAFE,
+  POLL_SECONDS,
+  IDLE_SECONDS,
+  PARK_TIMEOUT_SECONDS,
+  FLEET_URL,
+  FLEET_TOKEN,
+  USER_AGENT,
+} from './config.mjs';
+import { c, info, ok, warn } from './ui.mjs';
+import { sleep } from './claude.mjs';
+import { git, resetWorktree } from './git.mjs';
+import { loadPreviewConfig, startPreview } from './preview.mjs';
+
+// Register a branch preview's tunnel URL with Flowviant (fleet-authed). The
+// reviewer then drives it via "Open live preview" in the node.
+const LIVE_TARGET_URL = FLEET_URL.replace(/\/agents\/?$/, '/live-target');
+async function registerLiveTarget(intentId, kind, url) {
+  try {
+    await fetch(LIVE_TARGET_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${FLEET_TOKEN}`,
+        'User-Agent': USER_AGENT,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ intentId, kind, url }),
+    });
+  } catch {
+    /* best-effort — the tunnel still works; it just isn't linked in the app */
+  }
+}
+
+const SAFE_TOOLS = ['Edit', 'Write', 'Read', 'Grep', 'Glob', 'Bash', 'mcp__flowviant'];
+
+// Appended to Claude Code's preset. The reliable copy of the contract also
+// rides in the seed message below, so this degrades gracefully if the preset
+// shape shifts between SDK versions.
+const SYSTEM_LIVE = `You are a Flowviant build agent working ONE task inside a live, shared task
+channel. START by stating your approach in plain language (a short plan) BEFORE
+you touch any code — the whole team watches this channel and may redirect you.
+A human teammate may message you mid-task; treat any injected "The human
+answered…" or teammate line as a new instruction and adapt. There is NO terminal
+and NO interactive prompt — your only channel to a human is the flowviant MCP
+tools. When you hit a decision only a human can make, call report_blocker (with
+options when you can) and then STOP your turn — do not spin or guess; you will be
+resumed with the answer. When the work is done: call attach_evidence for EACH
+acceptance criterion (this is the floor the human reviews against); open ONE draft
+PR (git push + gh pr create --draft), call attach_pr, then call complete. A live
+preview of your branch is started for you automatically for the review — you do
+NOT need to open a tunnel or register a live target. NEVER merge — the human
+reviews and merging is handled separately.`;
+
+function seedPrompt(runId, brief, transcript) {
+  return [
+    `Your run id is ${runId}. Use it for every flowviant MCP tool call.`,
+    brief?.branch
+      ? `This is a REVISION — your prior branch "${brief.branch}" is checked out; address the review feedback and push to the SAME branch (the PR updates in place).`
+      : `Start from the clean base checkout and open a fresh draft PR when done.`,
+    ``,
+    `Task brief:`,
+    JSON.stringify(brief ?? {}, null, 2),
+    ...(transcript
+      ? [``, `Conversation so far (you may be resuming — pick up where this left off):`, transcript]
+      : []),
+    ``,
+    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first, then: report_progress as you go; report_blocker + stop if you hit a human decision; attach_evidence, open a draft PR, attach_pr, then complete when done.`,
+  ].join('\n');
+}
+
+// ── MCP JSON-RPC client (the daemon's own calls, outside the session) ───────
+// The flowviant MCP endpoint handles tools/call statelessly with a bearer
+// worker token — no handshake — so this is all the daemon needs.
+let rpcId = 0;
+async function mcpCall(mcpUrl, token, name, args) {
+  const res = await fetch(mcpUrl, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: ++rpcId,
+      method: 'tools/call',
+      params: { name, arguments: args },
+    }),
+  });
+  if (!res.ok) throw new Error(`mcp ${name} ${res.status}`);
+  const body = await res.json();
+  const text = body?.result?.content?.[0]?.text;
+  if (typeof text !== 'string') return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+// Flatten a tool_result's content (string | array of {type:'text',text}) to text.
+function resultText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content))
+    return content.map((b) => (b?.type === 'text' ? b.text : '')).join('');
+  return '';
+}
+const BLOCKER_ID_RE = /"blockerId"\s*:\s*"([^"]+)"/;
+
+// A streaming-input controller: seed message first, then push() more turns as
+// they arrive (human @-messages, injected blocker answers). close() ends it.
+function makeInput(seedText) {
+  const q = [{ type: 'user', message: { role: 'user', content: seedText }, parent_tool_use_id: null }];
+  let waker = null;
+  let closed = false;
+  return {
+    push(text, priority) {
+      q.push({
+        type: 'user',
+        message: { role: 'user', content: text },
+        parent_tool_use_id: null,
+        ...(priority ? { priority } : {}),
+      });
+      if (waker) { waker(); waker = null; }
+    },
+    close() {
+      closed = true;
+      if (waker) { waker(); waker = null; }
+    },
+    async *stream() {
+      while (true) {
+        if (q.length === 0) {
+          if (closed) return;
+          await new Promise((r) => (waker = r));
+          if (closed && q.length === 0) return;
+        }
+        while (q.length) yield q.shift();
+      }
+    },
+  };
+}
+
+// A stop word from any teammate halts the agent (interrupt at the next boundary,
+// then hold for direction) — the "stop, you're going the wrong way" valve.
+const STOP_RE = /(^|\W)stop(\W|$)/i;
+
+// Idle-park on a blocker: the session is idle (zero tokens); poll the human's
+// answer. Bounded by PARK_TIMEOUT — after that we tear the session down (free
+// the Claude process) and resume later, rather than hold it open forever.
+// Returns {status:'resolved',answer} | {status:'timeout'} | {status:'aborted'}.
+async function waitForResolution(mcpUrl, token, blockerId, isAlive) {
+  if (!blockerId) return { status: 'aborted' };
+  const deadline = Date.now() + PARK_TIMEOUT_SECONDS * 1000;
+  while (isAlive()) {
+    await sleep(POLL_SECONDS);
+    const r = await mcpCall(mcpUrl, token, 'get_blocker_resolution', { blockerId }).catch(() => null);
+    if (r?.resolved) return { status: 'resolved', answer: r.resolution ?? {} };
+    if (Date.now() >= deadline) return { status: 'timeout' };
+  }
+  return { status: 'aborted' };
+}
+
+// Park awaiting the next human message (used after a stop — no nudging).
+// Returns the message, or null on shutdown/timeout.
+async function waitForMessage(mcpUrl, token, runId, afterId, isAlive) {
+  const deadline = Date.now() + PARK_TIMEOUT_SECONDS * 1000;
+  while (isAlive()) {
+    await sleep(POLL_SECONDS);
+    const poll = await mcpCall(mcpUrl, token, 'poll_channel', {
+      runId,
+      ...(afterId ? { afterId } : {}),
+    }).catch(() => null);
+    const fresh = (poll?.messages ?? []).filter((x) => x.role === 'user');
+    if (fresh.length) return fresh[fresh.length - 1];
+    if (Date.now() >= deadline) return null;
+  }
+  return null;
+}
+
+// One task: claim → seed → stream/mirror/inject/park → complete. Returns
+// { outcome: 'nothing' | 'done' | 'blocked' | 'stalled' | 'error' }.
+export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive }) {
+  const claim = await mcpCall(mcpUrl, token, 'claim_next_intent', {}).catch(() => null);
+  if (!claim || claim.claimed !== true) return { outcome: 'nothing' };
+  const { runId, intentId } = claim;
+  const brief = claim.brief ?? {};
+  const title = brief.title ?? 'a task';
+
+  // Revision resumes its PR branch; otherwise a clean base checkout.
+  if (brief.branch) {
+    try {
+      git(['fetch', 'origin', '--quiet'], cwd);
+      git(['checkout', brief.branch], cwd);
+    } catch {
+      resetWorktree(cwd, baseRef);
+    }
+  } else {
+    resetWorktree(cwd, baseRef);
+  }
+
+  const env = { ...process.env };
+  delete env.ANTHROPIC_API_KEY; // force the user's Claude Code subscription
+
+  // Prior channel transcript — present when resuming a parked/re-claimed task;
+  // seed it so a fresh session picks up where the conversation left off. afterId
+  // starts at the last existing message so we never re-inject old ones as "new".
+  const prior = await mcpCall(mcpUrl, token, 'poll_channel', { runId }).catch(() => null);
+  const priorMsgs = prior?.messages ?? [];
+  const transcript = priorMsgs
+    .map((m) => `${m.authorName || m.role}: ${m.content}`)
+    .join('\n');
+  let afterId = priorMsgs.length ? priorMsgs[priorMsgs.length - 1].id : null;
+
+  const input = makeInput(seedPrompt(runId, brief, transcript));
+  const session = query({
+    prompt: input.stream(),
+    options: {
+      cwd,
+      env,
+      permissionMode: SAFE ? 'default' : 'bypassPermissions',
+      ...(SAFE ? { allowedTools: SAFE_TOOLS } : {}),
+      systemPrompt: { type: 'preset', preset: 'claude_code', append: SYSTEM_LIVE },
+      mcpServers: {
+        flowviant: { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${token}` } },
+      },
+    },
+  });
+
+  let turnId = null;
+  let turnText = '';
+  let turnAt = null;
+  let completed = false;
+  let sawBlocker = false;
+  let blockerId = null;
+  let nudges = 0;
+  let held = false; // asked to stop — park for direction, don't nudge
+
+  const flush = async () => {
+    if (turnId && turnText.trim())
+      await mcpCall(mcpUrl, token, 'stream_turn', {
+        runId,
+        turnId,
+        text: turnText.trim(),
+        createdAt: turnAt,
+      }).catch(() => {});
+  };
+  const inject = (msgs) => {
+    afterId = msgs[msgs.length - 1].id;
+    input.push(msgs.map((f) => (f.authorName ? `${f.authorName}: ` : '') + f.content).join('\n'));
+  };
+
+  try {
+    for await (const m of session) {
+      if (!isAlive()) return { outcome: 'blocked', title, intentId };
+
+      if (m.type === 'assistant') {
+        if (!turnId) {
+          turnId = `t-${runId}-${Date.now()}`;
+          turnAt = new Date().toISOString();
+          turnText = '';
+        }
+        for (const b of m.message?.content ?? []) {
+          if (b.type === 'text' && b.text) turnText += b.text;
+          else if (b.type === 'tool_use') {
+            const n = String(b.name ?? '');
+            if (n.endsWith('complete')) completed = true;
+            else if (n.endsWith('report_blocker')) sawBlocker = true;
+          }
+        }
+        await flush();
+      } else if (m.type === 'user') {
+        // tool_result echoes — capture the blockerId report_blocker returned.
+        for (const b of m.message?.content ?? []) {
+          if (b?.type === 'tool_result') {
+            const hit = BLOCKER_ID_RE.exec(resultText(b.content));
+            if (hit) blockerId = hit[1];
+          }
+        }
+      } else if (m.type === 'result') {
+        await flush();
+        turnId = null;
+
+        if (completed) return { outcome: 'done', title, intentId };
+
+        if (sawBlocker) {
+          const res = await waitForResolution(mcpUrl, token, blockerId, isAlive);
+          if (res.status === 'resolved') {
+            input.push(`The human answered your blocker: ${JSON.stringify(res.answer)}\nApply it and continue.`);
+            sawBlocker = false;
+            blockerId = null;
+            nudges = 0;
+            continue;
+          }
+          if (res.status === 'timeout') return { outcome: 'parked', title, intentId };
+          return { outcome: 'blocked', title, intentId }; // aborted (shutdown)
+        }
+
+        // Pick up new human @-messages (this is also where a stop lands — the
+        // checkpoint model: halt at the boundary, not a hard mid-tool kill).
+        const poll = await mcpCall(mcpUrl, token, 'poll_channel', {
+          runId,
+          ...(afterId ? { afterId } : {}),
+        }).catch(() => null);
+        const fresh = (poll?.messages ?? []).filter((x) => x.role === 'user');
+
+        if (fresh.some((f) => STOP_RE.test(f.content))) {
+          if (fresh.length) afterId = fresh[fresh.length - 1].id;
+          held = true;
+          input.push('A teammate asked you to STOP. Halt, summarize where you are in one line, and wait for direction — do not continue until told.');
+          continue;
+        }
+        if (fresh.length) {
+          inject(fresh);
+          nudges = 0;
+          held = false;
+          continue;
+        }
+
+        // Held after a stop — park for the next human message; never nudge.
+        if (held) {
+          const next = await waitForMessage(mcpUrl, token, runId, afterId, isAlive);
+          if (!next) return { outcome: 'parked', title, intentId };
+          held = false;
+          nudges = 0;
+          inject([next]);
+          continue;
+        }
+
+        // Idle turn with no completion — nudge a couple of times, then stop.
+        if (nudges < 2) {
+          nudges++;
+          input.push('Continue until the task is complete: open a draft PR and call complete, or report a blocker.');
+          continue;
+        }
+        return { outcome: 'stalled', title, intentId };
+      }
+    }
+    return { outcome: completed ? 'done' : 'stalled', title, intentId };
+  } catch (e) {
+    return { outcome: 'error', error: e?.message ?? String(e), title, intentId };
+  } finally {
+    input.close();
+    try {
+      await session.interrupt?.();
+    } catch {
+      /* session already ended */
+    }
+    try {
+      await session.return?.();
+    } catch {
+      /* generator already closed */
+    }
+  }
+}
+
+// Per-agent loop — same signature/scaffolding as runFleetWorker, but each task
+// is a persistent SDK session instead of a one-shot claude turn.
+export async function runLiveWorker({
+  agentId,
+  label,
+  cwd,
+  baseRef,
+  getToken,
+  getHasWork,
+  getMcpUrl,
+  isAlive,
+  onTokenSuspect,
+}) {
+  let phase = '';
+  const enter = (p, fn, msg) => {
+    if (phase !== p) {
+      phase = p;
+      fn(`${label} ${msg}`);
+    }
+  };
+
+  // One live preview at a time — the branch of the task most recently finished,
+  // kept up while it's in review (a gated agent parks, so it lives until review
+  // resolves). Replaced when the next task finishes; torn down on shutdown.
+  let preview = null;
+  const stopPreview = () => {
+    if (preview) {
+      try {
+        preview.stop();
+      } catch {
+        /* already gone */
+      }
+      preview = null;
+    }
+  };
+  const startReviewPreview = async (intentId) => {
+    stopPreview();
+    const cfg = loadPreviewConfig(cwd);
+    const kind = cfg?.ui ? 'ui' : cfg?.api ? 'api' : null;
+    const entry = kind ? cfg[kind] : null;
+    if (!entry || !intentId) return; // no preview config → captured evidence only
+    info(`${label} ${c.dim('starting a live preview of the branch for review…')}`);
+    preview = await startPreview({
+      worktree: cwd,
+      kind,
+      cmd: entry.cmd,
+      port: entry.port,
+      log: (m) => info(`${label} ${c.dim(m)}`),
+    });
+    if (preview) {
+      await registerLiveTarget(intentId, kind, preview.url);
+      ok(`${label} ${c.dim('live preview ready — open the node to drive it in your review')}`);
+    }
+  };
+
+  while (isAlive()) {
+    const token = getToken(agentId);
+    if (!token) {
+      await sleep(IDLE_SECONDS);
+      continue;
+    }
+    if (!getHasWork(agentId)) {
+      enter('idle', info, 'idle — no work assigned');
+      await sleep(IDLE_SECONDS);
+      continue;
+    }
+    let res;
+    try {
+      res = await runLiveTask({ mcpUrl: getMcpUrl() ?? MCP_URL, token, cwd, baseRef, isAlive });
+    } catch (e) {
+      enter('error', warn, `${c.yellow('error')} ${c.dim(`— ${e?.message ?? e}`)}`);
+      await sleep(IDLE_SECONDS);
+      continue;
+    }
+    if (!isAlive()) break;
+    if (res.outcome === 'nothing') {
+      enter('idle', info, 'idle — no work assigned');
+      await sleep(IDLE_SECONDS);
+      continue;
+    }
+    if (res.outcome === 'done') {
+      ok(`${label} ${c.dim(`finished "${res.title}" — PR opened for your review`)}`);
+      phase = '';
+      await startReviewPreview(res.intentId);
+      continue;
+    }
+    if (res.outcome === 'parked') {
+      // Idle-parked too long on a blocker: we freed the Claude process. The intent
+      // stays claimed; a later poll re-claims + resumes (with transcript) once the
+      // human answers. Idle, don't hard-stop the worker.
+      enter('parked', info, `${c.dim('parked — freed the session; resumes when you answer in Flowviant')}`);
+      await sleep(IDLE_SECONDS);
+      continue;
+    }
+    if (res.outcome === 'blocked') {
+      // Only reached on shutdown mid-park; the intent stays claimed and resumes
+      // on reconnect. Nothing to do but stop cleanly.
+      break;
+    }
+    // stalled / error — usually a stale token or a stuck turn. Refresh + retry.
+    enter('reconnect', warn, `${c.yellow(res.outcome)} ${c.dim('— refreshing token, retrying')}`);
+    onTokenSuspect?.(agentId);
+    phase = '';
+    await sleep(IDLE_SECONDS);
+  }
+  stopPreview();
+  info(`${label} stopped`);
+}

package/bin/lib/login.mjs

@@ -0,0 +1,84 @@
+/**
+ * `flowviant login` — device-auth, like `gh auth login`. Removes the
+ * paste-a-secret-into-your-shell friction: the daemon shows a short code, you
+ * approve it in Flowviant (in a project), and the freshly-minted fleet
+ * credential is stored locally at ~/.flowviant/credentials.json. After that,
+ * plain `flowviant` just runs — no token, no env var.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { FLEET_URL, USER_AGENT, VERSION } from './config.mjs';
+import { c, info, ok, warn, fail } from './ui.mjs';
+import { sleep } from './claude.mjs';
+
+const CRED_DIR = join(homedir(), '.flowviant');
+const CRED_FILE = join(CRED_DIR, 'credentials.json');
+const DEVICE_START = FLEET_URL.replace(/\/agents\/?$/, '/device/start');
+const DEVICE_POLL = FLEET_URL.replace(/\/agents\/?$/, '/device/poll');
+const APP_URL = process.env.FLOWVIANT_APP_URL || 'https://app.flowviant.com';
+
+/** The locally-stored credential from a prior `login`, or null. Read by config. */
+export function readStoredCredential() {
+  try {
+    return JSON.parse(readFileSync(CRED_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function store(cred) {
+  mkdirSync(CRED_DIR, { recursive: true });
+  writeFileSync(CRED_FILE, JSON.stringify(cred, null, 2), { mode: 0o600 });
+}
+
+async function post(url, body) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const j = await res.json();
+  return j.data ?? j;
+}
+
+export async function runLogin() {
+  console.log(`\n  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`login · v${VERSION}`)}\n`);
+  let start;
+  try {
+    start = await post(DEVICE_START, {});
+  } catch (e) {
+    fail(`couldn't reach Flowviant (${e.message}).`);
+    process.exit(1);
+  }
+  const { deviceCode, userCode, intervalSeconds = 5, expiresInSeconds = 600 } = start;
+  const pretty = `${userCode.slice(0, 4)}-${userCode.slice(4)}`;
+  console.log(`  1. Open ${c.cyan(APP_URL)} → your project → the ${c.bold('Agents')} panel → ${c.bold('Connect a machine')}.`);
+  console.log(`  2. Enter this code:   ${c.bold(c.green(pretty))}\n`);
+  info('waiting for you to approve…');
+
+  const deadline = Date.now() + expiresInSeconds * 1000;
+  while (Date.now() < deadline) {
+    await sleep(intervalSeconds);
+    let poll;
+    try {
+      poll = await post(DEVICE_POLL, { deviceCode });
+    } catch {
+      continue; // transient — keep polling
+    }
+    if (poll.status === 'approved') {
+      store({ fleetToken: poll.fleetToken, projectId: poll.projectId, mcpUrl: poll.mcpUrl });
+      ok('connected — credential saved to ~/.flowviant/credentials.json');
+      console.log(`\n  Now just run:  ${c.bold('npx flowviant')}\n`);
+      return;
+    }
+    if (poll.status === 'expired') {
+      warn('that code expired — run `flowviant login` again.');
+      process.exit(1);
+    }
+  }
+  warn('login timed out — run `flowviant login` again.');
+  process.exit(1);
+}

package/bin/lib/preflight.mjs

@@ -0,0 +1,49 @@
+/**
+ * Startup preflight: this tool DRIVES your local CLIs (it never sees their
+ * credentials), so it checks they're present + signed in and tells you exactly
+ * what's missing, rather than failing cryptically mid-run.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { ok, warn, info, c } from './ui.mjs';
+
+function present(cmd) {
+  try {
+    execFileSync(cmd, ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ghAuthed() {
+  try {
+    execFileSync('gh', ['auth', 'status'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Prints a checklist. Returns false only if a *fatal* prereq (claude, or git
+ *  when worktrees are used) is missing — callers may warn-and-continue. */
+export function preflight({ needGit = true } = {}) {
+  const claude = present('claude');
+  const gh = present('gh');
+  const node18 = Number(process.versions.node.split('.')[0]) >= 18;
+  const git = needGit ? present('git') : true;
+
+  info('checking your setup (this tool drives these — it never sees their logins):');
+  claude
+    ? ok(`claude installed ${c.dim('· must be signed in — run `claude` once if you haven’t')}`)
+    : warn('claude NOT found — install Claude Code: https://claude.com/claude-code');
+  gh && ghAuthed()
+    ? ok('gh authenticated')
+    : warn(gh ? 'gh not signed in — run: gh auth login' : 'gh NOT found — install it + run: gh auth login (needed to open PRs)');
+  if (needGit) (git ? ok('git installed') : warn('git NOT found — install git'));
+  node18 ? ok(`node ${process.versions.node}`) : warn(`node ${process.versions.node} — need 18+`);
+  console.log('');
+
+  if (!claude) warn('Without `claude` nothing can run — install + sign in, then restart.');
+  return claude && git;
+}