toolroll 0.9.104 → 0.9.105

package/dist/contracts/flow-send.js

@@ -1,61 +1,36 @@
-/**
- * What a "Send to me" or "Person chooses" visit sends its person (docs/plans/zod-revamp.md, item 8): worked out once
- * per visit and kept (`flow_send.content_json`), so every chat app and the card show the same (src/flow-send.ts).
- *
- * - `flowSendPayloadSchema`: a send's — the title, summary, links, screenshots and a research report's items.
- * - `flowChoosePayloadSchema`: a choice's — the same, with the options as they were offered and whether a reply is taken.
- * - `flowChoiceAnswerSchema`: the person's answer to a choice, by whichever door it comes (chooseFlowCard).
- *
- * Kept before this contract (version 0), a visit's content had no `version`; it reads as the 0.9.36 reader read it:
- * a title, a summary and a list of links make it readable, items that can't be shown are left out, and a link or
- * option that isn't one is skipped.
- */
 import { z } from "zod";
 import { parseContract, readVersioned, versioned } from "./contract.js";
 import { chatCardSchema } from "./chat-card.js";
 import { isRecord } from "../is-record.js";
-/** A link the message carries: a page of Toolroll's (a button) or the one outside page, a pull request. */
 export const flowSendLinkSchema = z.union([
     z.strictObject({ label: z.string(), path: z.string().regex(/^\//, { error: "must be a path in Toolroll, starting with /" }) }),
     z.strictObject({ label: z.string(), url: z.string().regex(/^https:\/\/[^\s<>"]+$/, { error: "must be an https:// address" }) }),
 ]);
-/** One item of a research report, as the message lists it (flow-items.ts). */
 export const flowSendItemSchema = z.strictObject({
     title: z.string(),
     why: z.string(),
     url: z.string().regex(/^https?:\/\//, { error: "must be a web address" }),
-    /** Where the link goes, by name: "Mobbin", "Linear", "Apple". */
     source: z.string(),
-    /** One line: how it plugs in (from the why, else the image's own caption). */
     plug: z.string(),
-    /** The item's screenshot (its evidence id in the report's run), when it has one. */
     shot: z.int().nullable(),
 });
 export const FLOW_SEND_VERSION = 1;
 const sendShape = {
-    /** The card's title and the step it comes from. */
     title: z.string(),
-    /** The step it comes from, when known. */
     from: z.string().optional(),
     summary: z.string(),
     links: z.array(flowSendLinkSchema),
-    /** The build's result whose screenshots go with it, when it saved any. */
     shots: z.strictObject({ taskId: z.string(), run: z.int() }).nullable(),
-    /** After research: the report's items, numbered in this order in every message and screenshot caption. */
     items: z.array(flowSendItemSchema).min(1).optional(),
-    /** A "Send to me" visit's result as a card (flow-result-card.ts), from what the flow recorded. */
     card: chatCardSchema.optional(),
 };
 export const flowChoiceOptionSchema = z.strictObject({ choice: z.int().min(0), label: z.string() });
 export const flowSendPayloadSchema = versioned(FLOW_SEND_VERSION, sendShape);
 export const flowChoosePayloadSchema = versioned(FLOW_SEND_VERSION, {
     ...sendShape,
-    /** The options as they were offered, by place. */
     options: z.array(flowChoiceOptionSchema),
-    /** Whether a reply is taken instead (the zone has somewhere replies go). */
     reply: z.boolean(),
 });
-/** A kept item as 0.9.36 read it: its five words (a web link), and a screenshot id only when it is a whole number. */
 const savedItemSchema = z.object({ ...flowSendItemSchema.shape, shot: z.unknown() });
 export function readFlowItems(raw) {
     if (!Array.isArray(raw))
@@ -68,7 +43,6 @@ export function readFlowItems(raw) {
         return [{ ...read.data, shot: typeof shot === "number" && Number.isSafeInteger(shot) ? shot : null }];
     });
 }
-/** Version 0: content kept before it carried `version`, in this contract's shape (what can't be read is left for the schema to refuse by path). */
 export function upgradeSavedSend(body) {
     if (typeof body["title"] !== "string" || typeof body["summary"] !== "string" || !Array.isArray(body["links"]))
         return body;
@@ -85,7 +59,6 @@ export function upgradeSavedSend(body) {
     }
     return out;
 }
-/** Read a visit's kept content: a choice's when it carries options, else a send's; version 0 upgraded, newer refused. */
 export function readFlowSendPayload(input) {
     const choose = isRecord(input) && Object.prototype.hasOwnProperty.call(input, "options");
     const read = choose ? readVersioned(flowChoosePayloadSchema, input, { 0: upgradeSavedSend }) : readVersioned(flowSendPayloadSchema, input, { 0: upgradeSavedSend });
@@ -94,14 +67,10 @@ export function readFlowSendPayload(input) {
     const { version: _version, ...content } = read.value;
     return { ok: true, value: content };
 }
-/** A visit's content as it is kept: the payload of its kind, with the current version. */
 export function flowSendForStore(content) {
     const payload = { version: FLOW_SEND_VERSION, ...content };
     return JSON.stringify(content.options === undefined ? flowSendPayloadSchema.parse(payload) : flowChoosePayloadSchema.parse(payload));
 }
-// ------------------------------------------------------------------ the person's choice
-/** A person's answer to a choice: an option by its place (and the words and zone they saw), or a reply (`choice` null)
- * that becomes the note for where replies go. `entry` is the visit they saw; without it, the card's current one. */
 export const flowChoiceAnswerSchema = z.strictObject({
     card: z.int().min(1),
     entry: z.int().min(1).optional(),

package/dist/contracts/flow.js

@@ -1,24 +1,8 @@
-/**
- * Flows' one contract (docs/plans/zod-revamp.md, item 3): one schema per zone kind, as a discriminated union on `kind`,
- * in each of the three vocabularies a flow is written in —
- *
- * - the saved drawing (`flowDefinitionSchema`): zones as the canvas and the store hold them, references by id;
- * - steps (`flowStepSchema`): the lead's, `toolroll flows create/edit`'s, starters', kits' and the gallery's words,
- *   references by id or name (`goesTo`, `ifFails`), what a kept step leaves out carried over;
- * - the flow file (`flowFileSchema`, docs/flow-file.schema.json): steps with an id and a place on the canvas;
- *
- * plus triggers as they are given (`triggerInputSchema`) and as they are saved (`triggerConfigSchema`). Types are
- * `z.infer`, limits come from TEXT_LIMITS, and every object is strict, so an unknown key is refused by name. What JSON
- * Schema cannot say — paths to zones that exist, no path back into its own zone, a merge only after a decision, a web
- * address's host, tool arguments as JSON, time zones, schedules, secrets, people and scripts — is checked in plain code
- * after parsing (flows.ts, flow-triggers.ts, flow-share.ts), each with a path-named error.
- */
 import { z } from "zod";
 import { TEXT_LIMITS } from "../text-limits.js";
 import { limited, toModelSchema, versioned } from "./contract.js";
 export const FLOW_STAGE_KINDS = ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "subagent", "send", "choose", "done"];
 export const FLOW_COLORS = ["slate", "blue", "violet", "amber", "green", "rose"];
-/** How a Pull request zone merges once checks pass. */
 export const FLOW_MERGE_METHODS = ["squash", "merge", "rebase"];
 export const FLOW_TRIGGER_KINDS = ["button", "schedule", "github", "linear", "flow", "webhook", "email", "chat", "plane-review"];
 export const FLOW_PLANNING = ["auto", "required", "skip"];
@@ -26,96 +10,62 @@ export const FLOW_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 export const FLOW_WAIT_FOR = ["reply", "time", "hours"];
 export const FLOW_RUN_IN = ["folder", "copy"];
 export const SCRIPT_LANGUAGES = ["shell", "python", "node"];
-/** Where a choose option that ends the card leads. */
 export const FLOW_END = "end";
-/** How many zones a flow has, options a choose zone offers, answers a sort or script picks from, and so on. */
 export const FLOW_ZONES_MAX = 24;
 export const CHOICES_MIN = 2, CHOICES_MAX = 4;
 export const SORT_ANSWERS_MIN = 2, SORT_ANSWERS_MAX = 12, SORT_NOTES_MAX = 3, SORT_LEVELS_MIN = 2, SORT_LEVELS_MAX = 10;
 export const ROUTES_MAX = 12, SECRETS_MAX = 10, HEADERS_MAX = 10;
-/** The longest a zone waits or a limit runs: 30 days. */
 export const LONGEST_WAIT_MINUTES = 30 * 24 * 60;
-/** "Sure enough to act alone", as a fraction (0.5–0.99) or a percentage (50–99). */
 export const SURE_AT_MIN = 0.5, SURE_AT_MAX = 0.99, SURE_AT_PERCENT_MAX = 99;
-/** A zone's id: short, lowercase, dashes. */
 export const ZONE_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
-/** A project script's name: short, lowercase, dashes — how zones and chat refer to it. */
 export const SCRIPT_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
-/** A saved secret's name, in capitals. */
 export const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,39}$/;
-/** A flow file parameter's id. */
 export const PARAMETER_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-/** A time of day as zones save it, and as people write it. */
 export const CLOCK = /^([01][0-9]|2[0-3]):[0-5][0-9]$/;
 export const CLOCK_WRITTEN = /^\s*([01]?[0-9]|2[0-3]):([0-5][0-9])\s*$/;
-/** No control characters (tabs and line breaks are fine). */
 const PLAIN = /^[^\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]*$/;
-/** No control characters and no hidden direction marks: text a flow file or trigger brings in from outside. */
 const VISIBLE = /^[^\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f​-‏‪-‮⁦-⁩]*$/;
-/** Words, within a TEXT_LIMITS bound, with no control characters. */
 const words = (field, key) => limited(field, key).regex(PLAIN, { error: "can't contain control characters" });
 const visible = (field, key) => limited(field, key).regex(VISIBLE, { error: "can't contain hidden characters" });
 const zoneId = z.string().regex(ZONE_ID, { error: "must be a short id: lowercase letters, numbers and dashes" });
 const scriptName = z.string().regex(SCRIPT_NAME, { error: "must be a script's name: lowercase letters, numbers and dashes" });
 const secretName = z.string().regex(SECRET_NAME, { error: "must be a saved secret's name in capitals, like API_TOKEN" });
 const minutes = z.int().min(1).max(LONGEST_WAIT_MINUTES);
-// ------------------------------------------------------------------ the saved drawing
-/** Where a zone sits on the canvas. */
 export const flowZoneSchema = z.strictObject({
     x: z.int().min(-20000).max(20000), y: z.int().min(-20000).max(20000), w: z.int().min(220).max(1200), h: z.int().min(160).max(1600), color: z.enum(FLOW_COLORS),
 });
 const stageRef = zoneId;
-/** One answer a sort zone can pick: its name, what it means (what Jev reads), and the zone it sends the card to. */
 export const flowSortAnswerSchema = z.strictObject({ answer: words("answer", "flowAnswer").min(1), means: words("means", "flowSortMeans").min(1), to: stageRef });
-/** Something else a sort zone notes on the card: a score on a scale of levels, or a yes/no. */
 export const flowSortNoteSchema = z.discriminatedUnion("kind", [
     z.strictObject({ id: zoneId, kind: z.literal("score"), question: words("question", "flowSortQuestion").min(1), levels: z.array(words("level", "flowSortLevel").min(1)).min(SORT_LEVELS_MIN).max(SORT_LEVELS_MAX) }),
     z.strictObject({ id: zoneId, kind: z.literal("yes-no"), question: words("question", "flowSortQuestion").min(1), levels: z.null() }),
 ]);
-/** How a sort answer is named to Jev: its words as a short key (the request's criteria, and the choice Jev returns). */
 export const sortKeyOf = (answer) => answer.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "answer";
-/** The key of a sort zone's question in its Jev request (a choice over its answers), and of each thing it also notes. */
 export const SORT_ROUTE_KEY = "route";
 export const sortNoteKeyOf = (noteId) => `note_${noteId.replace(/-/g, "_")}`;
-/** sort: the question, its answers, how sure Jev must be to act alone (0.5–0.99), and what else it notes. */
 export const flowSortSchema = z.strictObject({
     question: words("question", "flowSortQuestion").min(1),
     answers: z.array(flowSortAnswerSchema).min(SORT_ANSWERS_MIN).max(SORT_ANSWERS_MAX),
     sureAt: z.number().min(SURE_AT_MIN).max(SURE_AT_MAX),
     notes: z.array(flowSortNoteSchema).max(SORT_NOTES_MAX),
 });
-/** request: what is called. The address's scheme and host are fixed; fill-ins go in its path and query (encoded), headers and body. */
 export const flowRequestSchema = z.strictObject({
     method: z.enum(FLOW_METHODS), url: words("url", "flowUrl").min(1),
     headers: z.object({}).catchall(words("header", "flowHeader").min(1)), body: words("body", "flowBody").min(1).nullable(),
 });
-/** email: who it goes to, the subject and the text — all with fill-ins. */
 export const flowEmailSchema = z.strictObject({ to: words("to", "flowEmailTo").min(1), subject: words("subject", "flowEmailSubject").min(1), body: words("body", "flowBody").min(1) });
-/** tool: which of the project's tools (MCP servers), which of its functions, and the arguments as JSON with fill-ins. */
 export const flowToolSchema = z.strictObject({ server: words("server", "flowToolServer").min(1), name: words("name", "flowToolName").min(1), args: words("args", "flowToolArgs").min(1) });
-/** wait: for a reply to the card's email (next: replied, onFail: no reply in time), for a set time (then next), or until
- * the clock is between `from` and `to` (like 22:00–06:00), in the computer's time zone unless one is named. */
 export const flowWaitSchema = z.strictObject({
     for: z.enum(FLOW_WAIT_FOR),
-    /** reply, time: how long (a minute to 30 days); hours: 0. */
     minutes: z.int().min(0).max(LONGEST_WAIT_MINUTES),
     from: z.string().regex(CLOCK, { error: "must be a time like 22:00" }).optional(),
     to: z.string().regex(CLOCK, { error: "must be a time like 06:00" }).optional(),
     timeZone: z.string().min(1).max(TEXT_LIMITS.flowTimeZone).optional(),
 });
-/** A choose zone's option: its button's words, and the zone it leads to (FLOW_END closes the card as Ignored). */
 export const flowChoiceSchema = z.strictObject({ label: words("label", "flowChoice").min(1), to: z.union([stageRef, z.literal(FLOW_END)]) });
-/** A script's or subagent's answer and the zone it leads to. */
 export const flowRouteSchema = z.strictObject({ answer: z.string().min(1).max(TEXT_LIMITS.flowAnswer).regex(/^[^\n]*$/, { error: "must be one line" }), to: stageRef });
-/** A time limit on a zone: after this long, the person it waits on is reminded; a Holding, "Person decides" or "Person
- * chooses" zone can also move the card on (`to`). */
 const limitRemind = z.strictObject({ minutes, to: z.null() });
 const limitMove = z.strictObject({ minutes, to: stageRef.nullable() });
-/**
- * The 18 zones, given how long instructions may be (written now: TEXT_LIMITS.flowInstructions; saved earlier: any
- * length). Every zone carries the same first fields (null where a kind has no use for them) and its own after them, in
- * the order the store has always saved them: a zone's digest is its JSON, so the order is part of the contract.
- */
 function zoneSchemas(instructions) {
     const text = instructions.min(1).regex(PLAIN, { error: "can't contain control characters" });
     const said = text.nullable(), nil = z.null();
@@ -149,34 +99,23 @@ const definitionOf = (instructions) => versioned(FLOW_DEFINITION_VERSION, {
     start: stageRef,
     stages: z.array(z.discriminatedUnion("kind", zoneSchemas(instructions))).min(1).max(FLOW_ZONES_MAX),
 });
-/** A flow's drawing as it is written now: what the canvas saves and steps become. */
 export const flowDefinitionSchema = definitionOf(limited("instructions", "flowInstructions"));
-/** A drawing saved earlier: the same, except instructions keep the length they were saved with (a limit is for writing). */
 export const savedFlowDefinitionSchema = definitionOf(z.string());
 export const flowStageSchema = flowDefinitionSchema.shape.stages.element;
-// ------------------------------------------------------------------ steps (and the flow file's zones)
-/** A short field: bounded by its TEXT_LIMITS entry. Control and hidden characters in what a step or trigger says are
- * refused after parsing (the saved drawing's schema and the trigger reader name them), not restated per field here. */
 const short = (key) => z.string().max(TEXT_LIMITS[key]);
 const ref = short("flowRef");
 const duration = z.union([z.string().max(TEXT_LIMITS.flowDuration), minutes]);
 const clockWritten = z.string().regex(CLOCK_WRITTEN, { error: "must be a time like 22:00" });
-/** A step's route: an answer and the step it goes to. */
 export const flowStepRouteSchema = z.strictObject({ answer: z.string().min(1).max(TEXT_LIMITS.flowAnswer), goesTo: ref });
-/** A sort step's answer: its name, what it means (a few words Jev reads) and the step it goes to. */
 export const flowStepAnswerSchema = z.strictObject({ answer: short("flowAnswer").min(1), means: short("flowSortMeans").optional(), goesTo: ref });
-/** Something else a sort step notes: a score (levels lowest first) or a yes/no. */
 export const flowStepNoteSchema = z.strictObject({
     id: zoneId.optional(), question: short("flowSortQuestion").min(1), kind: z.enum(["score", "yes-no"]).optional(),
     levels: z.array(short("flowSortLevel")).min(SORT_LEVELS_MIN).max(SORT_LEVELS_MAX).optional(),
 });
-/** A choose step's button: its words, and the step it goes to ("end", or none, ignores the card). */
 export const flowStepOptionSchema = z.strictObject({ label: short("flowChoice").min(1), goesTo: ref.optional() });
-/** Every field a step may give, each once; the kinds below say which are theirs. */
 const STEP_FIELDS = {
     instructions: limited("instructions", "flowInstructions"),
     planning: z.enum(FLOW_PLANNING),
-    /** approval: a sign-in name, "me", "owner" (the flow's owner), or "anyone" (or null). */
     decider: short("flowDecider").nullable(),
     message: limited("message", "flowMessage"),
     close: z.boolean(),
@@ -184,11 +123,9 @@ const STEP_FIELDS = {
     runIn: z.enum(FLOW_RUN_IN),
     routes: z.array(flowStepRouteSchema).max(ROUTES_MAX),
     secrets: z.array(secretName).max(SECRETS_MAX),
-    /** check: the script starts a browser (Playwright's Chromium); it runs only once a person approves browser use for the flow (flow-browser.ts). */
     browser: z.boolean(),
     question: short("flowSortQuestion"),
     answers: z.array(flowStepAnswerSchema).min(SORT_ANSWERS_MIN).max(SORT_ANSWERS_MAX),
-    /** A percentage (80) or a fraction (0.8). */
     sureAt: z.number().min(SURE_AT_MIN).max(SURE_AT_PERCENT_MAX),
     alsoNote: z.array(flowStepNoteSchema).max(SORT_NOTES_MAX),
     method: z.enum(FLOW_METHODS),
@@ -199,20 +136,15 @@ const STEP_FIELDS = {
     subject: short("flowEmailSubject"),
     server: short("flowToolServer"),
     tool: short("flowToolName"),
-    /** An object, or the same as JSON text. */
     args: z.union([z.object({}).catchall(z.unknown()), short("flowToolArgs")]),
     waitFor: z.enum(FLOW_WAIT_FOR),
-    /** Like "3 days" or "4 hours" (up to 30 days), or minutes. */
     wait: duration,
     from: clockWritten,
     until: clockWritten,
     timeZone: z.string().min(1).max(TEXT_LIMITS.flowTimeZone),
-    /** squash, merge or rebase; true is squash. */
     merge: z.union([z.boolean(), z.enum(FLOW_MERGE_METHODS)]),
-    /** Like "2 days" ("none" removes it), or minutes. */
     remindAfter: duration,
     thenMoveTo: ref,
-    /** A subagent's short name; "nobody" takes one off. */
     subagent: z.string().min(1).max(TEXT_LIMITS.flowSubagent),
     reply: z.boolean(),
     options: z.array(flowStepOptionSchema).min(CHOICES_MIN).max(CHOICES_MAX),
@@ -226,7 +158,6 @@ const STEP_FIELDS = {
 function optional(keys) {
     return Object.fromEntries(keys.map(key => [key, STEP_FIELDS[key].optional()]));
 }
-/** What each kind of step takes, besides its id, title and kind. */
 const STEP_KINDS = {
     inbox: ["next", "ifFails", "remindAfter", "thenMoveTo"],
     task: ["instructions", "planning", "repo", "next", "ifFails", "remindAfter"],
@@ -248,7 +179,6 @@ const STEP_KINDS = {
     done: [],
 };
 const stepOf = (kind) => z.strictObject({
-    /** Keeps an existing zone by its id, or names a new one so other steps can point at it. */
     id: z.string().min(1).max(TEXT_LIMITS.flowStepId).optional(),
     title: short("flowTitle").min(1),
     kind: z.literal(kind),
@@ -260,23 +190,15 @@ const STEPS = {
     tool: stepOf("tool"), wait: stepOf("wait"), subagent: stepOf("subagent"), send: stepOf("send"), choose: stepOf("choose"), done: stepOf("done"),
 };
 const stepList = [STEPS.inbox, STEPS.task, STEPS.report, STEPS.approval, STEPS.check, STEPS["pull-request"], STEPS.update, STEPS.notify, STEPS.sort, STEPS.draft, STEPS.request, STEPS.email, STEPS.tool, STEPS.wait, STEPS.subagent, STEPS.send, STEPS.choose, STEPS.done];
-/** A step as the lead, `toolroll flows create/edit`, starters, kits and the gallery describe it, one schema per kind. */
 export const flowStepSchema = z.discriminatedUnion("kind", stepList);
-/** A flow's steps, in order: what `flowFromSteps` reads. */
 export const flowStepsSchema = z.strictObject({ steps: z.array(flowStepSchema).min(1).max(FLOW_ZONES_MAX) });
-/** Where a flow file's zone sits on the canvas. */
 const fileAt = z.strictObject({ x: z.number().optional(), y: z.number().optional(), w: z.number().optional(), h: z.number().optional(), color: z.enum(FLOW_COLORS).optional() }).describe("Where the zone sits on the canvas.");
 const fileZone = (step) => step.extend({ id: zoneId, at: fileAt.optional() });
-/** A flow file's zone: a step with its id and its place on the canvas. */
 export const flowFileZoneSchema = z.discriminatedUnion("kind", [
     fileZone(STEPS.inbox), fileZone(STEPS.task), fileZone(STEPS.report), fileZone(STEPS.approval), fileZone(STEPS.check), fileZone(STEPS["pull-request"]),
     fileZone(STEPS.update), fileZone(STEPS.notify), fileZone(STEPS.sort), fileZone(STEPS.draft), fileZone(STEPS.request), fileZone(STEPS.email),
     fileZone(STEPS.tool), fileZone(STEPS.wait), fileZone(STEPS.subagent), fileZone(STEPS.send), fileZone(STEPS.choose), fileZone(STEPS.done),
 ]);
-/**
- * D5 (schema v117): a subagent step was a "teammate" step, naming its "teammate", and a flow file's needs said
- * "teammate:<handle>". Saved drawings, step lists and flow files from before still read: the old words mean the new ones.
- */
 export function legacySubagentStep(step) {
     if (step === null || typeof step !== "object" || Array.isArray(step))
         return step;
@@ -286,9 +208,7 @@ export function legacySubagentStep(step) {
     const { teammate, ...rest } = row;
     return { ...rest, ...(rest["kind"] === "teammate" ? { kind: "subagent" } : {}), ...(teammate !== undefined && rest["subagent"] === undefined ? { subagent: teammate } : {}) };
 }
-/** A flow file's need as it was written before D5 ("teammate:maya"), in today's words. */
 export const legacyFlowNeed = (need) => typeof need === "string" && need.startsWith("teammate:") ? `subagent:${need.slice(9)}` : need;
-/** The keys people and models write for the ones a step means: refusals suggest them (contract.ts). */
 export const FLOW_ALIASES = {
     aliases: {
         onFail: ["ifFails", "ifNotSure", "ifNoReply", "ifReplied"], ifFails: ["ifNotSure", "ifNoReply", "ifReplied"], to: ["goesTo", "thenMoveTo"], goto: ["goesTo"], target: ["goesTo"],
@@ -297,13 +217,10 @@ export const FLOW_ALIASES = {
         stages: ["steps", "zones"], zone: ["at"], label: ["title"],
     },
 };
-// ------------------------------------------------------------------ triggers
 const zoneRef = { zone: z.string().max(TEXT_LIMITS.flowRef).optional() };
-/** v126: who signs a webhook's deliveries (webhook-signing.ts); `none` is the secret address alone. */
 export const WEBHOOK_SENDERS = ["none", "standard", "github-style", "sentry", "vercel"];
 const webhookSender = z.enum(WEBHOOK_SENDERS);
 const delivery = z.enum(["poll", "webhook"]);
-/** A trigger's settings as they are given: the console, `toolroll flows trigger add`, a flow file, a template, the lead. */
 const TRIGGER_INPUTS = {
     button: z.strictObject({ kind: z.literal("button"), label: short("triggerButton").min(1), questions: z.union([z.array(short("triggerQuestion")).max(6), limited("questions", "triggerDescription")]).optional(), ...zoneRef }),
     schedule: z.strictObject({
@@ -316,34 +233,20 @@ const TRIGGER_INPUTS = {
     }),
     linear: z.strictObject({ kind: z.literal("linear"), team: short("triggerTeam").optional(), state: short("triggerState").optional(), label: short("triggerLabel").optional(), delivery: delivery.optional(), ...zoneRef }),
     flow: z.strictObject({ kind: z.literal("flow"), flow: z.int().min(1), when: z.string().max(TEXT_LIMITS.flowRef).optional(), ...zoneRef }),
-    /** v126: `sender` signs it; Sentry and Vercel read their own payloads (scoped by `project`, Vercel's also by `team`),
-     * the others pick `titleField`, `bodyField`, `idField` and `urlField` from the JSON. */
     webhook: z.strictObject({ kind: z.literal("webhook"), title: short("triggerWebhookTitle").optional(), titleField: short("triggerWebhookField").optional(), bodyField: short("triggerWebhookField").optional(),
         sender: webhookSender.optional(), project: short("triggerWebhookScope").optional(), team: short("triggerWebhookScope").optional(), idField: short("triggerWebhookField").optional(), urlField: short("triggerWebhookField").optional(), ...zoneRef }),
     email: z.strictObject({ kind: z.literal("email"), folder: short("triggerFolder").optional(), sender: short("triggerSender").optional(), subject: short("triggerSubject").optional(), ...zoneRef }),
     "plane-review": z.strictObject({ kind: z.literal("plane-review"), at: z.string().regex(/^\d{1,2}:\d{2}$/, { error: "must be a time like 07:30" }).optional(), timeZone: z.string().max(TEXT_LIMITS.flowTimeZone).optional(), ...zoneRef }),
 };
 export const triggerInputSchema = z.discriminatedUnion("kind", [TRIGGER_INPUTS.button, TRIGGER_INPUTS.schedule, TRIGGER_INPUTS.github, TRIGGER_INPUTS.linear, TRIGGER_INPUTS.flow, TRIGGER_INPUTS.webhook, TRIGGER_INPUTS.email, TRIGGER_INPUTS["plane-review"]]);
-/** A flow file's trigger: one that names nothing on the installation it was made on (no chat channel, no other flow). */
 export const flowFileTriggerSchema = z.discriminatedUnion("kind", [TRIGGER_INPUTS.button, TRIGGER_INPUTS.schedule, TRIGGER_INPUTS.github, TRIGGER_INPUTS.linear, TRIGGER_INPUTS.webhook, TRIGGER_INPUTS.email, TRIGGER_INPUTS["plane-review"]]);
-/** The lead's trigger settings: no webhook (its address is made on the console), and no delivery setting; another flow is `follow`. */
 export const leadTriggerSchema = z.discriminatedUnion("kind", [
     TRIGGER_INPUTS.button, TRIGGER_INPUTS.schedule, TRIGGER_INPUTS.github.omit({ delivery: true }), TRIGGER_INPUTS.linear.omit({ delivery: true }),
     TRIGGER_INPUTS.flow.omit({ flow: true }).extend({ follow: z.int().min(1).describe("The other flow's id (get_flows).") }), TRIGGER_INPUTS.email, TRIGGER_INPUTS["plane-review"],
 ]);
 const ZONE_OR_NULL = { zone: zoneId.nullable() };
-/**
- * v115: the exact task a schedule files each time — what a routine was before routines became scheduled flows. Its
- * terms are copied into each firing's scope unchanged; `costCeilingUsd` caps what its tasks spend in a rolling 7 days
- * and a firing waits while the last task is unfinished. `approval` is a routine's approval carried over whole (the
- * digest the approver signed over these terms, this schedule and project, and the agents it froze): while it still
- * verifies, each firing is approved as the routine's were; otherwise each firing is an ordinary proposal under the
- * project's approval rules. Only the v115 migration carries an approval; a template or a recipe makes one with none
- * (createScheduledFlow), and no trigger settings a person or a flow file gives can carry one.
- */
 export const standingOrderSchema = z.strictObject({
     stem: z.string().regex(/^[a-z0-9][a-z0-9-]{0,40}$/),
-    // The terms exactly as they were approved: each firing's filing checks them again, as every filing is checked.
     goal: z.string().max(8_000),
     outOfScope: z.string().max(8_000).nullable(),
     touches: z.array(z.string().max(800)).max(200),
@@ -353,48 +256,35 @@ export const standingOrderSchema = z.strictObject({
     costCeilingUsd: z.number().nullable(),
     singleFlight: z.literal(true),
     filedBy: z.string().min(1).nullable(),
-    /** The routine it came from: that routine's earlier tasks still count toward one-at-a-time and the ceiling. */
     routine: z.int().nullable(),
     approval: z.strictObject({ digest: z.string().min(1), by: z.string().nullable(), at: z.string().min(1), profileJson: z.string().min(1), routeJson: z.string().min(1) }).nullable(),
-    /** The nightly full check on main (release-once.md, part 3): each firing files a check-only task at main's head, its
-     * approval bound to the release check grant and the fenced check access. */
     check: z.strictObject({ kind: z.literal("main-full"), grant: z.strictObject({ id: z.int(), digest: z.string().min(1) }), access: z.literal("sandboxed") }).optional(),
 });
-/** A trigger as it is saved (`configJson`), one schema per kind. */
 export const triggerConfigSchema = z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("button"), label: z.string().min(1).max(TEXT_LIMITS.triggerButton), questions: z.array(z.string().min(1).max(TEXT_LIMITS.triggerQuestion)).min(1).max(6), ...ZONE_OR_NULL }),
-    /** `script`: run this project script on the schedule and make a card of each item it prints, instead of one card titled `title`. */
     z.strictObject({ kind: z.literal("schedule"), schedule: z.string().min(1), title: z.string().min(1).max(TEXT_LIMITS.triggerTitle), description: z.string().max(TEXT_LIMITS.triggerDescription).nullable(), ...ZONE_OR_NULL, script: scriptName.optional(), secrets: z.array(secretName).min(1).max(SECRETS_MAX).optional(), order: standingOrderSchema.optional() }),
     z.strictObject({ kind: z.literal("github"), repo: z.string().min(1).max(TEXT_LIMITS.triggerGithubRepo), watch: z.enum(["issues", "pulls", "checks"]), label: z.string().max(TEXT_LIMITS.triggerLabel).nullable(), branch: z.string().max(TEXT_LIMITS.triggerBranch).nullable(), from: z.enum(["team", "anyone"]), delivery, ...ZONE_OR_NULL }),
     z.strictObject({ kind: z.literal("linear"), team: z.string().max(TEXT_LIMITS.triggerTeam).nullable(), state: z.string().max(TEXT_LIMITS.triggerState).nullable(), label: z.string().max(TEXT_LIMITS.triggerLabel).nullable(), delivery, ...ZONE_OR_NULL }),
     z.strictObject({ kind: z.literal("flow"), flow: z.int().min(1), when: zoneId, ...ZONE_OR_NULL }),
-    /** v126: a webhook saved before its sender was chosen reads unsigned, with no scope and no identity or link field. */
     z.strictObject({ kind: z.literal("webhook"), title: z.string().min(1).max(TEXT_LIMITS.triggerWebhookTitle), titleField: z.string().max(TEXT_LIMITS.triggerWebhookField).nullable(), bodyField: z.string().max(TEXT_LIMITS.triggerWebhookField).nullable(),
         sender: webhookSender.optional(), project: z.string().max(TEXT_LIMITS.triggerWebhookScope).nullable().optional(), team: z.string().max(TEXT_LIMITS.triggerWebhookScope).nullable().optional(),
         idField: z.string().max(TEXT_LIMITS.triggerWebhookField).nullable().optional(), urlField: z.string().max(TEXT_LIMITS.triggerWebhookField).nullable().optional(), ...ZONE_OR_NULL }),
-    /** `sender`: addresses or domains, comma-separated; `subject`: words the subject must contain. */
     z.strictObject({ kind: z.literal("email"), folder: z.string().min(1).max(TEXT_LIMITS.triggerFolder), sender: z.string().max(TEXT_LIMITS.triggerSender).nullable(), subject: z.string().max(TEXT_LIMITS.triggerSubject).nullable(), ...ZONE_OR_NULL }),
-    /** A channel in a chat app; `binding` is the pairing of the person who connected it (whose chat answers there). */
     z.strictObject({ kind: z.literal("chat"), app: z.enum(["slack", "discord", "teams", "telegram"]), installation: z.string().min(1), chat: z.string().min(1), binding: z.int(), ...ZONE_OR_NULL }),
-    /** `schedule`: always daily, in the routines' form ("daily:07:30@Europe/London"). */
     z.strictObject({ kind: z.literal("plane-review"), schedule: z.string().min(1), ...ZONE_OR_NULL }),
 ]);
-// ------------------------------------------------------------------ the flow file
 export const FLOW_FILE_FORMAT = "toolroll-flow";
 export const FLOW_FILE_VERSION = 1;
-/** Something the import asks for: `{{param.<id>}}` in a zone or trigger is replaced by its value. */
 export const flowFileParameterSchema = z.strictObject({
     id: z.string().regex(PARAMETER_ID, { error: "must be a short id: lowercase letters, numbers and dashes" }),
     about: visible("about", "flowParameter").min(1).describe("The question the import asks."),
     default: visible("default", "flowParameter").optional(),
     optional: z.boolean().optional().describe("May be left empty (the field is then left out)."),
 });
-/** A project script a zone or schedule runs. Imported held until a person approves it. */
 export const flowFileScriptSchema = z.strictObject({
     name: scriptName, about: limited("about", "flowScriptAbout"), language: z.enum(SCRIPT_LANGUAGES).optional().describe("Shell when left out."), timeoutMinutes: z.int().min(1).max(60).optional().describe("15 when left out."),
     body: limited("body", "flowScriptBody").optional(), file: limited("file", "flowScriptFile").optional().describe("A path inside the project, run instead of a body."),
 });
-/** A flow exported as readable JSON (*.toolroll-flow.json): docs/flow-file.schema.json is this schema. */
 export const flowFileSchema = versioned(FLOW_FILE_VERSION, {
     format: z.literal(FLOW_FILE_FORMAT),
     name: visible("name", "flowName").min(1),
@@ -405,8 +295,6 @@ export const flowFileSchema = versioned(FLOW_FILE_VERSION, {
     triggers: z.array(flowFileTriggerSchema).max(10).optional(),
     scripts: z.array(flowFileScriptSchema).max(20).optional(),
 });
-/** docs/flow-file.schema.json: the flow file's schema as published for people and other tools, generated from
- * flowFileSchema (`npx tsx scripts/flow-file-schema.ts`); flow.test.ts checks the file is exactly this. */
 export function flowFileJsonSchema() {
     return {
         $schema: "https://json-schema.org/draft/2020-12/schema",

package/dist/contracts/gateway-tools.js

@@ -1,13 +1,3 @@
-/**
- * The MCP gateway's tools (docs/plans/zod-revamp.md, item 5; docs/mcp-gateway-spec.md): one input schema per tool and
- * one output schema for what each returns. The input schema is the `inputSchema` tools/list advertises and the check
- * a call is read with before its handler runs (mcp.ts): a call it refuses is a JSON-RPC InvalidParams error naming each
- * path, never a tool refusal. The assignment tools' schemas are also what `toolroll assignment` reads its flags with
- * (assignment-adapters.ts), so the CLI and the gateway take exactly the same arguments.
- *
- * A coordinator names a project by its path and a task by `ref`; the lead's tools (lead-tools.ts) say r1 and `task`.
- * Output schemas describe a result's top level: checked in tests, logged when a result disagrees, never a refusal.
- */
 import { z } from "zod";
 import { TEXT_LIMITS } from "../text-limits.js";
 import { envelopeSchema } from "./cli.js";
@@ -18,7 +8,6 @@ const projectPath = text("projectPath").min(1);
 const gatewayRepo = text("gatewayRepo").min(1);
 const consumer = z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]{0,63}$/, { error: "must be a stable consumer name: lowercase letters, digits and hyphens" });
 const limit = (most) => z.int().min(1).max(most);
-/** The assignment tools, by the operation `toolroll assignment` names them. */
 export const ASSIGNMENT_INPUTS = {
     show: z.strictObject({ ref }),
     updates: z.strictObject({ after: z.int().min(0).optional(), limit: limit(100).optional() }),
@@ -59,13 +48,11 @@ export const GATEWAY_TOOL_INPUTS = {
         deliverable: z.enum(["branch", "report"]).optional(),
     }),
 };
-// ------------------------------------------------------------- outputs
 const str = z.string();
 const int = z.number().int();
 const list = z.array(z.unknown());
 const rows = (shape) => z.array(z.looseObject(shape));
 const proposed = z.looseObject({ proposal: int, kind: z.enum(["next", "reserve", "hold", "unhold", "scope", "cancel", "answer"]), awaiting: str });
-/** One assignment (assignment.ts `AssignmentSnapshot`). */
 const assignmentOutput = z.looseObject({ version: z.literal(1), rootId: str, activeTaskId: str, title: str, state: str, detail: str, attention: z.array(str) });
 export const GATEWAY_TOOL_OUTPUTS = {
     get_project_context: repositoryContextOutput,
@@ -95,14 +82,6 @@ export const GATEWAY_TOOL_OUTPUTS = {
     get_contract: z.looseObject({ contract: str }),
     file_proposal: z.looseObject({ ref: str, replayed: z.boolean(), admission: str }),
 };
-// ------------------------------------------------------------- a person's tools
-/**
- * The tools a PERSON's API token sees over the HTTP gateway (mcp-person.ts). Each call becomes the exact `toolroll`
- * command line the same person could type, run on the server under their own principal (operate.ts `runOperateAs`):
- * the command's own authorization, project grants and attribution apply, and its `--json` envelope is the answer.
- * Two reads keep the coordinator's names and arguments; the rest are new. Every value that lands in a command line
- * may not begin with "-", so an argument can never be read as a flag.
- */
 const notFlag = (schema) => schema.regex(/^[^-]/, { error: "must not begin with -" });
 const taskRef = notFlag(ref);
 const runId = z.int().min(1);
@@ -117,7 +96,6 @@ export const PERSON_TOOL_INPUTS = {
         deliverable: z.enum(["branch", "report"]).optional(),
     }),
 };
-/** The command's `--json` envelope (contracts/cli.ts); a refusal is `ok: false` with its stable reason. */
 const envelope = envelopeSchema;
 export const PERSON_TOOL_OUTPUTS = {
     status: envelope,

package/dist/contracts/handoff.js

@@ -1,17 +1,7 @@
-/**
- * The handoff artifact (`handoff.json`, M6.10): one schema for the machine's own statement of where a finished run
- * left the world — workspace identity, exact base and head, which answered decisions the brief carried, the agent's
- * conclusion and lists, and a freshness stamp a successor proves against the branch. `storeHandoffArtifact` writes it
- * and every reader reads it through `readHandoffArtifact`.
- *
- * The agent's own terminal handoff (`STANDING-ORDERS-DONE-*`, `parseHandoff` in decision.ts) is a different contract;
- * this file records what the machine made of it.
- */
 import { z } from "zod";
 import { readVersioned, versioned } from "./contract.js";
 export const ROUTE_PHASES = ["plan", "build", "repair", "review"];
 export const ROUTE_CHOICES = ["recommended", "override", "pinned", "legacy", "fallback"];
-/** The sealed route leg the run ran as (v47); absent on handoffs written before routes existed. */
 export const handoffRouteSchema = z.strictObject({
     digest: z.string(),
     phase: z.enum(ROUTE_PHASES),
@@ -24,7 +14,6 @@ export const handoffSchema = versioned(HANDOFF_VERSION, {
     taskId: z.string(),
     runId: z.int(),
     provider: z.string(),
-    /** v47: the exact model that ran. Absent on handoffs written before routes existed. */
     model: z.string().optional(),
     route: handoffRouteSchema.optional(),
     sessionId: z.string().nullable(),
@@ -34,26 +23,17 @@ export const handoffSchema = versioned(HANDOFF_VERSION, {
     head: z.string(),
     outcome: z.enum(["built", "no-change"]),
     committed: z.boolean(),
-    /** Decision ids whose answers were in this run's brief — causality, not time. */
     decisionsIncorporated: z.array(z.int()),
-    /** The agent's conclusion — agent-reported, and labeled so by its position here. */
     conclusion: z.string(),
-    /** The agent's structured lists; absent on handoffs written before they existed, read as none. */
     changes: z.array(z.string()).optional(),
     verification: z.array(z.string()).optional(),
     followUps: z.array(z.string()).optional(),
     freshness: z.strictObject({
         stampedAt: z.string(),
-        /** A successor proves this against the branch before trusting anything above. */
         currentAsOf: z.string(),
     }),
 });
 const HANDOFF_FIELDS = Object.keys(handoffSchema.shape).filter(field => field !== "version");
-/**
- * A handoff written before handoffs carried `version` (every handoff through 0.9.34, stamped `schema: 1`), as
- * version 1. The shape is the same; readers then read only the fields they knew and ignored any others, so this keeps
- * exactly the known fields. Anything not stamped `schema: 1` is left as it is, for the schema to refuse by path.
- */
 export function upgradeSchemaOneHandoff(body) {
     if (body["schema"] !== 1)
         return body;
@@ -65,11 +45,9 @@ export function upgradeSchemaOneHandoff(body) {
     return out;
 }
 export const HANDOFF_UPGRADES = { 0: upgradeSchemaOneHandoff };
-/** Read a handoff artifact: version 1 as itself, a `schema: 1` one upgraded, a newer one refused plainly. */
 export function readHandoffArtifact(input) {
     return readVersioned(handoffSchema, input, HANDOFF_UPGRADES);
 }
-/** Read a stored handoff's bytes: JSON first, then the schema. */
 export function parseHandoffArtifact(raw) {
     let body;
     try {