@loopstack/advanced-workflows-examples 0.1.1 → 0.1.2

package/dist/workflows/workflow-state/tool-results-example.workflow.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowToolResultsWorkflow = void 0;
 const common_1 = require("@loopstack/common");
 let WorkflowToolResultsWorkflow = class WorkflowToolResultsWorkflow extends common_1.BaseWorkflow {
-    async createSomeData(_state) {
+    async createSomeData() {
         await this.documentStore.save(common_1.MessageDocument, {
             role: 'assistant',
             text: `Stored in initial transition: Hello World.`,
@@ -30,7 +30,7 @@ exports.WorkflowToolResultsWorkflow = WorkflowToolResultsWorkflow;
 __decorate([
     (0, common_1.Transition)({ to: 'data_created' }),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", []),
     __metadata("design:returntype", Promise)
 ], WorkflowToolResultsWorkflow.prototype, "createSomeData", null);
 __decorate([

package/dist/workflows/workflow-state/tool-results-example.workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-results-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/workflow-state/tool-results-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAwF;AAUjF,IAAM,2BAA2B,GAAjC,MAAM,2BAA4B,SAAQ,qBAAY;IAErD,AAAN,KAAK,CAAC,cAAc,CAAC,MAAwB;QAC3C,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,4CAA4C;SACnD,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC,CAAC;IACtD,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU,CAAC,KAAuB;QACtC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,sCAAsC,KAAK,CAAC,aAAa,EAAE;SAClE,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAjBY,kEAA2B;AAEhC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;;;;iEAOlC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;6DAM/C;sCAhBU,2BAA2B;IAJvC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,yCAAyC;QAChD,WAAW,EAAE,iFAAiF;KAC/F,CAAC;GACW,2BAA2B,CAiBvC"}
+{"version":3,"file":"tool-results-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/workflow-state/tool-results-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAwF;AAUjF,IAAM,2BAA2B,GAAjC,MAAM,2BAA4B,SAAQ,qBAAY;IAErD,AAAN,KAAK,CAAC,cAAc;QAClB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,4CAA4C;SACnD,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC,CAAC;IACtD,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU,CAAC,KAAuB;QACtC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,sCAAsC,KAAK,CAAC,aAAa,EAAE;SAClE,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAjBY,kEAA2B;AAEhC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;;;;iEAOlC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;6DAM/C;sCAhBU,2BAA2B;IAJvC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,yCAAyC;QAChD,WAAW,EAAE,iFAAiF;KAC/F,CAAC;GACW,2BAA2B,CAiBvC"}

package/dist/workflows/workflow-state/workflow-state-example.workflow.d.ts

@@ -3,7 +3,7 @@ interface WorkflowStateState {
     message?: string;
 }
 export declare class WorkflowStateWorkflow extends BaseWorkflow {
-    createSomeData(_state: WorkflowStateState): void;
+    createSomeData(): void;
     showResults(state: WorkflowStateState): Promise<void>;
     private messageInUpperCase;
 }

package/dist/workflows/workflow-state/workflow-state-example.workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-state-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/workflow-state/workflow-state-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,mBAAmB,CAAC;AAExF,UAAU,kBAAkB;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAIa,qBAAsB,SAAQ,YAAY;IAErD,cAAc,CAAC,MAAM,EAAE,kBAAkB;IAKnC,WAAW,CAAC,KAAK,EAAE,kBAAkB;IAY3C,OAAO,CAAC,kBAAkB;CAG3B"}
+{"version":3,"file":"workflow-state-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/workflow-state/workflow-state-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,mBAAmB,CAAC;AAExF,UAAU,kBAAkB;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAIa,qBAAsB,SAAQ,YAAY;IAErD,cAAc;IAKR,WAAW,CAAC,KAAK,EAAE,kBAAkB;IAY3C,OAAO,CAAC,kBAAkB;CAG3B"}

package/dist/workflows/workflow-state/workflow-state-example.workflow.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowStateWorkflow = void 0;
 const common_1 = require("@loopstack/common");
 let WorkflowStateWorkflow = class WorkflowStateWorkflow extends common_1.BaseWorkflow {
-    createSomeData(_state) {
+    createSomeData() {
         this.assignState({ message: 'Hello :)' });
     }
     async showResults(state) {
@@ -33,7 +33,7 @@ exports.WorkflowStateWorkflow = WorkflowStateWorkflow;
 __decorate([
     (0, common_1.Transition)({ to: 'data_created' }),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", []),
     __metadata("design:returntype", void 0)
 ], WorkflowStateWorkflow.prototype, "createSomeData", null);
 __decorate([

package/dist/workflows/workflow-state/workflow-state-example.workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-state-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/workflow-state/workflow-state-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAwF;AAUjF,IAAM,qBAAqB,GAA3B,MAAM,qBAAsB,SAAQ,qBAAY;IAErD,cAAc,CAAC,MAA0B;QACvC,IAAI,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IAC5C,CAAC;IAGK,AAAN,KAAK,CAAC,WAAW,CAAC,KAAyB;QACzC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,oBAAoB,KAAK,CAAC,OAAO,EAAE;SAC1C,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,+BAA+B,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAQ,CAAC,EAAE;SAC/E,CAAC,CAAC;IACL,CAAC;IAEO,kBAAkB,CAAC,OAAe;QACxC,OAAO,OAAO,EAAE,WAAW,EAAE,CAAC;IAChC,CAAC;CACF,CAAA;AAtBY,sDAAqB;AAEhC;IADC,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;;;;2DAGlC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;wDAW/C;gCAjBU,qBAAqB;IAJjC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,mCAAmC;QAC1C,WAAW,EAAE,6FAA6F;KAC3G,CAAC;GACW,qBAAqB,CAsBjC"}
+{"version":3,"file":"workflow-state-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/workflow-state/workflow-state-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAwF;AAUjF,IAAM,qBAAqB,GAA3B,MAAM,qBAAsB,SAAQ,qBAAY;IAErD,cAAc;QACZ,IAAI,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IAC5C,CAAC;IAGK,AAAN,KAAK,CAAC,WAAW,CAAC,KAAyB;QACzC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,oBAAoB,KAAK,CAAC,OAAO,EAAE;SAC1C,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,+BAA+B,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAQ,CAAC,EAAE;SAC/E,CAAC,CAAC;IACL,CAAC;IAEO,kBAAkB,CAAC,OAAe;QACxC,OAAO,OAAO,EAAE,WAAW,EAAE,CAAC;IAChC,CAAC;CACF,CAAA;AAtBY,sDAAqB;AAEhC;IADC,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;;;;2DAGlC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;wDAW/C;gCAjBU,qBAAqB;IAJjC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,mCAAmC;QAC1C,WAAW,EAAE,6FAA6F;KAC3G,CAAC;GACW,qBAAqB,CAsBjC"}

package/package.json

@@ -16,7 +16,7 @@
     "agent",
     "error-handling"
   ],
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "author": {
     "name": "Jakob Klippel",

package/src/workflows/agent-error-handling/agent-error-handling-failing-sub.workflow.ts

@@ -7,7 +7,7 @@ import { BaseWorkflow, Transition, Workflow } from '@loopstack/common';
 @Workflow({ title: 'Agent Error Handling - Failing Sub-Workflow' })
 export class AgentErrorHandlingFailingSubWorkflow extends BaseWorkflow {
   @Transition({ to: 'done' })
-  start(_state: Record<string, unknown>) {
+  start() {
     return Promise.reject(new Error('Simulated sub-workflow failure.'));
   }
 }

package/src/workflows/agent-error-handling/agent-error-handling.workflow.ts

@@ -47,7 +47,7 @@ export class AgentErrorHandlingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'ready' })
-  async setup(_state: AgentErrorHandlingState) {
+  async setup() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text:
@@ -105,7 +105,7 @@ export class AgentErrorHandlingWorkflow extends BaseWorkflow {
 
   @Transition({ from: 'awaiting_tools', to: 'ready' })
   @Guard('allToolsComplete')
-  toolsComplete(_state: AgentErrorHandlingState) {}
+  toolsComplete() {}
 
   @Transition({ from: 'awaiting_tools', to: 'ready', wait: true })
   async cancelPendingTools(state: AgentErrorHandlingState, ctx: RunContext) {
@@ -113,8 +113,8 @@ export class AgentErrorHandlingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'prompt_executed', to: 'end' })
-  @Guard('isEndTurn')
-  respond(_state: AgentErrorHandlingState) {}
+  @Guard('isDone')
+  respond() {}
 
   private hasToolCalls(state: AgentErrorHandlingState): boolean {
     return state.llmResult?.message.stopReason === 'tool_use';
@@ -124,7 +124,7 @@ export class AgentErrorHandlingWorkflow extends BaseWorkflow {
     return !!state.delegateResult?.allCompleted;
   }
 
-  private isEndTurn(state: AgentErrorHandlingState): boolean {
+  private isDone(state: AgentErrorHandlingState): boolean {
     return state.llmResult?.message.stopReason === 'end_turn';
   }
 }

package/src/workflows/agent-error-handling/tools/failing-sub-workflow.tool.ts

@@ -5,12 +5,16 @@ import { AgentErrorHandlingFailingSubWorkflow } from '../agent-error-handling-fa
 
 export type FailingSubWorkflowToolResult = { workflowId: string };
 
+export const FailingSubWorkflowToolResultSchema = z.strictObject({ workflowId: z.string() });
+
 @Tool({
   name: 'failing_sub_workflow',
   description:
     'Launch an async sub-workflow that always fails. ' +
     'Used to test that failed sub-workflow errors propagate back to the parent.',
   schema: z.object({}),
+  resultSchema: FailingSubWorkflowToolResultSchema,
+  effects: 'none',
 })
 export class FailingSubWorkflowTool extends BaseTool<object, object, FailingSubWorkflowToolResult> {
   constructor(private readonly failingWorkflow: AgentErrorHandlingFailingSubWorkflow) {

package/src/workflows/agent-error-handling/tools/runtime-error.tool.ts

@@ -4,6 +4,8 @@ import type { RunContext } from '@loopstack/common';
 
 export type RuntimeErrorToolResult = string;
 
+export const RuntimeErrorToolResultSchema = z.string();
+
 @Tool({
   name: 'runtime_error',
   description:
@@ -12,6 +14,8 @@ export type RuntimeErrorToolResult = string;
   schema: z.object({
     shouldFail: z.boolean().describe('Whether the tool should simulate a runtime failure.'),
   }),
+  resultSchema: RuntimeErrorToolResultSchema,
+  effects: 'none',
 })
 export class RuntimeErrorTool extends BaseTool<{ shouldFail: boolean }, object, RuntimeErrorToolResult> {
   protected async handle(

package/src/workflows/agent-error-handling/tools/strict-schema.tool.ts

@@ -3,6 +3,8 @@ import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
 
 export type StrictSchemaToolResult = string;
 
+export const StrictSchemaToolResultSchema = z.string();
+
 @Tool({
   name: 'strict_schema',
   description: 'Greet a person by name. Requires a name argument. ' + 'Returns a greeting message.',
@@ -11,6 +13,8 @@ export type StrictSchemaToolResult = string;
       name: z.string().describe('The name of the person to greet.'),
     })
     .strict(),
+  resultSchema: StrictSchemaToolResultSchema,
+  effects: 'none',
 })
 export class StrictSchemaTool extends BaseTool<{ name: string }, object, StrictSchemaToolResult> {
   protected async handle(args: { name: string }): Promise<ToolEnvelope<StrictSchemaToolResult>> {

package/src/workflows/custom-tool/__tests__/custom-tool-facade.spec.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { BaseTool, BaseWorkflow, Tool, ToolCallOptions, ToolEnvelope, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { replay, runWorkflow } from '@loopstack/testing';
+import { CustomToolExampleWorkflow } from '../custom-tool-example.workflow';
+import { MathService } from '../services/math.service';
+import { CounterTool, MathSumTool } from '../tools';
+
+describe('CustomToolExampleWorkflow — runWorkflow facade', () => {
+  it('runs live tools, answers the wait transition, and completes', async () => {
+    const run = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: [CounterTool, MathSumTool, MathService],
+        answers: { userContinue: {} },
+      },
+    );
+
+    // Assert outcomes, not mechanics: where the run ended, the path it took, and what it
+    // produced. (For inspecting the trace itself — tool calls, park settles, coverage — see
+    // trace-consumers.spec.ts.)
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['calculate', 'userContinue', 'continueCount']);
+    expect(run.result).toEqual({ total: 5 });
+  });
+
+  it('replays the scripted tool responses strictly in sequence', async () => {
+    const run = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: [CounterTool, MathSumTool, MathService],
+        answers: { userContinue: {} },
+        replay: replay({
+          version: 3,
+          recordings: [
+            // The strict response sequence, in call order; transition names are assertions.
+            { tool: 'math_sum', transition: 'calculate', args: { a: 2, b: 3 }, envelope: { data: 999 } },
+            { tool: 'counter', transition: 'calculate', envelope: { data: 101 } },
+            { tool: 'counter', transition: 'calculate', envelope: { data: 102 } },
+            { tool: 'counter', transition: 'calculate', envelope: { data: 103 } },
+            { tool: 'counter', transition: 'continueCount', envelope: { data: 104 } },
+            { tool: 'counter', transition: 'continueCount', envelope: { data: 105 } },
+            { tool: 'counter', transition: 'continueCount', envelope: { data: 106 } },
+          ],
+        }),
+      },
+    );
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    // The replayed math_sum envelope (999) replaced the live 2+3 result
+    expect(run.result).toEqual({ total: 999 });
+
+    // The replayed counter sequence is transition-scoped: 101-103 before the wait, 104-106 after
+    const texts = run.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts.some((t) => t.includes('Counter before pause: 101, 102, 103'))).toBe(true);
+    expect(texts.some((t) => t.includes('Counter after resume: 104, 105, 106'))).toBe(true);
+  });
+});
+
+// --- Fixture v3: config capture and drift detection ---------------------------------------
+
+const PrefixConfigSchema = z.object({ prefix: z.string() });
+type PrefixConfig = z.infer<typeof PrefixConfigSchema>;
+
+@Tool({
+  name: 'prefixer',
+  schema: z.object({ word: z.string() }),
+  configSchema: PrefixConfigSchema,
+  resultSchema: z.string(),
+})
+class PrefixerTool extends BaseTool<{ word: string }, PrefixConfig, string> {
+  protected async handle(
+    args: { word: string },
+    _ctx: RunContext,
+    options?: ToolCallOptions<PrefixConfig>,
+  ): Promise<ToolEnvelope<string>> {
+    return Promise.resolve({ data: `${options?.config?.prefix ?? ''}${args.word}` });
+  }
+}
+
+// The config the workflow sends — mutated between record and replay to simulate a prompt change.
+let currentPrefix = 'hello-';
+
+@Workflow({ title: 'Config Replay Probe' })
+class ConfigReplayWorkflow extends BaseWorkflow {
+  constructor(private readonly prefixer: PrefixerTool) {
+    super();
+  }
+
+  @Transition({ to: 'end' })
+  async greet() {
+    const result = await this.prefixer.call({ word: 'world' }, { config: { prefix: currentPrefix } });
+    this.setResult({ message: result.data });
+  }
+}
+
+describe('fixture v3 — config capture and drift', () => {
+  it('records config, replays to the identical result, and fails on config drift', async () => {
+    currentPrefix = 'hello-';
+    const recorded = await runWorkflow(ConfigReplayWorkflow, undefined, {
+      providers: [PrefixerTool],
+      record: true,
+    });
+
+    expect(recorded.status).toBe('completed');
+    expect(recorded.result).toEqual({ message: 'hello-world' });
+    expect(recorded.recordings?.version).toBe(3);
+    expect(recorded.recordings?.recordings[0]).toMatchObject({
+      tool: 'prefixer',
+      args: { word: 'world' },
+      config: { prefix: 'hello-' },
+    });
+
+    // Same config → the fixture replays to the identical result.
+    const replayed = await runWorkflow(ConfigReplayWorkflow, undefined, {
+      providers: [PrefixerTool],
+      replay: replay(recorded.recordings!),
+    });
+    expect(replayed.status).toBe('completed');
+    expect(replayed.result).toEqual({ message: 'hello-world' });
+
+    // Changed config — the drift the feature exists to catch: the run fails naming the config.
+    currentPrefix = 'changed-';
+    const drifted = await runWorkflow(ConfigReplayWorkflow, undefined, {
+      providers: [PrefixerTool],
+      replay: replay(recorded.recordings!),
+    });
+    expect(drifted.status).toBe('failed');
+    expect(drifted.error).toMatch(/config for 'prefixer'/);
+    expect(drifted.error).toContain('hello-');
+    expect(drifted.error).toContain('changed-');
+  });
+
+  it('rejects version 2 fixtures outright', () => {
+    expect(() => replay({ version: 2, recordings: [] } as never)).toThrow(/version: 2.*Expected 3/s);
+  });
+});

package/src/workflows/custom-tool/__tests__/trace-consumers.spec.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import { coverage, createContractFake, diffTraces, runWorkflow } from '@loopstack/testing';
+import { CustomToolExampleWorkflow } from '../custom-tool-example.workflow';
+import { MathService } from '../services/math.service';
+import { CounterTool, MathSumTool } from '../tools';
+
+const PROVIDERS = [CounterTool, MathSumTool, MathService];
+
+describe('coverage — state-machine coverage over run traces', () => {
+  it('reports full coverage when runs exercise every transition and park', async () => {
+    const completed = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: PROVIDERS,
+        answers: { userContinue: {} },
+      },
+    );
+    const parked = await runWorkflow(CustomToolExampleWorkflow, { a: 1, b: 1 }, { providers: PROVIDERS });
+
+    const cov = coverage([completed, parked], CustomToolExampleWorkflow);
+
+    expect(cov.missingTransitions).toEqual([]);
+    expect(cov.missingParks).toEqual([]);
+    expect(cov.complete).toBe(true);
+    expect(cov.parkedOn).toContain('userContinue');
+  });
+
+  it('names what a partial suite leaves untested', async () => {
+    // Only the parked run: the wait transition and everything after it never execute.
+    const parked = await runWorkflow(CustomToolExampleWorkflow, { a: 1, b: 1 }, { providers: PROVIDERS });
+
+    const cov = coverage([parked], CustomToolExampleWorkflow);
+
+    expect(cov.complete).toBe(false);
+    expect(cov.missingTransitions).toContain('userContinue');
+    expect(cov.missingTransitions).toContain('continueCount');
+    expect(cov.executedTransitions).toContain('calculate');
+  });
+});
+
+describe('diffTraces — first divergence between two runs', () => {
+  it('diffs clean for two runs of identical behavior despite differing timings', async () => {
+    const first = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: PROVIDERS,
+        answers: { userContinue: {} },
+      },
+    );
+    const second = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: PROVIDERS,
+        answers: { userContinue: {} },
+      },
+    );
+
+    expect(diffTraces(first.trace, second.trace)).toBeNull();
+  });
+
+  it('reports the first point where two runs stopped doing the same thing', async () => {
+    const completed = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: PROVIDERS,
+        answers: { userContinue: {} },
+      },
+    );
+    const parked = await runWorkflow(CustomToolExampleWorkflow, { a: 2, b: 3 }, { providers: PROVIDERS });
+
+    const divergence = diffTraces(completed.trace, parked.trace);
+
+    expect(divergence).not.toBeNull();
+    expect(divergence!.reason).toBeTruthy();
+    // Both runs agree up to the park — the divergence is at or after the settle.
+    expect(divergence!.index).toBeGreaterThan(0);
+  });
+});
+
+describe('createContractFake — contract-validated DI mocks', () => {
+  it('validates scripted envelopes against the resultSchema at scripting time', () => {
+    const fake = createContractFake(MathSumTool);
+
+    expect(() => fake.returns({ data: 'not-a-number' })).toThrow(/result violates its resultSchema/);
+    expect(() => fake.returns({ data: 42 })).not.toThrow();
+  });
+
+  it('feeds validated responses into the workflow and supports interaction assertions', async () => {
+    const fake = createContractFake(MathSumTool).returns({ data: 999 });
+
+    const run = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: [{ provide: MathSumTool, useValue: fake }, CounterTool, MathService],
+        answers: { userContinue: {} },
+      },
+    );
+
+    expect(run.status).toBe('completed');
+    expect(run.result).toEqual({ total: 999 });
+    expect(fake.call).toHaveBeenCalledWith({ a: 2, b: 3 });
+  });
+
+  it('rejects unscripted calls loudly', async () => {
+    const fake = createContractFake(MathSumTool);
+
+    const run = await runWorkflow(
+      CustomToolExampleWorkflow,
+      { a: 2, b: 3 },
+      {
+        providers: [{ provide: MathSumTool, useValue: fake }, CounterTool, MathService],
+      },
+    );
+
+    expect(run.status).toBe('failed');
+    expect(run.error).toMatch(/Unscripted contract fake call on 'math_sum'/);
+  });
+});

package/src/workflows/custom-tool/custom-tool-example.workflow.ts

@@ -62,7 +62,7 @@ export class CustomToolExampleWorkflow extends BaseWorkflow<CustomToolExampleArg
   }
 
   @Transition({ from: 'waiting_for_user', to: 'resumed', wait: true })
-  userContinue(_state: CustomToolExampleState) {
+  userContinue() {
     // User pressed Next — counter state should persist from checkpoint
   }
 

package/src/workflows/custom-tool/tools/counter.tool.ts

@@ -1,10 +1,15 @@
+import { z } from 'zod';
 import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
 
 export type CounterToolResult = number;
 
+export const CounterToolResultSchema = z.number();
+
 @Tool({
   name: 'counter',
   description: 'Counter tool.',
+  resultSchema: CounterToolResultSchema,
+  effects: 'none',
 })
 export class CounterTool extends BaseTool<object, object, CounterToolResult> {
   count: number = 0;

package/src/workflows/custom-tool/tools/math-sum.tool.ts

@@ -13,10 +13,14 @@ type MathSumArgs = z.infer<typeof MathSumSchema>;
 
 export type MathSumToolResult = number;
 
+export const MathSumToolResultSchema = z.number();
+
 @Tool({
   name: 'math_sum',
   description: 'Math tool calculating the sum of two arguments by using an injected service.',
   schema: MathSumSchema,
+  resultSchema: MathSumToolResultSchema,
+  effects: 'none',
 })
 export class MathSumTool extends BaseTool<MathSumArgs, object, MathSumToolResult> {
   constructor(private readonly mathService: MathService) {

package/src/workflows/dynamic-routing/dynamic-routing-example.workflow.ts

@@ -27,7 +27,7 @@ export class DynamicRoutingExampleWorkflow extends BaseWorkflow<DynamicRoutingAr
   async createMockData(state: DynamicRoutingState, ctx: RunContext<DynamicRoutingArgs>) {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
-      text: `Analysing value = ${ctx.args.value}`,
+      text: `Analyzing value = ${ctx.args.value}`,
     });
     this.assignState({ value: ctx.args.value });
   }
@@ -36,32 +36,32 @@ export class DynamicRoutingExampleWorkflow extends BaseWorkflow<DynamicRoutingAr
 
   @Transition({ from: 'prepared', to: 'placeA', priority: 10 })
   @Guard('isAbove100')
-  routeToPlaceA(_state: DynamicRoutingState) {}
+  routeToPlaceA() {}
 
   isAbove100(state: DynamicRoutingState): boolean {
     return state.value > 100;
   }
 
   @Transition({ from: 'prepared', to: 'placeB' })
-  routeToPlaceB(_state: DynamicRoutingState) {} // no priority -> evaluated last, acts as fallback
+  routeToPlaceB() {} // no priority -> evaluated last, acts as fallback
 
   // --- Second routing fork (from 'placeA') ---
 
   @Transition({ from: 'placeA', to: 'placeC', priority: 10 })
   @Guard('isAbove200')
-  routeToPlaceC(_state: DynamicRoutingState) {}
+  routeToPlaceC() {}
 
   isAbove200(state: DynamicRoutingState): boolean {
     return state.value > 200;
   }
 
   @Transition({ from: 'placeA', to: 'placeD' })
-  routeToPlaceD(_state: DynamicRoutingState) {} // no priority -> evaluated last, acts as fallback
+  routeToPlaceD() {} // no priority -> evaluated last, acts as fallback
 
   // --- Terminal transitions ---
 
   @Transition({ from: 'placeB', to: 'end' })
-  async showMessagePlaceB(_state: DynamicRoutingState) {
+  async showMessagePlaceB() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Value is less or equal 100',
@@ -69,7 +69,7 @@ export class DynamicRoutingExampleWorkflow extends BaseWorkflow<DynamicRoutingAr
   }
 
   @Transition({ from: 'placeC', to: 'end' })
-  async showMessagePlaceC(_state: DynamicRoutingState) {
+  async showMessagePlaceC() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Value is greater than 200',
@@ -77,7 +77,7 @@ export class DynamicRoutingExampleWorkflow extends BaseWorkflow<DynamicRoutingAr
   }
 
   @Transition({ from: 'placeD', to: 'end' })
-  async showMessagePlaceD(_state: DynamicRoutingState) {
+  async showMessagePlaceD() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Value is less or equal 200, but greater than 100',