// Generated by `pnpm docs:authoring` from public declarations and TSDoc in src/flow. // Do not edit this file directly. // biome-ignore-all lint/suspicious/noTemplateCurlyInString: documentation strings contain TypeScript examples. export type AuthoringCapability = | "steps" | "data-flow" | "map" | "loop" | "foreach" | "parallel" | "branch" | "workflow" | "advanced-agent" export interface GeneratedAuthoringEntry { readonly symbol: string readonly signature: string readonly documentation: string } export const GENERATED_AUTHORING_REFERENCE: Readonly> = { steps: [ { symbol: "CreateAgentStepOptions", signature: "interface CreateAgentStepOptions { name: string description?: string input?: TInputSchema output?: TOutputSchema model?: string prompt: (args: AgentPromptArgs>) => string asks?: boolean retry?: RetryPolicy maxOutputRepairs?: number maxDurationMs?: number | ((args: { ctx: RunContext }) => number) optional?: boolean maxTokens?: number background?: boolean resumable?: boolean | string | ((args: { ctx: RunContext }) => string) }", documentation: "Agent-step configuration, including model selection, output repair, budgets, isolation, and resumability.\n\nRemarks: An acting agent omits `output`. A reporting agent declares `output`; an asking agent additionally sets\n`asks: true`. Asking cannot be combined with `background`. Static resumable keys cannot be shared by\nexecutions that may overlap.", }, { symbol: "createAgentStep", signature: "createAgentStep(options: CreateAgentStepOptions): AgentStep", documentation: 'Creates an agent step that acts, reports structured output, or interactively asks for information.\n\nRemarks: Omit `output` for an acting step whose result is its side effects. Declare `output` for a reporting\nstep; the agent must call `submit_result` with a matching value. Add `asks: true` when it may submit\nquestionnaire batches before its result. Never combine `asks: true` with `background: true`.\n\nExample: ```ts\nconst review = createAgentStep({\n name: "review",\n input: changeSchema,\n output: reviewSchema,\n prompt: ({ input }) => `Review ${input.path}`,\n})\n```', }, { symbol: "CreateQuestionnaireStepOptions", signature: "interface CreateQuestionnaireStepOptions { name: string description?: string output: TOutputSchema questionnaire?: Questionnaire }", documentation: "Configuration for deterministic, schema-driven user input collection.", }, { symbol: "createQuestionnaireStep", signature: "createQuestionnaireStep(options: CreateQuestionnaireStepOptions): QuestionnaireStep", documentation: 'Questionnaire step (spec §2.4): collect structured input to satisfy an annotated target `output`\nschema. Deterministic and LLM-free — the framework derives a questionnaire from `output` (or uses\nthe `questionnaire` override), blocks with it, and on answers reassembles + validates them into\n`output`.\n\nFor elicitation — an agent that composes and re-batches questions until it can satisfy `output` —\nuse `createAgentStep({ asks: true })` instead.\n\nExample: ```ts\nconst collectTarget = createQuestionnaireStep({\n name: "collect-target",\n output: Type.Object({ environment: Type.String({ title: "Environment" }) }),\n})\n```', }, { symbol: "CreateStepOptions", signature: "interface CreateStepOptions { name: string description?: string input?: TInputSchema output?: TOutputSchema retry?: RetryPolicy maxDurationMs?: number | ((args: { ctx: RunContext }) => number) optional?: boolean run: StepRunFn, InferOutput> }", documentation: "Configuration shared by a function step, including retry, duration, and optional-failure controls.\n\nRemarks: `retry.maxRetry` counts attempts after the first. `optional` should only be used when downstream\nnodes do not require this step's output, because a final failure produces `undefined`.", }, { symbol: "createStep", signature: "createStep(options: CreateStepOptions): FunctionStep", documentation: 'Creates a TypeScript function step whose input and output types are inferred from its TypeBox schemas.\n\nRemarks: The engine validates `input` before calling `run` and validates the returned value against `output`.\nThe callback may use `ctx` for earlier results, `abortSignal` for cancellation, and `logger` for\nstructured run-log messages.\n\nExample: ```ts\nconst summarize = createStep({\n name: "summarize",\n input: Type.Array(Type.String()),\n output: Type.String(),\n run: ({ input }) => input.join("\\n"),\n})\n```', }, ], "data-flow": [ { symbol: "ScopeFrame", signature: 'interface ScopeFrame { readonly kind: "loop" | "foreach" | "branch-arm" | "parallel" | "workflow" readonly name: string readonly iteration?: number readonly itemIndex?: number readonly itemCount?: number readonly input: unknown }', documentation: "One enclosing construct's position and input, exposed through RunContext.scope\n(iteration-context spec, Feature 1). Values are pure data derived from the engine's walk state:\ndeterministic, identical on resume (rebuilt as re-entry descends), and identical regardless of\nconcurrency interleaving. Retry attempt is deliberately NOT here (spec 1.5): loop iteration and\nretry attempt are different axes, and conflating them would invite resume keys that fork per retry.", }, { symbol: "RunContext.scope", signature: "RunContext.scope(name?: string): ScopeFrame | undefined", documentation: "The enclosing construct frames (iteration-context spec 1.2/1.6). Called with no argument it\nreturns the NEAREST enclosing frame; called with a construct name it walks outward to that\nconstruct (a nested loop-in-foreach is addressable by name, not just the innermost). Returns\n`undefined` at the top level, or when no enclosing construct carries the given name.", }, { symbol: "RunContext.getStepResult", signature: "RunContext.getStepResult(stepName: string): T | undefined", documentation: "Look up a prior step's or construct's output by its BARE name (names-only addressing, spec 4.1) —\nresolved lexically to the nearest enclosing scope that declares it, walking outward from the\ncalling step's own scope to the root. A declared name whose step has not been reached, or was\nskipped, reads `undefined` — a structural fact, not an error. A name NO enclosing scope declares\nTHROWS (a provable wiring bug, spec 4.2), as does any argument carrying path syntax (`/`, `#`,\n`@`) — the path form was removed outright. Paths remain identity in the event log and resume\naddressing; they are no longer an authoring query language.", }, { symbol: "RunContext.getInitData", signature: "RunContext.getInitData(): T | undefined", documentation: "The workflow's initial input, or `undefined` when the workflow has no input schema.", }, { symbol: "CreateWorkflowOptions", signature: "interface CreateWorkflowOptions { name: string description?: string input?: TInputSchema defaultModel?: string maxConcurrency?: number }", documentation: "Root workflow configuration. The optional TypeBox `input` schema validates initial run data and\ninfers its author-facing type; `maxConcurrency` defaults to 4.", }, { symbol: "WorkflowBuilder.then", signature: "WorkflowBuilder.then(step: StepDefinition): WorkflowBuilder", documentation: "Append a step node in sequence. Its input is the previous node's output and is validated against\nthe step's input schema.", }, { symbol: "WorkflowBuilder.commit", signature: "WorkflowBuilder.commit(): WorkflowDefinition", documentation: "Finalize and validate the workflow definition.", }, { symbol: "createWorkflow", signature: "createWorkflow(options: CreateWorkflowOptions): WorkflowBuilder", documentation: 'Starts a fluent workflow definition and returns its builder. Append at least one node and call\n`.commit()` to obtain a loadable WorkflowDefinition.\n\nRemarks: Linear hand-off passes every node\'s output to the next node. Use `ctx.getStepResult()` for a\nnon-adjacent result, `ctx.getInitData()` for the root input, and `ctx.scope()` for enclosing\nloop/foreach/branch/parallel input. Node names must be unique and cannot contain `/`, `#`, or `@`.\n\nExample: ```ts\nexport default createWorkflow({ name: "review", input: requestSchema })\n .then(loadRequest)\n .then(reviewRequest)\n .commit()\n```\n\nThrows: If the workflow is empty, names are invalid or duplicated, concurrency exceeds its ceiling,\nor incompatible execution options are combined.', }, ], map: [ { symbol: "MapFn", signature: "type MapFn = (ctx: RunContext) => TOutput", documentation: "A `.map()` transform (spec §3.7): derives the next step's input purely from the run context —\nprior step outputs (`getStepResult`) and workflow init data (`getInitData`). Pure and\ndeterministic; it has no host, network, or LLM access beyond `ctx`. The returned value is\nvalidated by the downstream step's input schema, so a map declares no schema of its own.", }, { symbol: "MapOptions", signature: "interface MapOptions { name?: string }", documentation: "Options for a `.map()` construct.", }, { symbol: "WorkflowBuilder.map", signature: "WorkflowBuilder.map(transform: MapFn, options?: MapOptions): WorkflowBuilder", documentation: "Insert a pure transform whose result becomes the next node's input via the linear hand-off\n(spec §3.7). Reads earlier, non-adjacent outputs via `ctx.getStepResult` / `ctx.getInitData`.", }, ], loop: [ { symbol: "LoopCondition", signature: "type LoopCondition = (ctx: RunContext, lastOutput: unknown) => boolean", documentation: "A pure loop predicate (spec §3.3) over the run context and the body's most recent output.\n`lastOutput` is the RAW body output (loop-feedback spec 2.4): it may be `undefined` when the round\nproduced nothing (a failed `optional` tail) even though the fed-back value passes through defined —\na predicate may legitimately need to know the round came up empty. The fed value itself is readable\nas `ctx.scope(loopName)?.input`.", }, { symbol: "LoopOptions", signature: "interface LoopOptions { name?: string maxIterations?: number }", documentation: "Options shared by `.dowhile()` and `.dountil()`; `maxIterations` defaults to 100.", }, { symbol: "WorkflowBuilder.dowhile", signature: "WorkflowBuilder.dowhile(body: WorkflowDefinition, condition: LoopCondition, options?: LoopOptions): WorkflowBuilder", documentation: "Loop (spec §3.3): run `body`, then repeat while `condition` holds.\n\n**Feedback** (loop-feedback spec, Feature 2): each iteration's body receives the PREVIOUS\niteration's body output as its input — the first iteration receives the value flowing into the\nloop from upstream. It is ordinary, schema-validated step I/O, so the body's input and output\nschemas must agree (checked at `.commit()` where both are declared). An iteration that produces\nno output (a failed `optional` tail) passes its input through unchanged, and the loop's own\noutput is the final effective value — readable downstream by the loop's bare name.", }, { symbol: "WorkflowBuilder.dountil", signature: "WorkflowBuilder.dountil(body: WorkflowDefinition, condition: LoopCondition, options?: LoopOptions): WorkflowBuilder", documentation: "Run `body`, then repeat until `condition` holds. Feedback follows WorkflowBuilder.dowhile.", }, ], foreach: [ { symbol: "ForeachSelector", signature: "type ForeachSelector = (ctx: RunContext) => readonly unknown[]", documentation: "A pure item selector for a foreach (spec §3.4): derives the collection to iterate from the run\ncontext. Must be side-effect-free and deterministic — a resume re-runs it and relies on it\nyielding the same array so recorded per-item outputs line up by index.", }, { symbol: "ForeachOptions", signature: "interface ForeachOptions { name?: string concurrency?: number feedback?: boolean }", documentation: "Options for `.foreach()`; `concurrency` defaults to 1. Feedback threads each body's output into the\nnext item and therefore requires `concurrency: 1`; the current item remains available through\n`ctx.scope(foreachName)?.input`.", }, { symbol: "WorkflowBuilder.foreach", signature: "WorkflowBuilder.foreach(body: WorkflowDefinition, selector: ForeachSelector, options?: ForeachOptions): WorkflowBuilder", documentation: "Foreach (spec §3.4): run `body` once per item selected by `selector` (pure), with the item as the\nbody's input. `options.concurrency` (default 1) bounds how many items run at once. Output is the\narray of per-item outputs, in item order — independent of completion order.\n\n**Author contract (spec §8.3, \"non-overlapping side effects\"):** at `concurrency > 1`, items run\ngenuinely concurrently — the engine does not, and cannot, know what a step or its subagent will\ntouch, so it enforces nothing here. Give each item's body its own files/branches/external\nresources; anything shared across items (two agents editing the same file, say) must be sequenced\n— either keep `concurrency` at 1, or restructure so the shared resource is touched outside the\nfan-out.", }, ], parallel: [ { symbol: "ParallelOptions", signature: "interface ParallelOptions { name?: string }", documentation: "Options for a `.parallel()` construct.", }, { symbol: "WorkflowBuilder.parallel", signature: "WorkflowBuilder.parallel(arms: readonly StepDefinition[], options?: ParallelOptions): WorkflowBuilder", documentation: "Parallel (spec §3.5): structural fan-out over independent STEPS — every arm runs concurrently\nagainst the same input, bounded only by the workflow ceiling (spec §3.6). Output is an object\nkeyed by each arm's own step name, independent of completion order.\n\n**Author contract (spec §8.3, \"non-overlapping side effects\"):** every arm runs genuinely\nconcurrently — the same rule as `.foreach`'s doc above applies per arm here: no two arms may touch\nthe same file, branch, or external resource, since the engine has no way to detect or prevent two\nconcurrent agents rewriting the same working-tree state. Sequence anything that shares state with\n`.then()` instead of putting it in the same `.parallel([...])`.", }, ], branch: [ { symbol: "BranchCondition", signature: "type BranchCondition = (ctx: RunContext) => boolean", documentation: "A pure branch predicate over the run context; it must be side-effect-free to keep transitions deterministic.", }, { symbol: "BranchOptions", signature: "interface BranchOptions { name?: string }", documentation: "Options for a `.branch()` construct.", }, { symbol: "BranchArmSpec", signature: "type BranchArmSpec = readonly [BranchCondition, WorkflowDefinition]", documentation: "One `.branch()` arm: a pure condition paired with the committed sub-workflow to run when it holds.", }, { symbol: "WorkflowBuilder.branch", signature: "WorkflowBuilder.branch(arms: readonly BranchArmSpec[], options?: BranchOptions): WorkflowBuilder", documentation: "Multi-match branch (spec §3.2): every arm whose condition holds runs sequentially; the node's\noutput is an object keyed by the executed arm names (each arm name is its body's workflow name).", }, ], workflow: [ { symbol: "NestedWorkflowOptions", signature: "interface NestedWorkflowOptions { name?: string }", documentation: "Options for a `.workflow()` nested-workflow construct.", }, { symbol: "WorkflowBuilder.workflow", signature: "WorkflowBuilder.workflow(subWorkflow: WorkflowDefinition, options?: NestedWorkflowOptions): WorkflowBuilder", documentation: "Nested workflow (spec §2.3/§11): run a committed sub-workflow's nodes here, transparently folding\ninto the parent run/log. Output is the sub-workflow's final output. Every step/node name must be\nunique across the flattened tree, so nesting the *same* sub-workflow twice is a `commit()` error.", }, ], "advanced-agent": [ { symbol: "RetryPolicy", signature: "interface RetryPolicy { readonly maxRetry: number readonly backoffMs?: number }", documentation: "Unified repeat policy for a step (spec §9.1). Covers thrown errors and invalid output uniformly;\nan input-schema violation is a deterministic wiring failure and is never retried.", }, { symbol: "CreateAgentStepOptions", signature: "interface CreateAgentStepOptions { name: string description?: string input?: TInputSchema output?: TOutputSchema model?: string prompt: (args: AgentPromptArgs>) => string asks?: boolean retry?: RetryPolicy maxOutputRepairs?: number maxDurationMs?: number | ((args: { ctx: RunContext }) => number) optional?: boolean maxTokens?: number background?: boolean resumable?: boolean | string | ((args: { ctx: RunContext }) => string) }", documentation: "Agent-step configuration, including model selection, output repair, budgets, isolation, and resumability.\n\nRemarks: An acting agent omits `output`. A reporting agent declares `output`; an asking agent additionally sets\n`asks: true`. Asking cannot be combined with `background`. Static resumable keys cannot be shared by\nexecutions that may overlap.", }, { symbol: "CreateStepOptions", signature: "interface CreateStepOptions { name: string description?: string input?: TInputSchema output?: TOutputSchema retry?: RetryPolicy maxDurationMs?: number | ((args: { ctx: RunContext }) => number) optional?: boolean run: StepRunFn, InferOutput> }", documentation: "Configuration shared by a function step, including retry, duration, and optional-failure controls.\n\nRemarks: `retry.maxRetry` counts attempts after the first. `optional` should only be used when downstream\nnodes do not require this step's output, because a final failure produces `undefined`.", }, ], }