@trailstep/core 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -14,6 +14,101 @@ interface AgentModelTarget {
     readonly model: string;
 }
 
+interface TrailStepProviderRegistration {
+    readonly source: TrailStepProviderSource;
+    readonly manifest: TrailStepProviderManifest;
+}
+type TrailStepProviderSource = {
+    readonly type: "local-manifest";
+    readonly path: string;
+} | {
+    readonly type: "legacy-custom-provider";
+} | {
+    readonly type: "npm" | "github" | "local-package";
+    readonly packageName: string;
+    readonly spec: string;
+    readonly resolvedVersion?: string;
+};
+/**
+ * ESM package contract for provider packages: export `trailstepProvider` from
+ * the package root. Keep hook functions outside `manifest` so the manifest is
+ * serializable and safe to persist.
+ */
+interface TrailStepProviderPackageDefinition {
+    readonly manifest: TrailStepProviderManifest;
+    readonly hooks?: Record<string, unknown>;
+}
+interface TrailStepProviderManifest {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly displayName: string;
+    readonly working: TrailStepProviderWorkingManifest;
+    readonly interactive: TrailStepProviderInteractiveManifest;
+    readonly model: TrailStepProviderModelManifest;
+    readonly thinking: TrailStepProviderThinkingManifest;
+    readonly env?: TrailStepProviderEnvironmentManifest;
+    readonly hooks?: Record<string, unknown>;
+}
+type TrailStepProviderPromptFileReferenceStyle = "at-prefixed-argument";
+interface TrailStepProviderPromptManifest {
+    readonly kind: "prompt-file";
+    readonly reference?: TrailStepProviderPromptFileReferenceStyle;
+}
+type TrailStepProviderOutputStyle = "provider-output-file" | "stdout-json-envelope" | "stdout-jsonl-transcript";
+interface TrailStepProviderOutputParsingManifest {
+    readonly resultField?: string;
+}
+interface TrailStepProviderOutputManifest {
+    readonly style: TrailStepProviderOutputStyle;
+    readonly parsing?: TrailStepProviderOutputParsingManifest;
+}
+interface TrailStepProviderWorkingManifest {
+    readonly supported: boolean;
+    readonly command?: string;
+    readonly args?: readonly string[];
+    readonly prompt?: TrailStepProviderPromptManifest;
+    readonly output?: TrailStepProviderOutputManifest;
+    readonly followUp?: TrailStepProviderFollowUpManifest;
+}
+interface TrailStepProviderFollowUpManifest {
+    readonly supported: boolean;
+    readonly reason?: string;
+    readonly sessionIdFlag?: string;
+    readonly resumeArgs?: readonly string[];
+}
+interface TrailStepProviderInteractiveManifest {
+    readonly supported: boolean;
+    readonly reason?: string;
+    readonly command?: string;
+    readonly args?: readonly string[];
+    readonly requiresSystemPromptFile?: boolean;
+    readonly systemPromptFileFlag?: string;
+    readonly modelFlag?: string;
+    readonly permissionBypassFlag?: string;
+}
+interface TrailStepProviderEnvironmentManifest {
+    readonly required?: readonly string[];
+    readonly optional?: readonly string[];
+}
+interface TrailStepProviderModelDiscoveryManifest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly outputParser: string;
+}
+interface TrailStepProviderModelManifest {
+    readonly supported: boolean;
+    readonly reason?: string;
+    readonly flag?: string;
+    readonly discovery?: TrailStepProviderModelDiscoveryManifest;
+}
+interface TrailStepProviderThinkingManifest {
+    readonly supported: boolean;
+    readonly reason?: string;
+    readonly flag?: string;
+    readonly levels?: readonly WorkflowAgentThinking[];
+}
+declare function parseTrailStepProviderManifest(path: string, value: unknown, diagnostics: string[]): TrailStepProviderManifest | undefined;
+
 interface RetryPolicy {
     readonly maxAttempts: number;
 }
@@ -64,11 +159,7 @@ interface TrailStepCustomProviderConfig {
     readonly env?: Readonly<Record<string, string>>;
 }
 interface TrailStepAgentTarget {
-    /**
-     * Either a key declared in the top-level `customProviders` object, or a
-     * built-in provider registry id (e.g. `"claude"`). The registry is checked
-     * first; `customProviders` is the fallback/escape hatch.
-     */
+    /** Either a key declared in top-level `providers` or `customProviders`. */
     readonly provider: string;
     readonly model?: string;
     readonly thinking?: WorkflowAgentThinking;
@@ -86,11 +177,28 @@ interface TrailStepWorkflowConfig {
     readonly agents?: TrailStepAgentMappings;
     readonly settings?: TrailStepSettings;
 }
+interface TrailStepStorageLifecycleRetentionConfig {
+    /** Duration string such as "7d"; false disables compression for the matching scope. */
+    readonly compressAfter?: string | false;
+    /** Duration string such as "30d"; false disables deletion for the matching scope. */
+    readonly deleteAfter?: string | false;
+}
+interface TrailStepStorageLifecycleConfig extends TrailStepStorageLifecycleRetentionConfig {
+    readonly enabled?: boolean;
+    readonly runOn?: readonly ("run" | "open" | "runs")[];
+    readonly throttle?: string | false;
+    readonly workflows?: Readonly<Record<string, TrailStepStorageLifecycleRetentionConfig>>;
+}
+interface TrailStepStorageConfig {
+    readonly lifecycle?: TrailStepStorageLifecycleConfig;
+}
 interface TrailStepConfig {
     readonly version: 1;
     readonly customProviders: Readonly<Record<string, TrailStepCustomProviderConfig>>;
+    readonly providers?: Readonly<Record<string, TrailStepProviderRegistration>>;
     readonly agents: TrailStepAgentMappings;
     readonly settings?: TrailStepSettings;
+    readonly storage?: TrailStepStorageConfig;
     readonly workflows?: Readonly<Record<string, TrailStepWorkflowConfig>>;
 }
 interface ResolveAgentTargetsOptions {
@@ -100,10 +208,6 @@ interface ResolveAgentTargetsOptions {
     readonly roleSize: string;
 }
 
-declare function parseTrailStepConfig(value: unknown): TrailStepConfig;
-
-declare function resolveAgentTargets(options: ResolveAgentTargetsOptions): readonly TrailStepAgentTarget[];
-
 type PlainObject = Record<string, unknown>;
 interface ValidationDiagnostic {
     readonly path: string;
@@ -120,67 +224,6 @@ type ShapePrimitive = "string" | "number" | "boolean";
 type ShapeObject = Readonly<Record<string, ShapePrimitive>>;
 type ShapeInput<T extends PlainObject = PlainObject> = Schema<T> | ShapeObject;
 
-/**
- * A captured document artifact. `Document` doubles as its own
- * `Schema<Document>`: `validate`/`diagnostics`/`assert`/`jsonSchema`/
- * `captureMode` are static members, so passing the class itself as
- * `.prompt(source, { output: Document })` gives both the TypeScript output
- * type and the runtime validator from one symbol -- no separate schema
- * constant to import or keep in sync.
- */
-declare class Document {
-    readonly content: string;
-    readonly path: string;
-    [key: string]: unknown;
-    static readonly captureMode: "raw-text";
-    static readonly jsonSchema: Record<string, unknown>;
-    static validate(value: unknown): value is Document;
-    static diagnostics(value: unknown): readonly ValidationDiagnostic[];
-    /**
-     * Deliberately duck-types instead of checking `instanceof Document`: on
-     * resume, a completed step's recorded output is replayed from
-     * `events.jsonl` via `JSON.parse`, producing a plain deserialized object —
-     * never a live `Document` instance — before `assert` is called on it. An
-     * `instanceof` check would fail every such replay. `assert` reconstructs a
-     * genuine `Document` from any content/path-shaped value, so every
-     * consumer downstream — a live capture or a replayed value alike — always
-     * receives a real `Document` instance with working prototype methods.
-     */
-    static assert(value: unknown, label?: string): Document;
-    constructor(content: string, path: string);
-}
-/**
- * Captures `content` as a durable document artifact for the currently
- * executing step. Must be called from within a step's `.do()` callback —
- * it reads the step-scoped ambient context (`RunContext.currentStep`, set
- * by `withStepContext` for the duration of the step) to determine both the
- * directory to write into and this call's 1-based index within the step, so
- * that a step calling `document(...)` more than once gets
- * `document-1.md`, `document-2.md`, etc.
- */
-declare function document(content: string): Promise<Document>;
-
-/**
- * Synchronously reads each named file relative to `dir` and returns its
- * trimmed content keyed the same way, so a step's `prompt.ts` can load all
- * of its shared markdown fragments in one call:
- * `loadFragments(import.meta.dirname, { methodology: "../shared/methodology.md" })`.
- */
-declare function loadFragments<TKey extends string>(dir: string, files: Record<TKey, string>): Record<TKey, string>;
-/**
- * Renders `body` as a `## title` markdown section, or `undefined` when
- * `body` is falsy -- so a conditional section can be inlined directly as a
- * `promptSections(...)` argument instead of built up separately.
- */
-declare function section(title: string, body: string | false | null | undefined): string | undefined;
-/**
- * Joins prompt fragments and `section(...)` results with a blank line
- * between each, dropping any falsy (conditionally-omitted) part.
- */
-declare function promptSections(...parts: ReadonlyArray<string | false | null | undefined>): string;
-/** Renders `items` as a markdown bullet list, one `- item` per line. */
-declare function list(items: readonly string[]): string;
-
 interface AgentStepRequestConfig<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
     readonly kind?: "agent";
     readonly id: string;
@@ -233,14 +276,37 @@ declare class TrailStepFailureError extends Error {
     constructor(failure: Failure);
 }
 
-/** A local text file to load a prompt's content from, resolved relative to the workflow's `cwd` at dispatch time. */
+interface RunContextState {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    getPersisted<T = unknown>(key: string): Promise<T | undefined>;
+    hydratePersisted(): Promise<void>;
+    set(key: string, value: unknown, options?: {
+        readonly persist?: boolean;
+    }): Promise<void>;
+}
+
+/** A local text file to load a prompt's content from, resolved relative to the workflow/project `cwd` at dispatch time. */
 interface PromptTemplateSource {
     readonly kind: "promptTemplate";
     readonly path: string;
 }
+interface StepCwdContext<TInput extends PlainObject = PlainObject> {
+    readonly input: TInput;
+    readonly state: RunContextState;
+    readonly workflow: {
+        readonly id: string;
+    };
+}
+type StepCwdCallback<TInput extends PlainObject = PlainObject> = {
+    bivarianceHack(context: StepCwdContext<TInput>): unknown | Promise<unknown>;
+}["bivarianceHack"];
+type StepCwdInput<TInput extends PlainObject = PlainObject> = string | StepCwdCallback<TInput>;
 /** The object passed to `step(...)`. Always relevant, regardless of whether `.prompt(...)` is called. */
 interface StepConfig {
     readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly cwd?: StepCwdInput;
     readonly retry?: RetryPolicyInput;
     readonly timeout?: TimeoutPolicyInput;
 }
@@ -263,31 +329,130 @@ interface SubPromptOptions<TOutput extends PlainObject = PlainObject> {
     readonly adapter?: AgentAdapterSelection<PlainObject, TOutput>;
     readonly maxSubPrompts?: number;
 }
-/** The runtime shape stored in `StepNode.config` -- `StepConfig` plus `PromptOptions` (when a prompt was given) plus the resolved `input` and `prompt` source. */
+type StepDisplayLevel = "info" | "warning" | "error" | "debug";
+interface StepDisplayObject {
+    readonly message: string;
+    readonly level?: StepDisplayLevel;
+    readonly data?: unknown;
+}
+type StepDisplayValue = string | StepDisplayObject;
+interface StepDisplayContext<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly input: TInput;
+    readonly output: TOutput;
+}
+type StepDisplayCallback<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = {
+    bivarianceHack(context: StepDisplayContext<TInput, TOutput>): StepDisplayValue | Promise<StepDisplayValue>;
+}["bivarianceHack"];
+type StepDisplayContent<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = StepDisplayValue | StepDisplayCallback<TInput, TOutput>;
+/** Ordered phase for durable progress display events. */
+interface DisplayPhase<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly kind: "display";
+    readonly content?: StepDisplayContent<TInput, TOutput>;
+    readonly options?: PlainObject;
+}
+interface WaitDefinition<TWaitOutput extends PlainObject = PlainObject> {
+    readonly id: string;
+    readonly kind: "input";
+    readonly message: string;
+    readonly output: ShapeInput<TWaitOutput>;
+}
+interface WaitOptions<TWaitOutput extends PlainObject = PlainObject> {
+    readonly output: ShapeInput<TWaitOutput>;
+}
+interface WaitPendingInput {
+    readonly id: string;
+    readonly message: string;
+    readonly retryAfterSeconds?: number;
+}
+interface WaitPendingResult {
+    readonly status: "pending";
+    readonly id: string;
+    readonly message: string;
+    readonly retryAfterSeconds?: number;
+}
+interface WaitDoneResult<TWaitOutput extends PlainObject = PlainObject> {
+    readonly status: "done";
+    readonly output: TWaitOutput;
+}
+type WaitCheckResult<TWaitOutput extends PlainObject = PlainObject> = WaitDoneResult<TWaitOutput> | WaitPendingResult;
+interface CheckWaitHelpers<TWaitOutput extends PlainObject = PlainObject> {
+    done(output: TWaitOutput): WaitDoneResult<TWaitOutput>;
+    pending(input: WaitPendingInput): WaitPendingResult;
+}
+interface StepWaitContext<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly input: TInput;
+    readonly output: TOutput;
+    readonly waits: Readonly<Record<string, PlainObject>>;
+}
+interface CheckWaitContext<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject, TWaitOutput extends PlainObject = PlainObject> extends StepWaitContext<TInput, TOutput> {
+    readonly wait: CheckWaitHelpers<TWaitOutput>;
+}
+type WaitCallback<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject, TWaitOutput extends PlainObject = PlainObject> = {
+    bivarianceHack(context: StepWaitContext<TInput, TOutput>): WaitDefinition<TWaitOutput> | Promise<WaitDefinition<TWaitOutput>>;
+}["bivarianceHack"];
+type CheckWaitCallback<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject, TWaitOutput extends PlainObject = PlainObject> = {
+    bivarianceHack(context: CheckWaitContext<TInput, TOutput, TWaitOutput>): WaitCheckResult<TWaitOutput> | Promise<WaitCheckResult<TWaitOutput>>;
+}["bivarianceHack"];
+type WaitInput<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject, TWaitOutput extends PlainObject = PlainObject> = WaitDefinition<TWaitOutput> | WaitCallback<TInput, TOutput, TWaitOutput>;
+/** Ordered durable pause phase for human/external input/check waits. */
+interface WaitPhase<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly kind: "wait";
+    readonly wait: WaitInput<TInput, TOutput> | CheckWaitCallback<TInput, TOutput>;
+    readonly options?: WaitOptions;
+}
+interface PromptPhase<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> extends PromptOptions<TOutput> {
+    readonly kind: "prompt";
+    readonly prompt: AgentPrompt<TInput> | PromptTemplateSource;
+}
+type StepContinuationOutput<TOutput extends PlainObject = PlainObject> = TOutput & {
+    readonly output: TOutput;
+    readonly waits: Readonly<Record<string, PlainObject>>;
+};
+type StepContinuation<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = {
+    bivarianceHack(output: TOutput, input: TInput): ContinuationResult | Promise<ContinuationResult>;
+}["bivarianceHack"];
+type StepContextContinuation<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = {
+    bivarianceHack(output: StepContinuationOutput<TOutput>, input: TInput): ContinuationResult | Promise<ContinuationResult>;
+}["bivarianceHack"];
+interface DoPhase<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly kind: "do";
+    readonly onOutput: StepContinuation<TInput, TOutput>;
+}
+type StepPhase<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = DisplayPhase<TInput, TOutput> | WaitPhase<TInput, TOutput> | PromptPhase<TInput, TOutput> | DoPhase<TInput, TOutput>;
+/** The runtime shape stored in `StepNode.config` -- `StepConfig` plus the resolved `input`. Legacy prompt fields are retained for compatibility; ordered `StepNode.phases` is the canonical execution model. */
 interface ContinuationStepConfig<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
     readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
     readonly input: TInput;
+    /** @deprecated Prefer the ordered prompt phase in `StepNode.phases`. */
     readonly output?: ShapeInput<TOutput>;
+    /** @deprecated Prefer the ordered prompt phase in `StepNode.phases`. */
     readonly prompt?: AgentPrompt<TInput> | PromptTemplateSource;
+    /** @deprecated Prefer the ordered prompt phase in `StepNode.phases`. */
     readonly agent?: string;
+    /** @deprecated Prefer the ordered prompt phase in `StepNode.phases`. */
     readonly mode?: "working" | "interactive";
+    /** @deprecated Prefer the ordered prompt phase in `StepNode.phases`. */
     readonly adapter?: AgentAdapterSelection<TInput, TOutput>;
+    /** @deprecated Prefer the ordered prompt phase in `StepNode.phases`. */
     readonly maxSubPrompts?: number;
+    readonly cwd?: StepCwdInput<TInput>;
     readonly retry?: RetryPolicyInput;
     readonly timeout?: TimeoutPolicyInput;
 }
-type StepContinuation<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = {
-    bivarianceHack(output: TOutput, input: TInput): ContinuationResult | Promise<ContinuationResult>;
-}["bivarianceHack"];
 type StepErrorContinuation = {
     bivarianceHack(error: Failure): ContinuationResult;
 }["bivarianceHack"];
 interface StepNode<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
     readonly kind: "step";
     readonly config: ContinuationStepConfig<TInput, TOutput>;
-    /** Receives the step's own input as the second argument, alongside its output as the first. */
+    /** Ordered phase pipeline. This is the canonical runtime representation for authored nodes. Optional only so legacy StepNode-shaped objects can still be translated at runtime. */
+    readonly phases?: readonly StepPhase<TInput, TOutput>[];
+    /** @deprecated Prefer the `do` phase in `StepNode.phases`. Retained for compatibility with existing callers. */
     readonly onOutput: StepContinuation<TInput, TOutput>;
     readonly onError?: StepErrorContinuation;
+    readonly options?: StepInvocationOptions;
 }
 /**
  * Returned by `step(...).prompt(...)?.do(...)`: a reusable step definition,
@@ -296,69 +461,83 @@ interface StepNode<TInput extends PlainObject = PlainObject, TOutput extends Pla
  * calling it. When `TInput` has no required keys (e.g. a step that ignores
  * its input), the call is `stepA()` -- the input argument is optional.
  */
-type StepFactory<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = ({} extends TInput ? (input?: TInput) => StepNode<TInput, TOutput> : (input: TInput) => StepNode<TInput, TOutput>) & {
+interface StepInvocationOptions extends Partial<Omit<StepConfig, "id">> {
+    readonly branchId?: string;
+}
+type StepFactory<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = ({} extends TInput ? (input?: TInput, options?: StepInvocationOptions) => StepNode<TInput, TOutput> : (input: TInput, options?: StepInvocationOptions) => StepNode<TInput, TOutput>) & {
     catch(onError: StepErrorContinuation): StepFactory<TInput, TOutput>;
 };
 type SubPromptFactory<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = {} extends TInput ? (input?: TInput) => Promise<TOutput> : (input: TInput) => Promise<TOutput>;
+interface TerminalMessageOptions {
+    readonly message?: string;
+}
 interface DoneNode<TOutput extends PlainObject = PlainObject> {
     readonly kind: "done";
     readonly output: TOutput;
+    readonly message?: string;
 }
 /** Terminates the workflow as a failure without dispatching a step -- no step.* events, just workflow.failed. */
 interface FailNode {
     readonly kind: "fail";
     readonly failure: Failure;
+    readonly message?: string;
 }
-type ContinuationResult<TOutput extends PlainObject = PlainObject> = StepNode<PlainObject, PlainObject> | DoneNode<TOutput> | FailNode;
-
-/** Loads a step's prompt from a local text file, resolved relative to the workflow's `cwd` at dispatch time. */
-declare function promptTemplate(path: string): PromptTemplateSource;
-
-type JsonSchemaObject = JSONSchemaType<PlainObject> | Record<string, unknown>;
-declare function normalizeShape<T extends PlainObject>(shapeInput: ShapeInput<T>): Schema<T>;
-declare function shape<T extends PlainObject>(shapeObject: ShapeObject): Schema<T>;
-declare function jsonSchema<T extends PlainObject>(schema: JsonSchemaObject): Schema<T>;
-
-/**
- * Ambient handle onto the active run's identity and durable key-value store.
- * Backed by AsyncLocalStorage, set once per run by `runWorkflow`; step
- * continuations import this directly rather than receiving it as an argument.
- */
-declare const state: {
-    get<T = unknown>(key: string): Promise<T | undefined>;
-    set(key: string, value: unknown): Promise<void>;
-    readonly id: string;
-    readonly name: string;
-    readonly path: string;
-    readonly cwd: string | undefined;
-};
-
-/**
- * The only step-authoring primitive. `.prompt(...)` is optional; when present,
- * the step dispatches to an agent and `.do(...)` receives its structured
- * output. When absent, nothing is dispatched -- `.do(...)` receives the
- * step's input directly and is responsible for the work and the continuation
- * in one function. Either way, `.do(...)` produces a reusable `StepFactory`
- * -- call it with a live input value (`stepA(input)`) to get a `StepNode`.
- * When the inferred input type has no required keys, the argument is
- * optional (`stepA()`) and defaults to `{}`.
- */
-declare function step(config: StepConfig): {
-    prompt<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject>(source: AgentPrompt<TInput> | PromptTemplateSource, options?: PromptOptions<TOutput>): {
-        do(onOutput: StepContinuation<TInput, TOutput>): StepFactory<TInput, TOutput>;
-    };
-    do<TInput extends PlainObject = PlainObject>(onOutput: StepContinuation<TInput, TInput>): StepFactory<TInput, TInput>;
-};
-declare function done<TOutput extends PlainObject = PlainObject>(output?: TOutput): DoneNode<TOutput>;
-declare function fail(failure: Failure): FailNode;
-declare function isStepNode(value: unknown): value is StepNode;
-declare function isDoneNode(value: unknown): value is DoneNode;
-declare function isFailNode(value: unknown): value is FailNode;
-
-declare function subPrompt<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject>(source: AgentPrompt<TInput> | PromptTemplateSource, options: SubPromptOptions<TOutput>): SubPromptFactory<TInput, TOutput>;
+interface WorkflowInvocationOptions {
+    readonly branchId?: string;
+}
+type PostContinuation<TOutput extends PlainObject = PlainObject> = {
+    bivarianceHack(output: TOutput): ContinuationResult | Promise<ContinuationResult>;
+}["bivarianceHack"];
+interface WorkflowInvocationNode<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly kind: "workflowInvocation";
+    readonly workflow: Workflow<TInput, TOutput>;
+    readonly input: TInput;
+    readonly options?: WorkflowInvocationOptions;
+    post(continuation: PostContinuation<TOutput>): WorkflowInvocationNode<TInput, TOutput>;
+    readonly postContinuation?: PostContinuation<TOutput>;
+}
+interface AbsoluteDoneNode<TOutput extends PlainObject = PlainObject> {
+    readonly kind: "absoluteDone";
+    readonly output: TOutput;
+    readonly message?: string;
+}
+interface AbsoluteFailNode {
+    readonly kind: "absoluteFail";
+    readonly failure: Failure;
+    readonly message?: string;
+}
+interface RunnableWorkflowInvocationNode {
+    readonly kind: "workflowInvocation";
+    readonly workflow: unknown;
+    readonly input: PlainObject;
+    readonly options?: unknown;
+    readonly postContinuation?: PostContinuation;
+}
+type RunnableContinuationNode = StepNode<PlainObject, PlainObject> | RunnableWorkflowInvocationNode;
+type ContinuationArray = readonly RunnableContinuationNode[];
+type ParallelFailurePolicy = "fail-fast" | "all-settled";
+interface ParallelOptions {
+    readonly concurrency?: number;
+    readonly failurePolicy?: ParallelFailurePolicy;
+}
+interface ParallelNode<TOutput extends PlainObject = PlainObject> {
+    readonly kind: "parallel";
+    readonly nodes: ContinuationArray;
+    readonly options?: ParallelOptions;
+    post(continuation: PostContinuation<TOutput>): ParallelNode<TOutput>;
+    readonly postContinuation?: PostContinuation<TOutput>;
+}
+type ContinuationResult<TOutput extends PlainObject = PlainObject> = StepNode<PlainObject, PlainObject> | DoneNode<TOutput> | FailNode | RunnableWorkflowInvocationNode | AbsoluteDoneNode<TOutput> | AbsoluteFailNode | ContinuationArray | ParallelNode<TOutput>;
 
+interface WorkflowSkillOptions {
+    readonly description?: string;
+    readonly instructions?: string;
+    readonly markdown?: string;
+}
 interface Workflow<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
     readonly id: string;
+    readonly description?: string;
+    readonly skill?: string | WorkflowSkillOptions;
     readonly input?: Schema<TInput>;
     readonly output?: Schema<TOutput>;
     readonly inputShape?: ShapeInput<TInput>;
@@ -368,43 +547,26 @@ interface Workflow<TInput extends PlainObject = PlainObject, TOutput extends Pla
     readonly timeout?: TimeoutPolicyInput;
     readonly start: (input: TInput) => ContinuationResult<TOutput>;
 }
+type WorkflowBuilderOptions<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = Workflow<TInput, TOutput>;
+type DefinedWorkflow<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = Workflow<TInput, TOutput> & ((input: TInput, options?: WorkflowInvocationOptions) => WorkflowInvocationNode<TInput, TOutput>);
 
-type DeprecationTargetPackage = "@trailstep/core" | "@trailstep/authoring";
-interface DeprecationEntry {
-    /** Which published package exports this symbol. A symbol re-exported by both (like `step`,
-     * which authoring re-exports from core) needs one entry per package it's importable from, since a
-     * workflow author might import it from either. */
-    readonly package: DeprecationTargetPackage;
-    /** The exact named export identifier, e.g. "step". Matched literally against import statement
-     * text by the scanner. */
-    readonly symbol: string;
-    /** Semver version at/after which this symbol is considered deprecated (still works, warns). */
-    readonly deprecatedSince: string;
-    /** Semver version at/after which this symbol is actually removed (no longer works). Omit if the
-     * symbol is deprecated but has no planned removal. */
-    readonly removedIn?: string;
-    /** Human-readable explanation, shown verbatim in doctor/update output. */
-    readonly message: string;
-    /** Optional suggested replacement API, shown as "Suggested replacement: <this>." */
-    readonly replacement?: string;
-}
-type DeprecationManifest = readonly DeprecationEntry[];
-interface DeprecationStatus extends DeprecationEntry {
-    readonly severity: "warning" | "blocking";
-}
-
-declare const deprecationManifest: DeprecationManifest;
-interface FindDeprecationsAsOfQuery {
-    readonly package: DeprecationTargetPackage;
-    readonly version: string;
+declare const CANCELLATION_MARKER_FILE = "cancel.json";
+interface CancellationMarker {
+    readonly requestedAt?: string;
+    readonly reason?: string;
+    readonly source?: string;
 }
-/**
- * Returns every manifest entry for query.package whose deprecatedSince is at or before
- * query.version, tagged with a severity. Calling this once with version set to a target
- * version naturally captures every entry between the installed version and the target, no matter
- * how many majors are being skipped in one update.
- */
-declare function findDeprecationsAsOf(manifest: DeprecationManifest, query: FindDeprecationsAsOfQuery): readonly DeprecationStatus[];
+declare function cancellationMarkerPath(runDir: string): string;
+declare function readCancellationMarker(runDir: string): Promise<CancellationMarker | undefined>;
+declare function writeCancellationMarker(options: {
+    readonly runDir: string;
+    readonly reason?: string;
+    readonly source?: string;
+    readonly requestedAt?: Date;
+}): Promise<{
+    readonly marker: CancellationMarker;
+    readonly alreadyExisted: boolean;
+}>;
 
 type TrailStepConfigInput = TrailStepConfig | Readonly<Record<string, unknown>>;
 interface InteractiveProcessRequest {
@@ -425,7 +587,7 @@ interface WorkingAgentProcessRequest {
     readonly args: readonly string[];
     readonly cwd: string;
     readonly shell: false;
-    readonly stdio: "inherit";
+    readonly stdio: "inherit" | "pipe";
     readonly promptFile: string;
     readonly outputFile: string;
     readonly model?: string;
@@ -433,6 +595,7 @@ interface WorkingAgentProcessRequest {
 }
 interface WorkingAgentProcessResult {
     readonly exitCode: number;
+    readonly stdout?: string;
 }
 type WorkingAgentProcessRunner = (request: WorkingAgentProcessRequest) => WorkingAgentProcessResult | Promise<WorkingAgentProcessResult>;
 interface Event<TPayload extends PlainObject = PlainObject> {
@@ -440,11 +603,22 @@ interface Event<TPayload extends PlainObject = PlainObject> {
     readonly runId: string;
     readonly workflowId: string;
     readonly stepId?: string;
-    readonly type: "workflow.started" | "workflow.resumed" | "workflow.retryStarted" | "workflow.failed" | "step.started" | "step.completed" | "step.failed" | "subPrompt.started" | "subPrompt.completed" | "subPrompt.failed" | "interactive.sessionStarted" | "interactive.sessionCompleted" | "agent.toolCall" | "workflow.completed";
+    readonly type: "workflow.started" | "workflow.resumed" | "workflow.retryStarted" | "workflow.cancelRequested" | "workflow.failed" | "workflow.cancelled" | "step.started" | "step.completed" | "step.failed" | "step.cancelled" | "step.display" | "step.progress" | "step.warning" | "step.artifact" | "wait.started" | "wait.satisfied" | "wait.failed" | "subPrompt.started" | "subPrompt.completed" | "subPrompt.failed" | "interactive.sessionStarted" | "interactive.sessionCompleted" | "agent.toolCall" | "workflow.completed";
     readonly timestamp: string;
     readonly schemaVersion: "v0";
     readonly payload: TPayload;
 }
+interface WaitResultDetails {
+    readonly stepId: string;
+    readonly waitId: string;
+    readonly kind?: "input" | "check";
+    readonly message: string;
+    readonly retryAfterSeconds?: number;
+    readonly artifactPaths: {
+        readonly requestFile: string;
+        readonly answerFile: string;
+    };
+}
 type Result<TOutput extends PlainObject = PlainObject> = {
     readonly status: "success";
     readonly runId: string;
@@ -457,9 +631,30 @@ type Result<TOutput extends PlainObject = PlainObject> = {
     readonly runDir: string;
     readonly failure: Failure;
     readonly events: readonly Event[];
-};
+} | ({
+    readonly status: "waiting";
+    readonly runId: string;
+    readonly runDir: string;
+    readonly wait: WaitResultDetails;
+    readonly events: readonly Event[];
+} & {
+    /** Type-only compatibility for existing non-success branches; waiting results do not carry a runtime failure. */
+    readonly failure: never;
+}) | ({
+    readonly status: "cancelled";
+    readonly runId: string;
+    readonly runDir: string;
+    readonly cancellation: CancellationMarker;
+    readonly events: readonly Event[];
+} & {
+    /** Type-only compatibility for existing non-success branches; cancelled results do not carry a runtime failure. */
+    readonly failure: never;
+});
 interface RunWorkflowBaseOptions<TInput extends PlainObject, TOutput extends PlainObject> {
     readonly workflow: Workflow<TInput, TOutput>;
+    /** Root used for workflow/config-relative resolution and default artifact storage. Defaults to `cwd` for backward compatibility, then `process.cwd()`. */
+    readonly projectCwd?: string;
+    /** Default execution cwd for steps and agent processes. Defaults to `projectCwd`. */
     readonly cwd?: string;
     readonly runsRoot?: string;
     readonly eventSink?: (event: Event) => void | Promise<void>;
@@ -469,12 +664,29 @@ interface RunWorkflowBaseOptions<TInput extends PlainObject, TOutput extends Pla
     /** Injectable stdout-capturing runner for built-in registry provider adapters (e.g. Claude). Test-only seam. */
     readonly providerWorkingRunner?: ProviderWorkingRunner;
     readonly maxSteps?: number;
+    readonly scheduler?: {
+        readonly workers?: number;
+    };
 }
+type RunWorkflowTrackRetryOptions = {
+    readonly mode: "failed-only";
+} | {
+    readonly mode: "branch";
+    readonly branchId: string;
+} | {
+    readonly mode: "wait-answered";
+};
+type RunWorkflowRetryOptions = {
+    readonly runDir: string;
+    readonly kind: "manual" | "automatic";
+    readonly track?: RunWorkflowTrackRetryOptions;
+};
 type RunWorkflowOptions<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = RunWorkflowBaseOptions<TInput, TOutput> & ({
     readonly input: TInput;
     readonly runName: string;
     readonly resume?: undefined;
     readonly retry?: undefined;
+    readonly continue?: undefined;
 } | {
     readonly resume: {
         readonly runDir: string;
@@ -482,14 +694,21 @@ type RunWorkflowOptions<TInput extends PlainObject = PlainObject, TOutput extend
     readonly input?: undefined;
     readonly runName?: undefined;
     readonly retry?: undefined;
+    readonly continue?: undefined;
+} | {
+    readonly retry: RunWorkflowRetryOptions;
+    readonly input?: undefined;
+    readonly runName?: undefined;
+    readonly resume?: undefined;
+    readonly continue?: undefined;
 } | {
-    readonly retry: {
+    readonly continue: {
         readonly runDir: string;
-        readonly kind: "manual" | "automatic";
     };
     readonly input?: undefined;
     readonly runName?: undefined;
     readonly resume?: undefined;
+    readonly retry?: undefined;
 });
 
 /**
@@ -581,6 +800,13 @@ interface ProviderWorkingInvocationSpec {
     readonly output: ProviderOutputSpec;
     readonly repair?: ProviderWorkingRepairInvocationSpec;
 }
+type ManagedSessionPromptInjectionMode = "hidden-system-prompt-file" | "visible-prompt-file" | "visible-inline-prompt";
+type ProviderManagedSessionPromptDelivery = {
+    readonly delivery: "hidden-system-prompt-file";
+} | {
+    readonly delivery: "visible-prompt";
+    readonly mode: "visible-prompt-file" | "visible-inline-prompt";
+};
 type ProviderInteractiveInvocationSpec = {
     readonly supported: true;
     readonly command: string;
@@ -588,6 +814,13 @@ type ProviderInteractiveInvocationSpec = {
     readonly systemPromptFileFlag?: string;
     readonly modelFlag?: string;
     readonly permissionBypassFlag?: string;
+    /**
+     * Declares how TrailStep-managed standalone sessions should deliver their
+     * managed-session prompt. Hidden/system delivery is only claimed when the
+     * provider adapter has a dedicated system-prompt mechanism; otherwise the
+     * managed prompt is intentionally passed as visible user input.
+     */
+    readonly managedSessionPrompt: ProviderManagedSessionPromptDelivery;
 } | {
     readonly supported: false;
     readonly reason?: string;
@@ -610,6 +843,7 @@ interface ProviderInteractiveRequest {
     readonly systemPromptFile?: string;
     readonly cwd: string;
     readonly model?: string;
+    readonly thinking?: WorkflowAgentThinking;
     /** Undefined means bypass (per-tool confirmation is skipped by default). */
     readonly permissionMode?: "bypass" | "prompt";
     readonly env?: Readonly<Record<string, string>>;
@@ -659,25 +893,260 @@ interface ProviderAdapter {
     runInteractive(request: ProviderInteractiveRequest, runner?: InteractiveProcessRunner): Promise<InteractiveProcessResult>;
 }
 
+interface LaunchInteractiveAgentTargetOptions {
+    readonly config: TrailStepConfig;
+    readonly target: TrailStepAgentTarget;
+    readonly prompt: string;
+    readonly promptFile: string;
+    readonly cwd: string;
+    readonly runner?: InteractiveProcessRunner;
+    readonly signal?: AbortSignal;
+}
+type LaunchInteractiveAgentTargetResult = InteractiveProcessResult & {
+    readonly promptInjectionMode: ManagedSessionPromptInjectionMode;
+};
+declare function launchInteractiveAgentTarget(options: LaunchInteractiveAgentTargetOptions): Promise<LaunchInteractiveAgentTargetResult>;
+
+type ParsedTrailStepConfig = TrailStepConfig & {
+    readonly providers: NonNullable<TrailStepConfig["providers"]>;
+};
+declare function parseTrailStepConfig(value: unknown): ParsedTrailStepConfig;
+
+declare function resolveAgentTargets(options: ResolveAgentTargetsOptions): readonly TrailStepAgentTarget[];
+
 /**
- * Core's built-in known-CLI provider registry. Each entry maps a provider id
- * (matched against a `.trailstep/config.json` target's `provider` field) to a
- * core-owned CLI print-mode invocation for a single named vendor.
- *
- * This is the full four-provider set. Unlike Claude/Codex/Pi, `gemini`'s
- * adapter is structurally verified only (an injected fake stdout-capturing
- * runner in `agent.test.ts`/`gemini.test.ts`) — the real `gemini` CLI is not
- * installed in this environment, so its argv/envelope shape has not been
- * confirmed against a live process.
+ * A captured document artifact. `Document` doubles as its own
+ * `Schema<Document>`: `validate`/`diagnostics`/`assert`/`jsonSchema`/
+ * `captureMode` are static members, so passing the class itself as
+ * `.prompt(source, { output: Document })` gives both the TypeScript output
+ * type and the runtime validator from one symbol -- no separate schema
+ * constant to import or keep in sync.
  */
-declare const providerRegistry: Record<"claude" | "codex" | "pi" | "gemini", ProviderAdapter>;
-type ProviderRegistryKey = keyof typeof providerRegistry;
+declare class Document {
+    readonly content: string;
+    readonly path: string;
+    [key: string]: unknown;
+    static readonly captureMode: "raw-text";
+    static readonly jsonSchema: Record<string, unknown>;
+    static validate(value: unknown): value is Document;
+    static diagnostics(value: unknown): readonly ValidationDiagnostic[];
+    /**
+     * Deliberately duck-types instead of checking `instanceof Document`: on
+     * resume, a completed step's recorded output is replayed from
+     * `events.jsonl` via `JSON.parse`, producing a plain deserialized object —
+     * never a live `Document` instance — before `assert` is called on it. An
+     * `instanceof` check would fail every such replay. `assert` reconstructs a
+     * genuine `Document` from any content/path-shaped value, so every
+     * consumer downstream — a live capture or a replayed value alike — always
+     * receives a real `Document` instance with working prototype methods.
+     */
+    static assert(value: unknown, label?: string): Document;
+    constructor(content: string, path: string);
+}
+/**
+ * Captures `content` as a durable document artifact for the currently
+ * executing step. Must be called from within a step's `.do()` callback —
+ * it reads the step-scoped ambient context (`RunContext.currentStep`, set
+ * by `withStepContext` for the duration of the step) to determine both the
+ * directory to write into and this call's 1-based index within the step, so
+ * that a step calling `document(...)` more than once gets
+ * `document-1.md`, `document-2.md`, etc.
+ */
+declare function document(content: string): Promise<Document>;
+
+/** Ambient handle onto the active run's track-scoped durable key-value store. */
+declare const globalState: {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    update<T = unknown>(key: string, updater: (current: T | undefined) => T | Promise<T>): Promise<T>;
+};
+
+interface NotifyArtifact {
+    readonly path: string;
+    readonly mediaType?: string;
+    readonly data?: PlainObject;
+}
+interface NotifyApi {
+    progress(message: string, data?: PlainObject): Promise<void>;
+    warning(message: string, data?: PlainObject): Promise<void>;
+    artifact(name: string, artifact: NotifyArtifact): Promise<void>;
+}
+declare const notify: NotifyApi;
+
+/**
+ * Synchronously reads each named file relative to `dir` and returns its
+ * trimmed content keyed the same way, so a step's `prompt.ts` can load all
+ * of its shared markdown fragments in one call:
+ * `loadFragments(import.meta.dirname, { methodology: "../shared/methodology.md" })`.
+ */
+declare function loadFragments<TKey extends string>(dir: string, files: Record<TKey, string>): Record<TKey, string>;
+/**
+ * Renders `body` as a `## title` markdown section, or `undefined` when
+ * `body` is falsy -- so a conditional section can be inlined directly as a
+ * `promptSections(...)` argument instead of built up separately.
+ */
+declare function section(title: string, body: string | false | null | undefined): string | undefined;
+/**
+ * Joins prompt fragments and `section(...)` results with a blank line
+ * between each, dropping any falsy (conditionally-omitted) part.
+ */
+declare function promptSections(...parts: ReadonlyArray<string | false | null | undefined>): string;
+/** Renders `items` as a markdown bullet list, one `- item` per line. */
+declare function list(items: readonly string[]): string;
+
+/** Loads a step's prompt from a local text file, resolved relative to the workflow/project `cwd` at dispatch time. */
+declare function promptTemplate(path: string): PromptTemplateSource;
+
+type JsonSchemaObject = JSONSchemaType<PlainObject> | Record<string, unknown>;
+declare function normalizeShape<T extends PlainObject>(shapeInput: ShapeInput<T>): Schema<T>;
+declare function shape<T extends PlainObject>(shapeObject: ShapeObject): Schema<T>;
+declare function jsonSchema<T extends PlainObject>(schema: JsonSchemaObject): Schema<T>;
+
+/**
+ * Ambient handle onto the active run's identity and durable key-value store.
+ * Backed by AsyncLocalStorage, set once per run by `runWorkflow`; step
+ * continuations import this directly rather than receiving it as an argument.
+ */
+declare const state: {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    getPersisted<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly cwd: string | undefined;
+    readonly executionCwd: string | undefined;
+    readonly isReplayingCompletedStep: boolean;
+    readonly projectCwd: string | undefined;
+};
+
+/**
+ * The only step-authoring primitive. `.prompt(...)` is optional; when present,
+ * the step dispatches to an agent and `.do(...)` receives its structured
+ * output. When absent, nothing is dispatched -- `.do(...)` receives the
+ * step's input directly and is responsible for the work and the continuation
+ * in one function. Either way, `.do(...)` produces a reusable `StepFactory`
+ * -- call it with a live input value (`stepA(input)`) to get a `StepNode`.
+ * When the inferred input type has no required keys, the argument is
+ * optional (`stepA()`) and defaults to `{}`.
+ */
+interface StepBuilder {
+    display(content?: StepDisplayContent<PlainObject, PlainObject>, options?: PlainObject): StepBuilder;
+    wait(wait: WaitInput<PlainObject, PlainObject>): StepBuilder;
+    wait<TWaitOutput extends PlainObject = PlainObject>(wait: CheckWaitCallback<PlainObject, PlainObject, TWaitOutput>, options: WaitOptions<TWaitOutput>): StepBuilder;
+    prompt<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject>(source: AgentPrompt<TInput> | PromptTemplateSource, options?: PromptOptions<TOutput>): PromptedStepBuilder<TInput, TOutput>;
+    do<TInput extends PlainObject = PlainObject>(onOutput: StepContextContinuation<TInput, TInput>): FluentStepFactory<TInput, TInput>;
+    do<TInput extends PlainObject = PlainObject>(onOutput: StepContinuation<TInput, TInput>): FluentStepFactory<TInput, TInput>;
+}
+interface PromptedStepBuilder<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    display(content?: StepDisplayContent<TInput, TOutput>, options?: PlainObject): PromptedStepBuilder<TInput, TOutput>;
+    wait(wait: WaitInput<TInput, TOutput>): PromptedStepBuilder<TInput, TOutput>;
+    wait<TWaitOutput extends PlainObject = PlainObject>(wait: CheckWaitCallback<TInput, TOutput, TWaitOutput>, options: WaitOptions<TWaitOutput>): PromptedStepBuilder<TInput, TOutput>;
+    do(onOutput: StepContextContinuation<TInput, TOutput>): FluentStepFactory<TInput, TOutput>;
+    do(onOutput: StepContinuation<TInput, TOutput>): FluentStepFactory<TInput, TOutput>;
+}
+type FluentStepFactory<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = StepFactory<TInput, TOutput> & {
+    catch(onError: StepErrorContinuation): FluentStepFactory<TInput, TOutput>;
+    display(content?: StepDisplayContent<TInput, TOutput>, options?: PlainObject): FluentStepFactory<TInput, TOutput>;
+    wait(wait: WaitInput<TInput, TOutput>): FluentStepFactory<TInput, TOutput>;
+    wait<TWaitOutput extends PlainObject = PlainObject>(wait: CheckWaitCallback<TInput, TOutput, TWaitOutput>, options: WaitOptions<TWaitOutput>): FluentStepFactory<TInput, TOutput>;
+};
+declare function step(config: StepConfig): StepBuilder;
+declare function done<TOutput extends PlainObject = PlainObject>(output?: TOutput, options?: TerminalMessageOptions): DoneNode<TOutput>;
+declare function fail(failure: Failure, options?: TerminalMessageOptions): FailNode;
+declare function absoluteDone<TOutput extends PlainObject = PlainObject>(output?: TOutput, options?: TerminalMessageOptions): AbsoluteDoneNode<TOutput>;
+declare function absoluteFail(failure: Failure, options?: TerminalMessageOptions): AbsoluteFailNode;
+declare function parallel<TOutput extends PlainObject = PlainObject>(nodes: ContinuationArray, options?: ParallelOptions): ParallelNode<TOutput>;
+declare function isStepNode(value: unknown): value is StepNode;
+declare function isDoneNode(value: unknown): value is DoneNode;
+declare function isFailNode(value: unknown): value is FailNode;
+declare function isWorkflowInvocationNode(value: unknown): value is WorkflowInvocationNode;
+declare function isParallelNode(value: unknown): value is ParallelNode;
+declare function isAbsoluteDoneNode(value: unknown): value is AbsoluteDoneNode;
+declare function isAbsoluteFailNode(value: unknown): value is AbsoluteFailNode;
+
+declare function subPrompt<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject>(source: AgentPrompt<TInput> | PromptTemplateSource, options: SubPromptOptions<TOutput>): SubPromptFactory<TInput, TOutput>;
+
+declare function defineWorkflow<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject>(options: WorkflowBuilderOptions<TInput, TOutput>): DefinedWorkflow<TInput, TOutput>;
+
+type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+interface WorkflowInputApi<TInput extends PlainObject = PlainObject> {
+    input(): Promise<DeepReadonly<TInput>>;
+    input<TOverrideInput extends PlainObject>(): Promise<DeepReadonly<TOverrideInput>>;
+    inputValue<TKey extends keyof TInput & string>(key: TKey): Promise<DeepReadonly<TInput[TKey]>>;
+    inputValue<TOverrideInput extends PlainObject, TKey extends keyof TOverrideInput & string>(key: TKey): Promise<DeepReadonly<TOverrideInput[TKey]>>;
+    withInput<TTypedInput extends PlainObject>(): WorkflowInputApi<TTypedInput>;
+}
+declare const workflow: WorkflowInputApi;
+
+interface CliCommandSpawnRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+interface ResolvedCliCommandSpawnRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+interface ResolveCliCommandForSpawnOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly execPath?: string;
+}
+/**
+ * Built-in provider CLIs are commonly npm-installed. On Windows, npm exposes
+ * those CLIs as `.cmd` shims, which cannot be launched through Node's
+ * `spawn(..., { shell: false })` by their bare command name. Resolve npm shims
+ * to their underlying Node entrypoint when possible so provider prompts remain
+ * argv values instead of being reinterpreted by a shell.
+ */
+declare function resolveCliCommandForSpawn(request: CliCommandSpawnRequest, options?: ResolveCliCommandForSpawnOptions): Promise<ResolvedCliCommandSpawnRequest>;
+
+type DeprecationTargetPackage = "@trailstep/core" | "@trailstep/authoring";
+interface DeprecationEntry {
+    /** Which published package exports this symbol. A symbol re-exported by both (like `step`,
+     * which authoring re-exports from core) needs one entry per package it's importable from, since a
+     * workflow author might import it from either. */
+    readonly package: DeprecationTargetPackage;
+    /** The exact named export identifier, e.g. "step". Matched literally against import statement
+     * text by the scanner. */
+    readonly symbol: string;
+    /** Semver version at/after which this symbol is considered deprecated (still works, warns). */
+    readonly deprecatedSince: string;
+    /** Semver version at/after which this symbol is actually removed (no longer works). Omit if the
+     * symbol is deprecated but has no planned removal. */
+    readonly removedIn?: string;
+    /** Human-readable explanation, shown verbatim in doctor/update output. */
+    readonly message: string;
+    /** Optional suggested replacement API, shown as "Suggested replacement: <this>." */
+    readonly replacement?: string;
+}
+type DeprecationManifest = readonly DeprecationEntry[];
+interface DeprecationStatus extends DeprecationEntry {
+    readonly severity: "warning" | "blocking";
+}
+
+declare const deprecationManifest: DeprecationManifest;
+interface FindDeprecationsAsOfQuery {
+    readonly package: DeprecationTargetPackage;
+    readonly version: string;
+}
+/**
+ * Returns every manifest entry for query.package whose deprecatedSince is at or before
+ * query.version, tagged with a severity. Calling this once with version set to a target
+ * version naturally captures every entry between the installed version and the target, no matter
+ * how many majors are being skipped in one update.
+ */
+declare function findDeprecationsAsOf(manifest: DeprecationManifest, query: FindDeprecationsAsOfQuery): readonly DeprecationStatus[];
 
 type RunState = Record<string, unknown>;
 declare function defaultRunsRoot(cwd: string): string;
 declare function readRunEvents(runDir: string): Promise<Event[]>;
 declare function readRunState(runDir: string): Promise<RunState>;
 declare function writeRunState(runDir: string, state: RunState): Promise<void>;
+declare function readGlobalState(runDir: string): Promise<RunState>;
+declare function writeGlobalState(runDir: string, state: RunState): Promise<void>;
 
 interface LatestUnresolvedFailure {
     readonly event: Event;
@@ -691,7 +1160,34 @@ declare function selectLatestUnresolvedFailure(events: readonly Event[]): Latest
 
 declare function runWorkflow<TInput extends PlainObject, TOutput extends PlainObject>(options: RunWorkflowOptions<TInput, TOutput>): Promise<Result<TOutput>>;
 
-type RunSummaryStatus = "active" | "completed" | "failed" | "unknown";
+interface TrackSummary {
+    readonly runId: string;
+    readonly status: string;
+    readonly workers?: number;
+    readonly failurePolicy?: string;
+    readonly rootBranchId?: string;
+    readonly terminalBranchId?: string;
+    readonly terminalKind?: string;
+    readonly terminalOutput?: unknown;
+    readonly failure?: unknown;
+    readonly splitOccurred?: boolean;
+    readonly branches: readonly BranchSummary[];
+}
+interface BranchSummary {
+    readonly branchId: string;
+    readonly requestedBranchId?: string;
+    readonly parentBranchId?: string;
+    readonly status?: string;
+    readonly workflowId?: string;
+    readonly latestStepIndex?: number;
+    readonly latestStepId?: string;
+    readonly latestMessage?: string;
+    readonly wait?: unknown;
+    readonly failure?: unknown;
+    readonly output?: unknown;
+}
+
+type RunSummaryStatus = "active" | "completed" | "failed" | "cancelled" | "archived" | "unknown";
 interface RunSummary {
     readonly runId: string;
     readonly runDir: string;
@@ -699,6 +1195,8 @@ interface RunSummary {
     readonly workflowId?: string;
     readonly lastTimestamp?: string;
     readonly latestFailure?: LatestUnresolvedFailure;
+    readonly track?: TrackSummary;
+    readonly trackWarning?: string;
     readonly warning?: string;
 }
 declare function listRunSummaries(options: {
@@ -710,4 +1208,73 @@ declare function selectRecentFailedRunSummaries(summaries: readonly RunSummary[]
 }): RunSummary[];
 declare function newestFirst(left: RunSummary, right: RunSummary): number;
 
-export { type AgentAdapter, type AgentAdapterObject, type AgentAdapterRequest, type AgentAdapterSelection, type AgentMessage, type AgentModelTarget, type AgentPrompt, type AgentTool, type ContinuationResult, type ContinuationStepConfig, type DeprecationEntry, type DeprecationManifest, type DeprecationStatus, type DeprecationTargetPackage, Document, type DoneNode, type Event, type FailNode, type Failure, type FindDeprecationsAsOfQuery, type InteractiveProcessRequest, type InteractiveProcessResult, type InteractiveProcessRunner, type JsonSchemaObject, type LatestUnresolvedFailure, type PlainObject, type PromptOptions, type PromptTemplateSource, type ProviderAdapter, type ProviderInteractiveInvocationSpec, type ProviderInteractiveRequest, type ProviderModelDiscoveryOutputParser, type ProviderModelDiscoverySpec, type ProviderModelOverrideSupport, type ProviderOutputParsingMetadata, type ProviderOutputSpec, type ProviderOutputStyle, type ProviderPromptFileReferenceStyle, type ProviderPromptInputSpec, type ProviderRegistryKey, type ProviderSpec, type ProviderThinkingOverrideSupport, type ProviderWorkingInvocationSpec, type ProviderWorkingProcessRequest, type ProviderWorkingProcessResult, type ProviderWorkingRepairInvocationSpec, type ProviderWorkingRequest, type ProviderWorkingRunner, type ResolveAgentTargetsOptions, type ResolveRetryPolicyOptions, type ResolveTimeoutPolicyOptions, type Result, type RetryPolicy, type RetryPolicyInput, type RunSummary, type RunSummaryStatus, type RunWorkflowOptions, type Schema, type ShapeInput, type ShapeObject, type ShapePrimitive, type StepConfig, type StepContinuation, type StepErrorContinuation, type StepFactory, type StepNode, type SubPromptFactory, type SubPromptOptions, type TimeoutPolicy, type TimeoutPolicyInput, type TrailStepAgentMappings, type TrailStepAgentTarget, type TrailStepConfig, type TrailStepCustomProviderConfig, type TrailStepCustomProviderModelOverrideSupport, type TrailStepCustomProviderThinkingOverrideSupport, TrailStepFailureError, type TrailStepSettings, type TrailStepWorkflowConfig, type Workflow, type WorkflowAgentRole, type WorkflowAgentSize, type WorkflowAgentThinking, type WorkingAgentProcessRequest, type WorkingAgentProcessResult, type WorkingAgentProcessRunner, defaultRunsRoot, deprecationManifest, document, done, fail, findDeprecationsAsOf, isDoneNode, isFailNode, isStepNode, jsonSchema, list, listRunSummaries, loadFragments, newestFirst, normalizeShape, parseTrailStepConfig, promptSections, promptTemplate, providerRegistry, readRunEvents, readRunState, resolveAgentTargets, resolveRetryPolicy, resolveTimeoutPolicy, runWorkflow, section, selectLatestUnresolvedFailure, selectRecentFailedRunSummaries, shape, state, step, subPrompt, validateRetryPolicy, validateTimeoutPolicy, writeRunState };
+interface StorageLifecyclePolicy {
+    readonly enabled?: boolean;
+    readonly archiveAfterDays?: number | false;
+    readonly deleteAfterDays?: number | false;
+    readonly workflows?: Readonly<Record<string, {
+        readonly archiveAfterDays?: number | false;
+        readonly deleteAfterDays?: number | false;
+    }>>;
+}
+interface StorageLifecycleAction {
+    readonly action: "archive" | "delete-hot" | "delete-archive";
+    readonly runId: string;
+    readonly reason: string;
+    readonly path: string;
+}
+interface StorageLifecycleStatus {
+    readonly runsRoot: string;
+    readonly enabled: boolean;
+    readonly hotRuns: number;
+    readonly archivedRuns: number;
+    readonly pinnedRuns: readonly string[];
+}
+declare function storageArchiveDir(runsRoot: string): string;
+declare function storagePinPath(runDir: string): string;
+declare function readStorageLifecycleStatus(options: {
+    readonly cwd: string;
+    readonly runsRoot?: string;
+    readonly policy?: StorageLifecyclePolicy;
+}): Promise<StorageLifecycleStatus>;
+declare function planStorageLifecycle(options: {
+    readonly cwd: string;
+    readonly runsRoot?: string;
+    readonly policy?: StorageLifecyclePolicy;
+    readonly now?: Date;
+}): Promise<StorageLifecycleAction[]>;
+declare function applyStorageLifecycle(options: {
+    readonly cwd: string;
+    readonly runsRoot?: string;
+    readonly policy?: StorageLifecyclePolicy;
+    readonly now?: Date;
+    readonly dryRun?: boolean;
+}): Promise<StorageLifecycleAction[]>;
+declare function archiveRun(options: {
+    readonly runsRoot: string;
+    readonly runId: string;
+    readonly now?: Date;
+}): Promise<void>;
+declare function restoreArchivedRun(options: {
+    readonly runsRoot: string;
+    readonly runId: string;
+}): Promise<void>;
+declare function pinRun(options: {
+    readonly runsRoot: string;
+    readonly runId: string;
+}): Promise<void>;
+declare function unpinRun(options: {
+    readonly runsRoot: string;
+    readonly runId: string;
+}): Promise<void>;
+declare function deleteRun(options: {
+    readonly runsRoot: string;
+    readonly runId: string;
+}): Promise<void>;
+declare function deleteArchivedRun(options: {
+    readonly runsRoot: string;
+    readonly runId: string;
+}): Promise<void>;
+declare function parseStorageLifecycleDurationDays(value: string): number | undefined;
+
+export { type AbsoluteDoneNode, type AbsoluteFailNode, type AgentAdapter, type AgentAdapterObject, type AgentAdapterRequest, type AgentAdapterSelection, type AgentMessage, type AgentModelTarget, type AgentPrompt, type AgentTool, type BranchSummary, CANCELLATION_MARKER_FILE, type CancellationMarker, type CheckWaitCallback, type CheckWaitContext, type CheckWaitHelpers, type CliCommandSpawnRequest, type ContinuationArray, type ContinuationResult, type ContinuationStepConfig, type DeepReadonly, type DefinedWorkflow, type DeprecationEntry, type DeprecationManifest, type DeprecationStatus, type DeprecationTargetPackage, type DisplayPhase, type DoPhase, Document, type DoneNode, type Event, type FailNode, type Failure, type FindDeprecationsAsOfQuery, type InteractiveProcessRequest, type InteractiveProcessResult, type InteractiveProcessRunner, type JsonSchemaObject, type LatestUnresolvedFailure, type LaunchInteractiveAgentTargetOptions, type LaunchInteractiveAgentTargetResult, type ManagedSessionPromptInjectionMode, type NotifyApi, type NotifyArtifact, type ParallelNode, type PlainObject, type PostContinuation, type PromptOptions, type PromptPhase, type PromptTemplateSource, type ProviderAdapter, type ProviderInteractiveInvocationSpec, type ProviderInteractiveRequest, type ProviderManagedSessionPromptDelivery, type ProviderModelDiscoveryOutputParser, type ProviderModelDiscoverySpec, type ProviderModelOverrideSupport, type ProviderOutputParsingMetadata, type ProviderOutputSpec, type ProviderOutputStyle, type ProviderPromptFileReferenceStyle, type ProviderPromptInputSpec, type ProviderSpec, type ProviderThinkingOverrideSupport, type ProviderWorkingInvocationSpec, type ProviderWorkingProcessRequest, type ProviderWorkingProcessResult, type ProviderWorkingRepairInvocationSpec, type ProviderWorkingRequest, type ProviderWorkingRunner, type ResolveAgentTargetsOptions, type ResolveCliCommandForSpawnOptions, type ResolveRetryPolicyOptions, type ResolveTimeoutPolicyOptions, type ResolvedCliCommandSpawnRequest, type Result, type RetryPolicy, type RetryPolicyInput, type RunSummary, type RunSummaryStatus, type RunWorkflowOptions, type RunWorkflowRetryOptions, type RunWorkflowTrackRetryOptions, type RunnableContinuationNode, type Schema, type ShapeInput, type ShapeObject, type ShapePrimitive, type StepConfig, type StepContextContinuation, type StepContinuation, type StepContinuationOutput, type StepCwdCallback, type StepCwdContext, type StepCwdInput, type StepDisplayCallback, type StepDisplayContent, type StepDisplayContext, type StepDisplayLevel, type StepDisplayObject, type StepDisplayValue, type StepErrorContinuation, type StepFactory, type StepInvocationOptions, type StepNode, type StepPhase, type StepWaitContext, type StorageLifecycleAction, type StorageLifecyclePolicy, type StorageLifecycleStatus, type SubPromptFactory, type SubPromptOptions, type TerminalMessageOptions, type TimeoutPolicy, type TimeoutPolicyInput, type TrackSummary, type TrailStepAgentMappings, type TrailStepAgentTarget, type TrailStepConfig, type TrailStepCustomProviderConfig, type TrailStepCustomProviderModelOverrideSupport, type TrailStepCustomProviderThinkingOverrideSupport, TrailStepFailureError, type TrailStepProviderEnvironmentManifest, type TrailStepProviderInteractiveManifest, type TrailStepProviderManifest, type TrailStepProviderModelDiscoveryManifest, type TrailStepProviderModelManifest, type TrailStepProviderOutputManifest, type TrailStepProviderOutputParsingManifest, type TrailStepProviderOutputStyle, type TrailStepProviderPackageDefinition, type TrailStepProviderPromptFileReferenceStyle, type TrailStepProviderPromptManifest, type TrailStepProviderRegistration, type TrailStepProviderSource, type TrailStepProviderThinkingManifest, type TrailStepProviderWorkingManifest, type TrailStepSettings, type TrailStepWorkflowConfig, type WaitCallback, type WaitCheckResult, type WaitDefinition, type WaitDoneResult, type WaitInput, type WaitOptions, type WaitPendingInput, type WaitPendingResult, type WaitPhase, type WaitResultDetails, type Workflow, type WorkflowAgentRole, type WorkflowAgentSize, type WorkflowAgentThinking, type WorkflowBuilderOptions, type WorkflowInputApi, type WorkflowInvocationNode, type WorkflowInvocationOptions, type WorkflowSkillOptions, type WorkingAgentProcessRequest, type WorkingAgentProcessResult, type WorkingAgentProcessRunner, absoluteDone, absoluteFail, applyStorageLifecycle, archiveRun, cancellationMarkerPath, defaultRunsRoot, defineWorkflow, deleteArchivedRun, deleteRun, deprecationManifest, document, done, fail, findDeprecationsAsOf, globalState, isAbsoluteDoneNode, isAbsoluteFailNode, isDoneNode, isFailNode, isParallelNode, isStepNode, isWorkflowInvocationNode, jsonSchema, launchInteractiveAgentTarget, list, listRunSummaries, loadFragments, newestFirst, normalizeShape, notify, parallel, parseStorageLifecycleDurationDays, parseTrailStepConfig, parseTrailStepProviderManifest, pinRun, planStorageLifecycle, promptSections, promptTemplate, readCancellationMarker, readGlobalState, readRunEvents, readRunState, readStorageLifecycleStatus, resolveAgentTargets, resolveCliCommandForSpawn, resolveRetryPolicy, resolveTimeoutPolicy, restoreArchivedRun, runWorkflow, section, selectLatestUnresolvedFailure, selectRecentFailedRunSummaries, shape, state, step, storageArchiveDir, storagePinPath, subPrompt, unpinRun, validateRetryPolicy, validateTimeoutPolicy, workflow, writeCancellationMarker, writeGlobalState, writeRunState };