@boboddy/sdk 0.4.3 → 0.5.0

package/dist/definitions/pipelines/node-input-ctx.d.ts

@@ -0,0 +1,31 @@
+import type { ZodType } from "zod";
+import type { DotPaths } from "../steps/define-step";
+import { type WorkItemAccessor } from "./builder-helpers";
+import type { FanOutItemBinding, LiteralBinding, PipelineInputBinding, SignalsListBinding, StepOutputBinding, StepSignalBinding } from "./bindings";
+/**
+ * The `input:` mapper ctx every `step`/`fanOut`/`loop`/parallel-branch
+ * state receives (see docs/research/flat-pipeline-sdk-and-visual-designer.md
+ * §4). Nodes are addressed by their plain string state key rather than a
+ * typed step reference — the flat, forward-only authoring model has no
+ * "tuple of prior steps" to statically check a binding's source/signal
+ * key against (cross-node static proof is explicitly out of scope; see
+ * that doc's §1).
+ */
+export type NodeInputCtx<TInput extends ZodType = ZodType> = {
+    /** Reads a value from the pipeline's own input, by dot-path. */
+    pipelineInput: (path: DotPaths<TInput["_output"]>) => PipelineInputBinding;
+    workItem: WorkItemAccessor;
+    /** Reads a signal declared by an earlier node, addressed by its state key. */
+    signal: (nodeKey: string, signalKey: string) => StepSignalBinding;
+    /** Reads an earlier node's whole result output, addressed by its state key. */
+    output: (nodeKey: string) => StepOutputBinding;
+    /** Reaches a fan-out's whole cohort (every terminal branch's signals + output). */
+    signalsList: (nodeKey: string) => SignalsListBinding;
+    literal: (value: unknown) => LiteralBinding;
+};
+/** `NodeInputCtx`, plus `item` — the current fan-out branch's own item. */
+export type FanOutNodeInputCtx<TInput extends ZodType = ZodType> = NodeInputCtx<TInput> & {
+    item: FanOutItemBinding;
+};
+export declare function makeNodeInputCtx<TInput extends ZodType>(): NodeInputCtx<TInput>;
+export declare function makeFanOutNodeInputCtx<TInput extends ZodType>(): FanOutNodeInputCtx<TInput>;

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

@@ -1,6 +1,6 @@
 import { PipelineDefinitions } from "../../generated/sdk.gen";
 import type { PutApiPipelineDefinitionsData } from "../../generated/types.gen";
-import type { PipelineDefinitionSpec } from "./define-pipeline";
+import { type PipelineDefinitionSpec } from "./define-pipeline";
 type RequestOptions = {
     headers?: Record<string, unknown> | undefined;
 };
@@ -26,6 +26,7 @@ declare const buildPipelineDefinitionsClient: (pipelineDefinitions: PipelineDefi
         stepDefinitions: Array<{
             id: string;
             pipelineDefinitionId: string;
+            kind: "step" | "fanOut" | "cohortGate" | "choice" | "parallel" | "loop" | "succeed" | "fail";
             stepDefinitionId: string;
             stepDefinitionVersion: number;
             key: string;
@@ -131,11 +132,23 @@ declare const buildPipelineDefinitionsClient: (pipelineDefinitions: PipelineDefi
     }[]>;
     /**
      * Upserts a pipeline definition keyed by (projectId, key). Accepts the
-     * `PipelineDefinitionSpec` produced by `pipeline().build()`, along with the
+     * `PipelineDefinitionSpec` produced by `definePipeline()`, along with the
      * list of pushed step definitions (used to resolve `stepDefinitionId` for
-     * each pipeline step).
+     * each node/branch referencing a step by key).
      *
-     * Throws if any pipeline step references a step key/version that isn't
+     * Pushes via the richer `nodeDefinitions[]`/`dependencyEdges[]` graph
+     * shape (see `buildGraphNodeInput`) rather than the old flat,
+     * `position`-ordered `stepDefinitions[]` shape — every node kind
+     * `definePipeline()` can produce (`choice`/`fanOut`/`cohortGate`/
+     * `parallel`/`loop`/`succeed`/`fail`, not just `step`) is representable
+     * this way; the flat shape could only ever represent a `step`-only
+     * chain. The generated `UpsertPipelineDefinitionInput` type doesn't yet
+     * reflect this (it's OpenAPI-codegen'd from the pre-existing flat
+     * contract), so the body is cast at the boundary — the server's zod
+     * schema (`createPipelineDefinitionInputSchema`, extended to accept
+     * either shape) is the real, enforced contract.
+     *
+     * Throws if any node/branch references a step key/version that isn't
      * present in `stepDefs`.
      */
     upsertFromSpec: (projectId: string, spec: PipelineDefinitionSpec, stepDefs: ReadonlyArray<StepDefinitionRef>, options?: RequestOptions) => Promise<{
@@ -152,6 +165,7 @@ declare const buildPipelineDefinitionsClient: (pipelineDefinitions: PipelineDefi
         stepDefinitions: Array<{
             id: string;
             pipelineDefinitionId: string;
+            kind: "step" | "fanOut" | "cohortGate" | "choice" | "parallel" | "loop" | "succeed" | "fail";
             stepDefinitionId: string;
             stepDefinitionVersion: number;
             key: string;

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

@@ -0,0 +1,104 @@
+import type { ZodType } from "zod";
+import type { RuleCondition } from "../advancement-policies/define-advancement-policy";
+import type { AdvanceAllCtx, AdvanceAllResult, AdvanceEachCtx, AdvanceEachResult } from "../advancement-policies/cohort-fluent-rules";
+import type { AnyTypedStep } from "./builder-helpers";
+import type { AnyBinding } from "./bindings";
+import type { FanOutNodeInputCtx, NodeInputCtx } from "./node-input-ctx";
+/**
+ * The 7 authoring state kinds (see
+ * docs/research/flat-pipeline-sdk-and-visual-designer.md §4/§5). Every
+ * kind besides `choice`/`succeed`/`fail` does its own work (a `step`) and
+ * therefore declares exactly one authored `input`/`timeout`; `choice` and
+ * `loop` are the only kinds with more than one possible exit.
+ */
+/** `next: "otherStateKey"`, or a special cross-pipeline route target. */
+export type NextTarget = string | {
+    routeToPipeline: string;
+    input?: Record<string, unknown> | null;
+};
+export type StepState = {
+    kind: "step";
+    step: AnyTypedStep;
+    input?: (ctx: NodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+    /**
+     * A single-condition "pause for human review" gate — the narrow
+     * replacement for the old per-step rules-engine policy object (see §5's
+     * `complete`/`route`/`block` migration notes). When the condition
+     * matches, the node run blocks instead of advancing to `next`.
+     */
+    blockWhen?: RuleCondition;
+    next: NextTarget;
+};
+export type ChoiceCase = {
+    when: RuleCondition;
+    next: string;
+};
+export type ChoiceState = {
+    kind: "choice";
+    /** At least one of `choices`/`default` is required — see `compileChoiceState`. */
+    choices?: ReadonlyArray<ChoiceCase>;
+    default?: string | null;
+};
+export type FanOutState = {
+    kind: "fanOut";
+    step: AnyTypedStep;
+    /**
+     * The signal to resolve branch cardinality (and, in array mode, each
+     * branch's own item) from. A bare signal key (`"changedFiles"`) or a
+     * `"stateKey.signalKey"` dotted convenience form — the dotted prefix is
+     * author-facing documentation only; the runtime resolves the signal by
+     * scanning every upstream node's own signals for a matching key (see
+     * `resolveFanOutCardinality`), not by an explicit node reference.
+     */
+    over: string;
+    maxConcurrency?: number | null;
+    input?: (ctx: FanOutNodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+    advanceEach: (ctx: AdvanceEachCtx) => AdvanceEachResult;
+    advanceAll: (ctx: AdvanceAllCtx) => AdvanceAllResult;
+    next: string;
+};
+export type ParallelBranchConfig = {
+    step: AnyTypedStep;
+    input?: (ctx: NodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+};
+export type ParallelState = {
+    kind: "parallel";
+    /** Named branches (v1: single-step only — see decision 5). */
+    branches: Record<string, ParallelBranchConfig>;
+    /** Defaults to "continue iff every branch continued" when omitted. */
+    advanceAll?: (ctx: AdvanceAllCtx) => AdvanceAllResult;
+    next: string;
+};
+export type LoopState = {
+    kind: "loop";
+    step: AnyTypedStep;
+    maxIterations: number;
+    input?: (ctx: NodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+    until: RuleCondition;
+    next: string;
+    onExhausted: string;
+};
+export type SucceedState = {
+    kind: "succeed";
+};
+export type FailState = {
+    kind: "fail";
+};
+export type PipelineState = StepState | ChoiceState | FanOutState | ParallelState | LoopState | SucceedState | FailState;
+export type DefinePipelineInput<TInput extends ZodType = ZodType> = {
+    key: string;
+    name?: string;
+    description?: string | null;
+    version?: number;
+    status?: "draft" | "active";
+    /** The pipeline's own input schema — drives `ctx.pipelineInput(path)`'s typing and `inputSchemaJson`. */
+    input?: TInput;
+    /** The entry state's key. Must not name a `choice`/`succeed`/`fail` state. */
+    startAt: string;
+    /** Every state in the pipeline, keyed by its unique node key. */
+    states: Record<string, PipelineState>;
+};

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

@@ -0,0 +1,50 @@
+import type { ZodType } from "zod";
+import type { SignalKeysOf, SignalTypeMapOf, TypedStepDefinitionSpec } from "./define-step";
+/**
+ * `codeStep()`'s own signal spec shape — unlike `defineStep()`'s
+ * `SignalSpecInput`, `type` is required rather than inferred from the
+ * result schema at a dot-path (`resolveZodSchemaAtPath`/
+ * `zodTypeToSignalType` are `define-step.ts`-internal, and a code step's
+ * result shape is arbitrary application data, not necessarily reflecting
+ * one at all) — a small, deliberate simplification over `defineStep`'s own
+ * signal authoring surface.
+ */
+export type CodeStepSignalSpec = {
+    key?: string;
+    sourcePath: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    required?: boolean;
+    availableWhenResultStatusIn?: string[] | null;
+};
+export type CodeStepFn<TInput, TResult> = (input: TInput) => TResult | Promise<TResult>;
+export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType> = {
+    key: string;
+    name: string;
+    description?: string | null;
+    version?: number;
+    /**
+     * The step's own implementation — resolved by `collect-definitions.ts`
+     * to a portable `{sourceFile, exportName}` pair (by identity-matching
+     * this reference against the declaring module's other exports) before
+     * the (unserializable) function reference is ever sent over the wire.
+     * Must be a plain named export of the same module `codeStep()` is
+     * called from (see docs/research/flat-pipeline-sdk-and-visual-designer.md
+     * §7.7/§8's "code-step entrypoints resolve against the target repo").
+     */
+    fn: CodeStepFn<TInput["_output"], TResult["_output"]>;
+    inputSchema?: TInput;
+    resultSchema?: TResult;
+    signals?: readonly CodeStepSignalSpec[];
+    status?: "draft" | "active";
+};
+/**
+ * Defines a `kind: "code"` step: a plain function instead of an LLM
+ * prompt. Produces the same phantom-typed `TypedStepDefinitionSpec` shape
+ * `defineStep()` does (so it plugs into `definePipeline()`'s
+ * `states[key].step` field unchanged), 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 TSignals extends ReadonlyArray<CodeStepSignalSpec> = never[]>(config: DefineCodeStepInput<TInput, TResult> & {
+    signals?: TSignals;
+}): TypedStepDefinitionSpec<TInput["_output"], TResult["_output"], SignalKeysOf<TSignals>, SignalTypeMapOf<TSignals, TResult["_output"]>>;

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

@@ -108,12 +108,21 @@ export type AdditionalStepInputLiteralBinding = LiteralBinding;
  * coincidence, not by design.
  */
 export type AdditionalStepInputBinding = WorkItemBinding | LiteralBinding;
+/**
+ * A `kind: "code"` step's portable entrypoint, once resolved by
+ * `collect-definitions.ts`'s identity-capture pass — see
+ * docs/research/flat-pipeline-sdk-and-visual-designer.md §7.7/§8.
+ */
+export type StepDefinitionEntrypointJson = {
+    sourceFile: string;
+    exportName: string;
+};
 export type StepDefinitionSpec = {
     key: string;
     name: string;
     description: string | null;
     version: number;
-    kind: "user_defined";
+    kind: "user_defined" | "code";
     status: "draft" | "active" | "archived";
     executionMode?: "workspace" | "no_workspace";
     prompt: string | null;
@@ -129,6 +138,18 @@ export type StepDefinitionSpec = {
     opencodeMcpJson: OpenCodeMcpServers | null;
     opencodePluginJson: OpenCodePlugins | null;
     healthChecksJson: HealthChecks | null;
+    /**
+     * `kind === "code"` only, and only *before* collection —
+     * `collect-definitions.ts` resolves this live `fn` reference down to
+     * `entrypointJson` (by identity-matching against the declaring module's
+     * other exports) and strips this field before the spec is ever pushed;
+     * it can never be serialized into the push request.
+     */
+    entrypoint?: {
+        fn: (input: unknown) => unknown;
+    };
+    /** `kind === "code"` only, present after `collect-definitions.ts` has run. */
+    entrypointJson?: StepDefinitionEntrypointJson | null;
 };
 export type SignalTypeStrToTs<T extends SignalTypeStr> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "array" ? unknown[] : T extends "object" ? object : unknown;
 export type SignalTypeMapOf<TSignals extends readonly unknown[], TResult> = Prettify<{

package/dist/definitions/steps/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./define-step";
+export * from "./define-code-step";
 export * from "./prompt-template";
 export * from "./step-definitions-client";
 export * from "./step-features";

package/dist/definitions/steps/index.js

@@ -12080,6 +12080,32 @@ ${feature._promptAddition}` : feature._promptAddition;
   };
   return spec;
 }
+// src/definitions/steps/define-code-step.ts
+function codeStep(config2) {
+  const spec = {
+    key: config2.key,
+    name: config2.name,
+    description: config2.description ?? null,
+    version: config2.version ?? 1,
+    kind: "code",
+    status: config2.status ?? "active",
+    prompt: null,
+    inputSchemaJson: config2.inputSchema ? toJSONSchema(config2.inputSchema) : null,
+    resultSchemaJson: config2.resultSchema ? toJSONSchema(config2.resultSchema) : null,
+    signalExtractorDefinitions: (config2.signals ?? []).map((signal) => ({
+      key: signal.key ?? signal.sourcePath,
+      sourcePath: signal.sourcePath,
+      type: signal.type,
+      required: signal.required ?? true,
+      availableWhenResultStatusIn: signal.availableWhenResultStatusIn ?? null
+    })),
+    opencodeMcpJson: null,
+    opencodePluginJson: null,
+    healthChecksJson: null,
+    entrypoint: { fn: config2.fn }
+  };
+  return spec;
+}
 // src/generated/core/bodySerializer.gen.ts
 var jsonBodySerializer = {
   bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value)
@@ -13159,29 +13185,6 @@ class PipelineDefinitions extends HeyApiClient {
   unarchivePipelineDefinition(options) {
     return (options.client ?? this.client).put({ url: "/api/pipeline-definitions/{pipelineDefinitionId}/unarchive", ...options });
   }
-  addPipelineStep(options) {
-    return (options.client ?? this.client).post({
-      url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps",
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        ...options.headers
-      }
-    });
-  }
-  removePipelineStep(options) {
-    return (options.client ?? this.client).delete({ url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps/{pipelineStepDefinitionId}", ...options });
-  }
-  updatePipelineStep(options) {
-    return (options.client ?? this.client).put({
-      url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps/{pipelineStepDefinitionId}",
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        ...options.headers
-      }
-    });
-  }
   setPipelineStepAdvancementPolicy(options) {
     return (options.client ?? this.client).put({
       url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps/{pipelineStepDefinitionId}/advancement-policy",
@@ -13710,8 +13713,21 @@ var buildStepDefinitionsClient = (stepDefinitions) => {
     },
     upsertFromSpec: async (projectId, spec, options) => {
       const body = {
-        ...spec,
+        key: spec.key,
+        name: spec.name,
+        description: spec.description,
         prompt: spec.prompt ?? "",
+        version: spec.version,
+        kind: spec.kind,
+        entrypointJson: spec.entrypointJson ?? null,
+        executionMode: spec.executionMode,
+        inputSchemaJson: spec.inputSchemaJson,
+        resultSchemaJson: spec.resultSchemaJson,
+        opencodeMcpJson: spec.opencodeMcpJson,
+        opencodePluginJson: spec.opencodePluginJson,
+        healthChecksJson: spec.healthChecksJson,
+        status: spec.status,
+        signalExtractorDefinitions: spec.signalExtractorDefinitions,
         projectId
       };
       const result = await stepDefinitions.upsertStepDefinition({
@@ -16136,5 +16152,6 @@ export {
   createStepDefinitionsClient,
   createPromptTemplateContext,
   createPromptInputProxy,
+  codeStep,
   Features
 };

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

@@ -16,7 +16,11 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
         description: string | unknown;
         prompt: string | unknown;
         version: number;
-        kind: "built_in" | "user_defined";
+        kind: "built_in" | "user_defined" | "code";
+        entrypointJson: {
+            sourceFile: string;
+            exportName: string;
+        } | unknown;
         executionMode: "workspace" | "no_workspace";
         inputSchemaJson: {
             [key: string]: unknown;
@@ -84,7 +88,11 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
         description: string | unknown;
         prompt: string | unknown;
         version: number;
-        kind: "built_in" | "user_defined";
+        kind: "built_in" | "user_defined" | "code";
+        entrypointJson: {
+            sourceFile: string;
+            exportName: string;
+        } | unknown;
         executionMode: "workspace" | "no_workspace";
         inputSchemaJson: {
             [key: string]: unknown;
@@ -146,8 +154,20 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
     }>;
     /**
      * Upserts a step definition keyed by (projectId, key, version). Accepts the
-     * `StepDefinitionSpec` produced by `defineStep()` directly — no separate
-     * fetch-existing/branch-on-id step needed.
+     * `StepDefinitionSpec` produced by `defineStep()`/`codeStep()` directly —
+     * no separate fetch-existing/branch-on-id step needed.
+     *
+     * `entrypointJson` (a `kind: "code"` step's resolved entrypoint — see
+     * `collect-definitions.ts`) and the widened `kind` union
+     * (`"user_defined" | "code"`) are not yet reflected in the
+     * OpenAPI-generated `UpsertStepDefinitionInput` type, so the request
+     * body is built explicitly and cast at the boundary rather than spread
+     * + `satisfies`-checked, mirroring the same pattern
+     * `pipeline-definitions-client.ts`'s `upsertFromSpec` already uses for
+     * its own wire-format-ahead-of-codegen gap. The spec's transient
+     * `entrypoint.fn` (a live, unserializable function reference —
+     * present only if a caller bypasses `collect-definitions.ts`'s own
+     * strip step) is never included here.
      */
     upsertFromSpec: (projectId: string, spec: StepDefinitionSpec, options?: RequestOptions) => Promise<{
         id: string;
@@ -157,7 +177,11 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
         description: string | unknown;
         prompt: string | unknown;
         version: number;
-        kind: "built_in" | "user_defined";
+        kind: "built_in" | "user_defined" | "code";
+        entrypointJson: {
+            sourceFile: string;
+            exportName: string;
+        } | unknown;
         executionMode: "workspace" | "no_workspace";
         inputSchemaJson: {
             [key: string]: unknown;