@agent-compose/sdk 0.7.0 → 0.8.1

package/src/types/workflow.ts

@@ -1,45 +1,33 @@
 /**
- * Workflow types — the context and function signature for authoring workflows.
+ * Workflow authoring types — `defineWorkflow` and the shared author-facing
+ * type surface.
  *
- * A workflow is `async (ctx, sandbox) => T`. Two positional args by design:
- *
- *   - `ctx` carries facts + observability about THIS run (id, input,
- *     setMetadata, step). Metadata bag.
- *   - `sandbox` is a capability handed to you by the engine for doing work
- *     (exec commands, write files). Pass it to `agent({ sandbox, ... })`
- *     and to any helper that takes a SandboxProvider (git utilities, file
- *     writers). Constructed once per run; reuse it.
+ * Workflows are STEP-FORM only: a builder of discrete, durable steps —
+ * `defineWorkflow({ id, input, output }).step(defineStep(...)).build()`.
+ * Every step is a replay checkpoint; pause/resume works at step
+ * granularity. The legacy run-form (`defineWorkflow({ run(ctx, sandbox)
+ * { … } })`) has been removed — passing a `run` key throws at
+ * definition time (i.e. at registration, loud and early).
  *
  * LLM agent loops live in `agent(opts)` (sdk/src/agent/run-agent.ts).
  * Invoking other workflows uses `AgentComposeClient.invoke[AndWait](...)`.
  */
 
-import { z } from "zod";
-import type { SandboxNetworkPolicy } from "../sandbox.js";
-import type { SandboxProvider } from "./sandbox.js";
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
-import type { Processor } from "../processors/processor.js";
 import { createStepWorkflow } from "../workflow-steps/workflow.js";
-import type { StepWorkflowDefinition } from "../workflow-steps/workflow.js";
-import type { Step, Workflow } from "../workflow-steps/types.js";
-import { WORKFLOW_BRAND } from "../workflow-steps/types.js";
-import type { BaseExecutionContext, WorkflowRun } from "./execution-context.js";
-import { extractMetadata, type WorkflowMetadata, type ConnectorRequirements, type ConnectorOperationTag, type InvokePolicy } from "./workflow-metadata.js";
+import type { StepWorkflowDefinition, WorkflowBuilder } from "../workflow-steps/workflow.js";
 
 export type { WorkflowRun, InvokeChild, BaseExecutionContext } from "./execution-context.js";
 // Re-export so consumers can keep importing `WorkflowMetadata` from
 // `@agent-compose/sdk` — the canonical definition lives in
 // `./workflow-metadata.js` to break a runtime import cycle with
 // `workflow-steps/workflow.ts`.
-export type { WorkflowMetadata } from "./workflow-metadata.js";
+export type { WorkflowMetadata, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
 
 export interface AgentEventSink {
   emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
 
-import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
-export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources };
-
 /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
  *  can type per-invoke budget overrides they pass as workflow input. */
 export interface AgentBudget {
@@ -47,282 +35,27 @@ export interface AgentBudget {
   maxIterations: number;
 }
 
-/** Context passed to a workflow function — facts + observability for this run. */
-export interface WorkflowCtx<TInput extends Record<string, unknown> = Record<string, unknown>> extends Omit<BaseExecutionContext, "sandbox"> {
-  input?: TInput;
-  /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
-  setMetadata: (data: Record<string, unknown>) => Promise<void>;
-  /**
-   * Durable named step (ADR-0012). Runs `fn` once and memoises its result to
-   * the sandbox state-dir; on a pause-resume re-entry the recorded value is
-   * returned and `fn` is NOT re-run (a duration-0 "restored" sub-step). Also
-   * emits substep_started / substep_completed / substep_failed lifecycle
-   * events with duration — use for long phases you want both durable and
-   * visible on the run's timeline (setup, external API calls, submit).
-   *
-   * Names must be unique within a step body (they key the memoise file).
-   * A body that pauses is never memoised — the resume re-runs it. For
-   * cross-process side effects (DB writes, emails) use `invokeChild`.
-   */
-  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
-  /** Pass to `agent({ events: ctx.agentEvents })` to stream agent lifecycle events. */
-  agentEvents: AgentEventSink;
-  /**
-   * Workflow-level processors registered via `defineWorkflow({ processors })`.
-   * Read-only here. Authors merge with agent-specific lists when calling
-   * `agent({ processors: [...ctx.processors, mySpecific] })`.
-   *
-   * Empty array when the workflow declared no processors.
-   */
-  processors: readonly Processor[];
-}
-
-/** A workflow is `async (ctx, sandbox) => TOutput`. */
-export type WorkflowFn<
-  TOutput = unknown,
-  TInput extends Record<string, unknown> = Record<string, unknown>,
-> = (ctx: WorkflowCtx<TInput>, sandbox: SandboxProvider) => Promise<TOutput>;
-
-/**
- * Declare a workflow with server-side metadata.
- * Use `export default defineWorkflow({ run, networkPolicy, ... })` to attach
- * a runner network policy so the server brokers credentials for the workflow
- * sandbox.
- *
- * Without defineWorkflow, a plain `export default async (ctx) => {...}` still
- * works — the workflow just runs with secrets passed directly in env.
- */
-export interface WorkflowDefinition<
-  TOutput = unknown,
-  TInput extends Record<string, unknown> = Record<string, unknown>,
-> {
-  /** One-line, human-readable description of what this workflow does.
-   *  Surfaced on the dashboard template tile + run page header. */
-  description?: string;
-  /** Zod schema for the workflow's `input`. When declared, the SDK
-   *  bundler captures it as JSON-Schema-shaped `inputSchema` in
-   *  template metadata, the dashboard playground renders a typed
-   *  form, and the engine validates dispatched payloads against it
-   *  at the step boundary. Omit to leave inputs as `unknown` (the
-   *  legacy default — playground falls back to a freeform JSON
-   *  textarea). */
-  input?:  z.ZodType<TInput>;
-  /** Same as `input`, for the workflow's return value. Captured into
-   *  `outputSchema` metadata and rendered in the IO panel. */
-  output?: z.ZodType<TOutput>;
-  /**
-   * @deprecated Legacy run-form. Prefer step-form — the
-   * `.step(defineStep(...))` builder — for per-step durability/replay and
-   * working pause. A run-form body compiles to one opaque step
-   * (`compileRunForm`), so any failure/resume re-runs the whole body.
-   */
-  run: WorkflowFn<TOutput, TInput>;
-  /**
-   * All snapshot config — boot source plus capture mode.
-   *
-   * `snapshots.bootFrom`: the runner restores from this exact provider
-   * snapshot id at run start. Omit to boot a fresh sandbox.
-   *
-   * `snapshots.saveLatest`: `true` captures one snapshot after each
-   * successful step (latest-only — prior is freed).
-   * `{ saveLatest: true, retainSteps: true }` keeps every step's
-   * snapshot for fork / replay / time-travel.
-   *
-   * Snapshots are long-lived (never auto-expire). List + delete via
-   * `agentc snapshot list/delete`. Per-invocation
-   * `invoke({ snapshots })` overrides this default.
-   */
-  snapshots?: SnapshotConfig;
-  /**
-   * Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string:
-   * `2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`) and `provider`
-   * (`vercel` | `e2b`). `size` maps to provider machine specs at create
-   * (Vercel: vCPUs, 2048 MB RAM per vCPU); E2B sizing is template-defined and
-   * ignores it. Optional; omit → smallest SKU on the default provider.
-   * Per-invocation `invoke({ size })` overrides the size.
-   */
-  resources?: SandboxResources;
-  /**
-   * Outbound network policy for the runner sandbox.
-   * Use "*": [] to allow all traffic while still injecting headers for specific domains.
-   * Secret values are referenced as $VARIABLE and resolved from GCP at dispatch time.
-   * Vercel only — E2B ignores.
-   *
-   * @example
-   * networkPolicy: {
-   *   allow: {
-   *     "*": [],
-   *     "api.github.com": [{ transform: [{ headers: { "Authorization": "basic:$GITHUB_TOKEN" } }] }],
-   *   }
-   * }
-   */
-  networkPolicy?: SandboxNetworkPolicy;
-  /**
-   * Workflow-level processor chain — runs around every `agent(...)` loop the
-   * workflow body launches, ahead of any agent-specific processors. Use for
-   * org-wide gating (deny destructive tools, require scopes). Authors merge
-   * with agent-specific lists via `[...ctx.processors, ...]`.
-   */
-  processors?: readonly Processor[];
-  /**
-   * Optional placeholder env var values for secrets referenced in the network policy.
-   * By default, brokered secrets are removed from the runner env entirely — the real
-   * values are only ever present inside the Vercel firewall config, never in the VM.
-   * Only set this if a tool or SDK validates the env var format on startup before
-   * making any requests (e.g. some CLIs check that ANTHROPIC_API_KEY looks like a
-   * real key). The placeholder is a syntactically valid but non-functional stand-in.
-   *
-   * @example
-   * placeholders: {
-   *   ANTHROPIC_API_KEY: `sk-ant-api03-${"a".repeat(95)}`,
-   * }
-   */
-  placeholders?: Record<string, string>;
-  /**
-   * Connector requirements (ADR-0007). Declaring a provider makes the
-   * server resolve an authorized OAuth grant for the calling principal at
-   * dispatch time and inject a fresh access token at the network layer —
-   * workflow code talks to the provider API with plain fetch/SDKs and
-   * never holds the credential.
-   *
-   * @example
-   * connectors: { github: { scopes: ["repo"] } }
-   */
-  connectors?: ConnectorRequirements;
-  /**
-   * Marks this workflow as a catalogue OPERATION of a connector — e.g.
-   * the `create-issue` operation of the `github` connector. Pair with
-   * `description` + `input`/`output` schemas so the operation is fully
-   * self-describing (MCP-tool-like) to humans and agents browsing the
-   * connector catalogue.
-   *
-   * @example
-   * connectorOperation: { provider: "github", operation: "create-issue" }
-   */
-  connectorOperation?: ConnectorOperationTag;
-  /**
-   * Tier-1 invoke ACL (connector credential boundary). When this workflow
-   * declares `connectors` (it brokers a credential) AND an `invokePolicy`,
-   * the server evaluates the calling principal against the policy BEFORE
-   * binding any grant — a caller matching no clause is refused with HTTP
-   * 403. Has no effect on workflows that declare no connectors. Omit to
-   * leave the workflow invokable by the whole team.
-   *
-   * @example
-   * connectors: { github: { access: "read" } },
-   * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
-   */
-  invokePolicy?: InvokePolicy;
-  /**
-   * Internal — set by `defineSandboxEnvironment`, not by workflow authors.
-   * Marks the workflow as an environment build (base-env / agent-env) so the
-   * server skips mounting the shared factory drive for its runs (#13). See
-   * `WorkflowMetadata.environmentBuild`.
-   */
-  environmentBuild?: boolean;
-}
-
 /**
- * Wrap a legacy `(ctx, sandbox) => T` workflow body as a single-step
- * `Workflow` so the engine has one shape to drive. The synthesised step
- * runs the user's `run` body inline; `ctx.setMetadata` / `ctx.step` /
- * `ctx.agentEvents` proxy directly to the underlying `StepContext` hooks,
- * which the engine flushes to the run timeline exactly as the legacy
- * full-mode runner did.
+ * Declare a workflow — the typed step builder. Multiple steps with
+ * explicit input/output schemas, durability + replay at every step
+ * boundary:
  *
- * Lifecycle granularity is workflow-level (one outer "run" step) — the
- * `ctx.step("name", fn)` calls inside the body become sub-step events
- * under that one step. Authors keep the same source; the dashboard sees
- * the same timeline shape.
- */
-// TODO: collapse run-form into pure sugar over step-form. Run-form
-// already compiles to step-form-with-one-step here, so maintaining two
-// authoring surfaces is API duplication that periodically drifts (see
-// the input/output thread-through bug fixed on 2026-05-20: step-form
-// preserved schemas, run-form silently stamped z.unknown()). Cleaner:
-// turn `defineWorkflow({ run })` into a thin wrapper that calls the
-// step builder with a synthesised `{name:"run", input, output, run}`
-// step, then delete this function. Runtime stays identical.
-function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
-  def: WorkflowDefinition<TOutput, TInput>,
-  metadata: WorkflowMetadata,
-): Workflow<TInput, TOutput> {
-  const unknownSchema = z.unknown() as z.ZodType<unknown>;
-  const inputSchema:  z.ZodType<TInput>  = def.input  ?? (unknownSchema as z.ZodType<TInput>);
-  const outputSchema: z.ZodType<TOutput> = def.output ?? (unknownSchema as z.ZodType<TOutput>);
-  const step: Step<TInput, TOutput> = {
-    name:   "run",
-    input:  inputSchema,
-    output: outputSchema,
-    run: async (stepCtx) => {
-      // Proxy the legacy WorkflowCtx hooks to the step's collector-backed
-      // implementations. The engine harvests the snapshot after execute
-      // returns; nothing here is a no-op.
-      const workflowCtx: WorkflowCtx<TInput> = {
-        input:          stepCtx.input,
-        run:            stepCtx.run,
-        requestContext: stepCtx.requestContext,
-        invokeChild:    stepCtx.invokeChild,
-        setMetadata:    stepCtx.setMetadata,
-        step:           stepCtx.step,
-        agentEvents:    stepCtx.agentEvents,
-        pause:           stepCtx.pause,
-        sleep:           stepCtx.sleep,
-        waitForEvent:    stepCtx.waitForEvent,
-        processors:      metadata.processors ?? [],
-      };
-      const sandbox = stepCtx.sandbox;
-      if (!sandbox) throw new Error("legacy run-form workflow requires a sandbox in StepContext");
-      return def.run(workflowCtx, sandbox);
-    },
-  };
-  const workflow: Workflow<TInput, TOutput> = {
-    id:     "@run-form",
-    input:  inputSchema,
-    output: outputSchema,
-    steps:  Object.freeze([step]),
-    metadata,
-  };
-  // Brand BEFORE freezing — defineProperty is the only way to set a
-  // non-enumerable key, and frozen objects refuse it.
-  Object.defineProperty(workflow, WORKFLOW_BRAND, { value: true, enumerable: false });
-  return Object.freeze(workflow);
-}
-
-/**
- * Declare a workflow. Two forms; both return a `Workflow` whose
- * `metadata` field carries the server-readable declarations.
+ *   defineWorkflow({ id, input, output }).step(defineStep(...)).build()
  *
- * Run form — wraps the legacy `(ctx, sandbox) => T` body as a single
- * step internally. Lifecycle granularity is workflow-level (one step).
- *
- * Step form — the typed builder. Multiple steps with explicit input/
- * output schemas, durability + replay at every step boundary.
- *
- * Both forms produce the same downstream shape: the bundler reads
- * `workflow.metadata.networkPolicy` / `placeholders` / etc.; the server
- * stores the step plan; runner subprocesses execute one step at a time
- * via the StepInvocation seam.
- */
-/**
- * @deprecated Run-form is legacy. Use the step-form overload —
- * `defineWorkflow({ id, input, output }).step(defineStep(...)).build()` — for
- * durable, replayable steps and working pause. Run-form compiles to a single
- * opaque step (`compileRunForm`); there is no per-step replay.
+ * The bundler reads `workflow.metadata.networkPolicy` / `placeholders` /
+ * etc. off the built `Workflow`; the server stores the step plan; runner
+ * subprocesses execute one step at a time via the StepInvocation seam.
  */
-export function defineWorkflow<
-  TOutput = unknown,
-  TInput extends Record<string, unknown> = Record<string, unknown>,
->(
-  def: WorkflowDefinition<TOutput, TInput>,
-): Workflow<TInput, TOutput>;
 export function defineWorkflow<TInput, TOutput>(
   def: StepWorkflowDefinition<TInput, TOutput>,
-): import("../workflow-steps/workflow.js").WorkflowBuilder<TInput, TInput>;
-export function defineWorkflow<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
-  def: WorkflowDefinition<TOutput, TInput> | StepWorkflowDefinition<unknown, unknown>,
-): Workflow<TInput, TOutput> | import("../workflow-steps/workflow.js").WorkflowBuilder<unknown, unknown> {
-  if ("run" in def) return compileRunForm(def, extractMetadata(def));
+): WorkflowBuilder<TInput, TInput> {
+  if ("run" in def) {
+    throw new Error(
+      "defineWorkflow: the legacy run-form (`defineWorkflow({ run(ctx, sandbox) { … } })`) has been removed. " +
+      "Author workflows in step-form — `defineWorkflow({ id, input, output }).step(defineStep(...)).build()` — " +
+      "or run /ac:generate-workflow to scaffold the current shape.",
+    );
+  }
   return createStepWorkflow(def);
 }