@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/pipelines/compile-args.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compiles args: each ref becomes its reference string, and each plain JSON
+ * value becomes `{ "value": ... }`. An array with a ref among its elements
+ * becomes `{ "list": [...] }`, one reference or literal per element. A ref
+ * nested deeper in a literal is an error.
+ */
+import type { ArgValue } from "../contracts/pipeline-document";
+import type { RawArgs } from "./model";
+/** One compiled arg. Throws `AuthoringError`. */
+export declare function compileArg(name: string, value: RawArgs[string]): ArgValue;
+/** The args in order, without undefined values; Proxy spreads expand here. */
+export declare function argEntries(args: RawArgs): [string, RawArgs[string]][];

package/dist/pipelines/compile-chain.d.ts

@@ -0,0 +1,9 @@
+import { type CompileState, type Segment } from "./compile-state";
+import type { TargetSpec } from "./model";
+import type { SourceSite } from "./source";
+type Json = Record<string, unknown>;
+/** Compiles one transition (start, `next` entry or `catch` target); undefined on error. */
+export declare function compileTransition(state: CompileState, spec: TargetSpec, context: object | null, pointer: readonly Segment[], site: SourceSite | null, kind: "start" | "next" | "catch"): Json | undefined;
+/** Wires a finished chain from `flow`. */
+export declare function wireChain(state: CompileState, value: object, site: SourceSite | null): void;
+export {};

package/dist/pipelines/compile-checks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Whole-graph checks run after every chain is wired: unreachable nodes,
+ * decisions without actions, reach-backs to missing nodes, unused reads,
+ * work-item field labels, and chains left out of `flow`. Split checks (scopes, merges, reach-backs into
+ * merged lanes) run in shared-core's validator.
+ */
+import { type CompileState } from "./compile-state";
+import type { BuildIssue } from "./errors";
+export declare function checkReachable(state: CompileState, start: string | undefined): void;
+export declare function checkDecisionActions(state: CompileState): void;
+export declare function checkReaches(state: CompileState): void;
+export declare function checkUnusedReads(state: CompileState): void;
+/** The `workItemFields` map, from the fields used, in order of first use. */
+export declare function workItemFields(state: CompileState): Record<string, string> | undefined;
+/** Finished chains for this pipeline's nodes that were never put in a flow. */
+export declare function unusedChainWarnings(state: CompileState): BuildIssue[];

package/dist/pipelines/compile-state.d.ts

@@ -0,0 +1,30 @@
+import { type BuildIssue } from "./errors";
+import type { ChainData, NodeDef } from "./model";
+import { type ReadTracker } from "./refs";
+import type { SourceSite } from "./source";
+export type Segment = string | number;
+export interface PlacedNode {
+    def: NodeDef;
+    chain: ChainData | undefined;
+    /** The compiled JSON node. */
+    json: Record<string, unknown>;
+}
+export interface CompileState {
+    readonly nodes: Map<string, PlacedNode>;
+    readonly issues: BuildIssue[];
+    readonly sourceMap: Record<string, SourceSite>;
+    readonly tracker: ReadTracker;
+    /** Every chain in `flow`. */
+    readonly usedChains: Set<ChainData>;
+}
+export declare function newState(): CompileState;
+export declare function issue(state: CompileState, site: SourceSite | null, pointer: readonly Segment[], message: string): void;
+export declare function mapSource(state: CompileState, pointer: readonly Segment[], site: SourceSite | null): void;
+/**
+ * Runs authoring code (a callback, an args object) for the JSON at
+ * `pointer`. Errors it throws become build issues there; returns undefined
+ * when it threw.
+ */
+export declare function attempt<T>(state: CompileState, pointer: readonly Segment[], site: SourceSite | null, run: () => T): T | undefined;
+/** Places `def`, or reports a clash with an earlier node of the same id. */
+export declare function place(state: CompileState, def: NodeDef, site: SourceSite | null, pointer: readonly Segment[]): PlacedNode | undefined;

package/dist/pipelines/condition-data.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Conditions at run time: data built by the condition helpers and compiled to
+ * JSON `when` objects once the pipeline is assembled. Compiling checks that
+ * paths inside `some` / `every` / `none` / `count` are relative to the
+ * element and paths outside them aren't, and marks every ref it uses.
+ */
+import type { ComputedFunction, Condition as JsonCondition, ConditionOperator, JsonValue } from "../contracts/pipeline-document";
+import { type RefData } from "./refs";
+import { type SourceSite } from "./source";
+export declare const conditionBrand: unique symbol;
+export declare const computedBrand: unique symbol;
+/** A condition, built with the helpers. Plain JS booleans aren't conditions. */
+export interface Condition {
+    readonly [conditionBrand]: true;
+}
+/** A number computed by `sum`, `avg`, `min`, `max` or `count`. */
+export interface ComputedValue {
+    readonly [computedBrand]: true;
+}
+export type Scope = "document" | "element";
+/** A ref or computed value on the left of a comparison. */
+export type LeftNode = {
+    kind: "ref";
+    ref: RefData;
+} | {
+    kind: "computed";
+    computed: ComputedNode;
+};
+export type RightNode = {
+    kind: "none";
+} | {
+    kind: "ref";
+    ref: RefData;
+} | {
+    kind: "value";
+    value: JsonValue;
+};
+export type ConditionNode = {
+    kind: "all" | "any";
+    items: ConditionData[];
+} | {
+    kind: "not";
+    item: ConditionData;
+} | {
+    kind: "compare";
+    left: LeftNode;
+    op: ConditionOperator;
+    right: RightNode;
+} | {
+    kind: "list";
+    list: RefData;
+    op: ConditionOperator;
+    where: ConditionData;
+};
+export type ComputedNode = {
+    fn: ComputedFunction;
+    refs: RefData[];
+    weights?: number[];
+} | {
+    fn: ComputedFunction;
+    list: RefData;
+    field?: RefData;
+    where?: ConditionData;
+};
+export declare class ConditionData {
+    readonly node: ConditionNode;
+    readonly site: SourceSite | null;
+    constructor(node: ConditionNode, site?: SourceSite | null);
+}
+export declare class ComputedData {
+    readonly node: ComputedNode;
+    readonly site: SourceSite | null;
+    constructor(node: ComputedNode, site?: SourceSite | null);
+}
+export declare function conditionData(value: unknown): ConditionData;
+export declare function requireRef(value: unknown, what: string): RefData;
+/** Compiles a condition to its JSON `when`. Throws `AuthoringError`. */
+export declare function compileCondition(data: ConditionData, scope?: Scope): JsonCondition;

package/dist/pipelines/conditions.d.ts

@@ -0,0 +1,47 @@
+import { type ComputedValue, type Condition } from "./condition-data";
+import type { JsonLiteral, Literal, Placeholder, Ref } from "./ref-types";
+export type { Condition, ComputedValue } from "./condition-data";
+/** What may be compared with a `T`: a reference of that type or a literal. */
+export type Right<T> = [T] extends [never] ? Ref<unknown> | JsonLiteral : Ref<T> | Literal<T>;
+type NumberLeft = Ref<number | null> | ComputedValue;
+type StringLeft = Ref<string | null>;
+export declare function equal<T>(left: Ref<T>, value: NoInfer<Right<T>>): Condition;
+export declare function equal(left: ComputedValue, value: number | Ref<number>): Condition;
+export declare function notEqual<T>(left: Ref<T>, value: NoInfer<Right<T>>): Condition;
+export declare function notEqual(left: ComputedValue, value: number | Ref<number>): Condition;
+export declare function lessThan(left: NumberLeft, value: number | Ref<number>): Condition;
+export declare function lessThanInclusive(left: NumberLeft, value: number | Ref<number>): Condition;
+export declare function greaterThan(left: NumberLeft, value: number | Ref<number>): Condition;
+export declare function greaterThanInclusive(left: NumberLeft, value: number | Ref<number>): Condition;
+export declare function exists(left: Ref<unknown>): Condition;
+export declare function isEmpty(left: Ref<string | readonly unknown[] | object | null>): Condition;
+export declare function contains(left: StringLeft, value: string | Ref<string>): Condition;
+export declare function contains<E>(left: Ref<readonly E[] | null>, value: NoInfer<Right<E>>): Condition;
+export declare function startsWith(left: StringLeft, value: string | Ref<string>): Condition;
+export declare function endsWith(left: StringLeft, value: string | Ref<string>): Condition;
+/** `pattern` is a regular expression source, matched with the `u` flag. */
+export declare function matches(left: StringLeft, pattern: string): Condition;
+/** Date strings (ISO 8601). */
+export declare function before(left: StringLeft, date: string | Ref<string>): Condition;
+export declare function after(left: StringLeft, date: string | Ref<string>): Condition;
+export declare function all(...conditions: [Condition, ...Condition[]]): Condition;
+export declare function any(...conditions: [Condition, ...Condition[]]): Condition;
+export declare function not(condition: Condition): Condition;
+type ElementCallback<E, R> = (element: Placeholder<E>) => R;
+export declare function some<E>(over: Ref<readonly E[] | null>, where: ElementCallback<E, Condition>): Condition;
+export declare function every<E>(over: Ref<readonly E[] | null>, where: ElementCallback<E, Condition>): Condition;
+export declare function none<E>(over: Ref<readonly E[] | null>, where: ElementCallback<E, Condition>): Condition;
+type NumberRefs = readonly [Ref<number | null>, ...Ref<number | null>[]];
+export declare function sum(values: NumberRefs): ComputedValue;
+export declare function sum<E>(over: Ref<readonly E[] | null>, field: ElementCallback<E, Ref<number | null>>): ComputedValue;
+export declare function avg(values: NumberRefs, options?: {
+    weights?: number[];
+}): ComputedValue;
+export declare function avg<E>(over: Ref<readonly E[] | null>, field: ElementCallback<E, Ref<number | null>>): ComputedValue;
+export declare function min(values: NumberRefs): ComputedValue;
+export declare function min<E>(over: Ref<readonly E[] | null>, field: ElementCallback<E, Ref<number | null>>): ComputedValue;
+export declare function max(values: NumberRefs): ComputedValue;
+export declare function max<E>(over: Ref<readonly E[] | null>, field: ElementCallback<E, Ref<number | null>>): ComputedValue;
+/** Counts the refs that exist and aren't null, or the list's elements (matching `where`). */
+export declare function count(values: readonly [Ref<unknown>, ...Ref<unknown>[]]): ComputedValue;
+export declare function count<E>(over: Ref<readonly E[] | null>, where?: ElementCallback<E, Condition>): ComputedValue;

package/dist/pipelines/context.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `r` objects passed to chain callbacks. Each property read creates a
+ * fresh root placeholder, so reads are tracked from the root, and each `r`
+ * owns its placeholders: using `r.result` from another node's callback is an
+ * error, because it would compile to the wrong node's `result`.
+ */
+import type { JsonSchema } from "../contracts/pipeline-document";
+import type { NodeDef } from "./model";
+export type ContextKind = "next" | "catch";
+/** The `r` for a callback on `node`'s chain. */
+export declare function makeContext(node: NodeDef, kind: ContextKind): object;
+/** The `item` parameter of an `each` start callback, and its owner token. */
+export declare function makeItem(itemsSchema: JsonSchema | undefined): {
+    item: object;
+    owner: object;
+};

package/dist/pipelines/define-pipeline.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `definePipeline`: runs the authoring callbacks once, with placeholders, and
+ * compiles the result to a pipeline JSON document. It doesn't validate the
+ * document (that's `validatePipeline` in `@scarn/shared-core/pipelines`);
+ * it reports what only the TS source can show, and throws
+ * `PipelineBuildError` when anything is wrong.
+ */
+import type { PipelineDocument, StepCatalog } from "../contracts/pipeline-document";
+import { type BuildIssue } from "./errors";
+import { type SourceSite } from "./source";
+import type { FlowChain, Target } from "./types";
+export interface PipelineConfig {
+    key: string;
+    title?: string;
+    /** The first node. Only `workItem.*` refs and literals are available here. */
+    start: Target;
+    flow: readonly FlowChain[];
+}
+/** What `definePipeline` returns: the compiled document and what the build needs. */
+export interface PipelineDefinition {
+    readonly _tag: "pipeline_document";
+    readonly key: string;
+    readonly document: PipelineDocument;
+    /** TS source sites by JSON pointer (`/nodes/fix/next/routes/0`), for error messages. */
+    readonly sourceMap: Readonly<Record<string, SourceSite>>;
+    /** The local steps' contracts, by step key. `stepRef` steps aren't in it. */
+    readonly steps: StepCatalog;
+    /** Problems that don't stop the build, such as chains left out of `flow`. */
+    readonly warnings: readonly BuildIssue[];
+}
+/** Compiles a pipeline to its JSON document. Throws `PipelineBuildError`. */
+export declare function definePipeline(config: PipelineConfig): PipelineDefinition;

package/dist/pipelines/each.d.ts

@@ -0,0 +1,5 @@
+import type { Placeholder, Ref } from "./ref-types";
+import type { EachOptions, EachTarget, Target } from "./types";
+/** Starts one lane per element of `over`, each at the target `start` returns for its item. */
+export declare function each<E>(over: Ref<readonly E[]>, options: EachOptions, start: (item: Placeholder<E>) => Target): EachTarget;
+export declare function each<E>(over: Ref<readonly E[]>, start: (item: Placeholder<E>) => Target): EachTarget;

package/dist/pipelines/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Build errors: problems `definePipeline` finds while compiling. Each one
+ * carries the TS source site and the JSON pointer it applies to, and prints as
+ * `file.ts:42 (/nodes/x/next/routes/0/args/plan): message`.
+ */
+import { type SourceSite } from "./source";
+export interface BuildIssue {
+    site: SourceSite | null;
+    /** JSON pointer into the compiled document; "" for the whole document. */
+    pointer: string;
+    message: string;
+}
+export declare function formatIssue(issue: BuildIssue): string;
+/** Thrown by `definePipeline` when the pipeline can't be compiled. */
+export declare class PipelineBuildError extends Error {
+    readonly issues: readonly BuildIssue[];
+    constructor(key: string, issues: readonly BuildIssue[]);
+}
+/**
+ * Thrown while authoring code runs (a coerced placeholder, a bad spread);
+ * the compiler turns it into a `BuildIssue` at the pointer being compiled.
+ */
+export declare class AuthoringError extends Error {
+    readonly site: SourceSite | null;
+    constructor(message: string, site?: SourceSite | null);
+}

package/dist/pipelines/handles.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Handles at run time: callable functions that record a target when called,
+ * with the chain-starting methods attached. Step handles from `defineStep` /
+ * `codeStep` and `stepRef` are built here, and so are wait handles.
+ */
+import type { JsonSchema } from "../contracts/pipeline-document";
+import type { NodeDef, RawArgs } from "./model";
+/** What `toPipelineStep` needs from a step definition. */
+export interface StepSource {
+    key: string;
+    inputSchemaJson: JsonSchema | Record<string, unknown> | null;
+    resultSchemaJson: JsonSchema | Record<string, unknown> | null;
+    errors?: readonly string[];
+    /** A code step always has a result schema, so only an agent step without one is a conversation step. */
+    kind?: "built_in" | "user_defined" | "code";
+}
+/** Makes `handle` a pipeline handle for `node`: chain methods, `.partial`, and `.as` for steps. */
+export declare function makeHandle<T extends object>(handle: T, node: NodeDef): T;
+/**
+ * The call behind a step handle: records a target for `source`'s node. Used
+ * by `toStepHandle` so `defineStep` / `codeStep` handles are pipeline steps.
+ */
+export declare function stepNode(source: StepSource, local?: boolean): NodeDef;
+/** A callable step handle for `node`, without the handle's own spec fields. */
+export declare function stepCall(node: NodeDef): (args?: RawArgs) => object;
+/** A callable wait or terminal-free handle, with chain methods. */
+export declare function waitHandle(node: NodeDef): object;
+/** A fresh step handle for a step known only by key. */
+export declare function bareStepHandle(source: StepSource, local: boolean): object;

package/dist/pipelines/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The pipeline authoring SDK: write a pipeline in TypeScript and compile it
+ * to a pipeline JSON document with `definePipeline`.
+ */
+export { definePipeline } from "./define-pipeline";
+export type { PipelineConfig, PipelineDefinition } from "./define-pipeline";
+export { decision, reply, succeed, fail, stepRef, workItem, workItemField, } from "./nodes";
+export type { DecisionActionOptions } from "./nodes";
+export { each } from "./each";
+export { equal, notEqual, lessThan, lessThanInclusive, greaterThan, greaterThanInclusive, exists, isEmpty, contains, startsWith, endsWith, matches, before, after, all, any, not, some, every, none, sum, avg, min, max, count, } from "./conditions";
+export type { Condition, ComputedValue, Right } from "./conditions";
+export { PipelineBuildError, formatIssue } from "./errors";
+export type { BuildIssue } from "./errors";
+export type { SourceSite } from "./source";
+export type { Arg, Args, ErrorValue, JsonLiteral, Literal, Placeholder, Ref, UntypedPlaceholder, } from "./ref-types";
+export type { BuiltInError, CatchContext, ConversationResult, DecisionResult, EachOptions, EachTarget, FlowChain, Mergeable, NextContext, NextOptions, NextRoute, NodeHandle, PartialTarget, PipelineStep, ReplyInput, ReplyResult, StepSettings, Target, Terminal, WaitError, WaitHandle, WaitSettings, } from "./types";
+export type { StepRef } from "../definitions/steps/step-ref";
+export type { Catch, Condition as ConditionJson, DecisionAction, DecisionBody, ListArg, JsonSchema, JsonValue, PipelineDocument, PipelineNode, StepCatalog, Next, Otherwise, Route, StepContract, ToleratedFailures, } from "../contracts/pipeline-document";

package/dist/pipelines/index.js

@@ -0,0 +1,83 @@
+// @bun
+import {
+  after,
+  all,
+  any,
+  avg,
+  before,
+  contains,
+  count,
+  decision,
+  definePipeline,
+  each,
+  endsWith,
+  equal,
+  every,
+  exists,
+  fail,
+  greaterThan,
+  greaterThanInclusive,
+  isEmpty,
+  lessThan,
+  lessThanInclusive,
+  matches,
+  max,
+  min,
+  none,
+  not,
+  notEqual,
+  reply,
+  some,
+  startsWith,
+  stepRef,
+  succeed,
+  sum,
+  workItem,
+  workItemField
+} from "../chunk-yjtaq94c.js";
+import"../chunk-p7yrcmqm.js";
+import {
+  PipelineBuildError,
+  formatIssue
+} from "../chunk-mz53r914.js";
+import"../chunk-dp86pa6m.js";
+import"../chunk-skzxcba3.js";
+import"../chunk-y64skrwp.js";
+export {
+  PipelineBuildError,
+  after,
+  all,
+  any,
+  avg,
+  before,
+  contains,
+  count,
+  decision,
+  definePipeline,
+  each,
+  endsWith,
+  equal,
+  every,
+  exists,
+  fail,
+  formatIssue,
+  greaterThan,
+  greaterThanInclusive,
+  isEmpty,
+  lessThan,
+  lessThanInclusive,
+  matches,
+  max,
+  min,
+  none,
+  not,
+  notEqual,
+  reply,
+  some,
+  startsWith,
+  stepRef,
+  succeed,
+  sum,
+  workItem,
+  workItemField
+};

package/dist/pipelines/model.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The run-time data behind handles, targets and chains. Every value is
+ * immutable once created; chain methods return new chains.
+ */
+import type { DecisionAction, JsonSchema, ToleratedFailures } from "../contracts/pipeline-document";
+import type { RefData } from "./refs";
+import { type SourceSite } from "./source";
+/** One node of the document, as described by its handle. */
+export type NodeDef = {
+    readonly kind: "step";
+    readonly id: string;
+    readonly step: string;
+    /** False for `stepRef` steps, which only the server catalog knows. */
+    readonly local: boolean;
+    readonly inputSchema: JsonSchema | null;
+    readonly resultSchema: JsonSchema | null;
+    /** A local agent step with no result schema: its result is `CONVERSATION_RESULT_SCHEMA`. */
+    readonly conversation: boolean;
+    readonly errors: readonly string[];
+    readonly site: SourceSite | null;
+} | {
+    readonly kind: "wait";
+    readonly id: string;
+    readonly for: "decision" | "reply";
+    /** A decision wait's actions, in button order; null on other waits. */
+    readonly actions: readonly DecisionAction[] | null;
+    readonly inputSchema: JsonSchema | null;
+    readonly resultSchema: JsonSchema;
+    readonly site: SourceSite | null;
+} | {
+    readonly kind: "succeed";
+    readonly id: string;
+    /** Creation order; terminals are emitted after other nodes, in this order. */
+    readonly seq: number;
+    readonly title?: string;
+    readonly site: SourceSite | null;
+} | {
+    readonly kind: "fail";
+    readonly id: string;
+    readonly seq: number;
+    readonly title?: string;
+    readonly error?: string;
+    readonly cause?: string;
+    readonly site: SourceSite | null;
+};
+/** Author-written args, before compiling: refs and literals by name. */
+export type RawArgs = Readonly<Record<string, object | string | number | boolean | null | undefined>>;
+export interface EachData {
+    readonly over: RefData;
+    readonly maxConcurrency: number | undefined;
+    readonly toleratedFailures: ToleratedFailures | undefined;
+    /** The lane's first target, from the item. */
+    readonly start: (item: object) => object;
+    readonly site: SourceSite | null;
+}
+/**
+ * "Go to this node with these args", from calling a handle; `partial` when
+ * it's from `handle.partial(args)` and ends a lane at a merge.
+ */
+export interface TargetData {
+    readonly node: NodeDef;
+    readonly args: RawArgs | undefined;
+    readonly site: SourceSite | null;
+    readonly partial?: true;
+}
+export interface NodeSettings {
+    title?: string;
+    timeoutSeconds?: number;
+    heartbeatSeconds?: number;
+    maxRuns?: number;
+    maxTurns?: number;
+}
+/** A target as written: a target value, a bare handle, an `each`, or a callback returning one. */
+export type TargetSpec = object;
+export interface CatchData {
+    readonly on: readonly string[];
+    readonly target: TargetSpec;
+    readonly site: SourceSite | null;
+}
+export interface RouteData {
+    readonly when: ((r: object) => object) | undefined;
+    readonly target: TargetSpec;
+}
+/** The `.next(...)` call: its routes, `otherwise`, and match mode. */
+export interface NextData {
+    readonly match: "first" | "all" | undefined;
+    readonly routes: readonly RouteData[];
+    readonly otherwise: TargetSpec | undefined;
+    readonly site: SourceSite | null;
+}
+export interface ChainData {
+    readonly node: NodeDef;
+    readonly settings: NodeSettings;
+    readonly retry: readonly {
+        on: readonly string[];
+        maxAttempts: number;
+    }[];
+    readonly catch: readonly CatchData[];
+    /** Set once `.next(...)` ends the chain. */
+    readonly next: NextData | undefined;
+    readonly site: SourceSite | null;
+}
+export declare function emptyChain(node: NodeDef): ChainData;

package/dist/pipelines/nodes.d.ts

@@ -0,0 +1,54 @@
+import { type DecisionBody } from "../contracts/pipeline-document";
+import type { Placeholder, UntypedPlaceholder } from "./ref-types";
+import type { DecisionResult, PipelineStep, ReplyInput, ReplyResult, Terminal, WaitHandle } from "./types";
+/** A zod schema, typed by its output. */
+interface Schema<T> {
+    readonly _output: T;
+}
+/** One action of a `decision` wait: its button label, and whether it needs a body. */
+export interface DecisionActionOptions {
+    label: string;
+    /** Defaults to `"optional"`. */
+    body?: DecisionBody;
+}
+/**
+ * A wait for a decision: the person picks one of `actions` (buttons in key
+ * order) and can write a body. The result is `{ action, body }`, with
+ * `action` one of the keys of `actions`. `input` is what's being decided
+ * about; it types the args and `r.input`.
+ */
+export declare function decision<I = Record<string, unknown>, const A extends Record<string, DecisionActionOptions> = Record<string, DecisionActionOptions>>(id: string, options: {
+    input?: Schema<I>;
+    actions: A;
+}): WaitHandle<I, DecisionResult<Extract<keyof A, string>>>;
+/**
+ * A wait for a reply to questions posted on the work item. Every transition
+ * into it passes `questions: string[]`; `{ questions: [] }` asks the default
+ * question.
+ */
+export declare function reply(id: string): WaitHandle<ReplyInput, ReplyResult>;
+/** Ends the run (or, inside a lane, that lane) successfully. */
+export declare function succeed(id: string, options?: {
+    title?: string;
+}): Terminal;
+/** Ends the run (or, inside a lane, that lane) as failed. */
+export declare function fail(id: string, options?: {
+    error?: string;
+    cause?: string;
+    title?: string;
+}): Terminal;
+/**
+ * A step that exists only on the server. Untyped unless you pass type
+ * arguments; the build validates it against the server catalog.
+ */
+export declare function stepRef<TInput = unknown, TResult = unknown, TErrors extends string = string>(key: string): PipelineStep<TInput, TResult, TErrors>;
+/** Work-item data, readable anywhere. */
+export declare const workItem: {
+    readonly title: Placeholder<string>;
+};
+/**
+ * A work-item form field, as `workItem.fields.<alias>`. `label` is the form
+ * label it's read from; the pipeline's `workItemFields` collects them.
+ */
+export declare function workItemField(alias: string, label: string): UntypedPlaceholder;
+export {};

package/dist/pipelines/ref-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The types of references. A `Placeholder<T>` stands for a value of type `T`
+ * that exists only when the pipeline runs: reading `.x` on it gives the
+ * placeholder for `T["x"]`, and passing it as an arg or to a condition helper
+ * records its reference string. The brands below exist only in the types.
+ */
+export declare const refType: unique symbol;
+export declare const untypedBrand: unique symbol;
+/** A reference to a run-time value of type `T`. */
+export interface Ref<out T> {
+    readonly [refType]: T;
+}
+/**
+ * A reference whose type isn't known (a `stepRef` without type arguments, a
+ * work-item field, a wait without an input schema). Any field can be read,
+ * and it fits any arg; the build checks it against the catalog.
+ */
+export interface UntypedPlaceholder extends Ref<never> {
+    readonly [untypedBrand]: true;
+    readonly [key: string]: UntypedPlaceholder;
+}
+/** A JSON value written in TypeScript, which may not contain references. */
+export type JsonLiteral = string | number | boolean | null | readonly JsonLiteral[] | {
+    readonly [key: string]: JsonLiteral;
+    readonly [untypedBrand]?: never;
+};
+/** A plain JSON value of type `T`; references inside it are a type error. */
+export type Literal<T> = unknown extends T ? JsonLiteral : T extends string | number | boolean | null | undefined ? T : T extends readonly (infer E)[] ? readonly Literal<E>[] : {
+    readonly [K in keyof T]: Literal<T[K]>;
+};
+type Fields<T> = [NonNullable<T>] extends [string] ? {
+    readonly length: Placeholder<number>;
+} : [NonNullable<T>] extends [readonly unknown[]] ? {
+    readonly length: Placeholder<number>;
+} : [NonNullable<T>] extends [object] ? {
+    readonly [K in keyof NonNullable<T>]-?: Placeholder<Exclude<NonNullable<T>[K], undefined>>;
+} : unknown;
+/** A reference to a `T`, plus a placeholder for each of its fields. */
+export type Placeholder<T> = [T] extends [never] ? UntypedPlaceholder : unknown extends T ? UntypedPlaceholder : Ref<T> & Fields<T>;
+/** An array arg built element by element: each a reference or a JSON literal. */
+export type ListOf<T> = T extends readonly (infer E)[] ? readonly (Ref<E> | Literal<E>)[] : never;
+/** One arg: a reference of a compatible type, a JSON literal, or a list of either. */
+export type Arg<T> = Ref<T> | Literal<T> | ListOf<T>;
+/** The args a step with input `I` is called with. */
+export type Args<I> = {
+    [K in keyof I]: Arg<Exclude<I[K], undefined>>;
+};
+/** The error a `catch` handles. */
+export interface ErrorValue {
+    name: string;
+    message: string;
+    cause?: unknown;
+}
+export {};