@sapiom/orchestration-core 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @sapiom/orchestration-core
 
+## 0.2.0
+
+### Minor Changes
+
+- 704c9ac: Make the local development loop (`run_local`) production-faithful and trustworthy for the dispatch/pause pattern (`agent.coding.launch` + `pauseUntilSignal`).
+
+  - Stub capability handles now survive JSON serialization, so a paused/resumed coding workflow runs end-to-end locally instead of failing with an opaque `'sandbox.toJSON' is not a method or field` error.
+  - The payload a paused step resumes with is delivered as plain JSON — the same shape production sends over the wire — so authors re-attach handles by name (`sandboxes.attach(...)`) locally exactly as they would in prod.
+  - `@sapiom/tools` exports `CodingResultPayload`: the shape a step resumed from `pauseUntilSignal(codingHandle, …)` receives, so resumed steps can be annotated instead of hand-rolling the type.
+  - Stubbing a handle-returning capability with plain JSON no longer strips the handle's instance methods (e.g. `repo.pushFromSandbox`), and `repositories.list` stubs are coerced and shape-checked.
+  - A dispatched `launch()` accepts the `agent.coding.launch` stub key as well as the shared `agent.coding.run` (ordered candidate resolution), so the stub key matching the call the author wrote takes effect.
+  - `run_local` now reports `unusedStubs` (a supplied key that matched no call) and `stubWarnings` (a key that matched but carried the wrong shape), surfacing stubs that silently didn't take effect; the MCP `run_local` also serializes its result defensively.
+  - New `coding-pause` scaffold template for the launch + pause + resume pattern, and AGENTS docs documenting the resume-input contract, list stub item shape, failure-branch stubbing, and step determinism under replay.
+
+### Patch Changes
+
+- Updated dependencies [704c9ac]
+  - @sapiom/tools@0.3.0
+  - @sapiom/orchestration@0.1.7
+
 ## 0.1.1
 
 ### Patch Changes

package/dist/cjs/local/dispatcher.d.ts

@@ -1,8 +1,8 @@
-import { type NextStepDirective, type OrchestrationDefinition } from '@sapiom/orchestration';
-import { type StepDispatcher, type StepDispatchRequest, type WorkflowRunnerCore } from '@sapiom/orchestration-runtime';
-import type { StubFile } from './stubs.js';
+import { type NextStepDirective, type OrchestrationDefinition } from "@sapiom/orchestration";
+import { type StepDispatcher, type StepDispatchRequest, type WorkflowRunnerCore } from "@sapiom/orchestration-runtime";
+import type { StubFile } from "./stubs.js";
 export interface LogEntry {
-    level: 'info' | 'warn' | 'error' | 'debug';
+    level: "info" | "warn" | "error" | "debug";
     msg: string;
     meta?: Record<string, unknown>;
 }
@@ -10,7 +10,7 @@ export interface LocalStepTrace {
     step: string;
     attempt: number;
     input: unknown;
-    status: 'succeeded' | 'threw';
+    status: "succeeded" | "threw";
     output?: unknown;
     directive?: NextStepDirective;
     error?: {
@@ -27,6 +27,8 @@ export declare class LocalStubDispatcher implements StepDispatcher {
     private maxAttemptsPerStep;
     private signals;
     readonly trace: LocalStepTrace[];
+    readonly usedKeysByStep: Map<string, Set<string>>;
+    readonly stubWarnings: Set<string>;
     constructor(definition: OrchestrationDefinition, stubs: StubFile);
     setCore(core: WorkflowRunnerCore): void;
     setMaxAttempts(max: number): void;

package/dist/cjs/local/dispatcher.js

@@ -11,6 +11,8 @@ class LocalStubDispatcher {
         this.core = null;
         this.signals = new Map();
         this.trace = [];
+        this.usedKeysByStep = new Map();
+        this.stubWarnings = new Set();
     }
     setCore(core) {
         this.core = core;
@@ -23,7 +25,7 @@ class LocalStubDispatcher {
     }
     async dispatch(request) {
         if (!this.core)
-            throw new Error('LocalStubDispatcher: setCore() was not called');
+            throw new Error("LocalStubDispatcher: setCore() was not called");
         const step = this.definition.steps[request.stepName];
         if (!step)
             throw new Error(`LocalStubDispatcher: no step '${request.stepName}' in the definition`);
@@ -33,7 +35,17 @@ class LocalStubDispatcher {
         const logs = [];
         const sharedStore = new orchestration_1.InMemoryContextStore(request.shared);
         const overrides = (this.stubs.steps[request.stepName] ?? {});
-        const sapiom = (0, stub_1.createStubClient)({ overrides, signals: this.signals });
+        let usedKeys = this.usedKeysByStep.get(request.stepName);
+        if (!usedKeys) {
+            usedKeys = new Set();
+            this.usedKeysByStep.set(request.stepName, usedKeys);
+        }
+        const sapiom = (0, stub_1.createStubClient)({
+            overrides,
+            signals: this.signals,
+            usedKeys,
+            warnings: this.stubWarnings,
+        });
         const ctx = {
             executionId: request.executionId,
             workflowName: request.workflowName,
@@ -56,7 +68,7 @@ class LocalStubDispatcher {
                 step: request.stepName,
                 attempt: request.attempt,
                 input: request.input,
-                status: 'threw',
+                status: "threw",
                 error: { name: e.name, message: e.message, stack: e.stack },
                 logs,
             });
@@ -74,7 +86,7 @@ class LocalStubDispatcher {
             step: request.stepName,
             attempt: request.attempt,
             input: request.input,
-            status: 'succeeded',
+            status: "succeeded",
             output,
             directive,
             logs,
@@ -94,22 +106,44 @@ function makeLogger(sink) {
     const at = (level) => (msg, meta) => {
         sink.push({ level, msg, ...(meta ? { meta } : {}) });
     };
-    return { info: at('info'), warn: at('warn'), error: at('error'), debug: at('debug') };
+    return {
+        info: at("info"),
+        warn: at("warn"),
+        error: at("error"),
+        debug: at("debug"),
+    };
 }
 function splitDirective(d) {
     switch (d.kind) {
-        case 'continue':
-            return { output: d.input, wire: { kind: 'continue', stepName: d.stepName, input: d.input } };
-        case 'terminate':
-            return { output: d.output, wire: { kind: 'terminate', reason: d.reason } };
-        case 'fail':
-            return { output: d.output, wire: { kind: 'fail', reason: d.reason } };
-        case 'pause_until_signal':
+        case "continue":
+            return {
+                output: d.input,
+                wire: { kind: "continue", stepName: d.stepName, input: d.input },
+            };
+        case "terminate":
             return {
                 output: d.output,
-                wire: { kind: 'pause_until_signal', signal: d.signal, timeoutMs: d.timeoutMs, resumeStep: d.resumeStep },
+                wire: { kind: "terminate", reason: d.reason },
+            };
+        case "fail":
+            return {
+                output: d.output,
+                wire: { kind: "fail", reason: d.reason },
+            };
+        case "pause_until_signal":
+            return {
+                output: d.output,
+                wire: {
+                    kind: "pause_until_signal",
+                    signal: d.signal,
+                    timeoutMs: d.timeoutMs,
+                    resumeStep: d.resumeStep,
+                },
+            };
+        case "retry":
+            return {
+                output: undefined,
+                wire: { kind: "retry", delayMs: d.delayMs, reason: d.reason },
             };
-        case 'retry':
-            return { output: undefined, wire: { kind: 'retry', delayMs: d.delayMs, reason: d.reason } };
     }
 }

package/dist/cjs/local/run-local.d.ts

@@ -1,6 +1,6 @@
-import type { OrchestrationDefinition, WorkflowManifest } from '@sapiom/orchestration';
-import { type LocalStepTrace } from './dispatcher.js';
-import { type StubFile } from './stubs.js';
+import type { OrchestrationDefinition, WorkflowManifest } from "@sapiom/orchestration";
+import { type LocalStepTrace } from "./dispatcher.js";
+import { type StubFile } from "./stubs.js";
 export declare const STUBS_FILE: string;
 export interface RunLocalOptions {
     definition: OrchestrationDefinition;
@@ -9,13 +9,19 @@ export interface RunLocalOptions {
     stubs?: StubFile;
     maxAttemptsPerStep?: number;
 }
-export type LocalRunOutcome = 'completed' | 'failed' | 'paused' | 'running';
+export type LocalRunOutcome = "completed" | "failed" | "paused" | "running";
+export interface UnusedStub {
+    step: string;
+    key: string;
+}
 export interface LocalRunResult {
     outcome: LocalRunOutcome;
     executionId: string;
     output?: unknown;
     error?: unknown;
     steps: LocalStepTrace[];
+    unusedStubs: UnusedStub[];
+    stubWarnings: string[];
 }
 export declare function runLocal(opts: RunLocalOptions): Promise<LocalRunResult>;
 export declare function runLocalFromDir(opts: {

package/dist/cjs/local/run-local.js

@@ -13,18 +13,18 @@ const errors_js_1 = require("../errors.js");
 const dispatcher_js_1 = require("./dispatcher.js");
 const load_js_1 = require("./load.js");
 const stubs_js_1 = require("./stubs.js");
-exports.STUBS_FILE = node_path_1.default.join('.sapiom-dev', 'stubs.json');
+exports.STUBS_FILE = node_path_1.default.join(".sapiom-dev", "stubs.json");
 function loadStubsFile(sourceDir) {
     const file = node_path_1.default.join(sourceDir, exports.STUBS_FILE);
     if (!(0, node_fs_1.existsSync)(file))
         return undefined;
     let raw;
     try {
-        raw = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+        raw = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
     }
     catch (err) {
         throw new errors_js_1.OrchestrationError({
-            code: 'STUBS_INVALID',
+            code: "STUBS_INVALID",
             message: `${exports.STUBS_FILE} is not valid JSON.`,
             hint: err instanceof Error ? err.message : String(err),
         });
@@ -39,7 +39,11 @@ async function runLocal(opts) {
     const dispatcher = new dispatcher_js_1.LocalStubDispatcher(opts.definition, stubs);
     const signals = new Map();
     dispatcher.setSignals(signals);
-    const core = new orchestration_runtime_1.WorkflowRunnerCore({ store, dispatcher, observer: orchestration_runtime_1.NOOP_OBSERVER });
+    const core = new orchestration_runtime_1.WorkflowRunnerCore({
+        store,
+        dispatcher,
+        observer: orchestration_runtime_1.NOOP_OBSERVER,
+    });
     dispatcher.setCore(core);
     dispatcher.setMaxAttempts(max);
     const executionId = await core.createExecution(opts.definition.name, opts.definition.entry, opts.input, {
@@ -49,25 +53,43 @@ async function runLocal(opts) {
     while (guard++ < MAX_ADVANCES) {
         await core.advance(executionId, max);
         const row = await store.loadExecution(executionId);
-        if (!row || row.status === 'completed' || row.status === 'failed' || row.status === 'cancelled')
+        if (!row ||
+            row.status === "completed" ||
+            row.status === "failed" ||
+            row.status === "cancelled")
             break;
-        if (row.status === 'paused') {
-            const payload = signals.get(row.pausedSignalCorrelationId ?? '') ?? {};
+        if (row.status === "paused") {
+            const payload = signals.get(row.pausedSignalCorrelationId ?? "") ?? {};
             await core.resetForResume(executionId, { fromStepInput: payload });
         }
     }
     const final = await store.loadExecution(executionId);
-    const outcome = final?.status === 'cancelled' ? 'failed' : (final?.status ?? 'running');
+    const outcome = final?.status === "cancelled" ? "failed" : (final?.status ?? "running");
+    const unusedStubs = [];
+    for (const [step, used] of dispatcher.usedKeysByStep) {
+        for (const key of Object.keys(stubs.steps[step] ?? {})) {
+            if (!used.has(key))
+                unusedStubs.push({ step, key });
+        }
+    }
     return {
         outcome,
         executionId,
         output: final?.output,
         error: final?.error,
         steps: dispatcher.trace,
+        unusedStubs,
+        stubWarnings: [...dispatcher.stubWarnings],
     };
 }
 async function runLocalFromDir(opts) {
     const { definition, manifest } = await (0, load_js_1.loadDefinition)(opts.sourceDir);
     const stubs = opts.stubs ?? loadStubsFile(opts.sourceDir);
-    return runLocal({ definition, manifest, input: opts.input, stubs, maxAttemptsPerStep: opts.maxAttemptsPerStep });
+    return runLocal({
+        definition,
+        manifest,
+        input: opts.input,
+        stubs,
+        maxAttemptsPerStep: opts.maxAttemptsPerStep,
+    });
 }

package/dist/esm/local/dispatcher.d.ts

@@ -1,8 +1,8 @@
-import { type NextStepDirective, type OrchestrationDefinition } from '@sapiom/orchestration';
-import { type StepDispatcher, type StepDispatchRequest, type WorkflowRunnerCore } from '@sapiom/orchestration-runtime';
-import type { StubFile } from './stubs.js';
+import { type NextStepDirective, type OrchestrationDefinition } from "@sapiom/orchestration";
+import { type StepDispatcher, type StepDispatchRequest, type WorkflowRunnerCore } from "@sapiom/orchestration-runtime";
+import type { StubFile } from "./stubs.js";
 export interface LogEntry {
-    level: 'info' | 'warn' | 'error' | 'debug';
+    level: "info" | "warn" | "error" | "debug";
     msg: string;
     meta?: Record<string, unknown>;
 }
@@ -10,7 +10,7 @@ export interface LocalStepTrace {
     step: string;
     attempt: number;
     input: unknown;
-    status: 'succeeded' | 'threw';
+    status: "succeeded" | "threw";
     output?: unknown;
     directive?: NextStepDirective;
     error?: {
@@ -27,6 +27,8 @@ export declare class LocalStubDispatcher implements StepDispatcher {
     private maxAttemptsPerStep;
     private signals;
     readonly trace: LocalStepTrace[];
+    readonly usedKeysByStep: Map<string, Set<string>>;
+    readonly stubWarnings: Set<string>;
     constructor(definition: OrchestrationDefinition, stubs: StubFile);
     setCore(core: WorkflowRunnerCore): void;
     setMaxAttempts(max: number): void;

package/dist/esm/local/dispatcher.js

@@ -1,6 +1,6 @@
-import { InMemoryContextStore, } from '@sapiom/orchestration';
-import { parseCorrelationId, STEP_COMPLETION_OUTCOME, } from '@sapiom/orchestration-runtime';
-import { createStubClient } from '@sapiom/tools/stub';
+import { InMemoryContextStore, } from "@sapiom/orchestration";
+import { parseCorrelationId, STEP_COMPLETION_OUTCOME, } from "@sapiom/orchestration-runtime";
+import { createStubClient } from "@sapiom/tools/stub";
 export class LocalStubDispatcher {
     constructor(definition, stubs) {
         this.definition = definition;
@@ -8,6 +8,8 @@ export class LocalStubDispatcher {
         this.core = null;
         this.signals = new Map();
         this.trace = [];
+        this.usedKeysByStep = new Map();
+        this.stubWarnings = new Set();
     }
     setCore(core) {
         this.core = core;
@@ -20,7 +22,7 @@ export class LocalStubDispatcher {
     }
     async dispatch(request) {
         if (!this.core)
-            throw new Error('LocalStubDispatcher: setCore() was not called');
+            throw new Error("LocalStubDispatcher: setCore() was not called");
         const step = this.definition.steps[request.stepName];
         if (!step)
             throw new Error(`LocalStubDispatcher: no step '${request.stepName}' in the definition`);
@@ -30,7 +32,17 @@ export class LocalStubDispatcher {
         const logs = [];
         const sharedStore = new InMemoryContextStore(request.shared);
         const overrides = (this.stubs.steps[request.stepName] ?? {});
-        const sapiom = createStubClient({ overrides, signals: this.signals });
+        let usedKeys = this.usedKeysByStep.get(request.stepName);
+        if (!usedKeys) {
+            usedKeys = new Set();
+            this.usedKeysByStep.set(request.stepName, usedKeys);
+        }
+        const sapiom = createStubClient({
+            overrides,
+            signals: this.signals,
+            usedKeys,
+            warnings: this.stubWarnings,
+        });
         const ctx = {
             executionId: request.executionId,
             workflowName: request.workflowName,
@@ -53,7 +65,7 @@ export class LocalStubDispatcher {
                 step: request.stepName,
                 attempt: request.attempt,
                 input: request.input,
-                status: 'threw',
+                status: "threw",
                 error: { name: e.name, message: e.message, stack: e.stack },
                 logs,
             });
@@ -71,7 +83,7 @@ export class LocalStubDispatcher {
             step: request.stepName,
             attempt: request.attempt,
             input: request.input,
-            status: 'succeeded',
+            status: "succeeded",
             output,
             directive,
             logs,
@@ -90,22 +102,44 @@ function makeLogger(sink) {
     const at = (level) => (msg, meta) => {
         sink.push({ level, msg, ...(meta ? { meta } : {}) });
     };
-    return { info: at('info'), warn: at('warn'), error: at('error'), debug: at('debug') };
+    return {
+        info: at("info"),
+        warn: at("warn"),
+        error: at("error"),
+        debug: at("debug"),
+    };
 }
 function splitDirective(d) {
     switch (d.kind) {
-        case 'continue':
-            return { output: d.input, wire: { kind: 'continue', stepName: d.stepName, input: d.input } };
-        case 'terminate':
-            return { output: d.output, wire: { kind: 'terminate', reason: d.reason } };
-        case 'fail':
-            return { output: d.output, wire: { kind: 'fail', reason: d.reason } };
-        case 'pause_until_signal':
+        case "continue":
+            return {
+                output: d.input,
+                wire: { kind: "continue", stepName: d.stepName, input: d.input },
+            };
+        case "terminate":
             return {
                 output: d.output,
-                wire: { kind: 'pause_until_signal', signal: d.signal, timeoutMs: d.timeoutMs, resumeStep: d.resumeStep },
+                wire: { kind: "terminate", reason: d.reason },
+            };
+        case "fail":
+            return {
+                output: d.output,
+                wire: { kind: "fail", reason: d.reason },
+            };
+        case "pause_until_signal":
+            return {
+                output: d.output,
+                wire: {
+                    kind: "pause_until_signal",
+                    signal: d.signal,
+                    timeoutMs: d.timeoutMs,
+                    resumeStep: d.resumeStep,
+                },
+            };
+        case "retry":
+            return {
+                output: undefined,
+                wire: { kind: "retry", delayMs: d.delayMs, reason: d.reason },
             };
-        case 'retry':
-            return { output: undefined, wire: { kind: 'retry', delayMs: d.delayMs, reason: d.reason } };
     }
 }

package/dist/esm/local/run-local.d.ts

@@ -1,6 +1,6 @@
-import type { OrchestrationDefinition, WorkflowManifest } from '@sapiom/orchestration';
-import { type LocalStepTrace } from './dispatcher.js';
-import { type StubFile } from './stubs.js';
+import type { OrchestrationDefinition, WorkflowManifest } from "@sapiom/orchestration";
+import { type LocalStepTrace } from "./dispatcher.js";
+import { type StubFile } from "./stubs.js";
 export declare const STUBS_FILE: string;
 export interface RunLocalOptions {
     definition: OrchestrationDefinition;
@@ -9,13 +9,19 @@ export interface RunLocalOptions {
     stubs?: StubFile;
     maxAttemptsPerStep?: number;
 }
-export type LocalRunOutcome = 'completed' | 'failed' | 'paused' | 'running';
+export type LocalRunOutcome = "completed" | "failed" | "paused" | "running";
+export interface UnusedStub {
+    step: string;
+    key: string;
+}
 export interface LocalRunResult {
     outcome: LocalRunOutcome;
     executionId: string;
     output?: unknown;
     error?: unknown;
     steps: LocalStepTrace[];
+    unusedStubs: UnusedStub[];
+    stubWarnings: string[];
 }
 export declare function runLocal(opts: RunLocalOptions): Promise<LocalRunResult>;
 export declare function runLocalFromDir(opts: {

package/dist/esm/local/run-local.js

@@ -1,22 +1,22 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { DEFAULT_MAX_ATTEMPTS_PER_STEP, InMemoryExecutionStore, NOOP_OBSERVER, WorkflowRunnerCore, } from '@sapiom/orchestration-runtime';
-import { OrchestrationError } from '../errors.js';
-import { LocalStubDispatcher } from './dispatcher.js';
-import { loadDefinition } from './load.js';
-import { parseStubFile } from './stubs.js';
-export const STUBS_FILE = path.join('.sapiom-dev', 'stubs.json');
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_MAX_ATTEMPTS_PER_STEP, InMemoryExecutionStore, NOOP_OBSERVER, WorkflowRunnerCore, } from "@sapiom/orchestration-runtime";
+import { OrchestrationError } from "../errors.js";
+import { LocalStubDispatcher } from "./dispatcher.js";
+import { loadDefinition } from "./load.js";
+import { parseStubFile } from "./stubs.js";
+export const STUBS_FILE = path.join(".sapiom-dev", "stubs.json");
 function loadStubsFile(sourceDir) {
     const file = path.join(sourceDir, STUBS_FILE);
     if (!existsSync(file))
         return undefined;
     let raw;
     try {
-        raw = JSON.parse(readFileSync(file, 'utf8'));
+        raw = JSON.parse(readFileSync(file, "utf8"));
     }
     catch (err) {
         throw new OrchestrationError({
-            code: 'STUBS_INVALID',
+            code: "STUBS_INVALID",
             message: `${STUBS_FILE} is not valid JSON.`,
             hint: err instanceof Error ? err.message : String(err),
         });
@@ -31,7 +31,11 @@ export async function runLocal(opts) {
     const dispatcher = new LocalStubDispatcher(opts.definition, stubs);
     const signals = new Map();
     dispatcher.setSignals(signals);
-    const core = new WorkflowRunnerCore({ store, dispatcher, observer: NOOP_OBSERVER });
+    const core = new WorkflowRunnerCore({
+        store,
+        dispatcher,
+        observer: NOOP_OBSERVER,
+    });
     dispatcher.setCore(core);
     dispatcher.setMaxAttempts(max);
     const executionId = await core.createExecution(opts.definition.name, opts.definition.entry, opts.input, {
@@ -41,25 +45,43 @@ export async function runLocal(opts) {
     while (guard++ < MAX_ADVANCES) {
         await core.advance(executionId, max);
         const row = await store.loadExecution(executionId);
-        if (!row || row.status === 'completed' || row.status === 'failed' || row.status === 'cancelled')
+        if (!row ||
+            row.status === "completed" ||
+            row.status === "failed" ||
+            row.status === "cancelled")
             break;
-        if (row.status === 'paused') {
-            const payload = signals.get(row.pausedSignalCorrelationId ?? '') ?? {};
+        if (row.status === "paused") {
+            const payload = signals.get(row.pausedSignalCorrelationId ?? "") ?? {};
             await core.resetForResume(executionId, { fromStepInput: payload });
         }
     }
     const final = await store.loadExecution(executionId);
-    const outcome = final?.status === 'cancelled' ? 'failed' : (final?.status ?? 'running');
+    const outcome = final?.status === "cancelled" ? "failed" : (final?.status ?? "running");
+    const unusedStubs = [];
+    for (const [step, used] of dispatcher.usedKeysByStep) {
+        for (const key of Object.keys(stubs.steps[step] ?? {})) {
+            if (!used.has(key))
+                unusedStubs.push({ step, key });
+        }
+    }
     return {
         outcome,
         executionId,
         output: final?.output,
         error: final?.error,
         steps: dispatcher.trace,
+        unusedStubs,
+        stubWarnings: [...dispatcher.stubWarnings],
     };
 }
 export async function runLocalFromDir(opts) {
     const { definition, manifest } = await loadDefinition(opts.sourceDir);
     const stubs = opts.stubs ?? loadStubsFile(opts.sourceDir);
-    return runLocal({ definition, manifest, input: opts.input, stubs, maxAttemptsPerStep: opts.maxAttemptsPerStep });
+    return runLocal({
+        definition,
+        manifest,
+        input: opts.input,
+        stubs,
+        maxAttemptsPerStep: opts.maxAttemptsPerStep,
+    });
 }