@trailstep/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,629 @@
+import { JSONSchemaType } from 'ajv/dist/ajv.js';
+
+type WorkflowAgentSize = "default" | "tiny" | "small" | "medium" | "large" | "xl";
+/** Provider-neutral effort/thinking level threaded into built-in provider adapters. */
+type WorkflowAgentThinking = "low" | "medium" | "high" | "xhigh" | "max";
+interface WorkflowAgentRole {
+    readonly description?: string;
+    readonly size: WorkflowAgentSize;
+    readonly thinking?: WorkflowAgentThinking;
+    readonly name?: string;
+}
+interface AgentModelTarget {
+    readonly adapterKey: string;
+    readonly model: string;
+}
+
+interface RetryPolicy {
+    readonly maxAttempts: number;
+}
+interface RetryPolicyInput {
+    readonly maxAttempts?: unknown;
+}
+interface ResolveRetryPolicyOptions {
+    readonly global?: RetryPolicyInput;
+    readonly workflow?: RetryPolicyInput;
+    readonly step?: RetryPolicyInput;
+}
+declare function resolveRetryPolicy(options: ResolveRetryPolicyOptions): RetryPolicy;
+declare function validateRetryPolicy(input: RetryPolicyInput): RetryPolicy;
+
+interface TimeoutPolicy {
+    readonly timeoutMs?: number;
+}
+type TimeoutPolicyInput = number;
+interface ResolveTimeoutPolicyOptions {
+    readonly global?: TimeoutPolicyInput;
+    readonly workflow?: TimeoutPolicyInput;
+    readonly step?: TimeoutPolicyInput;
+}
+declare function resolveTimeoutPolicy(options: ResolveTimeoutPolicyOptions): TimeoutPolicy;
+declare function validateTimeoutPolicy(input: unknown): TimeoutPolicy;
+
+interface TrailStepCustomProviderConfig {
+    readonly binary: string;
+    readonly args?: readonly string[];
+    readonly interactiveArgs?: readonly string[];
+    readonly cwd?: string;
+    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.
+     */
+    readonly provider: string;
+    readonly model?: string;
+    readonly thinking?: WorkflowAgentThinking;
+    readonly args?: readonly string[];
+    /** Undefined means bypass (per-tool confirmation is skipped by default). */
+    readonly permissionMode?: "bypass" | "prompt";
+}
+type TrailStepAgentMappings = Readonly<Record<string, readonly TrailStepAgentTarget[]>>;
+interface TrailStepSettings {
+    readonly retry?: RetryPolicyInput;
+    readonly timeout?: TimeoutPolicyInput;
+    readonly [key: string]: unknown;
+}
+interface TrailStepWorkflowConfig {
+    readonly agents?: TrailStepAgentMappings;
+    readonly settings?: TrailStepSettings;
+}
+interface TrailStepConfig {
+    readonly version: 1;
+    readonly customProviders: Readonly<Record<string, TrailStepCustomProviderConfig>>;
+    readonly agents: TrailStepAgentMappings;
+    readonly settings?: TrailStepSettings;
+    readonly workflows?: Readonly<Record<string, TrailStepWorkflowConfig>>;
+}
+interface ResolveAgentTargetsOptions {
+    readonly config: TrailStepConfig;
+    readonly workflowId: string;
+    readonly roleName: string;
+    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;
+    readonly message: string;
+}
+interface Schema<T extends PlainObject = PlainObject> {
+    readonly validate: (value: unknown) => value is T;
+    readonly diagnostics: (value: unknown) => readonly ValidationDiagnostic[];
+    readonly assert: (value: unknown, label?: string) => T;
+    readonly jsonSchema: Record<string, unknown>;
+    readonly captureMode?: "json" | "raw-text";
+}
+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;
+    readonly output: Schema<TOutput>;
+    readonly prompt: AgentPrompt<TInput>;
+    readonly requirements: WorkflowAgentRole;
+    readonly adapter?: AgentAdapterSelection<TInput, TOutput>;
+}
+
+interface AgentMessage {
+    readonly role: "user" | "assistant" | "system";
+    readonly content: string;
+}
+type AgentPromptRenderer<TInput extends PlainObject = PlainObject> = {
+    bivarianceHack(context: {
+        readonly input: TInput;
+    }): string;
+}["bivarianceHack"];
+type AgentPrompt<TInput extends PlainObject = PlainObject> = string | AgentPromptRenderer<TInput>;
+interface AgentTool<TInput extends PlainObject = PlainObject> {
+    readonly name: string;
+    readonly description?: string;
+    readonly schema: Schema<TInput>;
+    call(input: TInput): void | Promise<void>;
+}
+
+interface AgentAdapterRequest<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly messages: readonly AgentMessage[];
+    readonly tools: readonly AgentTool<TOutput>[];
+    readonly requirements: WorkflowAgentRole;
+    readonly model: AgentModelTarget;
+    readonly step: AgentStepRequestConfig<TInput, TOutput>;
+    readonly input: TInput;
+}
+type AgentAdapter<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = {
+    bivarianceHack(request: AgentAdapterRequest<TInput, TOutput>): void | Promise<void>;
+}["bivarianceHack"];
+interface AgentAdapterObject<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    runAgentStep(request: AgentAdapterRequest<TInput, TOutput>): void | Promise<void>;
+}
+type AgentAdapterSelection<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = AgentAdapter<TInput, TOutput> | AgentAdapterObject<TInput, TOutput>;
+
+interface Failure {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: unknown;
+}
+declare class TrailStepFailureError extends Error {
+    readonly failure: Failure;
+    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 PromptTemplateSource {
+    readonly kind: "promptTemplate";
+    readonly path: string;
+}
+/** The object passed to `step(...)`. Always relevant, regardless of whether `.prompt(...)` is called. */
+interface StepConfig {
+    readonly id: string;
+    readonly retry?: RetryPolicyInput;
+    readonly timeout?: TimeoutPolicyInput;
+}
+/**
+ * The object passed as `.prompt(...)`'s second argument -- config that only
+ * matters when a step dispatches to an agent, so it lives here instead of
+ * on `StepConfig` where a no-prompt step could set it and have it silently
+ * ignored. `output` constrains the agent's structured-output tool.
+ */
+interface PromptOptions<TOutput extends PlainObject = PlainObject> {
+    readonly output?: ShapeInput<TOutput>;
+    readonly agent?: string;
+    readonly mode?: "working" | "interactive";
+    readonly adapter?: AgentAdapterSelection<PlainObject, TOutput>;
+    readonly maxSubPrompts?: number;
+}
+interface SubPromptOptions<TOutput extends PlainObject = PlainObject> {
+    readonly output?: ShapeInput<TOutput>;
+    readonly agent?: string;
+    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. */
+interface ContinuationStepConfig<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly id: string;
+    readonly input: TInput;
+    readonly output?: ShapeInput<TOutput>;
+    readonly prompt?: AgentPrompt<TInput> | PromptTemplateSource;
+    readonly agent?: string;
+    readonly mode?: "working" | "interactive";
+    readonly adapter?: AgentAdapterSelection<TInput, TOutput>;
+    readonly maxSubPrompts?: number;
+    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. */
+    readonly onOutput: StepContinuation<TInput, TOutput>;
+    readonly onError?: StepErrorContinuation;
+}
+/**
+ * Returned by `step(...).prompt(...)?.do(...)`: a reusable step definition,
+ * called with a live input value to produce an actual `StepNode`
+ * (`stepA(input)`). Chain `.catch(...)` to add an error continuation before
+ * 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>) & {
+    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 DoneNode<TOutput extends PlainObject = PlainObject> {
+    readonly kind: "done";
+    readonly output: TOutput;
+}
+/** Terminates the workflow as a failure without dispatching a step -- no step.* events, just workflow.failed. */
+interface FailNode {
+    readonly kind: "fail";
+    readonly failure: Failure;
+}
+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 Workflow<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> {
+    readonly id: string;
+    readonly input?: Schema<TInput>;
+    readonly output?: Schema<TOutput>;
+    readonly inputShape?: ShapeInput<TInput>;
+    readonly outputShape?: ShapeInput<TOutput>;
+    readonly agents?: Readonly<Record<string, WorkflowAgentRole>>;
+    readonly retry?: RetryPolicyInput;
+    readonly timeout?: TimeoutPolicyInput;
+    readonly start: (input: TInput) => ContinuationResult<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;
+}
+/**
+ * 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 TrailStepConfigInput = TrailStepConfig | Readonly<Record<string, unknown>>;
+interface InteractiveProcessRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly shell: false;
+    readonly stdio: "inherit";
+    readonly env?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+}
+interface InteractiveProcessResult {
+    readonly exitCode: number;
+}
+type InteractiveProcessRunner = (request: InteractiveProcessRequest) => InteractiveProcessResult | Promise<InteractiveProcessResult>;
+interface WorkingAgentProcessRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly shell: false;
+    readonly stdio: "inherit";
+    readonly promptFile: string;
+    readonly outputFile: string;
+    readonly model?: string;
+    readonly signal?: AbortSignal;
+}
+interface WorkingAgentProcessResult {
+    readonly exitCode: number;
+}
+type WorkingAgentProcessRunner = (request: WorkingAgentProcessRequest) => WorkingAgentProcessResult | Promise<WorkingAgentProcessResult>;
+interface Event<TPayload extends PlainObject = PlainObject> {
+    readonly id: string;
+    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 timestamp: string;
+    readonly schemaVersion: "v0";
+    readonly payload: TPayload;
+}
+type Result<TOutput extends PlainObject = PlainObject> = {
+    readonly status: "success";
+    readonly runId: string;
+    readonly runDir: string;
+    readonly output: TOutput;
+    readonly events: readonly Event[];
+} | {
+    readonly status: "failure";
+    readonly runId: string;
+    readonly runDir: string;
+    readonly failure: Failure;
+    readonly events: readonly Event[];
+};
+interface RunWorkflowBaseOptions<TInput extends PlainObject, TOutput extends PlainObject> {
+    readonly workflow: Workflow<TInput, TOutput>;
+    readonly cwd?: string;
+    readonly runsRoot?: string;
+    readonly eventSink?: (event: Event) => void | Promise<void>;
+    readonly processRunner?: InteractiveProcessRunner;
+    readonly trailstepConfig?: TrailStepConfigInput;
+    readonly workingAgentProcessRunner?: WorkingAgentProcessRunner;
+    /** Injectable stdout-capturing runner for built-in registry provider adapters (e.g. Claude). Test-only seam. */
+    readonly providerWorkingRunner?: ProviderWorkingRunner;
+    readonly maxSteps?: number;
+}
+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 resume: {
+        readonly runDir: string;
+    };
+    readonly input?: undefined;
+    readonly runName?: undefined;
+    readonly retry?: undefined;
+} | {
+    readonly retry: {
+        readonly runDir: string;
+        readonly kind: "manual" | "automatic";
+    };
+    readonly input?: undefined;
+    readonly runName?: undefined;
+    readonly resume?: undefined;
+});
+
+/**
+ * Request shape for a built-in provider's non-interactive ("working") invocation.
+ * The runtime has already written `promptFile`; the adapter is responsible for
+ * invoking its vendor CLI and writing a single JSON object to `outputFile`.
+ */
+interface ProviderWorkingRequest {
+    readonly promptFile: string;
+    readonly outputFile: string;
+    readonly usageFile?: string;
+    readonly cwd: string;
+    readonly model?: string;
+    readonly thinking?: WorkflowAgentThinking;
+    readonly captureMode?: "json" | "raw-text";
+    readonly signal?: AbortSignal;
+}
+/** Low-level process request for a provider's stdout-capturing runner. */
+interface ProviderWorkingProcessRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /**
+     * Prompt text to write to the child's stdin and close, rather than appending
+     * it to `args`. Windows' `CreateProcess` concatenates argv into a single
+     * command-line string capped around 32,767 characters, so large rendered
+     * prompts must use either a tiny @prompt-file argv reference or stdin.
+     * Providers only set this for CLI flows that cannot use an existing prompt
+     * file artifact (for example, Claude's output-repair prompt).
+     */
+    readonly stdin?: string;
+    readonly signal?: AbortSignal;
+}
+interface ProviderWorkingProcessResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+}
+/**
+ * Spawns a provider's CLI, collecting stdout for envelope parsing instead of
+ * inheriting it. Runners may ignore stdin or pipe it depending on whether
+ * `stdin` is set. Injectable for tests.
+ */
+type ProviderWorkingRunner = (request: ProviderWorkingProcessRequest) => ProviderWorkingProcessResult | Promise<ProviderWorkingProcessResult>;
+/** Request shape for a built-in provider's interactive (human-in-the-loop) invocation. */
+interface ProviderInteractiveRequest {
+    readonly prompt: string;
+    /**
+     * Path to a file containing the full interactive prompt, for adapters that
+     * support a system-prompt-file flag instead of a positional prompt argument.
+     */
+    readonly systemPromptFile?: string;
+    readonly cwd: string;
+    readonly model?: string;
+    /** Undefined means bypass (per-tool confirmation is skipped by default). */
+    readonly permissionMode?: "bypass" | "prompt";
+    readonly env?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Request shape for a one-shot repair of a working-agent turn whose final
+ * answer failed JSON extraction. `sessionId` and `rawResultText` are the
+ * malformed turn's own session id and (best-effort) raw final-answer text, as
+ * surfaced by the failed `runWorking` call.
+ */
+interface ProviderWorkingRepairRequest {
+    readonly sessionId: string;
+    readonly rawResultText: string;
+    readonly outputFile: string;
+    readonly usageFile?: string;
+    readonly cwd: string;
+    readonly model?: string;
+    readonly thinking?: WorkflowAgentThinking;
+    readonly outputSchema: Record<string, unknown>;
+    readonly captureMode?: "json" | "raw-text";
+    readonly signal?: AbortSignal;
+}
+/**
+ * A built-in, core-owned known-CLI adapter for a single named vendor.
+ * This is CLI print-mode invocation knowledge, not an in-process vendor SDK
+ * adapter: adapters spawn a real CLI process and never import a vendor SDK
+ * library.
+ */
+interface ProviderAdapter {
+    readonly id: string;
+    /** Non-interactive invocation: writes `request.outputFile` itself before resolving. */
+    runWorking(request: ProviderWorkingRequest, runner?: ProviderWorkingRunner): Promise<void>;
+    /**
+     * Optional one-shot repair of a malformed final answer, for providers whose
+     * CLI can resume a prior session (currently only `claude`). Malformed JSON
+     * after a real agentic turn should not trigger a full re-run of the task —
+     * the agent may have already made real file edits, and redoing the task
+     * from scratch risks duplicating or conflicting with them — so this asks
+     * the *same* session to reformat its last answer only. Providers without a
+     * resumable session omit this entirely and keep today's immediate-failure
+     * behavior.
+     */
+    repairOutput?(request: ProviderWorkingRepairRequest, runner?: ProviderWorkingRunner): Promise<void>;
+    /** Interactive invocation: inherited stdio, a human is present. */
+    runInteractive(request: ProviderInteractiveRequest, runner?: InteractiveProcessRunner): Promise<InteractiveProcessResult>;
+}
+
+/**
+ * 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.
+ */
+declare const providerRegistry: Record<"claude" | "codex" | "pi" | "gemini", ProviderAdapter>;
+type ProviderRegistryKey = keyof typeof providerRegistry;
+
+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>;
+
+interface LatestUnresolvedFailure {
+    readonly event: Event;
+    readonly replayPosition: number;
+    readonly sourceFailureEventId?: string;
+    readonly workflowId: string;
+    readonly workflowInput?: PlainObject;
+    readonly stepId?: string;
+}
+declare function selectLatestUnresolvedFailure(events: readonly Event[]): LatestUnresolvedFailure | undefined;
+
+declare function runWorkflow<TInput extends PlainObject, TOutput extends PlainObject>(options: RunWorkflowOptions<TInput, TOutput>): Promise<Result<TOutput>>;
+
+type RunSummaryStatus = "active" | "completed" | "failed" | "unknown";
+interface RunSummary {
+    readonly runId: string;
+    readonly runDir: string;
+    readonly status: RunSummaryStatus;
+    readonly workflowId?: string;
+    readonly lastTimestamp?: string;
+    readonly latestFailure?: LatestUnresolvedFailure;
+    readonly warning?: string;
+}
+declare function listRunSummaries(options: {
+    readonly cwd: string;
+    readonly runsRoot?: string;
+}): Promise<RunSummary[]>;
+declare function selectRecentFailedRunSummaries(summaries: readonly RunSummary[], options?: {
+    readonly now?: Date;
+}): 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 ProviderInteractiveRequest, type ProviderRegistryKey, type ProviderWorkingProcessRequest, type ProviderWorkingProcessResult, 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, 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 };