@agent-compose/sdk 0.8.0 → 0.8.1

package/src/workflow-steps/workflow.ts

@@ -77,6 +77,13 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
    *  server skips mounting the shared factory drive for its runs (#13). See
    *  `WorkflowMetadata.environmentBuild`. */
   environmentBuild?: boolean;
+  /** Whether this workflow's runs need the factory drive. Omit (⇒
+   *  `"required"`) for any workflow that reads or writes /factory: a failed
+   *  mount then FAILS the run instead of silently proceeding drive-less.
+   *  Declare `"none"` for a drive-agnostic workflow — the server skips the
+   *  /factory mount entirely for its runs. See
+   *  `WorkflowMetadata.factoryDrive`. */
+  factoryDrive?: "required" | "none";
 }
 
 export function createStepWorkflow<TInput, TOutput>(

package/src/workflows/invoke-child.ts

@@ -1,6 +1,32 @@
 import { AgentComposeClient } from "../client.js";
+import { getActiveStep, nextPauseOrdinalInActiveStep } from "../active-step.js";
 import type { InvokeChild } from "../types/execution-context.js";
 
+/**
+ * Derive the deterministic per-call `Idempotency-Key` for a `ctx.invokeChild`
+ * dispatch: `invoke-child:<parentRunId>:step<stepIndex>:<childName>:<ordinal>`.
+ *
+ * Replay safety: a replayed step re-runs its body from the top, so the k-th
+ * `invokeChild(name)` call in a step re-derives the SAME key (the per-scope
+ * ordinal counter lives on the active-step state, which resets identically on
+ * every (re-)entry — the `nextPauseOrdinalInActiveStep` pattern). The server's
+ * idempotency window then returns the original child run instead of
+ * double-dispatching. Outside step execution (local dev, tests) there is no
+ * stable coordinate to key on — returns null and the dispatch is unkeyed,
+ * exactly the old behavior.
+ *
+ * Key syntax matches the server's `Idempotency-Key` grammar
+ * (`[A-Za-z0-9_\-:.]{1,255}`): runId is a UUID, step index a number, and
+ * workflow names are kebab-case.
+ */
+export function deriveInvokeChildIdempotencyKey(parentRunId: string, childName: string): string | null {
+  const step = getActiveStep();
+  if (!step) return null;
+  const ordinal = nextPauseOrdinalInActiveStep(`invoke-child:${childName}`);
+  if (ordinal === null) return null;
+  return `invoke-child:${parentRunId}:step${step.stepIndex}:${childName}:${ordinal}`;
+}
+
 /**
  * Build the public-API child workflow invoker used by legacy and sandboxed
  * workflow execution. Provider-backed engines may inject a different
@@ -21,15 +47,25 @@ export function buildInvokeChild(
     childClient = new AgentComposeClient({ apiKey, baseUrl });
     return childClient;
   };
-  return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
-    ...childOpts,
-    parentRunId: runId,
-    // The runner sets `AGENT_COMPOSE_FACTORY` (the run's factory slug — see
-    // activities.ts loadRunnerEnvs). Default the child to it so it lands in the
-    // SAME factory as the parent — the per-run API key is factory-scoped, so a
-    // child dispatched into another factory 403s. (Was reading the never-set
-    // `AGENT_COMPOSE_FACTORY_SLUG`, silently falling back to "default".)
-    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug
-      ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default",
-  });
+  return (name, input, childOpts) => {
+    // Replay-safe dispatch: derive a deterministic per-step key so a step
+    // re-entered after pause/resume (or a crash-replayed attempt) dedupes to
+    // the original child run instead of double-dispatching. An explicit
+    // caller-supplied key wins.
+    const idempotencyKey = childOpts?.idempotencyKey
+      ?? deriveInvokeChildIdempotencyKey(runId, name)
+      ?? undefined;
+    return getChildClient().invokeAndWait(name, input, {
+      ...childOpts,
+      ...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
+      parentRunId: runId,
+      // The runner sets `AGENT_COMPOSE_FACTORY` (the run's factory slug — see
+      // activities.ts loadRunnerEnvs). Default the child to it so it lands in the
+      // SAME factory as the parent — the per-run API key is factory-scoped, so a
+      // child dispatched into another factory 403s. (Was reading the never-set
+      // `AGENT_COMPOSE_FACTORY_SLUG`, silently falling back to "default".)
+      factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug
+        ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default",
+    });
+  };
 }