flowviant 0.75.0 → 0.76.0

package/bin/lib/agentPlan.mjs

@@ -0,0 +1,187 @@
+/**
+ * READING A PLANNER'S ANSWER.
+ *
+ * The scratch agent behind a Deploy press is asked for one JSON object and
+ * nothing else. This is what turns its final message into a proposal, and it is
+ * its own module because it is the one piece of that turn that can quietly LIE:
+ * everything else either works or throws, while a half-parsed proposal renders
+ * as a plausible-looking board somebody accepts.
+ *
+ * LENIENT ON PACKAGING, STRICT ON SHAPE.
+ *
+ * A model asked for one object will sometimes fence it and sometimes not, and
+ * sometimes say "Here you go:" first. Refusing the whole plan over that spends
+ * the operator's own model quota to produce nothing, so the packaging is
+ * forgiven. What is NOT forgiven is the shape: an agent holding no cards, a
+ * `taskIds` that is not an array of strings, or no agents at all is a proposal
+ * nobody can accept, and `null` — which the caller reports in the machine's own
+ * words — beats rendering an empty board with an Accept button on it.
+ *
+ * Every string is CAPPED here rather than downstream. This text is model
+ * output about untrusted card content, and it becomes a row.
+ *
+ * Run: node --test bin/lib/agentPlan.test.mjs
+ */
+
+/** The biggest a single proposal may be. Bounds on a machine, not a policy:
+ *  the server caps these again at its own boundary. */
+const MAX_AGENTS = 20;
+const MAX_TASKS_PER_AGENT = 60;
+const MAX_NAME = 80;
+const MAX_NOTE = 1000;
+
+/**
+ * Find the object.
+ *
+ * A fenced block first, because that is what was asked for. Otherwise every `{`
+ * in the text is tried as a start, and its BALANCED end is found by counting
+ * braces while skipping string literals — the first candidate that parses into
+ * something with an `agents` array wins.
+ *
+ * The obvious cheap version — first `{` to last `}` — is wrong in a way a test
+ * caught: a planner that writes "I looked at {the auth module} first" before its
+ * JSON produces a span starting at the wrong brace, and the whole plan is lost
+ * to a sentence. Scanning candidates costs nothing at this size and cannot be
+ * defeated by prose.
+ */
+function extract(raw) {
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidates = [];
+  if (fenced) candidates.push(fenced[1]);
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] !== '{') continue;
+    const end = balanced(raw, i);
+    if (end > i) candidates.push(raw.slice(i, end + 1));
+  }
+  for (const body of candidates) {
+    if (!body.trim()) continue;
+    try {
+      const v = JSON.parse(body);
+      if (v && typeof v === 'object' && Array.isArray(v.agents)) return v;
+    } catch {
+      /* the next candidate may be the object */
+    }
+  }
+  return null;
+}
+
+/** The index of the `}` that closes the `{` at `from`, or -1. Skips string
+ *  literals so a brace inside a card title cannot end the object early. */
+function balanced(s, from) {
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = from; i < s.length; i++) {
+    const ch = s[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === '\\') esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === '{') depth++;
+    else if (ch === '}' && --depth === 0) return i;
+  }
+  return -1;
+}
+
+export function parseProposal(text) {
+  const raw = String(text ?? '');
+  const parsed = extract(raw);
+  if (!parsed) return null;
+
+  const agents = [];
+  for (const [i, g] of parsed.agents.slice(0, MAX_AGENTS).entries()) {
+    if (!g || typeof g !== 'object') continue;
+    const taskIds = Array.isArray(g.taskIds)
+      ? g.taskIds.filter((t) => typeof t === 'string' && t.trim()).slice(0, MAX_TASKS_PER_AGENT)
+      : [];
+    // AN AGENT WITH NO CARDS IS NOT AN AGENT. Dropping it is right rather than
+    // merely tidy: accepting one would create a worktree and a branch for
+    // nothing, and it would sit in Working forever with an empty queue.
+    if (taskIds.length === 0) continue;
+    agents.push({
+      tempId: String(g.tempId || `a${i + 1}`).slice(0, 64),
+      name: String(g.name ?? '').slice(0, MAX_NAME),
+      taskIds,
+      ...(Number.isFinite(g.pointsBudget) && g.pointsBudget > 0
+        ? { pointsBudget: Math.min(Math.round(g.pointsBudget), 100_000) }
+        : {}),
+      ...(Array.isArray(g.waitsOn)
+        ? { waitsOn: g.waitsOn.filter((w) => typeof w === 'string' && w).slice(0, 20) }
+        : {}),
+      ...(typeof g.intoAgentId === 'string' && g.intoAgentId
+        ? { intoAgentId: g.intoAgentId.slice(0, 64) }
+        : {}),
+    });
+  }
+  if (agents.length === 0) return null;
+  return {
+    agents,
+    ...(typeof parsed.note === 'string' && parsed.note.trim()
+      ? { note: parsed.note.slice(0, MAX_NOTE) }
+      : {}),
+  };
+}
+
+/**
+ * READING AN AGENT'S ANSWER at the end of a turn.
+ *
+ * Same lenient-packaging / strict-shape rule as `parseProposal`, and the same
+ * reason: the turn already ran and the operator already paid for it, so
+ * refusing the whole thing over a stray "Here you go:" throws away real work.
+ *
+ * NULL IS A REAL ANSWER AND THE MOST IMPORTANT ONE. It means the turn declared
+ * NEITHER delivered nor blocked — a signed-out CLI, a crash, an exhausted
+ * quota, or a model that simply stopped — and the caller reports it as
+ * `nothing`, which sends the agent to Stuck. Optimistic status from a machine
+ * that quit is the one lie this board cannot afford, so anything ambiguous ends
+ * up here rather than being read as success.
+ */
+export function parseTurnResult(text) {
+  const parsedRaw = String(text ?? '');
+  const fenced = parsedRaw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidates = [];
+  if (fenced) candidates.push(fenced[1]);
+  for (let i = 0; i < parsedRaw.length; i++) {
+    if (parsedRaw[i] !== '{') continue;
+    const end = balanced(parsedRaw, i);
+    if (end > i) candidates.push(parsedRaw.slice(i, end + 1));
+  }
+  for (const body of candidates) {
+    let v;
+    try {
+      v = JSON.parse(body);
+    } catch {
+      continue;
+    }
+    if (!v || typeof v !== 'object') continue;
+    if (v.status === 'blocked') {
+      const question = typeof v.question === 'string' ? v.question.trim() : '';
+      // A "blocked" with no question is not an answer anybody can act on — it
+      // parks an agent with nothing to reply to. Treated as `nothing`, which
+      // at least says truthfully that the machine went quiet.
+      if (!question) continue;
+      return { outcome: 'question', answer: question.slice(0, 8000) };
+    }
+    if (v.status === 'delivered') {
+      return {
+        outcome: 'delivered',
+        answer: (typeof v.summary === 'string' ? v.summary : '').slice(0, 8000),
+        raised: Array.isArray(v.raised)
+          ? v.raised
+              .filter((r) => r && typeof r.title === 'string' && r.title.trim())
+              .slice(0, 10)
+              .map((r) => ({
+                title: r.title.trim().slice(0, 300),
+                ...(typeof r.brief === 'string' && r.brief.trim()
+                  ? { brief: r.brief.trim().slice(0, 2000) }
+                  : {}),
+              }))
+          : [],
+      };
+    }
+  }
+  return null;
+}

package/bin/lib/fleet.mjs

@@ -817,6 +817,10 @@ export async function runFleetDaemon() {
     processDiffJobs,
     processKillJobs,
     processPrJobs,
+    processAgentPlanJobs,
+    processAgentTurnJobs,
+    processAgentMergeJobs,
+    freshenManualPlaces,
     heldSessionIds,
     processPreviewJobs,
     livePreviewIds,
@@ -1616,6 +1620,21 @@ export async function runFleetDaemon() {
     // `gh` credential; a settle never closes a card (done is observed by the
     // landed walk when the merge reaches base).
     processPrJobs(roster.prJobs);
+    // A Deploy press waiting for a plan. AFTER the job lanes above and before
+    // the worktree report, for no reason other than that it reads directories
+    // those lanes may still be writing — it measures, so a stale read is a
+    // slightly worse hint and never a wrong action.
+    processAgentPlanJobs(roster.agentPlanJobs);
+    // …and an agent's next card. After the plan jobs because a press becoming
+    // agents is the thing that produces these.
+    processAgentTurnJobs(roster.agentTurnJobs);
+    // …and a branch somebody approved. After the turns: a merge takes the
+    // place's WRITER lock, and writer preference means it goes ahead of any
+    // reader queued behind it anyway.
+    processAgentMergeJobs(roster.agentMergeJobs);
+    // Catch each person's manual worktree up to base while it is clean. Silent,
+    // fast-forward only, and it never touches an agent's branch.
+    freshenManualPlaces();
     // …and what the SURVIVING ones hold: branch, ahead-of-base, diffstat.
     // Throttled inside, never awaited — a `git status` the human cannot run
     // themselves from a browser, relayed. After retirement so a directory that

package/bin/lib/prompts.mjs

@@ -501,3 +501,254 @@ export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages =
   `chapter that covers them), append the feature-history entry to log.md,\n` +
   `then output REGROUND_DONE.`;
 
+
+/**
+ * THE PLANNER — the scratch agent behind a Deploy press (2026-09-03).
+ *
+ * Somebody selected cards and pressed Deploy. This turn's whole job is to
+ * decide HOW THAT WORK SHOULD BE SPLIT across agents, and then stop. It writes
+ * no code, edits no files and starts nothing: a person reads what it proposes,
+ * edits it on the board, and accepting is what spawns anything.
+ *
+ * It runs READ-ONLY IN THE CHECKOUT under CONSULT_PERM — no Write, no Edit, no
+ * mkdir, no rm, and no MCP at all. The proposal comes back as its final
+ * message, not through a tool, which is what lets that permission set be this
+ * narrow. A planner authors a decision, and there is no file on this machine it
+ * has any business touching.
+ *
+ * The two facts it is asked to weigh are the only two that are actually
+ * knowable here: what the cards SAY, and what each live agent has already
+ * TOUCHED. Everything else — how long something will take, who should own it,
+ * whether it is a good idea — is not a question a planner can answer from a
+ * repository, and asking for it produces confident invention.
+ */
+export const SYSTEM_PLAN = `You are the human's own Claude, planning a batch of work in their repository.
+
+You are READ-ONLY. You cannot write, edit or create files, and you have no tools
+beyond reading the repo. Do not try. Your entire output is a plan.
+
+WHAT YOU ARE DECIDING: a set of task cards has been selected. Split them across
+one or more AGENTS. An agent is one CLI in one git worktree on one branch,
+working its cards ONE AT A TIME in the order you give, and landing all of them
+as a single reviewable branch.
+
+THE RULES THAT MATTER:
+
+1. SEQUENTIAL WORK BELONGS IN ONE AGENT. If B needs A's code to exist, put them
+   in the same agent, A first. Splitting a chain across agents means the second
+   one waits for the first to MERGE before it can even start.
+
+2. SPLIT ONLY WHAT CAN GENUINELY RUN AT THE SAME TIME. Two agents editing the
+   same files land two branches that conflict, and somebody resolves it by hand.
+   Read the repo to find out whether they collide — do not guess from titles.
+
+3. AN AGENT IS ONE REVIEWABLE BRANCH. Everything you put in one agent gets
+   approved or rejected TOGETHER. Cards a person would want to judge separately
+   belong in separate agents.
+
+4. FEWER, LARGER AGENTS BEAT MANY SMALL ONES. Only a limited number run at once;
+   past that they queue, and a queue of tiny agents is slower than a few real
+   ones. Never propose more agents than the cap you were given.
+
+5. NAME EACH AGENT AFTER THE WORK ("auth", "billing webhooks"), not after a
+   number. People say these names out loud.
+
+6. A POINTS BUDGET bounds how far an agent may grow while it works — it files
+   its own follow-up cards when it finds things, and the budget is where it
+   stops and asks. Set it from the size of what you put in, leaving some room.
+   Omit it if the cards carry no sizes.
+
+7. YOU MAY ADD CARDS TO A LIVE AGENT instead of creating a new one, when the
+   work needs what that agent has already built and has not merged yet. Use its
+   id in "intoAgentId".
+
+ANSWER WITH ONE JSON OBJECT AND NOTHING ELSE — no prose before it, no prose
+after it. Wrap it in a \`\`\`json fence:
+
+\`\`\`json
+{
+  "note": "one sentence on why you split it this way",
+  "agents": [
+    {
+      "tempId": "a1",
+      "name": "auth",
+      "taskIds": ["<card id>", "<card id>"],
+      "pointsBudget": 8,
+      "waitsOn": [],
+      "intoAgentId": null
+    }
+  ]
+}
+\`\`\`
+
+Every selected card id must appear EXACTLY ONCE across all agents. Use the ids
+exactly as given. "waitsOn" holds tempIds of agents that must MERGE first.`;
+
+/**
+ * The planner's turn.
+ *
+ * The cards and the live agents are FENCED: their titles, briefs and criteria
+ * are written by whoever files cards in this project and by agents themselves,
+ * and this turn reads a repository afterwards. The instruction that matters —
+ * "split this" — is ours and sits outside the fence.
+ */
+export const AGENT_PLAN_KICKOFF = ({ tasks, liveAgents, agentCap }) => {
+  const cards = tasks
+    .map(
+      (t) =>
+        `- id: ${t.id}\n  title: ${t.title}\n` +
+        (t.points ? `  points: ${t.points}\n` : '') +
+        (t.anchors?.length ? `  owns: ${t.anchors.join(', ')}\n` : '') +
+        (t.brief ? `  brief: ${t.brief}\n` : '') +
+        (t.criteria?.length ? `  done when:\n${t.criteria.map((c) => `    - ${c}`).join('\n')}\n` : '')
+    )
+    .join('\n');
+  const live = liveAgents.length
+    ? liveAgents
+        .map(
+          (a) =>
+            `- id: ${a.id}\n  name: ${a.name || '(unnamed)'}\n  status: ${a.status}\n` +
+            (a.changedFiles?.length
+              ? `  has already changed:\n${a.changedFiles.map((f) => `    - ${f}`).join('\n')}\n`
+              : '  has changed nothing yet\n')
+        )
+        .join('\n')
+    : '(none)';
+  return (
+    `Split this batch of work across agents.\n\n` +
+    `At most ${agentCap} agent${agentCap === 1 ? '' : 's'} run at once on this machine; ` +
+    `propose no more than that.\n\n` +
+    `${fence('THE SELECTED CARDS', cards)}\n\n` +
+    `${fence('AGENTS ALREADY RUNNING (you may add to one)', live)}\n\n` +
+    `Read whatever you need from the repository to decide whether these collide. ` +
+    `Then answer with the JSON object and nothing else.`
+  );
+};
+
+/**
+ * AN AGENT'S SYSTEM PROMPT — the contract for one card in one worktree.
+ *
+ * Deliberately not SYSTEM_WORK. A Workbench tab is a CONVERSATION: it narrates
+ * through tools, holds context across many turns, and a person is watching. An
+ * agent turn is a TASK — it starts, does one card, and ends — and nobody is
+ * watching while it runs. So the whole contract is: do this card, commit it,
+ * and end with a JSON object saying what happened.
+ *
+ * IT HAS NO TOOLS BEYOND THE REPOSITORY. There is no MCP on this turn at all,
+ * which is why everything it needs to say has to fit in that final object and
+ * everything it needs to PROVE is measured from git afterwards. An agent naming
+ * its own commit shas would be a receipt pointing at whatever it liked; the
+ * daemon reads the log instead.
+ *
+ * THE ONE THING IT MUST NOT DO IS GUESS. A turn that ends with a question costs
+ * a person one reply; a turn that guesses costs them a review, a rejection and
+ * a second run — and the guess arrives wearing a confident summary.
+ */
+export const SYSTEM_AGENT = `You are the human's own Claude, working one task in a git worktree of their
+repository. Nobody is watching this run. You have the repo and nothing else —
+no project tools, no board, no chat.
+
+WHAT TO DO:
+
+1. Do the card you are given. Read whatever you need first. Follow the
+   repository's own conventions over anything you would do by default.
+
+2. COMMIT YOUR WORK before you finish. Small, real commit messages. Uncommitted
+   work is work nobody can review or merge.
+
+3. If you cannot finish because you need a DECISION only a person can make —
+   an ambiguous requirement, a choice between two designs, a missing credential
+   — STOP AND ASK. Do not guess. A question costs one reply; a guess costs a
+   review, a rejection and a second run, and it arrives looking finished.
+
+4. If you find something broken that is NOT this card — a bug, a failing test
+   you did not cause — you may fix it, and you must SAY SO by raising it. It
+   becomes its own card so a person can see it happened rather than finding it
+   in the diff.
+
+COMMIT TRAILER: every commit you make must end with a line reading
+Flowviant-Task: <the card id you were given>
+It is how the board attaches your commits to the card; a commit without it is
+work nobody can trace back.
+
+END YOUR TURN WITH ONE JSON OBJECT AND NOTHING AFTER IT, in a \`\`\`json fence:
+
+\`\`\`json
+{
+  "status": "delivered",
+  "summary": "one or two sentences on what you actually changed",
+  "raised": [{ "title": "short title", "brief": "what is wrong and what you did" }]
+}
+\`\`\`
+
+or, if you are stopping to ask:
+
+\`\`\`json
+{
+  "status": "blocked",
+  "question": "the specific thing you need decided, in one or two sentences"
+}
+\`\`\`
+
+"raised" is optional and only for work you did that was NOT this card. Do not
+list the card itself there. Do not put commit shas in the summary — they are
+read from git.`;
+
+/**
+ * The turn itself.
+ *
+ * The card is FENCED: its title, brief and criteria are written by whoever
+ * files cards in this project, and this turn is about to edit code. The
+ * instruction is ours and sits outside the fence.
+ *
+ * The queue POSITION is stated because it changes behaviour: an agent that
+ * thinks it is finishing tidies up, writes summaries and stops; one that knows
+ * three more cards are coming leaves the ground ready for them.
+ */
+export const AGENT_TASK_KICKOFF = ({ agentName, task, position, total }) =>
+  `You are the agent "${safeName(agentName)}", working card ${position} of ${total} ` +
+  `on this branch. Everything you commit here is reviewed and merged TOGETHER with ` +
+  `the other cards in this run.\n\n` +
+  `${fence('THE CARD', taskBlock(task))}\n\n` +
+  `When you commit, put this trailer on the LAST line of each commit message so ` +
+  `the card can find its own commits:\n` +
+  `Flowviant-Task: ${task?.id ?? ''}\n\n` +
+  `Do it, commit it, and end with the JSON object.`;
+
+/**
+ * An agent's NAME is model-authored — the planner chose it — and it is
+ * interpolated at the head of the prompt, OUTSIDE the fence, where a sentence
+ * would read as an instruction from us. Fencing the name would be absurd (it is
+ * two words in the middle of ours), so it is reduced to something that cannot
+ * be a sentence: one line, no fence delimiters, and short.
+ */
+const safeName = (n) =>
+  String(n ?? '')
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/<<<|>>>/g, '')
+    .replace(/"/g, "'")
+    .trim()
+    .slice(0, 60) || 'agent';
+
+const taskBlock = (task) =>
+  `id: ${task?.id ?? ''}\n` +
+  `title: ${task?.title ?? ''}\n` +
+  (task?.brief ? `\nbrief:\n${task.brief}\n` : '') +
+  (task?.criteria?.length ? `\ndone when:\n${task.criteria.map((c) => `- ${c}`).join('\n')}\n` : '') +
+  (task?.anchors?.length ? `\nthis card owns:\n${task.anchors.map((a) => `- ${a}`).join('\n')}\n` : '');
+
+/**
+ * A PERSON SPOKE TO THE AGENT — usually the answer to its own question.
+ *
+ * It is the same shape as a task turn on purpose: the agent still ends with the
+ * JSON object, because whatever it does next either finishes the card it was on
+ * or blocks again, and those are the only two things the board can act on.
+ */
+export const AGENT_HUMAN_KICKOFF = ({ agentName, message, askedByName, task, position, total }) =>
+  `You are the agent "${safeName(agentName)}"` +
+  (task ? `, working card ${position} of ${total} on this branch` : '') +
+  `.\n\n` +
+  `${fence('WHO IS TALKING', askedByName || 'a member of this project')}\n\n` +
+  `${fence('WHAT THEY SAID', message)}\n\n` +
+  (task ? `${fence('THE CARD YOU ARE ON', taskBlock(task))}\n\n` : '') +
+  `Carry on, and end with the JSON object as usual.`;