flowviant 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flowviant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# flowviant
+
+Run your own [Claude Code](https://claude.com/claude-code) as headless build agents for [Flowviant](https://flowviant.com). You manage a team of agents in the app; this daemon runs them on your machine, on your own credentials — Flowviant never sees your Claude or GitHub logins.
+
+```bash
+npx flowviant login      # approve the code in Flowviant → connected
+npx flowviant            # run your fleet
+```
+
+## What it does
+
+You create named agents in Flowviant and dispatch work to them. This daemon, running on a machine you control, gives each agent its own git worktree and drives **your** locally-authenticated `claude` to do the work — it claims a task, works it, captures evidence for each acceptance criterion, opens a pull request, and routes any question it can't answer back to you as a blocker. You review and merge in the app.
+
+Because it drives the CLIs you're already logged into, **the cost is yours** (your Claude subscription, your GitHub) and **the daemon never handles a credential** — it shells out to tools you authenticated yourself.
+
+## Requirements
+
+On the machine that runs the daemon:
+
+- **[Claude Code](https://claude.com/claude-code)** installed and signed in (`claude`)
+- **[GitHub CLI](https://cli.github.com)** authenticated (`gh auth login`) — for opening PRs
+- **git**, and **Node 20+**
+- run it from inside the git repository you want worked
+
+## Connecting
+
+The easy way — device login, like `gh auth login`:
+
+```bash
+npx flowviant login
+```
+
+It shows a short code; enter it in Flowviant under **Agents → Connect a machine**. The credential is stored at `~/.flowviant/credentials.json`, and from then on `npx flowviant` just runs.
+
+Prefer an explicit token? Create a fleet credential in the app and pass it directly:
+
+```bash
+FLOWVIANT_FLEET=fva_… npx flowviant
+```
+
+## Live mode (opt-in)
+
+```bash
+FLOWVIANT_LIVE=1 npx flowviant
+```
+
+Each task runs a **persistent** Claude session you can talk to mid-task from the app: the agent streams its work into the task's conversation, you `@`-mention it to steer or answer questions, and it resumes in place. Blockers park the session at zero cost until you answer.
+
+### Live previews
+
+For UI/API tasks, the daemon can start the branch's dev server in the agent's worktree and open a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) quick tunnel so you can drive the real running change during review — no Cloudflare account needed (it's auto-fetched if missing). Configure it once per repo, or let it infer common setups:
+
+```json
+// .flowviant/preview.json
+{ "ui": { "cmd": "npm run dev", "port": 5173 } }
+```
+
+Flowviant only stores the tunnel URL; your browser talks to it directly.
+
+## Modes
+
+| Env | What runs |
+| --- | --- |
+| _(stored login)_ or `FLOWVIANT_FLEET` | **Fleet daemon** — one worktree + worker per agent on your roster, managed in the app |
+| `FLOWVIANT_TOKEN` | a single agent in the current checkout |
+| `FLOWVIANT_TOKENS=a,b,c` | a static fleet, one worktree each |
+| `FLOWVIANT_SAFE=1` | restrict the toolset instead of running unattended |
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/cli.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * flowviant — run your own Claude Code as headless Flowviant build agents.
+ *
+ * Three modes, picked by which env var is set:
+ *
+ *   FLOWVIANT_TOKEN=fva_…   npx flowviant        # 1 worker, current checkout
+ *   FLOWVIANT_TOKENS=a,b,c  npx flowviant        # static fleet, 1 worktree each
+ *   FLOWVIANT_FLEET=fft_…   npx flowviant        # FLEET DAEMON (recommended)
+ *
+ * Fleet daemon: install ONCE with a fleet credential, then manage everything
+ * from Flowviant. The daemon polls GET /api/v2/fleet/agents, reconciles one
+ * persistent git worktree + worker loop per roster agent, rotates each worker's
+ * short-lived MCP token, and only spawns Claude when an agent has work. Add/remove
+ * agents in the app — the daemon picks up the change on its next poll. Each worker
+ * claims its work, resets its worktree to base per task (fresh Claude conversation),
+ * opens one PR per intent, and routes questions back as blockers.
+ *
+ * Env:
+ *   FLOWVIANT_TOKEN / FLOWVIANT_TOKENS / FLOWVIANT_FLEET  (one of) credentials.
+ *   FLOWVIANT_API_URL   default https://api.flowviant.com/api/v2
+ *   FLOWVIANT_MCP_URL   default <API_URL>/mcp
+ *   FLOWVIANT_FLEET_URL default <API_URL>/fleet/agents
+ *   POLL_SECONDS        gap between turns while waiting on a blocker (default 20)
+ *   IDLE_SECONDS        gap between work checks when idle (default 30)
+ *   RECONCILE_SECONDS   fleet roster poll cadence (default 10)
+ *   FLOWVIANT_SAFE=1    restrict the toolset instead of running unattended.
+ *
+ * Requires the `claude` CLI (and `gh` for PRs) on PATH; run from inside the git
+ * repo you want worked. Fleet & static-fleet modes also require `git`.
+ *
+ * Implementation lives in ./lib/: config, ui, claude, git, fleet, single.
+ */
+import { FLEET_TOKEN, tokens, SAFE, MCP_URL } from './lib/config.mjs';
+import { runFleetDaemon } from './lib/fleet.mjs';
+import { runWorker, runStaticFleet } from './lib/single.mjs';
+import { runLogin } from './lib/login.mjs';
+import { preflight } from './lib/preflight.mjs';
+
+// `flowviant login` — device auth (recommended): approve a code in the
+// app, the credential is stored locally, then plain `flowviant` just runs.
+if (process.argv[2] === 'login') {
+  await runLogin();
+  process.exit(0);
+}
+
+if (!FLEET_TOKEN && tokens.length === 0) {
+  console.error(
+    'error: no credential found. Easiest:\n' +
+      '  flowviant login      (approve in the app — recommended)\n' +
+      'Or set one of:\n' +
+      '  FLOWVIANT_FLEET=fva_…   (fleet token, manage agents in Flowviant)\n' +
+      '  FLOWVIANT_TOKEN=fva_…   (one agent, current checkout)\n' +
+      '  FLOWVIANT_TOKENS=a,b,…  (static fleet)'
+  );
+  process.exit(1);
+}
+
+async function main() {
+  if (FLEET_TOKEN) {
+    await runFleetDaemon();
+    return;
+  }
+  console.log(
+    SAFE
+      ? '» safe mode: restricted toolset (unset FLOWVIANT_SAFE for full autonomy).'
+      : '» unattended mode: permission prompts skipped so the agent runs hands-off.'
+  );
+  preflight({ needGit: tokens.length > 1 });
+  if (tokens.length === 1) {
+    console.log(`» flowviant → ${MCP_URL}  (1 worker · token fva_…${tokens[0].slice(-4)})`);
+    await runWorker({ token: tokens[0], cwd: process.cwd(), label: '' });
+    return;
+  }
+  await runStaticFleet();
+}
+
+await main();

package/bin/lib/claude.mjs

@@ -0,0 +1,151 @@
+/**
+ * Driving Claude Code: the operating-contract system prompts, the permission
+ * posture, and one `claude -p` turn. The hard rule baked into both prompts:
+ * there is no interactive user — the only channel to a human is the blocker loop.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SAFE } from './config.mjs';
+
+// Multi-task loop (TOKEN / TOKENS modes): drain the whole queue in one session.
+export const SYSTEM_MULTI = `You are a Flowviant build agent running FULLY AUTONOMOUSLY via the "flowviant" MCP
+server. There is NO interactive user and NO terminal to ask in. The ONLY way to
+reach a human is the blocker loop. Never ask the user directly; never wait on stdin.
+
+Operate this loop:
+1. Call claim_next_intent. If it returns claimed:false, output exactly ALL_CLEAR on
+   its own line and stop.
+2. Read the brief. If it has an existing "branch" (a REVISION the human bounced back),
+   \`git checkout <branch>\` to resume your prior work and address the review feedback in
+   the description (under "— Review feedback —"). Use get_module_files / search_wiki /
+   list_related_intents for context. Call report_progress as you go.
+3. If you hit ANYTHING only a human can decide, call report_blocker with a clear
+   question (and options when you can), then call get_blocker_resolution. If it is
+   not yet resolved, output exactly BLOCKED:<blockerId> on its own line and STOP.
+4. Before finishing: for EACH acceptance criterion, call attach_evidence with concrete
+   proof it is met. This is what the human reviews instead of the diff.
+5. Ship: on a revision, \`git push\` to the SAME existing branch (the PR updates in place)
+   and re-call attach_pr with that PR URL; otherwise open ONE draft PR (git push +
+   \`gh pr create --draft\`) and call attach_pr. Then complete. NEVER merge — the human
+   approves the PR in Flowviant.
+6. Return to step 1.
+
+Keep every change scoped to the claimed intent. If a tool errors, report_progress with
+the error, then retry or report_blocker.`;
+
+// Single-task turn (FLEET mode): claim EXACTLY ONE intent, then stop. The daemon
+// owns the loop so it can reset the worktree + start a fresh conversation per task.
+export const SYSTEM_SINGLE = `You are a Flowviant build agent running FULLY AUTONOMOUSLY via the "flowviant" MCP
+server. There is NO interactive user and NO terminal to ask in. The ONLY way to
+reach a human is the blocker loop. Never ask the user directly; never wait on stdin.
+
+Do EXACTLY ONE task this turn:
+1. Call claim_next_intent. If it returns claimed:false, output exactly NOTHING on its
+   own line and stop. Do NOT retry.
+2. Read the brief. If it has an existing "branch" (a REVISION the human bounced back),
+   first \`git fetch && git checkout <branch>\` to resume YOUR prior work, and address
+   the review feedback in the description (under "— Review feedback —"). Otherwise work
+   from the clean base checkout. Use get_module_files / search_wiki /
+   list_related_intents for context. report_progress as you go.
+3. If you hit ANYTHING only a human can decide, call report_blocker (with options when
+   you can), then get_blocker_resolution. If unresolved, output exactly
+   BLOCKED:<blockerId> on its own line and STOP. Do NOT guess past a real decision.
+4. Before finishing: for EACH acceptance criterion call attach_evidence with concrete
+   proof it is met.
+5. Ship: if this is a revision, \`git push\` to the SAME existing branch (the open PR
+   updates in place) and re-call attach_pr with that same PR URL. Otherwise open ONE
+   draft PR (git push + \`gh pr create --draft\`) and call attach_pr. Then complete.
+   NEVER merge. Then output exactly DONE on its own line and stop.
+
+Do NOT claim a second intent — exactly one per turn. Keep every change scoped to the
+claimed intent. If a tool errors, report_progress with the error, then retry or
+report_blocker.`;
+
+export const KICKOFF =
+  'Begin the loop: claim and complete all dispatched Flowviant intents per your instructions.';
+export const RESUME =
+  'Resume. First call get_blocker_resolution for any blocker you reported; if resolved, ' +
+  'apply the human’s answer and continue. Otherwise keep claiming and completing ' +
+  'dispatched intents per your instructions.';
+export const SINGLE_KICKOFF =
+  'Claim and complete exactly ONE dispatched Flowviant intent per your instructions, then stop.';
+export const SINGLE_RESUME =
+  'Resume your current task. Call get_blocker_resolution for the blocker you reported; ' +
+  'if resolved, apply the human’s answer and finish this one intent, then stop.';
+
+// Unattended (default) skips prompts so the agent never stalls with no terminal;
+// FLOWVIANT_SAFE=1 restricts to a curated toolset instead.
+const PERM = SAFE
+  ? [
+      '--allowedTools',
+      'mcp__flowviant',
+      'Edit',
+      'Write',
+      'Read',
+      'Grep',
+      'Glob',
+      'Bash(git:*)',
+      'Bash(gh:*)',
+      'Bash(npm:*)',
+      'Bash(bun:*)',
+    ]
+  : ['--dangerously-skip-permissions'];
+
+export const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
+
+// Sentinels must appear on their OWN line (the prompts require it). Substring
+// matching falsely fired when an agent merely *mentioned* the word in prose
+// (e.g. "I won't fabricate a BLOCKED:<id> line"), trapping the worker in a fake
+// blocked loop. Anchor to a full line instead.
+export const sawSentinel = (out, name) => new RegExp(`^\\s*${name}\\s*$`, 'm').test(out);
+export const blockedId = (out) => {
+  const m = out.match(/^\s*BLOCKED:(\S+)\s*$/m);
+  return m ? m[1] : null;
+};
+
+export function mcpConfigFor(token, mcpUrl) {
+  const dir = mkdtempSync(join(tmpdir(), 'flowviant-'));
+  const p = join(dir, 'mcp.json');
+  writeFileSync(
+    p,
+    JSON.stringify({
+      mcpServers: {
+        flowviant: { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${token}` } },
+      },
+    })
+  );
+  return { dir, path: p };
+}
+
+// One Claude Code turn. Output is captured (for sentinel detection) and streamed
+// through, line-prefixed with the worker label so a fleet stays legible.
+export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn }) {
+  return new Promise((resolve) => {
+    const args = [];
+    if (resume) args.push('--continue');
+    args.push('-p', prompt, '--mcp-config', mcpConfig, '--append-system-prompt', system, ...PERM);
+    const child = spawn('claude', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    onSpawn?.(child);
+    let out = '';
+    const pfx = label ? `${label} ` : '';
+    const onChunk = (d) => {
+      const s = d.toString();
+      out += s;
+      process.stdout.write(pfx ? s.replace(/\n/g, `\n${pfx}`) : s);
+    };
+    child.stdout.on('data', onChunk);
+    child.stderr.on('data', onChunk);
+    child.on('error', (e) => {
+      if (e.code === 'ENOENT') {
+        console.error("\nerror: 'claude' CLI not found on PATH. Install Claude Code first.");
+        process.exit(1);
+      }
+      console.error(e);
+      resolve(out);
+    });
+    child.on('close', () => resolve(out));
+  });
+}

package/bin/lib/config.mjs

@@ -0,0 +1,55 @@
+/** Parsed configuration: env vars, CLI flags, and the chosen credentials. */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const VERSION = '0.6.0';
+
+// Credential stored by `flowviant login` (device auth) — the no-token,
+// no-env-var path. An explicit --fleet flag or FLOWVIANT_FLEET env still wins.
+function readStoredCredential() {
+  try {
+    return JSON.parse(readFileSync(join(homedir(), '.flowviant', 'credentials.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+const stored = readStoredCredential();
+
+function argFlag(name) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+}
+
+const API_BASE = process.env.FLOWVIANT_API_URL || 'https://api.flowviant.com/api/v2';
+export const MCP_URL = process.env.FLOWVIANT_MCP_URL || `${API_BASE}/mcp`;
+export const FLEET_URL = process.env.FLOWVIANT_FLEET_URL || `${API_BASE}/fleet/agents`;
+export const POLL_SECONDS = Number(process.env.POLL_SECONDS || 20);
+export const IDLE_SECONDS = Number(process.env.IDLE_SECONDS || 30);
+// Live mode: after this long idle-parked on a blocker, tear the session down to
+// free the Claude process (the intent stays claimed; it resumes when answered).
+export const PARK_TIMEOUT_SECONDS = Number(process.env.PARK_TIMEOUT_SECONDS || 900);
+export const RECONCILE_SECONDS = Number(process.env.RECONCILE_SECONDS || 10);
+// Proactively refresh a worker token this many seconds before its lease lapses,
+// so a long-lived daemon never silently 401s on an expired token.
+export const REFRESH_BEFORE_SECONDS = Number(process.env.REFRESH_BEFORE_SECONDS || 3600);
+export const SAFE = process.env.FLOWVIANT_SAFE === '1';
+// Opt-in phase-2 live mode: persistent Agent-SDK session per task (streams into
+// the task channel, injectable, blocker-parks in place) instead of one-shot
+// `claude -p` turns. Off = the proven poll/sentinel path, untouched.
+export const LIVE = process.env.FLOWVIANT_LIVE === '1';
+// Sent on the daemon's own HTTP calls so Cloudflare Bot Fight Mode doesn't 403
+// them (Node's default UA is treated as a bot). Claude Code sends its own UA.
+export const USER_AGENT = `flowviant/${VERSION}`;
+
+// One of: a fleet credential (recommended), one worker token, or a comma list.
+export const FLEET_TOKEN =
+  argFlag('--fleet') || process.env.FLOWVIANT_FLEET || stored?.fleetToken || '';
+const rawTokens =
+  argFlag('--tokens') ||
+  process.env.FLOWVIANT_TOKENS ||
+  argFlag('--token') ||
+  process.env.FLOWVIANT_TOKEN ||
+  '';
+export const tokens = rawTokens.split(',').map((t) => t.trim()).filter(Boolean);