@agent-compose/sdk 0.6.0 → 0.8.0

package/src/workflow-steps/types.ts

@@ -15,6 +15,7 @@ import type { z } from "zod";
 import type { BaseExecutionContext } from "../types/execution-context.js";
 import type { AgentEventSink } from "../types/workflow.js";
 import type { WorkflowMetadata } from "../types/workflow-metadata.js";
+import type { StepObservability } from "./observability.js";
 
 /**
  * Per-step execution context. Threaded into every step's `execute(...)` so
@@ -62,6 +63,15 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
   agentEvents: AgentEventSink;
 }
 
+/** One artifact a step promises to produce. `path` is workspace/drive-relative
+ *  (e.g. "out/report.html"); the dashboard derives the format tag from the
+ *  extension client-side — no `format` field here. */
+export interface StepDeliverable {
+  path: string;
+  /** Optional one-line description of the artifact. */
+  description?: string;
+}
+
 /**
  * Step definition — a single typed unit of work in a workflow chain.
  *
@@ -80,6 +90,11 @@ export interface Step<TInput, TOutput> {
   readonly output: z.ZodType<TOutput>;
   /** Step body. Receives a `StepContext<TInput>` and returns the typed output. */
   run(ctx: StepContext<TInput>): TOutput | Promise<TOutput>;
+  /** One plain sentence of what the step actually does — rendered on the
+   *  dashboard workflow graph. ≤200 chars, no newlines. */
+  readonly summary?: string;
+  /** Files the step promises to produce. ≤8 entries. */
+  readonly deliverables?: readonly StepDeliverable[];
 }
 
 /**
@@ -90,14 +105,14 @@ export interface Step<TInput, TOutput> {
  * the step; undefined when no hooks were used.
  */
 export type StepRunResult<TOutput = unknown> =
-  | { status: "completed"; output: TOutput; durationMs: number; observability?: import("./observability.js").StepObservability }
-  | { status: "failed";    error: string;   durationMs: number; observability?: import("./observability.js").StepObservability };
+  | { status: "completed"; output: TOutput; durationMs: number; observability?: StepObservability }
+  | { status: "failed";    error: string;   durationMs: number; observability?: StepObservability };
 
 /**
  * Workflow — a list of typed steps plus the workflow's input/output
- * schemas plus its server-side metadata bag. Returned by `defineWorkflow(...)`
- * (run form) and `defineWorkflow(...).step(...)...build()` (step form).
- * Engine adapters consume this shape.
+ * schemas plus its server-side metadata bag. Returned by
+ * `defineWorkflow(...).step(...)...build()`. Engine adapters consume
+ * this shape.
  *
  * `input` validates the workflow input before the first step runs.
  * `output` validates the final step's output before the workflow

package/src/workflow-steps/workflow.ts

@@ -23,7 +23,7 @@ import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
 import { WORKFLOW_BRAND } from "./types.js";
 import { extractMetadata } from "../types/workflow-metadata.js";
-import type { SnapshotConfig, SandboxResources } from "../types/workflow-metadata.js";
+import type { SnapshotConfig, SandboxResources, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, DriveMergePolicy } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 
@@ -55,7 +55,28 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
    *  and `provider` (`vercel` | `e2b`). Vercel maps `size` to vCPUs; E2B
    *  sizing is template-defined. Omit → smallest SKU on the default provider. */
   resources?:     SandboxResources;
+  /** What happens to this workflow's drive branch when a run ends:
+   *  `"auto"` (the default when omitted — today's behaviour) folds it into
+   *  `main`; `"manual"` proposes a merge approval at the same terminus
+   *  instead, leaving the branch durable until a human clicks approve. A
+   *  cancelled run neither merges nor proposes under either policy. */
+  mergePolicy?:   DriveMergePolicy;
   processors?:    readonly Processor[];
+  /** Connector requirements (ADR-0007) — providers whose APIs this workflow
+   *  calls. Dispatch resolves an authorized grant per provider and injects a
+   *  fresh access token at the network layer. */
+  connectors?: ConnectorRequirements;
+  /** Marks this workflow as a catalogue OPERATION of a connector — e.g. the
+   *  `create-issue` operation of the `github` connector. */
+  connectorOperation?: ConnectorOperationTag;
+  /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
+   *  See `InvokePolicy`. */
+  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;
 }
 
 export function createStepWorkflow<TInput, TOutput>(

package/src/workflows/engine.ts

@@ -9,7 +9,8 @@
  * (platform problem) for the runner harness to surface upstream.
  */
 
-import type { WorkflowHooks, WorkflowCtx } from "../types/workflow.js";
+import type { WorkflowHooks } from "../types/workflow.js";
+import type { InvokeChild } from "../types/execution-context.js";
 import { makeLocalSandboxProvider } from "../sandbox.js";
 import { formatError } from "../utils/errors.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -94,7 +95,7 @@ export interface RunWorkflowOptions {
   /** Provider-specific child workflow invocation. Temporal/Inngest providers
    *  inject their native child-workflow primitive; the LocalProvider injects
    *  the public Agent Compose API client. */
-  invokeChild?:     WorkflowCtx["invokeChild"];
+  invokeChild?:     InvokeChild;
 }
 
 export async function runWorkflow<TInput, TOutput>(

package/src/workflows/invoke-child.ts

@@ -1,5 +1,5 @@
 import { AgentComposeClient } from "../client.js";
-import type { WorkflowCtx } from "../types/workflow.js";
+import type { InvokeChild } from "../types/execution-context.js";
 
 /**
  * Build the public-API child workflow invoker used by legacy and sandboxed
@@ -9,7 +9,7 @@ import type { WorkflowCtx } from "../types/workflow.js";
 export function buildInvokeChild(
   runId: string,
   opts: { fallbackBaseUrl?: string; defaultFactorySlug?: string } = {},
-): WorkflowCtx["invokeChild"] {
+): InvokeChild {
   let childClient: AgentComposeClient | null = null;
   const getChildClient = (): AgentComposeClient => {
     if (childClient) return childClient;