@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/definitions/pipelines/pipeline-definitions-client.d.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import { PipelineDefinitions } from "../../generated/sdk.gen";
+import type { PostApiPipelineDefinitionsByPipelineDefinitionIdVersionsResponses, PostApiPipelineDefinitionsResponses } from "../../generated/types.gen";
+type RequestOptions = {
+    headers?: Record<string, unknown> | undefined;
+};
+export type PipelineDefinition = PostApiPipelineDefinitionsResponses[200];
+export type PublishPipelineVersionResult = PostApiPipelineDefinitionsByPipelineDefinitionIdVersionsResponses[200];
+declare const pipelineDocumentIssueSchema: z.ZodObject<{
+    code: z.ZodString;
+    path: z.ZodString;
+    message: z.ZodString;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One validation error the server reports for a rejected pipeline document. */
+export type PipelineDocumentIssue = z.infer<typeof pipelineDocumentIssueSchema>;
+type ApiError = {
+    title?: string;
+    detail?: string;
+    code?: string;
+    meta?: {
+        [key: string]: unknown;
+    };
+};
+/**
+ * Thrown when the API rejects a request. `issues` carries the per-path
+ * validation errors of a `PIPELINE_DOCUMENT_INVALID` rejection.
+ */
+export declare class PipelineDefinitionsApiError extends Error {
+    readonly code: string | undefined;
+    readonly issues: readonly PipelineDocumentIssue[];
+    constructor(error: ApiError);
+}
+export declare function createPipelineDefinitionsClient(baseUrl: string): ReturnType<typeof buildPipelineDefinitionsClient>;
+declare const buildPipelineDefinitionsClient: (pipelineDefinitions: PipelineDefinitions) => {
+    listByProjectId: (projectId: string, options?: RequestOptions) => Promise<{
+        id: string;
+        projectId: string;
+        key: string;
+        name: string;
+        archivedAt: string | unknown;
+        currentVersion: {
+            id: string;
+            pipelineDefinitionId: string;
+            version: number;
+            schemaVersion: number;
+            contentHash: string;
+            definition: {
+                [key: string]: unknown;
+            };
+            steps: Array<{
+                stepKey: string;
+                stepDefinitionId: string;
+            }>;
+            createdAt: string;
+        } | unknown;
+        createdAt: string;
+        updatedAt: string;
+    }[]>;
+    get: (pipelineDefinitionId: string, options?: RequestOptions) => Promise<{
+        id: string;
+        projectId: string;
+        key: string;
+        name: string;
+        archivedAt: string | unknown;
+        currentVersion: {
+            id: string;
+            pipelineDefinitionId: string;
+            version: number;
+            schemaVersion: number;
+            contentHash: string;
+            definition: {
+                [key: string]: unknown;
+            };
+            steps: Array<{
+                stepKey: string;
+                stepDefinitionId: string;
+            }>;
+            createdAt: string;
+        } | unknown;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Creates a pipeline; `document`, when given, is published as version 1. */
+    create: (input: {
+        projectId: string;
+        key: string;
+        name: string;
+        document?: Record<string, unknown>;
+    }, options?: RequestOptions) => Promise<{
+        id: string;
+        projectId: string;
+        key: string;
+        name: string;
+        archivedAt: string | unknown;
+        currentVersion: {
+            id: string;
+            pipelineDefinitionId: string;
+            version: number;
+            schemaVersion: number;
+            contentHash: string;
+            definition: {
+                [key: string]: unknown;
+            };
+            steps: Array<{
+                stepKey: string;
+                stepDefinitionId: string;
+            }>;
+            createdAt: string;
+        } | unknown;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Publishes `document` as the pipeline's next version, which becomes the
+     * active one. `published` is false when it matched the latest version.
+     */
+    publishVersion: (pipelineDefinitionId: string, document: Record<string, unknown>, options?: RequestOptions) => Promise<{
+        published: boolean;
+        version: {
+            id: string;
+            pipelineDefinitionId: string;
+            version: number;
+            schemaVersion: number;
+            contentHash: string;
+            definition: {
+                [key: string]: unknown;
+            };
+            steps: Array<{
+                stepKey: string;
+                stepDefinitionId: string;
+            }>;
+            createdAt: string;
+        };
+        pipelineDefinition: {
+            id: string;
+            projectId: string;
+            key: string;
+            name: string;
+            archivedAt: string | unknown;
+            currentVersion: {
+                id: string;
+                pipelineDefinitionId: string;
+                version: number;
+                schemaVersion: number;
+                contentHash: string;
+                definition: {
+                    [key: string]: unknown;
+                };
+                steps: Array<{
+                    stepKey: string;
+                    stepDefinitionId: string;
+                }>;
+                createdAt: string;
+            } | unknown;
+            createdAt: string;
+            updatedAt: string;
+        };
+    }>;
+    activateVersion: (pipelineDefinitionId: string, version: number, options?: RequestOptions) => Promise<{
+        id: string;
+        projectId: string;
+        key: string;
+        name: string;
+        archivedAt: string | unknown;
+        currentVersion: {
+            id: string;
+            pipelineDefinitionId: string;
+            version: number;
+            schemaVersion: number;
+            contentHash: string;
+            definition: {
+                [key: string]: unknown;
+            };
+            steps: Array<{
+                stepKey: string;
+                stepDefinitionId: string;
+            }>;
+            createdAt: string;
+        } | unknown;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    listVersions: (pipelineDefinitionId: string, options?: RequestOptions) => Promise<{
+        id: string;
+        pipelineDefinitionId: string;
+        version: number;
+        schemaVersion: number;
+        contentHash: string;
+        createdAt: string;
+    }[]>;
+    getVersion: (pipelineDefinitionId: string, version: number, options?: RequestOptions) => Promise<{
+        id: string;
+        pipelineDefinitionId: string;
+        version: number;
+        schemaVersion: number;
+        contentHash: string;
+        definition: {
+            [key: string]: unknown;
+        };
+        steps: Array<{
+            stepKey: string;
+            stepDefinitionId: string;
+        }>;
+        createdAt: string;
+    }>;
+};
+export {};

package/dist/definitions/pipelines/work-item-fields.d.ts

@@ -0,0 +1,93 @@
+import type { GetApiWorkItemsByWorkItemIdResponses } from "../../generated/types.gen";
+/**
+ * Top-level work-item properties addressable by the default-pipeline-assignment
+ * DSL's `workItem.<field>` accessor (`define-default-pipeline-assignment.ts`)
+ * and, reversed, its `scarn pipelines pull` file generator
+ * (`default-pipeline-assignment-file-generator.ts`). `fields` is deliberately excluded from this
+ * list: it's reached via `.field(name)` on every one of those accessors, not
+ * as a top-level property.
+ *
+ * This is the single source of truth for the list — it must stay in sync
+ * with the `workItem` fact/context shape every corresponding server-side
+ * resolver publishes (`buildFacts` in
+ * `evaluate-default-pipeline-assignment.ts`; `buildResolvedWorkItemContext`
+ * in `resolve-node-input.ts`).
+ */
+export declare const WORK_ITEM_TOP_LEVEL_FIELDS: readonly ["id", "projectId", "platform", "platformId", "platformKey", "url", "title", "description", "sourceCreatedAt", "sourceUpdatedAt", "createdByUserId", "parentWorkItemId", "createdAt", "updatedAt"];
+export type WorkItemTopLevelField = (typeof WORK_ITEM_TOP_LEVEL_FIELDS)[number];
+/**
+ * The literal union of valid work-item platforms, sourced from the generated
+ * OpenAPI response type (`GetApiWorkItemsByWorkItemIdResponses[200]["platform"]`)
+ * rather than hand-duplicated, so it cannot drift from the API contract. It
+ * must mirror `WorkItemPlatform` in
+ * `packages/core/src/work-items/work-item/domain/work-item-platform.ts`.
+ */
+type WorkItemPlatformLiteral = GetApiWorkItemsByWorkItemIdResponses[200]["platform"];
+/**
+ * Per-field value types for every member of `WORK_ITEM_TOP_LEVEL_FIELDS`,
+ * mirroring exactly what the server-side resolvers publish at evaluation/
+ * resolution time (`buildFacts` for default-pipeline-assignment;
+ * `buildResolvedWorkItemContext` for regular pipeline/step input bindings).
+ * Notably, `sourceCreatedAt`/`sourceUpdatedAt`/`createdAt`/`updatedAt` are
+ * serialized as ISO date strings (or `null`), never `Date` objects.
+ */
+export type WorkItemTopLevelFieldTypeMap = {
+    id: string;
+    projectId: string;
+    platform: WorkItemPlatformLiteral;
+    platformId: string | null;
+    platformKey: string;
+    url: string | null;
+    title: string;
+    description: string | null;
+    sourceCreatedAt: string | null;
+    sourceUpdatedAt: string | null;
+    createdByUserId: string | null;
+    parentWorkItemId: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+};
+/**
+ * The path prefix marking a reference into a work item's platform-specific
+ * `fields` bag (a Jira custom field, a GitHub label, etc.), as opposed to a
+ * `WorkItemTopLevelField`. Shared by every accessor that authors these paths
+ * (`workItem.field(name)` in the default-pipeline-assignment DSL) and every resolver that
+ * reads them back (`resolveWorkItemFieldPath` below; the JSONPath-rooted
+ * variant in `evaluate-default-pipeline-assignment.ts`, which layers a `$.`
+ * prefix on top of this same convention).
+ */
+export declare const WORK_ITEM_FIELDS_PATH_PREFIX = "fields.";
+/**
+ * Resolves a work-item path — either a `WorkItemTopLevelField` name (a
+ * single, code-controlled segment) or a `fields.<name>` reference into the
+ * platform-specific `fields` bag — against a plain object shaped like
+ * `WorkItemTopLevelFieldTypeMap & { fields: ... }`.
+ *
+ * `<name>` in `fields.<name>` is an arbitrary, unescaped, platform-supplied
+ * field name (a Jira custom field label, a GitHub key, etc.) that may
+ * contain any character, including `.`, `[`, `]`, `~`, `^`, `;`, or even be
+ * the empty string. A naive dot-splitting path walker would silently
+ * misresolve a field literally named `"a.b"` as nested property access
+ * (`fields.a.b`) instead of the flat key `fields["a.b"]` — a silent-wrong-
+ * match hazard, not a visible error, since the walker degrades to "no
+ * match"/"wrong match" rather than throwing.
+ *
+ * This resolver sidesteps that hazard entirely: everything after `fields.`
+ * is treated as one atomic, unsplit key. Every work-item path resolver in
+ * the codebase must use this same convention for a field name to round-trip
+ * correctly — see `evaluate-default-pipeline-assignment.ts`'s
+ * `resolveWorkItemAssignmentPath` (which layers `$.` path-rooting on top of
+ * this function) and `resolve-node-input.ts`'s `work_item` binding
+ * resolution (which calls this function directly, replacing what used to be
+ * a dot-splitting walker shared with unrelated binding sources and
+ * susceptible to the exact hazard described above).
+ *
+ * `path` is untyped (`string`, not `WorkItemTopLevelField | \`fields.${string}\``)
+ * because callers validate membership separately
+ * (`WORK_ITEM_TOP_LEVEL_FIELDS`/`isSupportedWorkItemField`) before ever
+ * reaching a resolver — this function's contract is purely "resolve
+ * whatever path string you hand it, treating `fields.` as atomic," not
+ * "validate the path."
+ */
+export declare function resolveWorkItemFieldPath(record: unknown, path: string): unknown;
+export {};

package/dist/definitions/steps/compile-mcps.d.ts

@@ -0,0 +1,34 @@
+import type { EnvVarSpec, EnvVarsInput } from "../../env-vars";
+import type { HealthChecksInput } from "../../health-checks";
+import type { OpenCodeMcpServers } from "../../opencode-mcp";
+import { type McpHandle } from "./define-mcp";
+/**
+ * Compiles a step's `mcps` (`defineMcp` handles keyed by the step's server
+ * key) into the wire fields, and merges them with the step's own
+ * `healthChecks` and `environment.vars`.
+ */
+type InheritEnvVarSpec = Extract<EnvVarSpec, {
+    source: "inherit";
+}>;
+export type CompiledMcps = {
+    opencodeMcpJson: OpenCodeMcpServers;
+    healthChecks: HealthChecksInput;
+    envEntries: InheritEnvVarSpec[];
+};
+export type StepMcpFields = {
+    opencodeMcpJson: OpenCodeMcpServers | null;
+    healthChecksJson: HealthChecksInput | null;
+    envJson: EnvVarsInput | null;
+};
+/** Throws when a value under `mcps` is not a `defineMcp` handle. */
+export declare function compileMcps(mcps: Readonly<Record<string, McpHandle>>, stepKey: string): CompiledMcps;
+/**
+ * Merges compiled `mcps` into the step's own fields: MCP checks run before the
+ * step's own, and a step var replaces an MCP var of the same name.
+ */
+export declare function mergeStepMcps(stepKey: string, input: {
+    mcps: Readonly<Record<string, McpHandle>> | undefined;
+    healthChecks: HealthChecksInput | null | undefined;
+    envJson: EnvVarsInput | null;
+}): StepMcpFields;
+export {};

package/dist/definitions/steps/define-code-step.d.ts

@@ -0,0 +1,84 @@
+import type { ZodType } from "zod";
+import type { EffectiveResult, StepRetryEntry } from "./define-step";
+import type { BuiltInError } from "../../pipelines/types";
+import { type StepHandle } from "./step-handle";
+import { type CodeStepEnvironment } from "./runtime";
+import type { AnyStepFeature } from "./step-features";
+/** What the worker passes a code step besides its input. */
+export type CodeStepContext = {
+    /**
+     * Absolute path of the step-artifacts folder, which already exists. Write
+     * a file here and return its path relative to this folder with
+     * `Artifact.path(...)` to fill an artifact field.
+     */
+    artifactsDir: string;
+};
+export type CodeStepFn<TInput, TResult> = (input: TInput, context: CodeStepContext) => TResult | Promise<TResult>;
+export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TFeatures extends ReadonlyArray<AnyStepFeature> = never[]> = {
+    key: string;
+    name: string;
+    description?: string | null;
+    version?: number;
+    /**
+     * The step's own implementation. It may be an inline arrow or a reference
+     * to a function declared elsewhere; it does not need to be exported. Only
+     * the file that defines the step is pushed (as `{ sourceFile }`), and the
+     * worker re-imports that file from the repo checkout and finds the step by
+     * `key`, so closures and module-level helpers keep working. The step must
+     * be exported by name from that file.
+     *
+     * Typed against `EffectiveResult`, not the bare `resultSchema` output, so
+     * a step with `features: [Features.notifications()]` can return the
+     * `$scarn_notifications_v1` field (e.g. via `Notify.inApp(...)`)
+     * without a type error.
+     */
+    fn: CodeStepFn<TInput["_output"], EffectiveResult<TResult["_output"], TFeatures>>;
+    inputSchema?: TInput;
+    resultSchema?: TResult;
+    /**
+     * Step features to attach — unlike `defineStep()`, only each feature's
+     * `_resultExtension` applies here (there is no prompt to append
+     * to on a `kind: "code"` step).
+     */
+    features?: TFeatures;
+    /**
+     * Where the step's runner executes (`runtime`) and the environment variables
+     * it receives (`vars`). The function reads the variables back through
+     * `process.env`; unlike `defineStep()`, there is no typed `env` argument to
+     * `fn`.
+     *
+     * Omitting `runtime` compiles to `Runtime.managed.bun1()`, a worker-supplied
+     * container. `Runtime.devcontainer()` opts into the project's own container,
+     * which must then provide a JS runtime for the runner script.
+     *
+     * `Runtime.host()` is not supported: a code step runs repo code, so it needs
+     * a workspace, and the host runtime has none. It is a type error here and
+     * `validateDefinitionSpecs` rejects it for hand-built specs.
+     *
+     * `repo` follows the same rules as for `defineStep()`; `result` is typed from
+     * `resultSchema`.
+     */
+    environment?: CodeStepEnvironment<TInput["_output"], TResult["_output"]>;
+    status?: "draft" | "active";
+    /**
+     * Error names this step can fail with, beyond the built-in ones. A
+     * pipeline's `retry.on` and `catch.on` may name them.
+     */
+    errors?: readonly string[];
+    /** As `defineStep()`'s `retry`: how a standalone Task of this step retries. */
+    retry?: readonly StepRetryEntry[];
+};
+/**
+ * Defines a `kind: "code"` step: a plain function instead of an LLM
+ * prompt. Produces the same callable step handle `defineStep()` does (so a
+ * pipeline calls it the same way), but with no `prompt` and a live
+ * `entrypoint.fn` reference attached instead — see `StepDefinitionSpec`'s
+ * own doc comment for what happens to it during collection.
+ */
+export declare function codeStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<AnyStepFeature> = never[], const TErrors extends string = never>(config: Omit<DefineCodeStepInput<TInput, TResult, TFeatures>, "errors" | "retry"> & {
+    errors?: readonly TErrors[];
+    retry?: readonly {
+        on: readonly (BuiltInError | TErrors)[];
+        maxAttempts: number;
+    }[];
+}): StepHandle<TInput["_output"], EffectiveResult<TResult["_output"], TFeatures>, TErrors>;

package/dist/definitions/steps/define-mcp.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { toolHealthCheckSchema } from "../../health-checks";
+import { type McpServerConfig, type McpServerDefinition } from "./mcp-server-config";
+export type { McpLocalServerFields, McpRefServerFields, McpRemoteServerFields, McpServerDefinition, McpServerType, } from "./mcp-server-config";
+type ToolCheckAuthoring = Omit<z.input<typeof toolHealthCheckSchema>, "kind" | "mcp" | "name">;
+/** A health check on a `defineMcp` server: a tool check without `mcp`/`name`. */
+export type McpCheckInput = ToolCheckAuthoring & {
+    enabled?: boolean;
+};
+/** The fields `overrideCheck` may change. */
+export type McpCheckPatch = Partial<Pick<McpCheckInput, "tool" | "args" | "timeoutSeconds" | "severity" | "serialGroup">>;
+export type McpOp = {
+    readonly op: "override";
+    readonly name: string;
+    readonly patch: McpCheckPatch;
+} | {
+    readonly op: "enable";
+    readonly name: string;
+} | {
+    readonly op: "disable";
+    readonly name: string;
+} | {
+    readonly op: "add";
+    readonly name: string;
+    readonly check: McpCheckInput;
+} | {
+    readonly op: "disableAll";
+};
+/**
+ * `{ type: "ref", name }`, `{ type: "local", name, command, cwd?,
+ * environment? }` or `{ type: "remote", name, url, headers?, oauth? }`, each
+ * with the shared OpenCode fields (`timeout`, `protocol`, `codemode`). Inline
+ * `environment` and `headers` values must be written as `{env:VAR}`.
+ */
+export type DefineMcpConfig<TChecks extends Record<string, McpCheckInput>> = McpServerConfig & {
+    /** Worker env vars the server needs; a missing one fails the step. */
+    env?: readonly string[];
+    /** Worker env vars passed through when set. */
+    optionalEnv?: readonly string[];
+    healthChecks?: TChecks;
+};
+type McpHandleData = {
+    readonly env: readonly string[];
+    readonly optionalEnv: readonly string[];
+    /** The checks from `defineMcp`; `addCheck`ed checks live in `overrides`. */
+    readonly checks: Readonly<Record<string, Readonly<McpCheckInput>>>;
+    readonly overrides: readonly McpOp[];
+};
+interface McpHandleMethods<TNames extends string> {
+    overrideCheck(name: TNames, patch: McpCheckPatch): McpHandle<TNames>;
+    disableCheck(name: TNames): McpHandle<TNames>;
+    enableCheck(name: TNames): McpHandle<TNames>;
+    addCheck<N extends string>(name: N & Exclude<N, TNames>, check: McpCheckInput): McpHandle<TNames | N>;
+    disableAllChecks(): McpHandle<TNames>;
+}
+/**
+ * An immutable `defineMcp` server: `type`, `name` and `server` (its OpenCode
+ * fields; for a `ref`, only the shared ones), its env vars, checks and op log.
+ */
+export type McpHandle<TNames extends string = string> = McpServerDefinition & McpHandleData & McpHandleMethods<TNames>;
+export type ResolvedMcpCheck = {
+    readonly name: string;
+    readonly check: McpCheckInput;
+    readonly enabled: boolean;
+};
+/** True for a handle built by `defineMcp` or one of its builder methods. */
+export declare function isMcpHandle(value: unknown): value is McpHandle;
+/**
+ * Defines an MCP server once, with its env vars and health checks. Throws on
+ * an invalid server field, a literal `environment`/`headers` value, or an
+ * invalid check or env var name.
+ */
+export declare function defineMcp<TChecks extends Record<string, McpCheckInput> = Record<never, never>>(config: DefineMcpConfig<TChecks>): McpHandle<keyof TChecks & string>;
+/**
+ * Replays a handle's op log over its checks and returns every check, in
+ * definition then `addCheck` order, with its patched fields and whether it is
+ * enabled. See the module comment for the precedence rules.
+ */
+export declare function resolveMcpChecks(handle: McpHandle): ResolvedMcpCheck[];

package/dist/definitions/steps/define-step.d.ts

@@ -0,0 +1,137 @@
+import type { ZodType } from "zod";
+import type { AnyStepFeature, FeatureResultExtensions } from "./step-features";
+import { type PromptTemplateContext } from "./prompt-template";
+import { type HealthChecksInput, type StepHealthChecksInput } from "../../health-checks";
+import type { OpenCodeMcpServers } from "../../opencode-mcp";
+import type { EnvVarsInput } from "../../env-vars";
+import type { RepoConfigInput } from "../../repo-config";
+import type { EnvRecord, PromptEnvContext } from "./env";
+import { type StepEnvironment } from "./runtime";
+import type { McpHandle } from "./define-mcp";
+import type { BuiltInError, ConversationResult } from "../../pipelines/types";
+import { type StepHandle } from "./step-handle";
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TEnv extends EnvRecord = EnvRecord> = {
+    key: string;
+    name: string;
+    description?: string | null;
+    version?: number;
+    /**
+     * Where the step runs (`runtime`), its environment variables (`vars`) and what
+     * it may do to the repository (`repo`). Declare it before `agentPrompt` so
+     * `TEnv` is inferred from `vars` into the prompt's `env`, which is then
+     * strict: only declared, non-secret keys.
+     */
+    environment?: StepEnvironment<TInput["_output"], TEnv, TResult["_output"]>;
+    agentPrompt: string | ((context: PromptTemplateContext<TInput["_output"], PromptEnvContext<TEnv>>) => string);
+    additionalInput?: TInput;
+    result?: TResult;
+    features?: AnyStepFeature[];
+    /**
+     * The step's MCP servers, built with `defineMcp` and keyed by the step's
+     * server key. Each contributes its server, its health checks (run before
+     * `healthChecks`) and its env vars (a same-named `environment.vars` entry
+     * wins).
+     */
+    mcps?: Record<string, McpHandle>;
+    /**
+     * `cli` checks and `tool` checks for plugin or built-in tools. MCP checks
+     * belong on the server's `defineMcp`.
+     */
+    healthChecks?: StepHealthChecksInput | null;
+    status?: "draft" | "active";
+    /**
+     * Error names this step can fail with, beyond the built-in ones. A
+     * pipeline's `retry.on` and `catch.on` may name them.
+     */
+    errors?: readonly string[];
+    /**
+     * How a standalone Task of this step retries: errors named in `on` (built-in
+     * or declared in `errors`) get up to `maxAttempts` more runs. A pipeline
+     * step uses its node's `.retry(...)` instead.
+     */
+    retry?: readonly StepRetryEntry[];
+};
+/** One `retry` entry: the same shape as a pipeline node's `retry`. */
+export type StepRetryEntry = {
+    on: readonly string[];
+    maxAttempts: number;
+};
+/**
+ * A `kind: "code"` step's portable entrypoint, once resolved by
+ * `collect-definitions.ts`: the repo-relative file that defines the step. The
+ * worker finds the step inside that file by its `key`.
+ */
+export type StepDefinitionEntrypointJson = {
+    sourceFile: string;
+};
+export type StepDefinitionSpec = {
+    key: string;
+    name: string;
+    description: string | null;
+    version: number;
+    kind: "user_defined" | "code";
+    status: "draft" | "active" | "archived";
+    executionMode?: "workspace" | "no_workspace";
+    /**
+     * Repo-relative path of the devcontainer config to launch; `null` or omitted
+     * means auto-detect. Only valid with `executionMode: "workspace"`.
+     */
+    devcontainerConfigPath?: string | null;
+    /**
+     * Identifier of the worker-supplied managed runtime (`Runtime.managed.<id>()`);
+     * `null` or omitted means not managed. Only valid on a `code` step with
+     * `executionMode: "workspace"` and no `devcontainerConfigPath`.
+     */
+    managedRuntime?: string | null;
+    /**
+     * Repository access. Omitted means the runtime's default (`readWrite` for
+     * `workspace`, `none` for `no_workspace`), which the server resolves.
+     */
+    repo?: RepoConfigInput;
+    prompt: string | null;
+    inputSchemaJson: Record<string, unknown> | null;
+    resultSchemaJson: Record<string, unknown> | null;
+    opencodeMcpJson: OpenCodeMcpServers | null;
+    healthChecksJson: HealthChecksInput | null;
+    envJson?: EnvVarsInput | null;
+    /** Error names the step declares besides the built-in ones. */
+    errors?: readonly string[];
+    /**
+     * The step's `retry` policy for standalone Tasks. Not `retry`: that name is
+     * the handle's pipeline chain method.
+     */
+    retryJson?: StepRetryEntry[];
+    /**
+     * `kind === "code"` only: the live function of a spec produced by
+     * `codeStep()`. Code-step discovery (`findCodeStepInModule`) reads it to
+     * find the function to run. `collect-definitions.ts` strips it from the
+     * copy it pushes, since a function cannot be serialized into the push
+     * request; the original spec keeps it.
+     */
+    entrypoint?: {
+        fn: (input: unknown, context: {
+            artifactsDir: string;
+        }) => unknown;
+    };
+    /** `kind === "code"` only, present after `collect-definitions.ts` has run. */
+    entrypointJson?: StepDefinitionEntrypointJson | null;
+};
+export type EffectiveResult<TResult, TFeatures extends ReadonlyArray<AnyStepFeature>> = Prettify<TResult & FeatureResultExtensions<TFeatures>>;
+/**
+ * A `defineStep` handle's result type: `ConversationResult` when the step has
+ * no `result` and no features (a conversation step), else its effective
+ * result.
+ */
+export type DefineStepResult<TResult extends ZodType, TFeatures extends ReadonlyArray<AnyStepFeature>> = ZodType extends TResult ? [TFeatures[number]] extends [never] ? ConversationResult : EffectiveResult<TResult["_output"], TFeatures> : EffectiveResult<TResult["_output"], TFeatures>;
+export declare function defineStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<AnyStepFeature> = never[], TEnv extends EnvRecord = EnvRecord, const TErrors extends string = never>(config: Omit<DefineStepInput<TInput, TResult, TEnv>, "features" | "errors" | "retry"> & {
+    features?: TFeatures;
+    errors?: readonly TErrors[];
+    retry?: readonly {
+        on: readonly (BuiltInError | TErrors)[];
+        maxAttempts: number;
+    }[];
+}): StepHandle<TInput["_output"], DefineStepResult<TResult, TFeatures>, TErrors>;
+export {};