@evandu/super-pi 0.1.1 → 0.1.2

package/dist/server/workflow.js

@@ -0,0 +1,387 @@
+import { randomUUID } from "node:crypto";
+/**
+ * The workflow PLAN: an ordered list of sub-agent steps the server will execute on the primary agent's
+ * behalf, carrying each step's output into the next one.
+ *
+ * WHY THIS FILE EXISTS, and why it holds no I/O at all.
+ *
+ * The dispatch pipe was already built and already proved: `task-tool.ts` is the policy half of the mouth,
+ * `subagent-runs.ts` records and publishes a run, `subagents.ts` spawns and drains a child. What was
+ * missing was that a MODEL, given a request that needs three different specialists in a row, had to
+ * remember the order itself and hand-copy each result into the next prompt by hand. That is the
+ * orchestration gap - and the reason the seam here is pure is the same reason `task-tool.ts` is: every
+ * rule in this file can then be proved without spawning a process, which is the only layer where a
+ * plan's shape, its refusals and its truncation budgets are cheap to test exhaustively.
+ *
+ * WHAT IS BORROWED FROM OPENCODE, and what is not: nothing. That is a deliberate departure from the
+ * sibling files, which each cite upstream lines they ported. OpenCode has no multi-sub-agent pipeline
+ * primitive to port - it composes `task` calls the same way this project did, by model convention, which
+ * is the gap. What this file reuses instead is local: the roster filter from `task-tool.ts` (the same one
+ * that decides who may be dispatched), and the `SubagentRunRecorder.dispatch` seam, which always resolves
+ * with a settled record and therefore needs no error parsing here.
+ *
+ * WHAT THIS FILE DELIBERATELY DOES NOT MODEL, because `docs/AGENT_LOOP_DESIGN.md` proposed all of it and
+ * each one is a second orchestration authority rather than a capability:
+ *
+ * - BRANCHES AND EDGES. A declared graph makes the model learn a language to express sequencing it can
+ *   already express by dispatching twice. It also cannot be expressive enough, and a model that finds it
+ *   too rigid bypasses it, leaving two ways to orchestrate that behave differently.
+ * - LOOP-BACK. `verifier.md` already ends its report with `通过`/`失败`, so the model can read a failed
+ *   step and decide whether to run another round. That judgement is the thing worth keeping on the side
+ *   that can read the output; encoding it as an edge would move it to a component that never sees the text.
+ * - A SEPARATE ARTIFACT STORE. `WorkflowAttempt` below IS the versioned artefact: one attempt's output is
+ *   written once and never edited, and the next attempt appends beside it rather than replacing it.
+ */
+/**
+ * The id an orchestrated plan answers to.
+ *
+ * Prefixed and uuid-shaped for the same reason run ids are: the string is a lookup key in `state.json`
+ * and appears in `data-*` attributes in the browser, and a shape a person can recognise in a log is worth
+ * more than a bare uuid. `engine.ts` validates caller-supplied ids against this prefix the way
+ * `subagents.ts:358` validates run ids, because the same string becomes a reconciliation key at startup.
+ */
+export const newWorkflowRunId = () => `wf_${randomUUID()}`;
+/** Matches the shape `newWorkflowRunId` produces, for validating a caller-supplied id. */
+export const WORKFLOW_ID_PATTERN = /^wf_[A-Za-z0-9_-]{1,120}$/;
+/**
+ * How many steps one plan may hold.
+ *
+ * A bound, because every step is a real Pi process that runs for minutes and every step's output is
+ * carried forward: the cost of a plan grows with both its length and the size of what it accumulates.
+ * Eight steps is more than the pipelines this install's four sub-agents are built for (`scout` to
+ * `patcher` to `verifier`, maybe twice), so the bound is one a real request would not reach rather than
+ * one it would hit by accident.
+ */
+export const WORKFLOW_MAX_STEPS = 8;
+/** Every accepted policy, in the order the refusal message lists them for a model that guesses wrong. */
+export const WORKFLOW_FAILURE_POLICIES = ["stop", "skip", "retry:1", "retry:2", "retry:3"];
+/**
+ * Reads a failure policy, or `undefined` for anything that is not one.
+ *
+ * `retry` alone normalizes to `retry:1`: a model that reaches for retry almost always means "try it
+ * again once", and refusing over a missing count would cost a retry of the plan itself. Everything else
+ * is refused rather than coerced, because guessing `stop` for a model that asked for `parallel` would
+ * silently run a different plan than the one it wrote.
+ */
+export function parseFailurePolicy(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const text = raw.trim().toLowerCase();
+    if (text === "retry")
+        return "retry:1";
+    return WORKFLOW_FAILURE_POLICIES.find((policy) => policy === text);
+}
+/** How many times a policy re-runs a failing step. `stop` and `skip` both run it zero further times. */
+export function retriesFor(policy) {
+    const match = /^retry:([123])$/.exec(policy);
+    return match ? Number.parseInt(match[1], 10) : 0;
+}
+/**
+ * Caps a block of text from the FRONT, and says in the surviving text that something was dropped.
+ *
+ * THE TAIL IS WHAT SURVIVES, and that is not an arbitrary choice. Every sub-agent in `agents/` is written
+ * to put its conclusion last - `verifier.md` says its last line is `通过`/`失败`/`无法验证` and nothing
+ * else - so keeping the end of a report keeps the part the next step and the human both need. Cutting
+ * from the end would keep the preamble and discard the verdict, which is the one line that matters.
+ */
+export function capText(text, budget, what) {
+    if (budget <= 0)
+        return { text: "", truncated: text.length > 0, droppedChars: text.length };
+    if (text.length <= budget)
+        return { text, truncated: false, droppedChars: 0 };
+    const dropped = text.length - budget;
+    return {
+        text: `…（前面 ${dropped} 个字符的${what}已省略，完整内容在 Super Pi 的运行记录里）\n${text.slice(text.length - budget)}`,
+        truncated: true,
+        droppedChars: dropped,
+    };
+}
+/** The word a PERSON reads beside a status. Colour is never the only signal, so this is not optional decoration. */
+const STEP_STATUS_WORD = {
+    pending: "未开始",
+    running: "运行中",
+    completed: "已完成",
+    failed: "失败",
+    skipped: "已跳过",
+    stopped: "已停止",
+};
+/** As above, for a whole plan. `failed` and `stopped` differ: one ran out of steps, the other was halted. */
+const WORKFLOW_STATUS_WORD = {
+    running: "运行中",
+    completed: "全部完成",
+    failed: "中途失败",
+    stopped: "已停止",
+};
+export const stepStatusWord = (status) => STEP_STATUS_WORD[status] ?? status;
+export const workflowStatusWord = (status) => WORKFLOW_STATUS_WORD[status] ?? status;
+/**
+ * Per-step cap on how much of one prior output is carried into the next step's prompt.
+ *
+ * Eight KB is roughly two thousand tokens of Chinese prose or a little more of code, which is enough for
+ * the conclusion-plus-evidence shape every sub-agent in `agents/` is instructed to produce, and small
+ * enough that eight of them plus the plan itself stay inside a normal model's working context.
+ */
+export const STEP_OUTPUT_BUDGET = 8_000;
+/**
+ * Total cap across all carried-forward output in one step's prompt.
+ *
+ * Separate from the per-step cap because the per-step one alone does not bound anything: eight steps
+ * carrying 8 KB each is 64 KB, which is larger than the whole context most sub-agents run with. The
+ * budget is spent newest-first, so the immediately preceding step - the one whose conclusion the current
+ * step is most likely acting on - is never the one that loses characters.
+ */
+export const WORKFLOW_CONTEXT_BUDGET = 32_000;
+/** The token that hands a step exactly the previous step's output, with nothing prepended. */
+export const PREVIOUS_TOKEN = "{{previous}}";
+/** The token that hands a step every prior step's output, with nothing prepended. */
+export const HISTORY_TOKEN = "{{history}}";
+/**
+ * Renders one prior step as a block, or as a sentence when it has no output to hand on.
+ *
+ * A SKIPPED STEP IS SPOKEN, NOT OMITTED. Silence about a step that never ran would leave the next
+ * sub-agent - which has a fresh context and cannot see the plan - working from a gap it has no way to
+ * know about. So a skipped step contributes a line saying it was skipped, and contributes no output.
+ */
+function renderPriorStep(step, output) {
+    const heading = `### 第 ${step.index + 1} 步 · ${step.label?.trim() || step.agentId}（${step.agentId}）— ${stepStatusWord(step.status)}`;
+    if (step.status === "skipped")
+        return `${heading}\n（这一步按编排声明的失败策略被跳过了，没有产出。）`;
+    if (!output?.trim())
+        return `${heading}\n（这一步没有留下文字输出。）`;
+    return `${heading}\n${output}`;
+}
+/**
+ * Composes the prompt one step actually runs with, carrying earlier results into it.
+ *
+ * THE DEFAULT IS THE HANDOFF BLOCK, and the two tokens are the opt-outs. A model that does nothing
+ * special gets every prior step's output prepended, because "did the model remember to copy the last
+ * result forward" is not a property worth trusting a multi-step plan to. A model that WANTS control -
+ * wants the last output and nothing else, or wants the whole history verbatim - says so with a token,
+ * and in exchange the automatic block is suppressed entirely rather than being added alongside. Both
+ * spellings keep one rule intact: whatever this returns is the complete prompt, never a prefix that
+ * hides some of the instruction.
+ *
+ * AN EMPTY FIRST STEP IS THE PROMPT, VERBATIM. Composing a handoff header onto step one would tell a
+ * sub-agent about previous steps that do not exist, and would spend its attention on the header.
+ */
+export function composeStepPrompt(prompt, prior) {
+    const own = prompt.trim();
+    // Steps that ran, oldest first. A pending or running step is not a result yet, and neither is a step
+    // beyond the one being composed - the caller passes a slice, but the filter makes the contract local.
+    const ran = prior.filter((step) => step.status !== "pending");
+    if (own.includes(HISTORY_TOKEN)) {
+        const filled = fillHistoryToken(own, ran);
+        return { prompt: filled.text, handedOff: filled.used, truncated: filled.truncated };
+    }
+    if (own.includes(PREVIOUS_TOKEN)) {
+        const filled = fillPreviousToken(own, ran);
+        return { prompt: filled.text, handedOff: filled.used, truncated: filled.truncated };
+    }
+    if (!ran.length)
+        return { prompt: own, handedOff: 0, truncated: false };
+    const { blocks, used, truncated } = budgetPrior(ran);
+    // Gated on BLOCKS, NOT ON OUTPUT. A skipped step contributes no output at all, so an output count of
+    // zero does not mean there is nothing to say - it means the one thing that must be said is that the step
+    // was skipped. Gating on the count would drop exactly the message a fresh-context sub-agent most needs,
+    // since it has no other way to learn a step was walked past. This is the bug the skip test caught.
+    if (!blocks.length)
+        return { prompt: own, handedOff: 0, truncated: false };
+    // Blocks are joined with a BLANK line, not a newline: each one starts with a `###` heading, and a
+    // heading flush against the paragraph above it does not render as a heading under most Markdown
+    // parsers - so the report of the step before would be swallowed into the heading. The same blank line
+    // after the rule keeps the model's own task from being read as part of the handoff.
+    const header = [
+        "编排上下文：下面是这个编排里前面已经跑过的步骤和它们的结论。你自己是一个全新上下文的子 agent，看不到编排本身，所以这段是你唯一的前序信息。最后才是这次派给你的活。",
+        "",
+        blocks.join("\n\n"),
+        "",
+        "--- 以下是你这次的任务 ---",
+        "",
+        "",
+    ].join("\n");
+    return { prompt: `${header}${own}`, handedOff: used, truncated };
+}
+/** The output a step hands forward: its LAST attempt's, because that is the one a retry corrected. */
+function lastOutputOf(step) {
+    for (let index = step.attempts.length - 1; index >= 0; index -= 1) {
+        const output = step.attempts[index]?.output;
+        if (output?.trim())
+            return output;
+    }
+    return undefined;
+}
+/**
+ * Spends the context budget across prior steps, newest first, and renders the survivors oldest-first.
+ *
+ * NEWEST FIRST IS THE ALLOCATION ORDER, and it is also why a long plan degrades gracefully rather than
+ * dropping its most recent context. A plan whose earlier steps produced large reports keeps its tail
+ * intact and loses its preamble, which is the right thing to lose: step seven acting on step six's
+ * conclusion does not need step one's full output, and step two acting on step one already happened
+ * while the budget still had room.
+ */
+function budgetPrior(ran) {
+    let remaining = WORKFLOW_CONTEXT_BUDGET;
+    const chosen = new Map();
+    let used = 0;
+    let truncated = false;
+    for (let index = ran.length - 1; index >= 0 && remaining > 0; index -= 1) {
+        const step = ran[index];
+        const output = lastOutputOf(step);
+        if (!output?.trim()) {
+            // Still renders - as the "no output" or "was skipped" line - but spends no budget, because a line
+            // that says nothing took nothing.
+            chosen.set(index, { output: "", truncated: false });
+            continue;
+        }
+        const capped = capText(output, Math.min(STEP_OUTPUT_BUDGET, remaining), "前序输出");
+        if (!capped.text.trim())
+            continue;
+        truncated ||= capped.truncated;
+        chosen.set(index, { output: capped.text, truncated: capped.truncated });
+        remaining -= capped.text.length;
+        used += 1;
+    }
+    const blocks = [];
+    for (let index = 0; index < ran.length; index += 1) {
+        const entry = chosen.get(index);
+        // A step whose output did not fit the budget is dropped from the rendered block entirely rather
+        // than rendered with nothing in it, which would read as "this step produced no conclusion".
+        if (entry === undefined) {
+            truncated = true;
+            continue;
+        }
+        blocks.push(renderPriorStep(ran[index], entry.output || undefined));
+    }
+    return { blocks, used, truncated };
+}
+/**
+ * Replaces `{{previous}}` with the output of the single nearest preceding step that produced any.
+ *
+ * NEAREST, NOT ALL, because the token's name is a promise: a model that wrote `{{previous}}` asked for the
+ * last result, and quietly handing it the whole plan instead would be the same surprise as prepending a
+ * block it declined. A skipped step does not count as the previous step for this purpose - it has no
+ * output - so the search walks back to the nearest step that has one, and the rendered header still says
+ * which step it was, so the gap in the numbering is visible rather than inferred.
+ *
+ * The token is REPLACED EVEN WHEN THERE IS NOTHING TO REPLACE IT WITH. Leaving a literal `{{previous}}`
+ * in front of a sub-agent would read as an instruction it cannot satisfy; saying plainly that the first
+ * step has nothing before it is the honest version of the same fact.
+ */
+function fillPreviousToken(prompt, ran) {
+    const nearest = [...ran].reverse().find((step) => Boolean(lastOutputOf(step)?.trim()));
+    if (!nearest) {
+        return { text: prompt.split(PREVIOUS_TOKEN).join("（这是编排的第一步，前面还没有上一步的产出。）"), used: 0, truncated: false };
+    }
+    const output = lastOutputOf(nearest) ?? "";
+    const capped = capText(output, STEP_OUTPUT_BUDGET, "上一步输出");
+    return { text: prompt.split(PREVIOUS_TOKEN).join(renderPriorStep(nearest, capped.text)), used: 1, truncated: capped.truncated };
+}
+/**
+ * Replaces `{{history}}` with every prior step, under the same budget the default block uses.
+ *
+ * Shares `budgetPrior` with the default path on purpose: the two spellings of "hand me what came before"
+ * must not be able to disagree about what fits, or a model that chose the explicit token would get a
+ * different conversation than one that took the default for the same plan.
+ */
+function fillHistoryToken(prompt, ran) {
+    const { blocks, used, truncated } = budgetPrior(ran);
+    const replacement = blocks.join("\n\n");
+    return { text: replacement ? prompt.split(HISTORY_TOKEN).join(replacement) : prompt.split(HISTORY_TOKEN).join("（这是编排的第一步，前面还没有任何产出。）"), used, truncated };
+}
+/**
+ * Checks an untrusted plan body against the roster that may actually be dispatched.
+ *
+ * VALIDATES, NEVER REWRITES, THE AGENT LIST. `agentId` is matched against the roster rather than
+ * defaulted, because defaulting would run a different sub-agent than the model asked for - a plan that
+ * silently substituted `patcher` for a misspelled `patchre` would edit files on a read-only request.
+ * The roster arrives already filtered to `mode: subagent` and non-hidden (`task-tool.ts:88`), so a
+ * primary agent's id is refused here by the same rule that refuses it at dispatch time
+ * (`subagents.ts:368`) - one lock, consulted twice, rather than a second list that could drift.
+ */
+export function validateWorkflowPlan(raw, roster) {
+    const ids = roster.map((entry) => entry.id);
+    const available = ids.length ? ids.join(", ") : "(none)";
+    if (typeof raw !== "object" || raw === null)
+        return { refusal: `A workflow must be an object with "summary", "onFailure" and "steps". Got ${raw === null ? "null" : typeof raw}.` };
+    const body = raw;
+    const rawSteps = body.steps;
+    if (!Array.isArray(rawSteps))
+        return { refusal: `workflow.steps must be an array of at least 1 and at most ${WORKFLOW_MAX_STEPS} steps. Got ${rawSteps === undefined ? "nothing" : typeof rawSteps}.` };
+    if (rawSteps.length < 1)
+        return { refusal: "workflow.steps was empty. A workflow needs at least one step; for a single sub-agent, call the task tool instead." };
+    if (rawSteps.length > WORKFLOW_MAX_STEPS)
+        return { refusal: `workflow.steps holds ${rawSteps.length} steps and the limit is ${WORKFLOW_MAX_STEPS}. Shorten the plan, or split it into two workflows and use background dispatch for the parts that are independent.` };
+    const onFailure = body.onFailure === undefined ? "stop" : parseFailurePolicy(body.onFailure);
+    if (!onFailure)
+        return { refusal: `workflow.onFailure must be one of ${WORKFLOW_FAILURE_POLICIES.join(", ")}, or "retry" on its own for a single retry. Got ${JSON.stringify(body.onFailure)}. "stop" is used when you leave it out.` };
+    const steps = [];
+    for (let index = 0; index < rawSteps.length; index += 1) {
+        const entry = rawSteps[index];
+        const where = `workflow.steps[${index}]`;
+        if (typeof entry !== "object" || entry === null)
+            return { refusal: `${where} must be an object with "agentId" and "prompt". Got ${entry === null ? "null" : typeof entry}.` };
+        const step = entry;
+        const agentId = typeof step.agentId === "string" ? step.agentId.trim() : "";
+        if (!agentId)
+            return { refusal: `${where}.agentId is required. Dispatchable sub-agents: ${available}.` };
+        if (!ids.includes(agentId))
+            return { refusal: `${JSON.stringify(agentId)} is not a dispatchable sub-agent (${where}.agentId). Dispatchable sub-agents: ${available}. Pick one of those, or call the task tool directly for a single delegation.` };
+        const prompt = typeof step.prompt === "string" ? step.prompt.trim() : "";
+        if (!prompt)
+            return { refusal: `${where}.prompt is required and must not be empty: the sub-agent starts with a fresh context, so this is everything it will know about the work.` };
+        const label = typeof step.label === "string" ? step.label.trim() : "";
+        steps.push({ agentId, prompt, ...(label ? { label } : {}) });
+    }
+    // Defaulted rather than refused. The summary is a heading for a human, and a model that wrote three
+    // good steps but no summary has still written a runnable plan; refusing would spend a whole retry on
+    // a field that exists to be pretty.
+    const summary = typeof body.summary === "string" && body.summary.trim() ? body.summary.trim().slice(0, 200) : `${steps.length} 步编排`;
+    return { plan: { summary, onFailure, steps } };
+}
+/**
+ * Reduces a persisted plan to what the primary agent is told when the workflow returns.
+ *
+ * ONE ATTEMPT PER STEP, THE LAST ONE. The earlier attempts stay in the run records and on the timeline,
+ * which is where a person debugging a retried plan looks; putting all of them in the envelope would make
+ * the model re-read a failure it has already acted on.
+ */
+export function workflowSummary(plan) {
+    return {
+        id: plan.id,
+        summary: plan.summary,
+        status: plan.status,
+        onFailure: plan.onFailure,
+        steps: plan.steps.map((step) => {
+            const last = step.attempts[step.attempts.length - 1];
+            return {
+                n: step.index + 1,
+                agentId: step.agentId,
+                ...(step.label ? { label: step.label } : {}),
+                status: step.status,
+                attempts: step.attempts.length,
+                ...(last?.output !== undefined ? { output: last.output, ...(last.outputTruncated ? { outputTruncated: true } : {}) } : {}),
+                ...(last?.error ? { error: last.error } : {}),
+            };
+        }),
+        ...(plan.finishedAt ? { finishedAt: plan.finishedAt } : {}),
+    };
+}
+/**
+ * The step a settled run became, as an attempt record.
+ *
+ * The narrow seam between the run recorder and this engine: everything about spawning, streaming and
+ * process teardown is the recorder's, and the only thing that crosses here is the settled record it
+ * always resolves with (`subagent-runs.ts:159`). `output` is copied rather than referenced because the
+ * store hands out clones, and a plan that kept a live reference would read whatever the run wrote next.
+ */
+export function attemptFromRun(run, n) {
+    return {
+        n,
+        runId: run.id,
+        status: run.status === "completed" ? "completed" : run.status === "stopped" ? "stopped" : "failed",
+        ...(run.output !== undefined ? { output: run.output, ...(run.outputTruncated ? { outputTruncated: true } : {}) } : {}),
+        startedAt: run.startedAt,
+        ...(run.finishedAt ? { finishedAt: run.finishedAt } : {}),
+        ...(run.error ? { error: run.error } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -53,6 +53,10 @@
     "scripts/subagent-runs.test.mjs",
     "scripts/conversation-reconcile.test.mjs",
     "scripts/subagent-dispatch.test.mjs",
+    "scripts/workflow-plan.test.mjs",
+    "scripts/workflow-engine.test.mjs",
+    "scripts/workflow-endpoint.test.mjs",
+    "scripts/workflow-ui.test.mjs",
     "scripts/agent-vis-records.test.mjs",
     "scripts/queue-store.test.mjs",
     "scripts/followup.test.mjs",