@warlock.js/ai 4.1.1

package/esm/workflow/router.mjs

@@ -0,0 +1,56 @@
+import { RoutingError } from "../errors/routing-error.mjs";
+import "../errors/index.mjs";
+
+//#region ../../@warlock.js/ai/src/workflow/router.ts
+/**
+* Resolve the next step to run after `step` completes. Tries
+* step-level `nextStep` first, then workflow-level, then falls
+* through (returns `undefined`, engine picks the next declared step).
+*
+* Throws `RoutingError` when either callback throws — routing is
+* authoritative, so a broken router terminates the workflow instead
+* of being retried.
+*/
+async function resolveNextStep(params) {
+	const { step, definition, ctx } = params;
+	if (step.nextStep) {
+		let outcome;
+		try {
+			outcome = await step.nextStep(ctx);
+		} catch (err) {
+			throw new RoutingError(`workflow "${definition.name}": step "${step.name}" nextStep threw`, {
+				stepName: step.name,
+				cause: err
+			});
+		}
+		const mapped = mapNextStep(outcome);
+		if (mapped !== void 0) return mapped;
+	}
+	if (definition.nextStep) {
+		let outcome;
+		try {
+			outcome = await definition.nextStep(step.name, ctx);
+		} catch (err) {
+			throw new RoutingError(`workflow "${definition.name}": workflow-level nextStep threw after "${step.name}"`, {
+				stepName: step.name,
+				cause: err
+			});
+		}
+		const mapped = mapNextStep(outcome);
+		if (mapped !== void 0) return mapped;
+	}
+}
+function mapNextStep(outcome) {
+	if (!outcome) return void 0;
+	if ("end" in outcome && outcome.end === true) return "end";
+	if ("goto" in outcome && typeof outcome.goto === "string") return outcome.goto;
+}
+function nextDeclaredStep(definition, currentName) {
+	const idx = definition.steps.findIndex((s) => s.name === currentName);
+	if (idx === -1) return null;
+	return definition.steps[idx + 1]?.name ?? null;
+}
+
+//#endregion
+export { mapNextStep, nextDeclaredStep, resolveNextStep };
+//# sourceMappingURL=router.mjs.map

package/esm/workflow/router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/workflow/router.ts"],"sourcesContent":["import type { NextStepResult } from \"../contracts/workflow/next-step-result.type\";\nimport type { StepDefinition } from \"../contracts/workflow/step.contract\";\nimport type { WorkflowContext } from \"../contracts/workflow/workflow-context.type\";\nimport type { WorkflowDefinition } from \"../contracts/workflow/workflow.contract\";\nimport { RoutingError } from \"../errors\";\n\n/**\n * Resolve the next step to run after `step` completes. Tries\n * step-level `nextStep` first, then workflow-level, then falls\n * through (returns `undefined`, engine picks the next declared step).\n *\n * Throws `RoutingError` when either callback throws — routing is\n * authoritative, so a broken router terminates the workflow instead\n * of being retried.\n */\nexport async function resolveNextStep<T>(params: {\n  step: StepDefinition;\n  definition: WorkflowDefinition<any, T, any, any>;\n  ctx: WorkflowContext;\n}): Promise<\"end\" | string | undefined> {\n  const { step, definition, ctx } = params;\n\n  if (step.nextStep) {\n    let outcome: NextStepResult;\n    try {\n      outcome = await step.nextStep(ctx);\n    } catch (err) {\n      throw new RoutingError(\n        `workflow \"${definition.name}\": step \"${step.name}\" nextStep threw`,\n        { stepName: step.name, cause: err },\n      );\n    }\n    const mapped = mapNextStep(outcome);\n    if (mapped !== undefined) return mapped;\n  }\n\n  if (definition.nextStep) {\n    let outcome: NextStepResult;\n    try {\n      outcome = await definition.nextStep(step.name, ctx);\n    } catch (err) {\n      throw new RoutingError(\n        `workflow \"${definition.name}\": workflow-level nextStep threw after \"${step.name}\"`,\n        { stepName: step.name, cause: err },\n      );\n    }\n    const mapped = mapNextStep(outcome);\n    if (mapped !== undefined) return mapped;\n  }\n\n  return undefined;\n}\n\nexport function mapNextStep(\n  outcome: NextStepResult,\n): \"end\" | string | undefined {\n  if (!outcome) return undefined;\n  if (\"end\" in outcome && outcome.end === true) return \"end\";\n  if (\"goto\" in outcome && typeof outcome.goto === \"string\")\n    return outcome.goto;\n  return undefined;\n}\n\nexport function nextDeclaredStep<T>(\n  definition: WorkflowDefinition<any, T, any, any>,\n  currentName: string,\n): string | null {\n  const idx = definition.steps.findIndex(s => s.name === currentName);\n  if (idx === -1) return null;\n  return definition.steps[idx + 1]?.name ?? null;\n}\n"],"mappings":";;;;;;;;;;;;;AAeA,eAAsB,gBAAmB,QAID;CACtC,MAAM,EAAE,MAAM,YAAY,QAAQ;CAElC,IAAI,KAAK,UAAU;EACjB,IAAI;EACJ,IAAI;GACF,UAAU,MAAM,KAAK,SAAS,GAAG;EACnC,SAAS,KAAK;GACZ,MAAM,IAAI,aACR,aAAa,WAAW,KAAK,WAAW,KAAK,KAAK,mBAClD;IAAE,UAAU,KAAK;IAAM,OAAO;GAAI,CACpC;EACF;EACA,MAAM,SAAS,YAAY,OAAO;EAClC,IAAI,WAAW,QAAW,OAAO;CACnC;CAEA,IAAI,WAAW,UAAU;EACvB,IAAI;EACJ,IAAI;GACF,UAAU,MAAM,WAAW,SAAS,KAAK,MAAM,GAAG;EACpD,SAAS,KAAK;GACZ,MAAM,IAAI,aACR,aAAa,WAAW,KAAK,0CAA0C,KAAK,KAAK,IACjF;IAAE,UAAU,KAAK;IAAM,OAAO;GAAI,CACpC;EACF;EACA,MAAM,SAAS,YAAY,OAAO;EAClC,IAAI,WAAW,QAAW,OAAO;CACnC;AAGF;AAEA,SAAgB,YACd,SAC4B;CAC5B,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,SAAS,WAAW,QAAQ,QAAQ,MAAM,OAAO;CACrD,IAAI,UAAU,WAAW,OAAO,QAAQ,SAAS,UAC/C,OAAO,QAAQ;AAEnB;AAEA,SAAgB,iBACd,YACA,aACe;CACf,MAAM,MAAM,WAAW,MAAM,WAAU,MAAK,EAAE,SAAS,WAAW;CAClE,IAAI,QAAQ,IAAI,OAAO;CACvB,OAAO,WAAW,MAAM,MAAM,IAAI,QAAQ;AAC5C"}

package/esm/workflow/run-scoped-emitter.mjs

@@ -0,0 +1,32 @@
+//#region ../../@warlock.js/ai/src/workflow/run-scoped-emitter.ts
+/**
+* Bind a factory-scoped `WorkflowEmitter` to one run's identity.
+*
+* The engine and step-runner emit bare payloads through this sink;
+* it injects `runId` / `rootRunId` once and delegates to the real
+* three-tier emitter. This is the single place workflow run identity
+* is stamped — the alternative (editing every `emitter.emit` call
+* site) would be ~15 scattered edits and easy to miss one.
+*
+* `rootRunId === runId` for a standalone run; nested propagation
+* (a child workflow inheriting an outer run's root) lands in a
+* follow-up.
+*
+* @example
+* // Inside runWorkflow(), once per execution:
+* const emitter = runScopedEmitter(params.emitter, { runId, rootRunId: runId });
+* emitter.emit("workflow.starting", { workflowName, input }, executionHandlers);
+*/
+function runScopedEmitter(emitter, identity) {
+	return { emit(event, payload, executionHandlers) {
+		const fullPayload = {
+			...payload,
+			...identity
+		};
+		emitter.emit(event, fullPayload, executionHandlers);
+	} };
+}
+
+//#endregion
+export { runScopedEmitter };
+//# sourceMappingURL=run-scoped-emitter.mjs.map

package/esm/workflow/run-scoped-emitter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-scoped-emitter.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/workflow/run-scoped-emitter.ts"],"sourcesContent":["import type { EventIdentity } from \"../contracts/events/event-identity.type\";\nimport type { WorkflowEventMap } from \"../contracts/events/event-map.type\";\nimport type { WorkflowEventHandlers } from \"../contracts/workflow/workflow.contract\";\nimport type { WorkflowEmitter, WorkflowEventSink } from \"./emitter\";\n\n/**\n * Bind a factory-scoped `WorkflowEmitter` to one run's identity.\n *\n * The engine and step-runner emit bare payloads through this sink;\n * it injects `runId` / `rootRunId` once and delegates to the real\n * three-tier emitter. This is the single place workflow run identity\n * is stamped — the alternative (editing every `emitter.emit` call\n * site) would be ~15 scattered edits and easy to miss one.\n *\n * `rootRunId === runId` for a standalone run; nested propagation\n * (a child workflow inheriting an outer run's root) lands in a\n * follow-up.\n *\n * @example\n * // Inside runWorkflow(), once per execution:\n * const emitter = runScopedEmitter(params.emitter, { runId, rootRunId: runId });\n * emitter.emit(\"workflow.starting\", { workflowName, input }, executionHandlers);\n */\nexport function runScopedEmitter(\n  emitter: WorkflowEmitter,\n  identity: EventIdentity,\n): WorkflowEventSink {\n  return {\n    emit(event, payload, executionHandlers?: WorkflowEventHandlers) {\n      const fullPayload = {\n        ...payload,\n        ...identity,\n      } as WorkflowEventMap[typeof event];\n\n      emitter.emit(event, fullPayload, executionHandlers);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,iBACd,SACA,UACmB;CACnB,OAAO,EACL,KAAK,OAAO,SAAS,mBAA2C;EAC9D,MAAM,cAAc;GAClB,GAAG;GACH,GAAG;EACL;EAEA,QAAQ,KAAK,OAAO,aAAa,iBAAiB;CACpD,EACF;AACF"}

package/esm/workflow/signature.d.mts

@@ -0,0 +1,7 @@
+import { WorkflowDefinition } from "../contracts/workflow/workflow.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/workflow/signature.d.ts
+declare function computeSignature<T>(definition: WorkflowDefinition<any, T, any, any>): string;
+//#endregion
+export { computeSignature };
+//# sourceMappingURL=signature.d.mts.map

package/esm/workflow/signature.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/workflow/signature.ts"],"mappings":";;;iBAoCgB,gBAAA,GAAA,CAAoB,UAAA,EAAY,kBAAkB,MAAM,CAAA"}

package/esm/workflow/signature.mjs

@@ -0,0 +1,34 @@
+//#region ../../@warlock.js/ai/src/workflow/signature.ts
+function stepFingerprint(step) {
+	const tag = step.parallel ? "parallel" : step.agent ? "agent" : step.run ? "run" : "empty";
+	const agentName = step.agent?.name;
+	return {
+		n: step.name,
+		t: tag,
+		a: agentName,
+		c: step.parallel?.map((child) => stepFingerprint(child)) ?? null
+	};
+}
+/**
+* FNV-1a 32-bit hash — deterministic, no crypto dependency.
+*/
+function hash(input) {
+	let h = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		h ^= input.charCodeAt(i);
+		h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+function computeSignature(definition) {
+	const fingerprint = {
+		n: definition.name,
+		v: definition.version ?? null,
+		s: definition.steps.map((step) => stepFingerprint(step))
+	};
+	return hash(JSON.stringify(fingerprint));
+}
+
+//#endregion
+export { computeSignature };
+//# sourceMappingURL=signature.mjs.map

package/esm/workflow/signature.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/workflow/signature.ts"],"sourcesContent":["import type { StepDefinition } from \"../contracts/workflow/step.contract\";\nimport type { WorkflowDefinition } from \"../contracts/workflow/workflow.contract\";\n\nfunction stepFingerprint(step: StepDefinition): unknown {\n  const tag = step.parallel\n    ? \"parallel\"\n    : step.agent\n      ? \"agent\"\n      : step.run\n        ? \"run\"\n        : \"empty\";\n\n  const agentName = step.agent?.name;\n\n  return {\n    n: step.name,\n    t: tag,\n    a: agentName,\n    c: step.parallel?.map(child => stepFingerprint(child)) ?? null,\n  };\n}\n\n/**\n * FNV-1a 32-bit hash — deterministic, no crypto dependency.\n */\nfunction hash(input: string): string {\n  let h = 0x811c9dc5;\n\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n  }\n\n  return h.toString(16).padStart(8, \"0\");\n}\n\nexport function computeSignature<T>(definition: WorkflowDefinition<any, T, any, any>): string {\n  const fingerprint = {\n    n: definition.name,\n    v: definition.version ?? null,\n    s: definition.steps.map(step => stepFingerprint(step)),\n  };\n\n  return hash(JSON.stringify(fingerprint));\n}\n"],"mappings":";AAGA,SAAS,gBAAgB,MAA+B;CACtD,MAAM,MAAM,KAAK,WACb,aACA,KAAK,QACH,UACA,KAAK,MACH,QACA;CAER,MAAM,YAAY,KAAK,OAAO;CAE9B,OAAO;EACL,GAAG,KAAK;EACR,GAAG;EACH,GAAG;EACH,GAAG,KAAK,UAAU,KAAI,UAAS,gBAAgB,KAAK,CAAC,KAAK;CAC5D;AACF;;;;AAKA,SAAS,KAAK,OAAuB;CACnC,IAAI,IAAI;CAER,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,KAAK,MAAM,WAAW,CAAC;EACvB,IAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,SAAU;CACxE;CAEA,OAAO,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG;AACvC;AAEA,SAAgB,iBAAoB,YAA0D;CAC5F,MAAM,cAAc;EAClB,GAAG,WAAW;EACd,GAAG,WAAW,WAAW;EACzB,GAAG,WAAW,MAAM,KAAI,SAAQ,gBAAgB,IAAI,CAAC;CACvD;CAEA,OAAO,KAAK,KAAK,UAAU,WAAW,CAAC;AACzC"}

package/esm/workflow/snapshot.mjs

@@ -0,0 +1,71 @@
+import { WorkflowError } from "../errors/workflow-error.mjs";
+import { WorkflowDriftError } from "../errors/workflow-drift-error.mjs";
+import "../errors/index.mjs";
+import { resolveDefaultStore } from "../config.mjs";
+
+//#region ../../@warlock.js/ai/src/workflow/snapshot.ts
+/**
+* Resolve the effective snapshot store: the workflow's own
+* `snapshotStore` field wins; absent that, fall back to the global
+* default set via `ai.config({ defaultStore })`.
+*/
+function resolveSnapshotStore(definition) {
+	return definition.snapshotStore ?? resolveDefaultStore();
+}
+/**
+* Write the current run's state to the configured `KVStore`. Returns
+* an outcome object instead of throwing so the engine can surface
+* persistence failures via events + logs without aborting the run.
+* Callers decide whether a failed checkpoint is fatal.
+*
+* No-op (returns `{ ok: true }`) when the workflow has no store
+* configured — the common in-memory test case.
+*/
+async function persistSnapshot(params) {
+	const store = resolveSnapshotStore(params.definition);
+	if (!store) return { ok: true };
+	const snapshot = {
+		runId: params.runId,
+		workflowName: params.definition.name,
+		signature: params.signature,
+		version: params.definition.version,
+		input: params.input,
+		state: { ...params.state },
+		steps: { ...params.steps },
+		next: params.next,
+		status: params.status,
+		startedAt: params.startedAt,
+		savedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		await store.set(params.runId, snapshot);
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			error: err
+		};
+	}
+}
+/**
+* Load a prior run's snapshot from the store and run the drift
+* check. Throws `WorkflowError` when no snapshot exists, and
+* `WorkflowDriftError` when the stored signature doesn't match the
+* current definition (unless `force` is set).
+*/
+async function loadSnapshotForResume(params) {
+	const store = resolveSnapshotStore(params.definition);
+	if (!store) throw new WorkflowError(`workflow "${params.definition.name}" has no store configured — set \`snapshotStore\` on the definition or call \`ai.config({ defaultStore })\` at boot before calling resume()`);
+	const snap = await store.get(params.runId) ?? null;
+	if (!snap) throw new WorkflowError(`workflow "${params.definition.name}": no snapshot for runId "${params.runId}"`);
+	if (!params.options?.force && snap.signature !== params.signature) throw new WorkflowDriftError(`workflow "${params.definition.name}" signature drift on resume`, {
+		savedSignature: snap.signature,
+		currentSignature: params.signature,
+		runId: params.runId
+	});
+	return snap;
+}
+
+//#endregion
+export { loadSnapshotForResume, persistSnapshot };
+//# sourceMappingURL=snapshot.mjs.map

package/esm/workflow/snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/workflow/snapshot.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { StepSnapshot } from \"../contracts/result/step-result.type\";\nimport type { WorkflowSnapshot } from \"../contracts/workflow/workflow-snapshot.type\";\nimport type {\n  WorkflowDefinition,\n  WorkflowResumeOptions,\n} from \"../contracts/workflow/workflow.contract\";\nimport { WorkflowDriftError, WorkflowError } from \"../errors\";\n\n/**\n * Resolve the effective snapshot store: the workflow's own\n * `snapshotStore` field wins; absent that, fall back to the global\n * default set via `ai.config({ defaultStore })`.\n */\nfunction resolveSnapshotStore<T>(definition: WorkflowDefinition<any, T, any, any>) {\n  return definition.snapshotStore ?? resolveDefaultStore();\n}\n\nexport type PersistParams<T> = {\n  definition: WorkflowDefinition<any, T, any, any>;\n  signature: string;\n  runId: string;\n  startedAt: string;\n  input: unknown;\n  state: Record<string, unknown>;\n  steps: Record<string, StepSnapshot>;\n  next: string | null;\n  status: WorkflowSnapshot[\"status\"];\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run's state to the configured `KVStore`. Returns\n * an outcome object instead of throwing so the engine can surface\n * persistence failures via events + logs without aborting the run.\n * Callers decide whether a failed checkpoint is fatal.\n *\n * No-op (returns `{ ok: true }`) when the workflow has no store\n * configured — the common in-memory test case.\n */\nexport async function persistSnapshot<T>(\n  params: PersistParams<T>,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.definition);\n\n  if (!store) return { ok: true };\n\n  const snapshot: WorkflowSnapshot = {\n    runId: params.runId,\n    workflowName: params.definition.name,\n    signature: params.signature,\n    version: params.definition.version,\n    input: params.input,\n    state: { ...params.state },\n    steps: { ...params.steps },\n    next: params.next,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.set(params.runId, snapshot);\n    return { ok: true };\n  } catch (err) {\n    return { ok: false, error: err };\n  }\n}\n\n/**\n * Load a prior run's snapshot from the store and run the drift\n * check. Throws `WorkflowError` when no snapshot exists, and\n * `WorkflowDriftError` when the stored signature doesn't match the\n * current definition (unless `force` is set).\n */\nexport async function loadSnapshotForResume<T>(params: {\n  definition: WorkflowDefinition<any, T, any, any>;\n  signature: string;\n  runId: string;\n  options?: WorkflowResumeOptions;\n}): Promise<WorkflowSnapshot> {\n  const store = resolveSnapshotStore(params.definition);\n\n  if (!store) {\n    throw new WorkflowError(\n      `workflow \"${params.definition.name}\" has no store configured — set \\`snapshotStore\\` on the definition or call \\`ai.config({ defaultStore })\\` at boot before calling resume()`,\n    );\n  }\n\n  const snap = (await store.get<WorkflowSnapshot>(params.runId)) ?? null;\n\n  if (!snap) {\n    throw new WorkflowError(\n      `workflow \"${params.definition.name}\": no snapshot for runId \"${params.runId}\"`,\n    );\n  }\n\n  if (!params.options?.force && snap.signature !== params.signature) {\n    throw new WorkflowDriftError(\n      `workflow \"${params.definition.name}\" signature drift on resume`,\n      {\n        savedSignature: snap.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snap;\n}\n"],"mappings":";;;;;;;;;;;AAcA,SAAS,qBAAwB,YAAkD;CACjF,OAAO,WAAW,iBAAiB,oBAAoB;AACzD;;;;;;;;;;AAyBA,eAAsB,gBACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,UAAU;CAEpD,IAAI,CAAC,OAAO,OAAO,EAAE,IAAI,KAAK;CAE9B,MAAM,WAA6B;EACjC,OAAO,OAAO;EACd,cAAc,OAAO,WAAW;EAChC,WAAW,OAAO;EAClB,SAAS,OAAO,WAAW;EAC3B,OAAO,OAAO;EACd,OAAO,EAAE,GAAG,OAAO,MAAM;EACzB,OAAO,EAAE,GAAG,OAAO,MAAM;EACzB,MAAM,OAAO;EACb,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,GAAE,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,IAAI,OAAO,OAAO,QAAQ;EACtC,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,KAAK;EACZ,OAAO;GAAE,IAAI;GAAO,OAAO;EAAI;CACjC;AACF;;;;;;;AAQA,eAAsB,sBAAyB,QAKjB;CAC5B,MAAM,QAAQ,qBAAqB,OAAO,UAAU;CAEpD,IAAI,CAAC,OACH,MAAM,IAAI,cACR,aAAa,OAAO,WAAW,KAAK,4IACtC;CAGF,MAAM,OAAQ,MAAM,MAAM,IAAsB,OAAO,KAAK,KAAM;CAElE,IAAI,CAAC,MACH,MAAM,IAAI,cACR,aAAa,OAAO,WAAW,KAAK,4BAA4B,OAAO,MAAM,EAC/E;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,KAAK,cAAc,OAAO,WACtD,MAAM,IAAI,mBACR,aAAa,OAAO,WAAW,KAAK,8BACpC;EACE,gBAAgB,KAAK;EACrB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT"}

package/esm/workflow/state.mjs

@@ -0,0 +1,37 @@
+import { WorkflowError } from "../errors/workflow-error.mjs";
+import "../errors/index.mjs";
+
+//#region ../../@warlock.js/ai/src/workflow/state.ts
+/**
+* Deep-clone workflow state. Uses `structuredClone` — handles Date,
+* Map, Set, ArrayBuffer, nested objects, arrays, primitives. Throws
+* a typed `WorkflowError` on older runtimes (pre-Node-17) rather
+* than silently falling back to a JSON round-trip that would drop
+* non-serializable values like Dates without warning.
+*
+* Workflow state should stay serializable anyway (it round-trips
+* through `KVStore` on every checkpoint). If `structuredClone` chokes
+* on a value, that's a bug in the user's state — surface it.
+*/
+function cloneState(value) {
+	if (typeof structuredClone !== "function") throw new WorkflowError("workflow state cloning requires `structuredClone` (Node 17+ or a modern browser)");
+	return structuredClone(value);
+}
+/**
+* Recursively freeze `value` and every nested plain object / array so
+* consumers of `ctx.steps[x].state` or `report.state` can't mutate
+* historical snapshots. Already-frozen values are skipped.
+*/
+function deepFreeze(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Object.isFrozen(value)) return value;
+	for (const key of Object.keys(value)) {
+		const child = value[key];
+		if (child && typeof child === "object") deepFreeze(child);
+	}
+	return Object.freeze(value);
+}
+
+//#endregion
+export { cloneState, deepFreeze };
+//# sourceMappingURL=state.mjs.map

package/esm/workflow/state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/workflow/state.ts"],"sourcesContent":["import { WorkflowError } from \"../errors\";\n\n/**\n * Deep-clone workflow state. Uses `structuredClone` — handles Date,\n * Map, Set, ArrayBuffer, nested objects, arrays, primitives. Throws\n * a typed `WorkflowError` on older runtimes (pre-Node-17) rather\n * than silently falling back to a JSON round-trip that would drop\n * non-serializable values like Dates without warning.\n *\n * Workflow state should stay serializable anyway (it round-trips\n * through `KVStore` on every checkpoint). If `structuredClone` chokes\n * on a value, that's a bug in the user's state — surface it.\n */\nexport function cloneState<T>(value: T): T {\n  if (typeof structuredClone !== \"function\") {\n    throw new WorkflowError(\n      \"workflow state cloning requires `structuredClone` (Node 17+ or a modern browser)\",\n    );\n  }\n\n  return structuredClone(value);\n}\n\n/**\n * Recursively freeze `value` and every nested plain object / array so\n * consumers of `ctx.steps[x].state` or `report.state` can't mutate\n * historical snapshots. Already-frozen values are skipped.\n */\nexport function deepFreeze<T>(value: T): T {\n  if (value === null || typeof value !== \"object\") return value;\n  if (Object.isFrozen(value)) return value;\n\n  for (const key of Object.keys(value as Record<string, unknown>)) {\n    const child = (value as Record<string, unknown>)[key];\n    if (child && typeof child === \"object\") deepFreeze(child);\n  }\n\n  return Object.freeze(value);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAaA,SAAgB,WAAc,OAAa;CACzC,IAAI,OAAO,oBAAoB,YAC7B,MAAM,IAAI,cACR,kFACF;CAGF,OAAO,gBAAgB,KAAK;AAC9B;;;;;;AAOA,SAAgB,WAAc,OAAa;CACzC,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO;CACxD,IAAI,OAAO,SAAS,KAAK,GAAG,OAAO;CAEnC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,GAAG;EAC/D,MAAM,QAAS,MAAkC;EACjD,IAAI,SAAS,OAAO,UAAU,UAAU,WAAW,KAAK;CAC1D;CAEA,OAAO,OAAO,OAAO,KAAK;AAC5B"}

package/esm/workflow/step-runner.mjs

@@ -0,0 +1,371 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { WorkflowError } from "../errors/workflow-error.mjs";
+import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
+import { StepFailedError } from "../errors/step-failed-error.mjs";
+import { WorkflowCancelledError } from "../errors/workflow-cancelled-error.mjs";
+import "../errors/index.mjs";
+import { createCancelledError, sleep } from "./cancellation.mjs";
+import { cloneState, deepFreeze } from "./state.mjs";
+import { isAbortError, resolveBackoff, resolveRetryConfig } from "./retry.mjs";
+
+//#region ../../@warlock.js/ai/src/workflow/step-runner.ts
+/**
+* Narrow an `executionResult` to an `AgentResult` when the step ran
+* an agent. Custom `run` steps return arbitrary values, so the
+* `type: "agent"` discriminant keeps us honest.
+*/
+function asAgentResult(result) {
+	if (!result || typeof result !== "object") return void 0;
+	if (result.type !== "agent") return void 0;
+	return result;
+}
+/**
+* Drive one step's full lifecycle — skip evaluation, parallel
+* dispatch, retry loop around before → run|agent → output → after.
+* Returns a mutable snapshot; the engine deep-freezes it before
+* exposing.
+*/
+async function executeStep(params) {
+	const { step, emitter, executionHandlers, logger, logModule, signal } = params;
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const stepStartPerf = performance.now();
+	params.step.on?.starting?.({ step: step.name });
+	emitter.emit("workflow.step.starting", { step: step.name }, executionHandlers);
+	logger.debug(logModule, "step.starting", `${step.name} step starting`, { step: step.name });
+	const stepState = cloneState(params.state);
+	try {
+		if (step.skip) {
+			if (await step.skip(params.buildContext({ state: stepState }))) {
+				const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+				const duration = performance.now() - stepStartPerf;
+				emitter.emit("workflow.step.skipped", { step: step.name }, executionHandlers);
+				logger.debug(logModule, "step.skipped", `${step.name} step skipped`, { step: step.name });
+				return {
+					output: void 0,
+					skipped: true,
+					status: "skipped",
+					startedAt,
+					endedAt,
+					duration,
+					attempts: 0,
+					attemptHistory: [],
+					state: stepState
+				};
+			}
+		}
+	} catch (err) {
+		return buildFailedSnapshot(step, stepState, startedAt, stepStartPerf, 1, [failedAttempt(1, err, (/* @__PURE__ */ new Date()).toISOString(), performance.now())]);
+	}
+	if (step.parallel && step.parallel.length > 0) return runParallelStep({
+		...params,
+		step,
+		stepState,
+		startedAt,
+		startPerf: stepStartPerf
+	});
+	const retryConfig = resolveRetryConfig(step, params.workflowDefaultRetry);
+	const attempts = [];
+	const totalAttempts = Math.max(1, retryConfig.attempts ?? 1);
+	let lastError;
+	let executionResult;
+	let output;
+	let succeeded = false;
+	for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+		if (signal?.aborted) throw createCancelledError(signal);
+		const attemptStart = (/* @__PURE__ */ new Date()).toISOString();
+		const attemptStartPerf = performance.now();
+		try {
+			const attemptState = cloneState(params.state);
+			if (step.before) await step.before(params.buildContext({ state: attemptState }));
+			if (step.agent) {
+				const { prompt, ...agentOpts } = step.input ? await step.input(params.buildContext({ state: attemptState })) : { prompt: "" };
+				const result = await step.agent.execute(prompt, {
+					...agentOpts,
+					signal
+				});
+				executionResult = result;
+				if (result.usage) {
+					params.usage.input += result.usage.input ?? 0;
+					params.usage.output += result.usage.output ?? 0;
+					params.usage.total += result.usage.total ?? 0;
+				}
+				if (result.error) throw result.error;
+			} else if (step.run) executionResult = await step.run(params.buildContext({ state: attemptState }));
+			if (step.output) {
+				const extracted = await step.output.extract(params.buildContext({
+					state: attemptState,
+					agentResult: executionResult
+				}));
+				output = await validateSchema(step.output.schema, extracted);
+			} else output = void 0;
+			if (step.after) await step.after(params.buildContext({
+				state: attemptState,
+				agentResult: executionResult
+			}));
+			Object.assign(stepState, attemptState);
+			attempts.push({
+				index: attempt,
+				startedAt: attemptStart,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				duration: performance.now() - attemptStartPerf,
+				status: "success"
+			});
+			succeeded = true;
+			break;
+		} catch (err) {
+			if (isAbortError(err) || err instanceof WorkflowCancelledError) throw createCancelledError(signal);
+			attempts.push({
+				index: attempt,
+				startedAt: attemptStart,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				duration: performance.now() - attemptStartPerf,
+				status: "failed",
+				error: toAIError(err)
+			});
+			lastError = err;
+			if (!(attempt < totalAttempts && (retryConfig.retryOn ? retryConfig.retryOn(err, attempt) !== false : true))) break;
+			emitter.emit("workflow.step.retrying", {
+				step: step.name,
+				attempt: attempt + 1,
+				totalAttempts,
+				lastError: err
+			}, params.executionHandlers);
+			step.on?.retrying?.({
+				step: step.name,
+				attempt: attempt + 1,
+				totalAttempts,
+				lastError: err
+			});
+			logger.warn(logModule, "step.retrying", `${step.name} step retrying`, {
+				step: step.name,
+				attempt: attempt + 1
+			});
+			retryConfig.onRetry?.(attempt + 1, err);
+			const delay = resolveBackoff(attempt, retryConfig.backoff);
+			if (delay > 0) await sleep(delay, signal);
+		}
+	}
+	const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const duration = performance.now() - stepStartPerf;
+	if (!succeeded) {
+		const aiError = toAIError(lastError);
+		const stepError = new StepFailedError(`step "${step.name}" failed after ${attempts.length} attempt(s): ${aiError.message}`, {
+			stepName: step.name,
+			attempts: attempts.length,
+			cause: aiError
+		});
+		emitter.emit("workflow.step.failed", {
+			step: step.name,
+			error: stepError,
+			attempts: attempts.length
+		}, params.executionHandlers);
+		step.on?.failed?.({
+			step: step.name,
+			error: stepError,
+			attempts: attempts.length
+		});
+		logger.error(logModule, "step.failed", `${step.name} step failed`, {
+			step: step.name,
+			attempts: attempts.length,
+			code: stepError.code
+		});
+		const failedAgentResult = asAgentResult(executionResult);
+		return {
+			output: void 0,
+			skipped: false,
+			status: "failed",
+			startedAt,
+			endedAt,
+			duration,
+			attempts: attempts.length,
+			attemptHistory: attempts,
+			error: stepError,
+			state: stepState,
+			executionResult: executionResult && typeof executionResult === "object" ? executionResult : void 0,
+			agentReport: failedAgentResult?.report,
+			agentUsage: failedAgentResult?.usage
+		};
+	}
+	emitter.emit("workflow.step.completed", {
+		step: step.name,
+		output,
+		duration
+	}, params.executionHandlers);
+	step.on?.completed?.({
+		step: step.name,
+		output,
+		duration
+	});
+	logger.debug(logModule, "step.completed", "step completed", {
+		step: step.name,
+		duration
+	});
+	const completedAgentResult = asAgentResult(executionResult);
+	return {
+		output,
+		skipped: false,
+		status: "completed",
+		startedAt,
+		endedAt,
+		duration,
+		attempts: attempts.length,
+		attemptHistory: attempts,
+		state: stepState,
+		executionResult: executionResult && typeof executionResult === "object" ? executionResult : void 0,
+		agentReport: completedAgentResult?.report,
+		agentUsage: completedAgentResult?.usage
+	};
+}
+async function runParallelStep(params) {
+	const { step, emitter, executionHandlers, logger, logModule, signal } = params;
+	const sharedState = params.stepState;
+	const childSnapshots = {};
+	let firstError;
+	const results = await Promise.all((step.parallel ?? []).map(async (child) => {
+		const snap = await executeStep({
+			step: child,
+			state: sharedState,
+			emitter,
+			executionHandlers,
+			logger,
+			logModule,
+			signal,
+			buildContext: params.buildContext,
+			usage: params.usage
+		});
+		Object.assign(sharedState, snap.state);
+		return {
+			child,
+			snap
+		};
+	}));
+	for (const { child, snap } of results) {
+		childSnapshots[child.name] = finalizeSnapshot(snap);
+		if (snap.status === "failed" && !firstError && snap.error) firstError = snap.error;
+	}
+	const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const duration = performance.now() - params.startPerf;
+	let output;
+	if (step.output) try {
+		const ctx = params.buildContext({ state: sharedState });
+		const ctxWithChildren = {
+			...ctx,
+			steps: {
+				...ctx.steps,
+				[step.name]: {
+					...childSnapshots,
+					steps: childSnapshots,
+					status: firstError ? "failed" : "completed"
+				}
+			}
+		};
+		const extracted = await step.output.extract(ctxWithChildren);
+		output = await validateSchema(step.output.schema, extracted);
+	} catch (err) {
+		firstError = firstError ?? toAIError(err);
+	}
+	const status = firstError ? "failed" : "completed";
+	if (status === "completed") {
+		emitter.emit("workflow.step.completed", {
+			step: step.name,
+			output,
+			duration
+		}, executionHandlers);
+		step.on?.completed?.({
+			step: step.name,
+			output,
+			duration
+		});
+	} else {
+		emitter.emit("workflow.step.failed", {
+			step: step.name,
+			error: firstError,
+			attempts: 1
+		}, executionHandlers);
+		step.on?.failed?.({
+			step: step.name,
+			error: firstError,
+			attempts: 1
+		});
+	}
+	return {
+		output,
+		skipped: false,
+		status,
+		startedAt: params.startedAt,
+		endedAt,
+		duration,
+		attempts: 1,
+		attemptHistory: [],
+		error: firstError,
+		state: sharedState,
+		steps: childSnapshots
+	};
+}
+function finalizeSnapshot(snap) {
+	return Object.freeze({
+		output: snap.output,
+		skipped: snap.skipped,
+		status: snap.status,
+		startedAt: snap.startedAt,
+		endedAt: snap.endedAt,
+		duration: snap.duration,
+		attempts: snap.attempts,
+		attemptHistory: snap.attemptHistory,
+		error: snap.error,
+		state: deepFreeze(cloneState(snap.state)),
+		executionResult: snap.executionResult,
+		agentReport: snap.agentReport,
+		agentUsage: snap.agentUsage,
+		steps: snap.steps
+	});
+}
+function buildFailedSnapshot(step, state, startedAt, startPerf, attemptsCount, attemptHistory) {
+	const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const duration = performance.now() - startPerf;
+	const lastErr = attemptHistory[attemptHistory.length - 1]?.error;
+	return {
+		output: void 0,
+		skipped: false,
+		status: "failed",
+		startedAt,
+		endedAt,
+		duration,
+		attempts: attemptsCount,
+		attemptHistory,
+		error: lastErr ? new StepFailedError(`step "${step.name}" skip threw: ${lastErr.message}`, {
+			stepName: step.name,
+			attempts: attemptsCount,
+			cause: lastErr
+		}) : new StepFailedError(`step "${step.name}" failed`, {
+			stepName: step.name,
+			attempts: attemptsCount
+		}),
+		state
+	};
+}
+function failedAttempt(index, err, startedAt, startPerf) {
+	return {
+		index,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		status: "failed",
+		error: toAIError(err)
+	};
+}
+function toAIError(err) {
+	if (err instanceof AIError) return err;
+	if (err instanceof Error) return new WorkflowError(err.message, { cause: err });
+	return new WorkflowError(String(err));
+}
+async function validateSchema(schema, value) {
+	if (!schema) return value;
+	const result = await schema["~standard"].validate(value);
+	if ("issues" in result && result.issues) throw new SchemaValidationError("workflow step output failed schema validation", { issues: result.issues });
+	return result.value;
+}
+
+//#endregion
+export { executeStep, finalizeSnapshot, toAIError };
+//# sourceMappingURL=step-runner.mjs.map