@evandu/super-pi 0.1.0 → 0.1.2

package/dist/server/workflow.d.ts

@@ -0,0 +1,287 @@
+import type { SubagentRosterEntry } from "./task-tool.js";
+import type { SubagentRun } from "./types.js";
+/**
+ * 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 declare const newWorkflowRunId: () => string;
+/** Matches the shape `newWorkflowRunId` produces, for validating a caller-supplied id. */
+export declare const WORKFLOW_ID_PATTERN: RegExp;
+/**
+ * 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 declare const WORKFLOW_MAX_STEPS = 8;
+/**
+ * What happens to a step that failed.
+ *
+ * `stop` is the DEFAULT and it is the honest one. `docs/AGENT_LOOP_DESIGN.md` named the failure this
+ * guards against in a sentence worth keeping: "A failed step never silently advances with missing input."
+ * Continuing past a failed step means the next sub-agent is handed a hole it cannot see, and the plan
+ * reports success. So a caller that says nothing about failure gets the behaviour that cannot lie.
+ */
+export type WorkflowFailurePolicy = "stop" | "skip" | "retry:1" | "retry:2" | "retry:3";
+/** Every accepted policy, in the order the refusal message lists them for a model that guesses wrong. */
+export declare const WORKFLOW_FAILURE_POLICIES: readonly WorkflowFailurePolicy[];
+/**
+ * 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 declare function parseFailurePolicy(raw: unknown): WorkflowFailurePolicy | undefined;
+/** How many times a policy re-runs a failing step. `stop` and `skip` both run it zero further times. */
+export declare function retriesFor(policy: WorkflowFailurePolicy): number;
+/** Where a whole plan ended. `running` is the only state from which it advances on its own. */
+export type WorkflowStatus = "running" | "completed" | "failed" | "stopped";
+/** Where one step ended. `skipped` means the policy chose to walk past it after a failure. */
+export type WorkflowStepStatus = "pending" | "running" | "completed" | "failed" | "skipped" | "stopped";
+/**
+ * One try at one step.
+ *
+ * THE ARTEFACT, AND THE REASON THERE IS NO ARTIFACT STORE. A failed `verifier` that is retried has two
+ * different answers - the first one found two failing assertions, the second found none - and the first
+ * is exactly what makes the second legible. So an attempt is written once and never edited, and a retry
+ * appends beside the attempt it replaced instead of overwriting it. `n` is the attempt number within its
+ * step, not a global counter, so one step's history reads 1, 2, 3 without knowing anything about its neighbours.
+ */
+export type WorkflowAttempt = {
+    /** 1-based within the step. Attempt 1 is the first try, not a zero-th. */
+    n: number;
+    /** The `SubagentRun` this attempt produced. Absent only when the dispatch was refused before a run row existed. */
+    runId?: string;
+    /** How the run settled. Never `running`: `dispatch` resolves only once the child is terminal. */
+    status: "completed" | "failed" | "stopped";
+    /** The child's final message. Carried forward to later steps, and read by the primary agent afterwards. */
+    output?: string;
+    outputTruncated?: boolean;
+    startedAt: string;
+    finishedAt?: string;
+    /** Why this attempt did not complete. Present only beside a `failed` or `stopped` status. */
+    error?: string;
+};
+/** One step of a plan. Its `attempts` array is append-only; `status` is the derived summary of it. */
+export type WorkflowStep = {
+    index: number;
+    agentId: string;
+    /** An opaque label for a person to read. The engine never branches on it. */
+    label?: string;
+    /** The prompt as the model wrote it, before any prior output is composed into it. */
+    prompt: string;
+    attempts: WorkflowAttempt[];
+    status: WorkflowStepStatus;
+};
+/**
+ * A whole orchestrated plan, as persisted.
+ *
+ * The plan is written in full BEFORE step one runs, and that is the point of the record: progression is
+ * controlled by the server walking this structure, not by conventions inside successive prompts, so a
+ * browser that reloads mid-plan reads an accurate account of what was intended and not merely what
+ * happened to be written in a transcript so far.
+ */
+export type WorkflowRun = {
+    id: string;
+    conversationId: string;
+    /** One line describing what the whole plan is for, shown to a person above the timeline. */
+    summary: string;
+    onFailure: WorkflowFailurePolicy;
+    status: WorkflowStatus;
+    steps: WorkflowStep[];
+    /** Which step is executing or next. `steps.length` means the plan is past its last step. */
+    currentIndex: number;
+    startedAt: string;
+    finishedAt?: string;
+};
+/** One step as the primary agent is told about it: the last attempt, not the whole history. */
+export type WorkflowStepSummary = {
+    n: number;
+    agentId: string;
+    label?: string;
+    status: WorkflowStepStatus;
+    /** How many tries this step took. Above one, the step failed before it passed, and that is visible. */
+    attempts: number;
+    output?: string;
+    outputTruncated?: boolean;
+    error?: string;
+};
+/**
+ * What the endpoint hands back so the extension can render one envelope.
+ *
+ * The last attempt's output rather than all of them, for the same reason the conversation transcript is
+ * not re-sent into every turn: the primary agent needs to know what the pipeline concluded, and the
+ * earlier attempts are already in the run records and the timeline. Rendering happens on the extension
+ * side because the envelope is the tool's return value, not the server's - the same split
+ * `task-tool.ts:17-19` states for `<task>`.
+ */
+export type WorkflowSummary = {
+    id: string;
+    summary: string;
+    status: WorkflowStatus;
+    onFailure: WorkflowFailurePolicy;
+    steps: WorkflowStepSummary[];
+    finishedAt?: string;
+};
+/** The plan shape the engine executes, after validation. What `validateWorkflowPlan` returns on success. */
+export type WorkflowPlan = {
+    summary: string;
+    onFailure: WorkflowFailurePolicy;
+    steps: {
+        agentId: string;
+        label?: string;
+        prompt: string;
+    }[];
+};
+/**
+ * Text that had to lose its front, plus what it lost and why.
+ *
+ * `truncated` is carried rather than inferred from length so a CALLER can announce the loss. The house
+ * rule here is the one `task-tool.ts:102-116` already follows for an over-long roster: a payload that
+ * quietly omits part of itself makes a reader act on a belief that is not true, with no way to notice.
+ */
+export type CappedText = {
+    text: string;
+    truncated: boolean;
+    droppedChars: number;
+};
+/**
+ * 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 declare function capText(text: string, budget: number, what: string): CappedText;
+export declare const stepStatusWord: (status: WorkflowStepStatus) => string;
+export declare const workflowStatusWord: (status: WorkflowStatus) => string;
+/**
+ * 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 declare const STEP_OUTPUT_BUDGET = 8000;
+/**
+ * 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 declare const WORKFLOW_CONTEXT_BUDGET = 32000;
+/** The token that hands a step exactly the previous step's output, with nothing prepended. */
+export declare const PREVIOUS_TOKEN = "{{previous}}";
+/** The token that hands a step every prior step's output, with nothing prepended. */
+export declare const HISTORY_TOKEN = "{{history}}";
+/** What a composed prompt ended up carrying, so a caller can report it without re-parsing the string. */
+export type ComposedPrompt = {
+    prompt: string;
+    /** How many prior steps actually contributed output. */
+    handedOff: number;
+    /** Whether anything was dropped for space. */
+    truncated: boolean;
+};
+/**
+ * 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 declare function composeStepPrompt(prompt: string, prior: readonly WorkflowStep[]): ComposedPrompt;
+/**
+ * A plan that survived validation, or a sentence telling a MODEL what to fix.
+ *
+ * The refusal half exists because this value's first reader is a model about to retry: every message
+ * names what was wrong AND what an acceptable value looks like, following the rule `task-tool.ts:142`
+ * states for the depth refusal. `agents` is supplied in full even when the mistake is one member of it,
+ * because a model that guessed `scouter` has one correct answer and should not have to infer it.
+ */
+export type ValidatedPlan = {
+    plan: WorkflowPlan;
+    refusal?: undefined;
+} | {
+    plan?: undefined;
+    refusal: string;
+};
+/**
+ * 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 declare function validateWorkflowPlan(raw: unknown, roster: readonly SubagentRosterEntry[]): ValidatedPlan;
+/**
+ * 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 declare function workflowSummary(plan: WorkflowRun): WorkflowSummary;
+/**
+ * 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 declare function attemptFromRun(run: SubagentRun, n: number): WorkflowAttempt;