flowviant 0.103.0 → 0.104.0

package/bin/lib/runtimeCodex.mjs

@@ -0,0 +1,217 @@
+/**
+ * CODEX, AS A RUNTIME — its registry row: argv per profile (the kernel
+ * sandbox postures), efforts, the env-carried MCP token, and its parser.
+ *
+ * Split out of runtimes.mjs (2026-09-26, SOLID F045). Each vendor's argv moves
+ * on its own vendor's release schedule; the registry (runtimes.mjs) assembles
+ * the rows and owns the rule that reads them, and the JSONL parser this row
+ * hands out as `parse` lives with the other stream parsers in
+ * runtimeEvents.mjs.
+ */
+
+import { SAFE } from './config.mjs';
+import { parseCodexLine } from './runtimeEvents.mjs';
+
+function codexMcp(token, mcpUrl) {
+  return {
+    dir: null, // nothing written — the token rides in the environment
+    args: [
+      '-c',
+      `mcp_servers.flowviant.url="${mcpUrl}"`,
+      '-c',
+      'mcp_servers.flowviant.bearer_token_env_var="FLOWVIANT_MCP_TOKEN"',
+    ],
+    env: { FLOWVIANT_MCP_TOKEN: token },
+  };
+}
+
+export const CODEX_RUNTIME = {
+  id: 'codex',
+  label: 'Codex',
+  vendor: 'OpenAI',
+  bin: 'codex',
+  install: 'npm i -g @openai/codex',
+  login: 'codex login',
+  live: false,
+  /**
+   * BUILD AND CONSULT. See `args()` below for how consult is expressed — the
+   * short version is that Codex keeps the promise at the kernel rather than in
+   * a verb allowlist, and for a consult's actual threat (exfiltration driven
+   * by an injected question) that is sufficient and arguably stronger.
+   *
+   * ALL THREE, and `wiki` is the one worth pausing on: Codex expresses it
+   * MORE strictly than Claude does. A cartographer must read the repo and
+   * write only the vault; Claude's WIKI_PERM cannot path-scope Write and says
+   * so, leaning on the worktree reset as a backstop. Codex's permission
+   * profiles enforce the same rule in the kernel — measured: repo readable,
+   * vault writable, repo writes refused, network off.
+   *
+   * Enforcement was verified on Linux (bubblewrap + seccomp). macOS Seatbelt
+   * and Windows are UNTESTED; if this daemon starts running there, re-verify
+   * before trusting the consult posture on those platforms.
+   */
+  profiles: ['build', 'consult', 'wiki', 'plan'],
+  /** `model_reasoning_effort` tops out at `xhigh` — there is no `max`, and a
+   *  queued or skewed job naming it would be an argument Codex refuses. */
+  efforts: ['low', 'medium', 'high', 'xhigh'],
+  mcp: codexMcp,
+  /**
+   * Codex has NO system-prompt flag. The contract therefore rides inside the
+   * prompt, fenced and placed first, and this is a genuine weakening worth
+   * stating plainly: a system prompt is a rule, and a prompt preamble is a
+   * strong suggestion the model may drift from over a long turn. It is the
+   * best available; AGENTS.md was the alternative and is worse, because it is
+   * a FILE IN THE WORKTREE — one `git add -A` from being committed into the
+   * user's repository, which is not a risk worth taking for a slightly
+   * stickier instruction.
+   *
+   * Agent turns additionally pass reviewed base instructions as a developer
+   * config override when the personal config has no developer instruction;
+   * the prompt always carries them too. Workbench tabs keep their normal
+   * checkout discovery.
+   *
+   * `--skip-git-repo-check` is deliberately NOT passed: a task always builds
+   * in a git worktree, and if it somehow is not one, failing loudly beats
+   * silently editing files nobody can diff.
+   *
+   * THE PROMPT IS LAST, and that is load-bearing rather than tidy. Codex takes
+   * it as a trailing POSITIONAL, so every flag — including the two `-c` MCP
+   * overrides, which the caller hands in rather than appending — has to be
+   * placed before it. Appending them after the positional is the kind of argv
+   * that parses today and stops parsing on some future clap upgrade.
+   */
+  args({ prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools }) {
+    // Adoption resumes a conversation in ITS OWN CLI's store (claude forks,
+    // agy moves) — codex has no adoptable store wired yet. Reaching here
+    // with an adopt id is a wiring mistake upstream, and it fails loudly on
+    // purpose: quietly dropping the flag would answer that session's held
+    // context with a different brain.
+    if (adoptResumeId) throw new Error("codex has no adoptable terminal store — an adopt id can't reach this builder");
+    const a = ['exec'];
+    // BY ID when the caller knows WHICH conversation this is — a Workbench
+    // tab's held context, captured off thread.started and stored with its
+    // worktree. `--last` resumes the machine's most recent codex conversation,
+    // which is only safe on the dispatch path (one lane, one turn at a time,
+    // in its own worktree); for a session it is a machine-global guess that
+    // two tabs — or a tab plus a dispatch — would cross-resume.
+    if (resumeThreadId) a.push('resume', resumeThreadId);
+    else if (resume) a.push('resume', '--last');
+    a.push('--json');
+    if (agentTools) {
+      a.push('-c', 'project_doc_max_bytes=0');
+      // A person's existing developer instructions keep their authority.
+      // The base snapshot is also present in the per-turn prompt preamble.
+      if (!agentTools.personalDeveloperInstructions)
+        a.push('-c', `developer_instructions=${JSON.stringify(agentTools.instructions)}`);
+    }
+    if (model) a.push('--model', model);
+    // Effort is a config value on Codex rather than a flag.
+    if (effort) a.push('-c', `model_reasoning_effort="${effort}"`);
+
+    if (profile === 'consult') {
+      // A CONSULT, EXPRESSED THE ONLY WAY CODEX CAN EXPRESS IT — and it is a
+      // different shape from Claude's, which is the whole reason `profile` is
+      // a promise rather than a flag list.
+      //
+      // Claude gets a VERB allowlist: Read, Grep, Glob and a handful of
+      // read-only Bash forms, with nothing that reaches the network. Codex has
+      // no such thing — it has no file-read tool at all, so reading the repo
+      // IS command execution (`cat`, `rg`). Removing the shell leaves the
+      // model with exactly ["update_plan","request_user_input"], which cannot
+      // answer a question about a codebase. You get both capabilities or
+      // neither.
+      //
+      // So the promise is kept one layer down instead. `read-only` is
+      // kernel-enforced (bubblewrap + seccomp on Linux): writes fail, and a
+      // direct-IP connect fails with "Operation not permitted" — socket() is
+      // denied, not merely DNS. An injected command still RUNS and still
+      // cannot take the repository anywhere, which is the threat a consult
+      // actually has: its prompt is steered by a question any project editor
+      // can type. Arguably a stronger guarantee than the allowlist, being
+      // below the agent rather than inside it.
+      a.push('--sandbox', 'read-only');
+
+      // THE HOLE THE SANDBOX DOES NOT COVER. `web_search` ships in `codex
+      // exec`'s default tool list even without --search, and it executes
+      // SERVER-SIDE at OpenAI — no local sandbox touches it. An injected turn
+      // could pack repo contents into a query and egress them straight past
+      // everything above. Both spellings, because the two config systems
+      // disagree about which one is live.
+      a.push('-c', 'tools.web_search=false', '-c', 'web_search="disabled"');
+
+      // Sub-agents would be a second turn whose posture nobody here chose.
+      a.push('-c', 'features.multi_agent=false', '-c', 'features.goals=false');
+
+      // HERMETIC. Without these a user's ~/.codex/config.toml, a project
+      // `.rules` execpolicy file, or their own MCP servers can widen a posture
+      // we are asserting on their behalf — silently, and on the one turn whose
+      // prompt comes from someone else's typing.
+      a.push('--ignore-user-config', '--ignore-rules');
+    } else if (profile === 'plan') {
+      // A PLANNING SESSION. Read-only on the filesystem, exactly like a
+      // consult — the writes it makes go through the control plane, not
+      // through this box — so the kernel sandbox is the same one, and for the
+      // same reason: this turn's prompt is steered by anything a project
+      // editor can type.
+      //
+      // Everything the consult branch above closes stays closed, and the
+      // reasoning is unchanged, so it is not restated: web_search egresses
+      // server-side at OpenAI where no local sandbox reaches it, sub-agents
+      // would be a turn whose posture nobody here chose, and a user's own
+      // config or MCP servers must not widen a posture we are asserting on
+      // their behalf.
+      //
+      // What differs from a consult is the ONE thing this profile exists for:
+      // an MCP config IS passed, carrying the plan principal's token. That
+      // token's whole tool set is the five plan tools — the server refuses
+      // anything else on it — so the control plane being open here does not
+      // widen what a hijacked turn could reach beyond the plan it is already
+      // sitting in.
+      a.push('--sandbox', 'read-only');
+      a.push('-c', 'tools.web_search=false', '-c', 'web_search="disabled"');
+      a.push('-c', 'features.multi_agent=false', '-c', 'features.goals=false');
+      a.push('--ignore-user-config', '--ignore-rules');
+    } else if (profile === 'wiki' && vaultDir) {
+      // THE CARTOGRAPHER, AND THIS ONE IS STRICTER THAN CLAUDE'S.
+      //
+      // A wiki turn reads the whole repo and writes ONLY the vault. Claude
+      // cannot actually express that: WIKI_PERM hands it Write/Edit and its own
+      // comment admits "Write/Edit can't be path-scoped here; the worktree
+      // reset is the backstop" — i.e. the cartographer CAN scribble on the
+      // checkout and we clean up afterwards.
+      //
+      // Codex's permission profiles take a per-path filesystem map, so the
+      // rule is enforced by the kernel instead of apologised for. Measured:
+      // repo readable, vault writable, repo writes fail "Read-only file
+      // system", and curl returns 000 — the network is off, which is the half
+      // WIKI_PERM was really protecting (its comment: "Command execution is
+      // the line: it enables network exfil").
+      //
+      // The table is set WHOLE rather than as a dotted key, and that is not
+      // style: `-c permissions.wiki.filesystem."<path>"="write"` splits the
+      // dotted path on the dots INSIDE the path, and every real vault lives
+      // under `~/.flowviant/vaults/…`. It fails with "filesystem path must be
+      // absolute", which reads like a path problem and is a parsing one.
+      a.push('-c', 'permissions.flowviantwiki.extends=":read-only"');
+      a.push('-c', `permissions.flowviantwiki.filesystem={"${vaultDir}"="write"}`);
+      a.push('-P', 'flowviantwiki');
+      a.push('--ignore-user-config', '--ignore-rules');
+    } else {
+      // The daemon's build posture, mapped: SAFE keeps writes inside the
+      // workspace, the default lets the agent run its own tests and git
+      // commands. Neither asks a human — there is no human on this end of the
+      // pipe. Deliberately NOT hermetic: a build is work the user asked for by
+      // @mentioning this CLI, and their own config is theirs to apply.
+      a.push('--sandbox', SAFE ? 'workspace-write' : 'danger-full-access');
+    }
+
+    a.push(...mcp, ...resultSchemaArgs);
+    a.push(`${system}\n\n---\n\n${prompt}`);
+    return a;
+  },
+  parse: parseCodexLine,
+  /** `codex exec --output-schema <file>` constrains the FINAL message to a
+   *  JSON Schema. Only needed on the mediated path; the direct path reports
+   *  through MCP tool calls, which are already structured. */
+  resultSchema: (path) => ['--output-schema', path],
+};

package/bin/lib/runtimeDetection.mjs

@@ -0,0 +1,121 @@
+/**
+ * WHAT THIS MACHINE HAS — which declared CLIs are installed here, and, of
+ * those, which one runs a job nobody @mentioned.
+ *
+ * Split out of runtimes.mjs (2026-09-26, SOLID F045). The registry is a
+ * statement about the CLIs (their argv, their profiles); this file is a
+ * measurement of the box (a `--version` exec per CLI, cached with a TTL), and a
+ * probe changing is not a reason to edit a table of argv builders.
+ *
+ * `pickRuntimeFor` lives HERE rather than beside `canRun` because it is the one
+ * reader that joins the registry's promise with this box's measurement: the
+ * registry imports nothing machine-stateful, so the dependency runs one way
+ * (this file → runtimes.mjs) and never in a cycle.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { RUNTIMES, canRun, drivableHere } from './runtimes.mjs';
+
+/**
+ * WHICH RUNTIME RUNS A JOB THAT NOBODY @MENTIONED.
+ *
+ * Building a task has an author: you @mentioned a CLI, and that is the only
+ * dispatch in this product. The other turns have none — the wiki sweep, the
+ * re-ground, the plan check, the quick edit and the consult are all started by
+ * the daemon or the server, and until now every one of them took `runTurn`'s
+ * default parameter value and ran Claude. That was not a decision; it was five
+ * call sites omitting an argument, and it only looked correct while Claude was
+ * the only runtime and preflight refused to start without it.
+ *
+ * A PROFILE is a promise about what is IMPOSSIBLE during the turn, not a flag
+ * list — flag lists are per-vendor, promises are not, and the goal is that every
+ * runtime behaves the same way predictably. A runtime declares the profiles it
+ * can actually express; one that cannot express a profile does not get that job,
+ * rather than getting it with weaker guarantees nobody wrote down.
+ *
+ * Claude first when it qualifies — not favouritism, and worth saying plainly:
+ * these prompts were written and tuned against it, so it is the known-good
+ * answer and anything else is a substitution. When it is absent, any runtime
+ * that can express the profile runs the job, which is the whole point.
+ */
+export function pickRuntimeFor(profile, { detected } = {}) {
+  const rows = detected ?? detectRuntimes();
+  const ok = (id) =>
+    canRun(RUNTIMES[id], profile) && Boolean(rows.find((d) => d.id === id)?.installed);
+  if (ok('claude')) return 'claude';
+  return Object.keys(RUNTIMES).find(ok) ?? null;
+}
+
+/**
+ * Which of these is on this machine, asked at most once per DETECT_TTL_MS.
+ *
+ * `--version` rather than `which`: a binary on PATH that cannot execute (a
+ * broken install, a wrong-arch download, a shell alias pointing at nothing) is
+ * not a runtime you can dispatch to, and reporting it as one sends work into a
+ * hole. 5s is generous for a version print and short enough that three missing
+ * CLIs cannot stall a roster poll.
+ *
+ * Reported to the server on the roster poll so the app can stop saying "we have
+ * not looked". It is a statement about THIS MACHINE and nothing else — no
+ * account, no quota, no entitlement. Flowviant relays; it does not enforce.
+ */
+let detectedCache = null;
+let detectedAt = 0;
+// The cache EXPIRES rather than living for the process: pickRuntimeFor's whole
+// premise is "a CLI can be installed while the daemon runs", and both it and
+// the roster poll read this cache — a forever-cache made that comment a lie
+// (nothing after preflight ever passed refresh, so a mid-run install was
+// invisible until restart, to the server included). 5 minutes keeps the probes
+// (3 sync --version execs) off the hot path while an install still surfaces on
+// the next poll or job.
+const DETECT_TTL_MS = 5 * 60 * 1000;
+/**
+ * THE POLL'S `runtimes` VALUE — the CLIs this machine can drive, comma-joined,
+ * and '' when a detection that RAN found none (2026-09-26, SOLID F015).
+ *
+ * Three states on the wire, like `skills`: absent = nothing was measured (an
+ * older daemon, or a detection that threw); '' = measured, and none; a list =
+ * measured. Omitting the param after an empty detection — the old spelling —
+ * read as "said nothing", so the server kept advertising the last CLI a
+ * machine lost.
+ */
+export function runtimesReport(detected) {
+  return detected
+    .filter((r) => r.dispatchable)
+    .map((r) => r.id)
+    .join(',');
+}
+
+export function detectRuntimes({ refresh = false } = {}) {
+  if (detectedCache && !refresh && Date.now() - detectedAt < DETECT_TTL_MS) return detectedCache;
+  detectedAt = Date.now();
+  detectedCache = Object.values(RUNTIMES).map((rt) => {
+    let version = null;
+    try {
+      version = String(
+        execFileSync(rt.bin, ['--version'], {
+          timeout: 5000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        })
+      )
+        .trim()
+        .split('\n')[0]
+        .slice(0, 40);
+    } catch {
+      version = null;
+    }
+    return {
+      id: rt.id,
+      installed: version !== null,
+      version,
+      // Installed and drivable are different questions, and conflating them is
+      // how a user ends up @mentioning something that silently never starts.
+      // THREE questions, in fact — see `drivableHere`: the CLI can be installed,
+      // and this module can know how to spawn it, and the worker this daemon is
+      // running can still be unable to drive it.
+      dispatchable: version !== null && drivableHere(rt),
+      blocked: rt.blocked ?? null,
+    };
+  });
+  return detectedCache;
+}