@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/schemas/workflows.ts

@@ -3,62 +3,27 @@ import { z } from "zod";
 import { AgentHarnessSchema, AgentProviderSchema, RepoBaseSchema } from "./agent.js";
 import { entryId } from "./internal.js";
 import { LoopCheckSchema, LoopContextSchema, LoopDocumentSchema, LoopOutputSchema, LoopStateSchema } from "./loops.js";
-/* THE THIRD DRIVER. An automation answers "run this at 3am", a loop answers "run this until it is done", and a
- * workflow answers "run these, in this order, each handing its result to the next".
- *
- * IT IS A GRAPH OF LOOPS, and that is the whole implementation. A step is not a new kind of execution, it is
- * a Loop with a declared output and a place in a dependency graph, driven on a conversation of its own. So
- * every step gets the fleet card, the worktree, the transcript, the cost ledger, the Stop button, the stall
- * detector and the spend ceiling without a line of new code, and this file's job is only to say what the steps
- * are and what depends on what.
- *
- * WHY IT IS NOT "AN AUTOMATION WITH SEVERAL PROMPTS". Because the value is in the SEAM between steps: the
- * output of one is validated before the next is allowed to start, the reviewing step is a different session
- * from the implementing one, and a step that cannot converge stops the branch below it rather than feeding
- * garbage forward. None of that exists in a prompt that says "then do X".
- */
+// A workflow runs steps in order, each one's output feeding the next, unlike an automation's schedule or a loop's
+// until-done. Each step is a Loop with a declared output in a dependency graph, so it inherits the fleet card, worktree
+// and ledger. Output is validated between steps; a failing step stops the branch below it.
 
-// A step id: short and slug-shaped because it is spliced into the derived conversation id (`wf-<run>-<step>`),
-// which is itself a branch name and a directory name. The regex is the injection guard, the length cap is what
-// keeps the derived id inside ConversationIdSchema's 64.
+// Slug spliced into `wf-<run>-<step>` (branch/dir name); regex guards injection, length keeps the id under 64.
 const StepIdSchema = z
     .string()
     .min(1)
     .max(24)
     .regex(/^[a-z0-9][a-z0-9-]*$/);
-/* HOW A STEP MEETS ITS PREDECESSOR, the fork the whole feature turns on, and the one the user has to choose
- * because neither answer is right twice in a row.
- *
- * `fresh` opens a NEW conversation: its own fleet card, its own session, its own worktree when the run is
- * isolated. What it knows about the step before it is exactly what that step declared as output. This is the
- * only honest way to run a review, an audit or a second opinion, a session that spent nine turns arguing for
- * an approach is the worst available judge of whether that approach worked, and the fix is not a better prompt,
- * it is a different session.
- *
- * `continue` sends the next prompt into the SAME conversation. The model keeps everything it learned, the
- * prefix stays cached, and, when the run is isolated, the work stays in one worktree on one branch, which is
- * the only way a chain like implement → test → document can build on itself at all. Requires exactly one
- * predecessor: two upstream sessions cannot both be continued into one.
- */
+// How a step meets its predecessor: fresh opens a new conversation, knowing only the predecessor's declared output;
+// continue carries the same conversation forward, and requires exactly one predecessor.
 export const WorkflowHandoffSchema = z.enum(["fresh", "continue"]);
 export type WorkflowHandoff = z.infer<typeof WorkflowHandoffSchema>;
-// Enough steps for a real pipeline, few enough that a workflow stays legible as one picture. A design past
-// this is two workflows, and reading it as one graph was never going to work.
+// Enough for a real pipeline; more than this reads as two workflows, not one graph.
 const WORKFLOW_STEPS_MAX = 24;
 export const WorkflowStepSchema = z.object({
     id: StepIdSchema.describe("This step's own name, which other steps use to say they wait on it."),
-    // What the node says on the graph. Short, the prompt is where the detail goes.
+    // What the node shows on the graph; keep it short, detail belongs in the prompt.
     title: z.string().min(1).max(60).describe("What to call it on screen. Short: the instruction below is where the detail goes."),
-    /* What "done" means for this step, in the user's words. Put to the judge, and restated to the model unless
-     * its instruction already carries it (loop-brief); it is the sentence the step is measured against.
-     *
-     * ABSENT ⇒ THE RUN'S OWN REQUEST IS THE GOAL, which is the ordinary case and not the exotic one. A saved
-     * workflow is a SHAPE, "two models on one task", and for most of its steps the thing being asked for is
-     * whatever the person typed this time. Writing a goal here as well means saying the same thing twice and
-     * keeping the two in agreement forever; leaving it out means the step is measured against the request,
-     * which is what anyone would have written anyway. Declare one only where the step's bar is genuinely its
-     * own ("the suite is green") rather than the run's.
-     */
+    // Absent means the step is judged against the run's own request; set only when its bar differs from that.
     goal: z
         .string()
         .min(1)
@@ -66,15 +31,7 @@ export const WorkflowStepSchema = z.object({
         .describe(
             "What done means for this step, in your words. It is what the step is judged against, and a different sentence from what it is told to do.",
         ),
-    /* What the step is told to DO. A different sentence from the goal: "the suite is green" is the goal,
-     * "run the tests, take the top failure, fix it" is the instruction.
-     *
-     * ABSENT ⇒ THE REQUEST IS HANDED OVER VERBATIM, with none of the workflow's own framing around it (see
-     * briefForStep). That is the default because the framing is not free: every heading between the reader's
-     * sentence and the model is a chance for the model to answer the frame instead of the question, and a step
-     * whose whole job is "do what was asked" has nothing to add to it. A step that DOES declare a prompt is
-     * saying it has a job of its own, review this, merge those, and gets the full brief, request included.
-     */
+    // Absent hands the run's own request over verbatim; declare a prompt only when the step has a job of its own.
     prompt: z
         .string()
         .min(1)
@@ -82,8 +39,7 @@ export const WorkflowStepSchema = z.object({
         .describe(
             "What the step is told to do. The goal is the suite is green; this is run the tests, take the top failure, fix it. Leaving it out hands over the run's own request untouched, which is right for a step whose whole job is do what was asked.",
         ),
-    // The steps that must finish before this one starts. Empty ⇒ a root, started when the run starts. The
-    // graph must be acyclic and every id must exist; both are checked when the workflow is saved.
+    // Steps that must finish first; empty means a root. Must be acyclic with every id existing, checked on save.
     needs: z
         .array(StepIdSchema)
         .describe(
@@ -94,14 +50,11 @@ export const WorkflowStepSchema = z.object({
     ),
     output: LoopOutputSchema.describe("What it has to produce for the step to count."),
     checks: z.array(LoopCheckSchema).describe("What has to pass before it counts as done."),
-    // How the step's own ITERATIONS meet each other, the Ralph question, one level down from `handoff`. A
-    // long-running step wants `fresh` (no context rot); a short refine-this step wants `continue`.
+    // How the step's own iterations meet each other: a long step wants fresh each round, a short one continue.
     context: LoopContextSchema.describe(
         "How the step's own repeats meet each other. A long-running step wants to start clean each round; a short polish-this step wants to carry on.",
     ),
-    /* Iteration/stall limits remain scheduler backstops rather than form questions. Spend is different: it is
-     * the one resource the owner cannot recover after an unattended fan-out, and the underlying loop already
-     * enforces it exactly. Absent remains uncapped for short, person-started work. */
+    // Unrecoverable after an unattended fan-out, unlike iteration or stall limits; absent means uncapped.
     maxSpendUsd: z
         .number()
         .positive()
@@ -113,11 +66,7 @@ export const WorkflowStepSchema = z.object({
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it."),
     account: z.string().optional().describe("Which account pays for it."),
     model: z.string().optional().describe("Which model runs it."),
-    /* Which persona the step acts as, the same field a chat turn and an automation carry (AgentTurnSchema.
-     * actsAs), because a step IS an unattended turn under the loop machinery. Unpinned, a step keeps the
-     * strict unattended default: full tools, no logged-in accounts. Pinning a card is how a gated release
-     * check gets a voice, a folder scope, or the one Reddit it is allowed to post from, a decision the owner
-     * already wrote down once, on the card. */
+    // Unpinned, a step defaults to every tool and no signed-in accounts; pinning grants a scope or an account.
     actsAs: entryId
         .optional()
         .describe(
@@ -125,58 +74,29 @@ export const WorkflowStepSchema = z.object({
         ),
 });
 export type WorkflowStep = z.infer<typeof WorkflowStepSchema>;
-/* THE GATE, how a finished run becomes a release decision, and how a machine with no identity asks for one.
- *
- * A workflow is a DESIGN; a gate is a PROMISE ABOUT ITS RESULT, and keeping the two separable is the whole
- * point. What a run does, how many sessions, whether they drive a browser, which repos they touch, stays the
- * graph's business, because the value of running a release check this way is that the check is a workflow like
- * any other: an acceptance sweep today, a security review or a performance budget next month, with nothing
- * here ever learning what any of them are.
- *
- * So a gate reads exactly one thing: a named FIELD off a named STEP's declared output (output-fields.ts). That
- * field already exists for precisely the reason this needs it, a declared field is the one part of a session's
- * answer that was VALIDATED rather than parsed back out of the prose the model was talking to a person in,
- * and pointing at one is the entire rule.
- */
+// A gate is a promise about a run's result, separate from the design itself. It reads one named field off one step's
+// declared output, the one part of an answer that was validated rather than parsed from prose.
 export const WorkflowGateSchema = z.object({
-    // Which step's declared output carries the decision. Ordinarily a leaf that weighs up the steps before it;
-    // nothing requires that, and a one-step workflow naming its only step is the common small case.
+    // Which step's declared output carries the decision; usually a leaf that weighs up the ones before it.
     step: StepIdSchema.describe(
         "Which step's answer carries the decision. Usually a last step that weighs up the ones before it, though nothing requires that.",
     ),
-    // Which of that step's declared fields is read. Checked against what the step actually declares when the
-    // workflow is saved, a gate pointed at a field nobody writes answers `blocked` on every run, forever.
+    // Which of that step's declared fields is read; checked against what it actually declares when saved.
     field: z
         .string()
         .min(1)
         .describe(
             "Which of that step's declared answers to read. A declared field is the one part of a step's answer that was checked rather than fished out of prose, which is the whole rule here. Checked when the workflow is saved.",
         ),
-    /* The values of that field that mean SHIP IT. Everything else fails the gate.
-     *
-     * An allowlist rather than a blocklist, because the two are not symmetric under a model's vocabulary. A
-     * step that answers "mostly-pass", "pass-with-notes" or "pass (2 minor defects)" must not ship, and the
-     * allowlist gets that right without anyone having had to enumerate the ways a model can hedge.
-     */
+    // Values meaning ship it; everything else fails. An allowlist, since a hedge like mostly-pass must not ship.
     pass: z
         .array(z.string().min(1))
         .min(1)
         .describe(
             "Which values mean ship it. Everything else fails. A list of what passes rather than what fails, because a step answering mostly-pass or pass-with-notes must not ship, and this gets that right without anybody having had to enumerate the ways a model can hedge.",
         ),
-    // The webhook's own auth, minted on save exactly as an event automation's is. The caller is a pipeline
-    // runner with no Google identity, so this is the only credential in the exchange.
-    token: z
-        .string()
-        .optional()
-        .describe(
-            "The credential the calling pipeline presents. It is the only one in the exchange, because a build runner has no identity of its own here.",
-        ),
-    /* Runs per UTC day, across every caller. A gate is a paid endpoint reachable with no person in the loop:
-     * one of these wired into a push-triggered pipeline is a fan-out of sessions per commit, and the
-     * per-request deadline bounds one call's WALL CLOCK without bounding the day's SPEND. Absent ⇒
-     * GATE_DAILY_MAX_DEFAULT, not uncapped, for the reason the Front Desk's ceiling is not optional either.
-     */
+    // Token isn't here: minted on save into the secrets store, carried separately as gateToken.
+    // Runs per UTC day, across every caller; absent defaults to GATE_DAILY_MAX_DEFAULT, not uncapped.
     dailyMax: z
         .number()
         .int()
@@ -187,26 +107,18 @@ export const WorkflowGateSchema = z.object({
         ),
 });
 export type WorkflowGate = z.infer<typeof WorkflowGateSchema>;
-/* The gate's daily ceiling when its author sets none. Deliberately small next to the Front Desk's 200: a
- * Front Desk message is one turn, a gate run is a whole graph of sessions, and the honest comparison is cost
- * rather than count. Twenty is a busy day of merges and a script's first minute. */
+// Small next to the Front Desk's 200: a gate run is a whole graph of sessions, not one turn.
 export const GATE_DAILY_MAX_DEFAULT = 20;
-/* What a gate answers a pipeline, and the three-way split matters.
- *
- * `blocked` exists for the same reason acceptance's verdict has one: "we could not reach a judgment" is not
- * "the product is broken". A gate that reported them the same way would go red for its own outages, and a team
- * that cannot tell the two apart turns the gate off, so `blocked` is meant to be the honest answer far more
- * often than it is the convenient one. It maps to a NEUTRAL pipeline exit, never a failed build.
- */
+// blocked means the gate couldn't reach a judgment, not that the product is broken; conflating the two makes teams turn
+// the gate off. Maps to a neutral pipeline exit, never a failed build.
 export const GateOutcomeSchema = z.enum(["pass", "fail", "blocked"]);
 export type GateOutcome = z.infer<typeof GateOutcomeSchema>;
-// What the gate route answers with. `value` is the field as the step actually wrote it, absent when the gate
-// never got one to read, which is every `blocked` that is not a disagreement about the value.
+// value is the field as the step wrote it; absent means most blocked verdicts had nothing to read.
 export const GateVerdictSchema = z.object({
     outcome: GateOutcomeSchema.describe(
         "Ship it, do not, or we could not tell. That third answer exists because could not reach a judgement is not the product is broken: a gate that reported its own outages as failures is one a team switches off, so it should be the honest answer far more often than the convenient one, and it means a neutral build rather than a red one.",
     ),
-    // One line: why. Realistically the only part of this a pipeline log will ever show.
+    // Why, in one line; realistically the only part of this a pipeline log will show.
     reason: z.string().describe("Why, in one line. Realistically the only part of this a build log will ever show."),
     runId: z.string().describe("The run behind the verdict, so somebody can go and read it."),
     value: z
@@ -226,22 +138,13 @@ export const WorkflowSchema = z.object({
         .describe(
             "The steps, each with what it waits on. Every one runs in its own private copy of the repos, always, because parallel steps sharing a tree collide.",
         ),
-    // Present ⇒ this design can be run by a machine and answers a release decision. Absent ⇒ an ordinary
-    // workflow, started by a person from the workflows page, with no public door onto it at all.
+    // Present means a machine can run this for a ship decision; absent means an ordinary person-started workflow.
     gate: WorkflowGateSchema.optional().describe(
         "Present means a machine can run this design and get a ship-it answer back. Absent means an ordinary workflow, started by a person, with no outside door onto it at all.",
     ),
-    /* EVERY STEP RUNS IN ITS OWN WORKTREE, always, with no toggle, the same thing an isolated agent session
-     * does, which is what every session in this product already is.
-     *
-     * It was a per-workflow choice between worktrees and the shared /work tree, and the shared side never
-     * earned its place: parallel steps on one tree collide, a `fresh` step there sees a half-finished
-     * predecessor's edits as if they were the workspace, and the pinned-base-to-branch comparisons that make
-     * a fan-in READABLE (see workflow-brief) only exist on the isolated side. A setting whose other value is a
-     * subtle trap is not a setting, it is a mistake waiting for somebody to make it.
-     */
-    // How many steps may run at once. Bounded because a fan-out of twelve is twelve provider sessions, twelve
-    // worktrees and twelve times the burn rate, and because the machine this runs on is one machine.
+    // Every step runs in its own worktree, always, with no toggle; a shared tree lets a fresh step see a predecessor's
+    // half-finished edits, and breaks fan-in diffs.
+    // Bounded: a fan-out of N is N provider sessions, N worktrees and N times the burn rate, on one machine.
     maxParallel: z
         .number()
         .int()
@@ -252,13 +155,9 @@ export const WorkflowSchema = z.object({
         ),
 });
 export type Workflow = z.infer<typeof WorkflowSchema>;
-// The rules a graph has to clear before it can be saved or run, the acyclic `needs`, the once-only
-// continuation, are in workflow-faults.ts, because they are about the graph rather than about any field here.
 
-/* How one step ended. `skipped` is the one that carries information the others cannot: it means the step never
- * ran because something it waited for did not finish, which is why a failed workflow shows one red node and a
- * trail of grey ones rather than a wall of failures that all say the same thing.
- */
+// skipped means the step never ran because something it waited on didn't finish; that's why a failed run shows one red
+// node and a trail of grey ones.
 export const WorkflowStepStateSchema = z.enum(["pending", "running", "done", "failed", "skipped", "stopped"]);
 export type WorkflowStepState = z.infer<typeof WorkflowStepStateSchema>;
 export const WorkflowStepRunSchema = z.object({
@@ -266,8 +165,7 @@ export const WorkflowStepRunSchema = z.object({
     state: WorkflowStepStateSchema.describe(
         "How it went. Skipped carries what the others cannot: it never ran, because something it was waiting on did not finish. That is why a failed run shows one red step and a trail of grey ones.",
     ),
-    // The conversation this step ran on, derived, and the door from a node on the graph to a real transcript.
-    // Shared with the predecessor when the handoff is `continue`, which is what makes those steps one card.
+    // The conversation this step ran on; shared with its predecessor under continue, making them one card.
     conversationId: z
         .string()
         .describe(
@@ -277,27 +175,23 @@ export const WorkflowStepRunSchema = z.object({
     endedAt: z.number().optional().describe("When it ended, in milliseconds."),
     iterations: z.number().int().min(0).describe("How many rounds it took."),
     costUsd: z.number().optional().describe("What it cost, in dollars."),
-    // How the step's LOOP ended, `exhausted` and `stalled` both land as a `failed` step, and the difference
-    // between them is the difference between "give it more room" and "more room will not help".
+    // exhausted and stalled both surface as failed; the difference is whether more room would have helped.
     loopState: LoopStateSchema.optional().describe(
         "How its repeating ended. Out of rounds and stuck both come out as a failed step, and the difference between them is the difference between give it more room and more room will not help.",
     ),
     detail: z.string().optional().describe("What went wrong, when something did."),
-    // What the step produced. Present once the step has written a valid document, which for a `json` output
-    // means it matched the declared fields. This is what the steps downstream are given.
+    // Present once the step writes a document matching its declared shape; what downstream steps are handed.
     document: LoopDocumentSchema.optional().describe(
         "What it produced, once it has produced something that passes its own declared shape. This is what the steps after it are handed.",
     ),
-    /* A bounded preview of the step's closing words. The complete response lives at `reportPath`, so a long-form
-     * handoff is not silently reduced to its last few thousand characters and the ledger stays bounded. */
+    // Bounded preview of the closing words; the full text lives at reportPath, keeping the ledger small.
     report: z
         .string()
         .optional()
         .describe(
             "The start of its closing words. Bounded, so a long answer is not silently cut down to its last few thousand characters and the record stays a sensible size.",
         ),
-    // Workspace-relative shared-state artifact containing the complete response. Fresh worktrees and a resumed
-    // daemon see the same .intentic mount, so downstream steps can read it without copying it into their prompt.
+    // Workspace-relative path on the shared .intentic mount; steps read it without copying into a prompt.
     reportPath: z
         .string()
         .optional()
@@ -306,22 +200,16 @@ export const WorkflowStepRunSchema = z.object({
         ),
 });
 export type WorkflowStepRun = z.infer<typeof WorkflowStepRunSchema>;
-// `done` means every step that ran finished; a run with skipped steps is `failed`, because a graph that did not
-// reach its leaves did not do what it was asked whatever the survivors managed.
+// done means every step that ran finished; any run with a skipped step counts as failed.
 export const WorkflowRunStateSchema = z.enum(["running", "done", "failed", "stopped", "overspent", "error"]);
 export type WorkflowRunState = z.infer<typeof WorkflowRunStateSchema>;
 export const WorkflowRunSchema = z.object({
     runId: z.string().min(1).describe("This run's id."),
-    /* The workflow AS IT WAS WHEN THE RUN STARTED, snapshotted rather than referenced. Three things need this
-     * and none of them tolerate a live lookup: the run view draws the graph the run actually ran (not the one
-     * that has been edited twice since), the boot resume needs the step definitions of a workflow that may have
-     * been deleted, and a history row for a deleted workflow is otherwise an id and nothing else. */
+    // Snapshot at run start, not a live reference; the run stays readable even if the design is edited or deleted.
     workflow: WorkflowSchema.describe(
         "The design as it stood when the run started, copied rather than looked up. The run has to keep showing the graph it actually ran, not the one edited twice since, and a run of a deleted workflow has to stay readable.",
     ),
-    /* The workspace as this run began, one immutable commit per repository. Every fresh step branches from
-     * these exact commits, even if main moves while a wide fan-out is still opening worktrees. Handoffs use the
-     * same bases in their diff commands, so provenance works in nested repositories as well as at root. */
+    // One immutable commit per repo at run start; every step branches from these exact commits regardless of main.
     repos: z
         .array(RepoBaseSchema)
         .min(1)
@@ -329,17 +217,7 @@ export const WorkflowRunSchema = z.object({
         .describe(
             "The workspace as this run began, one exact commit per repository. Every step branches from these, even if the shared tree moves while a wide fan-out is still opening its copies, so the steps can be compared with each other afterwards.",
         ),
-    /* WHAT THIS RUN WAS ASKED TO DO, the sentence the user typed when they started it, handed to every step
-     * on top of its own prompt. Absent for a run started from the workflows page, which has no composer.
-     *
-     * It is what makes one saved design worth keeping: "two models, one task" is a SHAPE, and the task is
-     * different every time. Without this the only way to point a workflow at today's job is to open the
-     * designer and retype a step's prompt, which means the design and the request are the same document,
-     * and editing a graph to ask a question is not something anybody does twice.
-     *
-     * Snapshotted on the run beside the workflow, and for the same reason: the run has to stay readable, and
-     * "what was this one about" is the first thing anyone asks of a row in the history.
-     */
+    // What the run was asked to do, handed to every step atop its own prompt; absent when there is no composer.
     request: z
         .string()
         .optional()
@@ -351,25 +229,16 @@ export const WorkflowRunSchema = z.object({
     ),
     startedAt: z.number().describe("When it began, in milliseconds."),
     endedAt: z.number().optional().describe("When it ended, in milliseconds."),
-    // How many daemon boots have picked this run back up, the same counter, and the same reason, as a loop's.
+    // How many times the sandbox restarted and picked this run back up.
     resumed: z.number().int().min(0).describe("How many times the sandbox restarted under it and picked it back up."),
     detail: z.string().optional().describe("What went wrong, when something did."),
-    // One entry per step, in the workflow's own order. Written at start with every step `pending`, so the graph
-    // is complete from the first frame and a node's absence never has to mean two things.
+    // One entry per step, in the design's order; all start pending so the graph is complete from the first frame.
     steps: z
         .array(WorkflowStepRunSchema)
         .describe(
             "One entry per step, in the design's own order. Every one is written down as waiting when the run starts, so the picture is complete from the first frame and a missing step never has to mean two things.",
         ),
-    /* When the run was ARCHIVED (ms epoch), off the board, exactly as an agent's `archivedAt` takes a card off
-     * it, and the same promise: the run record stays readable in the history and every step's branch,
-     * transcript and counters are untouched. Absent ⇒ live on the board.
-     *
-     * A RUN AND ITS STEPS ARCHIVE AS ONE, which is the whole reason this field exists rather than the record
-     * simply being dropped. A run's steps have no card of their own, the run's row is what stands for them,
-     * so deleting the record was releasing five loose conversations back onto the board at the moment the user
-     * said they were finished with the job. Archiving the run archives its sessions with it and unarchiving
-     * brings both back, so "done with this" means the same thing for a workflow as it does for an agent. */
+    // Off the board like an agent's archivedAt; a run and its steps archive and unarchive as one unit.
     archivedAt: z
         .number()
         .optional()
@@ -378,8 +247,15 @@ export const WorkflowRunSchema = z.object({
         ),
 });
 export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
-// The list row: the stored workflow plus the runs it has had, newest first.
-export const WorkflowSummarySchema = WorkflowSchema.extend({ runs: z.array(WorkflowRunSchema).describe("Its runs, newest first.") });
+// The gate's credential; attached for a maintainer or the owner, and for nobody else.
+const gateToken = z
+    .string()
+    .optional()
+    .describe("What a pipeline presents at /workflows/{id}/gate, when the design declares a gate. Shown to a maintainer or the owner only.");
+// Save answers with the stored design plus the gate credential, the only way the designer learns the pipeline URL.
+export const WorkflowSavedSchema = WorkflowSchema.extend({ gateToken });
+export type WorkflowSaved = z.infer<typeof WorkflowSavedSchema>;
+export const WorkflowSummarySchema = WorkflowSchema.extend({ runs: z.array(WorkflowRunSchema).describe("Its runs, newest first."), gateToken });
 export type WorkflowSummary = z.infer<typeof WorkflowSummarySchema>;
 export const WorkflowsListSchema = z.object({ workflows: z.array(WorkflowSummarySchema).describe("Every saved design with its own run history.") });
 export const WorkflowRunsListSchema = z.object({
@@ -387,9 +263,8 @@ export const WorkflowRunsListSchema = z.object({
 });
 export const WorkflowIdParamSchema = z.object({ id: z.string().describe("Which workflow.") });
 export const WorkflowRunIdParamSchema = z.object({ runId: z.string().describe("Which run.") });
-/* Starting a run: which design, and what to point it at. The request is optional because the workflows page
- * starts runs with no composer to read one from, a design whose steps already say what they want is complete
- * on its own, and only a design written as a shape needs today's sentence. */
+// request is optional: a workflows-page run has no composer to fill it from, and a design whose steps already say what
+// they want needs nothing more.
 export const WorkflowRunStartSchema = WorkflowIdParamSchema.extend({
     request: z
         .string()
@@ -400,9 +275,8 @@ export const WorkflowRunStartSchema = WorkflowIdParamSchema.extend({
             "What to point it at. Optional, because a design whose steps already say what they want is complete on its own; only one written as a shape needs today's sentence.",
         ),
 });
-// Creation and replacement are deliberately distinct. An id collision on create is a conflict; an update of
-// a missing id is not an implicit create. That makes the daemon, rather than a browser naming convention, the
-// authority that prevents one saved design from overwriting another.
+// Create and replace are explicit and distinct: an id collision on create conflicts, and updating a missing id never
+// implicitly creates one. The daemon enforces this, not a browser convention.
 export const WorkflowSaveSchema = z.object({
     workflow: WorkflowSchema.describe("The design to write."),
     create: z

package/src/schemas/workspace-repos.ts

@@ -15,8 +15,7 @@ export const CloneResultSchema = z.object({
     name: z.string().describe("What it ended up called."),
     path: z.string().describe("Where it landed."),
 });
-// Per-repo result of a workspace sync (fetch + guarded fast-forward). `status` mirrors GitSyncResult plus the
-// turn-orchestration outcomes skipped/error; behind/ahead/head/message are present per status (see RepoSyncOutcome).
+// status mirrors GitSyncResult plus turn outcomes skipped/error; behind/ahead/head/message are present per status.
 export const RepoSyncSchema = z.object({
     repo: z.string().describe("Which repository."),
     status: z
@@ -30,9 +29,8 @@ export const RepoSyncSchema = z.object({
     message: z.string().optional().describe("What went wrong, when something did."),
 });
 export const WorkspaceSyncSchema = z.object({ repos: z.array(RepoSyncSchema).describe("One entry per repository, saying what happened to it.") });
-// Add one or more named app instances into an EXISTING monorepo. Each entry pairs a template key from the
-// source repo's templates.json manifest (e.g. "api", "web", "landing") with a user-chosen instance name
-// (e.g. "shop-api"); {repo} names the target monorepo.
+// Adds named app instances to an existing monorepo: template is a key from the source repo's templates.json, name is
+// the user's chosen instance name.
 export const AppInstanceInputSchema = z.object({
     template: z.string().min(1).describe("Which kind of app to scaffold, by its key in the template list."),
     name: z
@@ -46,17 +44,14 @@ export const AddAppsSchema = z.object({
     repo: z.string().describe("Which repository to scaffold into."),
     apps: z.array(AppInstanceInputSchema).min(1).describe("The apps to add."),
 });
-// Run vitest for one or more repo-relative project dirs in a named one-shot tmux panel session
-// (panel-<repo>--<session>), driven by the apps extension's Run-tests actions. `session` is a slug suffix
-// (an app/package name as `<name>__test`, or `tests` for the library section); `dirs` are repo-relative
-// package dirs, where "" targets the repo root.
+// Runs vitest in a one-shot tmux panel session (panel-<repo>--<session>). dirs are repo-relative package dirs; ""
+// targets the repo root.
 export const RunTestsSchema = z.object({
     repo: z.string().describe("Which repository."),
     session: z.string().describe("What to call the terminal this runs in, so you can find it again."),
     dirs: z.array(z.string()).min(1).describe("Which projects to test, as folders relative to the repository. Empty targets the repository root."),
 });
-// One addable app type the configured source repo offers (from its templates.json), listed for the operator
-// panel's Add-app picker: the manifest key + its label/description.
+// One addable app type from the source repo's templates.json, for the Add-app picker.
 export const TemplateSummarySchema = z.object({
     key: z.string().describe("The id to name when scaffolding one."),
     label: z.string().describe("What to call it on screen."),
@@ -67,11 +62,8 @@ export const TemplatesListSchema = z.object({
     templates: z.array(TemplateSummarySchema).describe("The kinds of app the configured source repository knows how to scaffold."),
 });
 export type TemplatesList = z.infer<typeof TemplatesListSchema>;
-// One app instance currently in a monorepo, with its own preview dev server + live status (started/stopped
-// from the apps extension). `app` is the user-chosen instance name (the _apps/ dir); `kind` is what sort of
-// app it is, the manifest key it was scaffolded from (api/web/landing), else the framework detected from its
-// dependencies (astro/next/…), and absent when it was discovered purely by its `dev` script. previewUrl is
-// https://preview-<repo>--<app>-<sandboxId>.<zone> (absent on loopback, no zone or no connect token).
+// One app instance in a monorepo, with its own dev server and status. previewUrl is
+// https://preview-<repo>--<app>-<sandboxId>.<zone>, absent without a zone or connect token.
 export const RepoAppSchema = z.object({
     app: z.string().describe("The app's name, which is also its folder."),
     kind: z
@@ -83,8 +75,7 @@ export const RepoAppSchema = z.object({
     previewUrl: z.string().optional().describe("Where to open it. Absent when this sandbox has no outside address."),
     running: z.boolean().describe("Whether its dev server is up."),
     healthy: z.boolean().describe("Whether it is actually answering."),
-    // The same two facts a repository's panel row carries (PanelSummarySchema), for the same screens: an app
-    // installs at its monorepo's root, so `installed` is the root's node_modules.
+    // Same as a repo's panel row: an app installs at its monorepo's root, so this is the root's node_modules.
     installed: z
         .boolean()
         .describe("Whether its dependencies are installed, which is what decides whether a start takes seconds or an install first."),
@@ -95,8 +86,7 @@ export const RepoAppSchema = z.object({
 export type RepoApp = z.infer<typeof RepoAppSchema>;
 export const AppsListSchema = z.object({ apps: z.array(RepoAppSchema).describe("The apps in this repository.") });
 export type AppsList = z.infer<typeof AppsListSchema>;
-// One workspace package in a pnpm monorepo, discovered from pnpm-workspace.yaml's packages globs. `dir` is the
-// repo-relative package dir (e.g. "_editor/web"); `group` is its top-level dir segment (e.g. "_editor"), the
+// A pnpm-workspace package, discovered from pnpm-workspace.yaml's globs. group is the top-level dir segment, the
 // dependencies view's coloring axis.
 export const WorkspacePackageSchema = z.object({
     name: z.string().describe("The name the package declares."),
@@ -106,8 +96,7 @@ export const WorkspacePackageSchema = z.object({
 export type WorkspacePackage = z.infer<typeof WorkspacePackageSchema>;
 export const WorkspaceDepTypeSchema = z.enum(["prod", "dev", "peer"]);
 export type WorkspaceDepType = z.infer<typeof WorkspaceDepTypeSchema>;
-// A workspace-internal dependency edge: `from` DEPENDS ON `to` (from's package.json lists to), typed by which
-// dependency block declared it. Pure data, layout/direction is the client's concern.
+// A workspace-internal dependency edge: from depends on to, typed by which dependency block declared it.
 export const WorkspaceDepEdgeSchema = z.object({
     from: z.string().describe("The package that depends."),
     to: z.string().describe("The package it depends on."),
@@ -119,8 +108,7 @@ export const WorkspaceGraphSchema = z.object({
     edges: z.array(WorkspaceDepEdgeSchema).describe("Which of them use which. Pure data: how to lay it out is yours to decide."),
 });
 export type WorkspaceGraph = z.infer<typeof WorkspaceGraphSchema>;
-// Path params for the per-repo apps routes: the monorepo name (validated in the handler like PanelRepoParam)
-// and, for per-app preview control (start/stop), the app key (api/web/landing).
+// Path params for the per-repo apps routes: repo names the monorepo, validated like PanelRepoParam.
 export const RepoAppsParamSchema = z.object({ repo: z.string().describe("Which repository.") });
 export const AppParamSchema = z.object({
     repo: z.string().describe("Which repository."),