@agent-compose/sdk 0.7.0 → 0.8.1

package/src/workflows/invoke-child.ts

@@ -1,5 +1,31 @@
 import { AgentComposeClient } from "../client.js";
-import type { WorkflowCtx } from "../types/workflow.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
@@ -9,7 +35,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;
@@ -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",
+    });
+  };
 }