@pikku/inspector 0.12.96 → 0.12.99

package/CHANGELOG.md

@@ -1,3 +1,56 @@
+## 0.12.99
+
+### Patch Changes
+
+- ce3e5f5: Saga compensation for workflows. A function declares `compensate` inline; when a workflow step fails, completed steps are undone newest-first as durable `<step>:compensate` steps. New run statuses `compensating`, `compensated` and `compensation_failed`, `workflow.milestone(name)` to bound the unwind, `{ compensate: false }` to opt a call out, nested-workflow unwinding, and `PikkuWorkflowService.cancelRun` which unwinds too. Graph nodes replace `onError` with `recover` (`nodeId`, `nodeId[]` or `'ignore'`), exposing the error as `wire.graph.recoveringFrom`. **Breaking:** the DSL `onError` step option and the graph `onError` node field are removed; `getRunSteps` is now abstract on `PikkuWorkflowService`.
+- Updated dependencies [ce3e5f5]
+- Updated dependencies [fb36c37]
+  - @pikku/core@0.12.135
+
+## 0.12.98
+
+### Patch Changes
+
+- 8ac25a8: An OAuth2 credential can set `scopeSeparator` for a provider that wants scopes joined by something other than a space (Twist wants a comma). A credential with no scopes already sent no `scope` parameter; that is now tested.
+- 6606777: A webhook source can declare how its requests are signed, and the runner checks every request before `receive` runs:
+
+  ```ts
+  wireTriggerWebhookSource({
+    name: 'github',
+    verify: {
+      hmac: {
+        header: 'x-hub-signature-256',
+        prefix: 'sha256=',
+        algorithm: 'sha256',
+        encoding: 'hex',
+      },
+    },
+    receive: githubWebhookReceive,
+  })
+  ```
+
+  `verify` is an HMAC over the raw body, a shared token or a public-key signature in one header, or a function `(request, secret, services) => boolean` for anything else. A request is refused while the secret is unset or when the signature does not match. A request without a body reaches `receive` unchecked so handshakes still work, but it may only be answered: events from it are refused.
+
+  Declaring `verify` declares the secret's credential too, so it needs no `defineCredential`. It is a singleton string named `<source>WebhookSecret` in camelCase (`microsoft-outlook` → `microsoftOutlookWebhookSecret`, see `webhookSecretCredentialName`), or whatever `credential` names, described by `credentialDescription`.
+
+  `@pikku/core/hmac` gains `hmacDigest`, `verifyHmacSignature` and `verifyPublicKeySignature`. `WebhookSigningSecret` is deprecated.
+
+- Updated dependencies [d327fa5]
+- Updated dependencies [942ebdd]
+- Updated dependencies [8ac25a8]
+- Updated dependencies [6606777]
+  - @pikku/core@0.12.132
+
+## 0.12.97
+
+### Patch Changes
+
+- 26dbfc0: A `func` written inline in a `wireCLI` command now registers its function metadata under `cli:<program>:<command path>`, with `sessionless` taken from the helper it was built with. Before, the command pointed at an id nothing had registered. An inline channel `onMessage` still fails the build with the named "No function metadata found" error, and a test now pins that.
+- 2dcc651: The inspector finds a project's source on Windows: its root directory is compared with TypeScript's forward-slash file names, not the backslash path `path.resolve` returns.
+- Updated dependencies [58cccc1]
+- Updated dependencies [a26c60e]
+  - @pikku/core@0.12.131
+
 ## 0.12.96
 
 ### Patch Changes

package/dist/add/add-cli.js

@@ -3,6 +3,7 @@ import { extractFunctionName, makeContextBasedId, } from '../utils/extract-funct
 import { resolveCoreType } from '../utils/resolve-core-type.js';
 import { resolveMiddleware } from '../utils/middleware.js';
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js';
+import { ensureInlineWiringFunction } from '../utils/ensure-function-metadata.js';
 import { extractWireNames } from '../utils/post-process.js';
 import { getPropertyValue } from '../utils/get-property-value.js';
 import { resolveIdentifier } from '../utils/resolve-identifier.js';
@@ -253,9 +254,11 @@ function processCommand(logger, inspectorState, options, name, node, sourceFile,
                 }
             }
             else {
-                pikkuFuncId = extractFunctionName(prop.initializer, typeChecker, inspectorState.rootDir).pikkuFuncId;
+                const extracted = extractFunctionName(prop.initializer, typeChecker, inspectorState.rootDir);
+                pikkuFuncId = extracted.pikkuFuncId;
                 if (pikkuFuncId.startsWith('__temp_')) {
                     pikkuFuncId = makeContextBasedId('cli', programName, ...fullPath);
+                    ensureInlineWiringFunction(inspectorState, pikkuFuncId, fullPath.join(' '), prop.initializer, typeChecker, extracted.isHelper);
                 }
                 meta.pikkuFuncId = pikkuFuncId;
                 const cliPackageName = ts.isIdentifier(prop.initializer)

package/dist/add/add-credential.js

@@ -81,6 +81,7 @@ export const addCredential = (logger, node, checker, state, _options) => {
             const authorizationUrl = getPropertyValue(oauth2Obj, 'authorizationUrl');
             const tokenUrl = getPropertyValue(oauth2Obj, 'tokenUrl');
             const scopes = getArrayPropertyValue(oauth2Obj, 'scopes');
+            const scopeSeparator = getPropertyValue(oauth2Obj, 'scopeSeparator');
             const pkce = getPropertyValue(oauth2Obj, 'pkce');
             const additionalParams = getRecordPropertyValue(oauth2Obj, 'additionalParams');
             if (appCredentialSecretId && authorizationUrl && tokenUrl && scopes) {
@@ -90,6 +91,7 @@ export const addCredential = (logger, node, checker, state, _options) => {
                     authorizationUrl,
                     tokenUrl,
                     scopes,
+                    scopeSeparator: scopeSeparator || undefined,
                     pkce: pkce || undefined,
                     additionalParams: additionalParams || undefined,
                 };

package/dist/add/add-functions.js

@@ -3,6 +3,7 @@ import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
 import { extractFunctionName, funcIdToTypeName, } from '../utils/extract-function-name.js';
 import { extractFunctionNode } from '../utils/extract-function-node.js';
 import { extractUsedWires } from '../utils/extract-services.js';
+import { getPropertyAssignmentInitializer } from '../utils/type-utils.js';
 import { collectInvokedRpcNames } from './add-rpc-invocations.js';
 import { collectStartedWorkflows } from './collect-started-workflows.js';
 import { formatVersionedId, parseVersionedId } from '@pikku/core/utils';
@@ -721,7 +722,43 @@ export const addFunctions = (logger, node, checker, state, options) => {
             services.optimized = false;
         }
     }
-    const wires = extractUsedWires(handler, 2);
+    let wires = extractUsedWires(handler, 2);
+    // `compensate` runs as the function's own sibling step, deployed wherever the
+    // function is, so what it needs is what the function needs.
+    const compensateInitializer = objectNode
+        ? getPropertyAssignmentInitializer(objectNode, 'compensate', true, checker)
+        : undefined;
+    const compensateNode = compensateInitializer &&
+        (ts.isArrowFunction(compensateInitializer) ||
+            ts.isFunctionExpression(compensateInitializer)
+            ? compensateInitializer
+            : undefined);
+    if (compensateNode) {
+        const compensateServices = compensateNode.parameters[0];
+        if (compensateServices) {
+            if (ts.isObjectBindingPattern(compensateServices.name)) {
+                for (const elem of compensateServices.name.elements) {
+                    const original = elem.propertyName && ts.isIdentifier(elem.propertyName)
+                        ? elem.propertyName.text
+                        : ts.isIdentifier(elem.name)
+                            ? elem.name.text
+                            : undefined;
+                    if (original && !services.services.includes(original)) {
+                        services.services.push(original);
+                    }
+                }
+            }
+            else if (ts.isIdentifier(compensateServices.name) &&
+                !compensateServices.name.text.startsWith('_')) {
+                services.optimized = false;
+            }
+        }
+        const compensateWires = extractUsedWires(compensateNode, 2);
+        wires = {
+            optimized: wires.optimized && compensateWires.optimized,
+            wires: [...new Set([...wires.wires, ...compensateWires.wires])],
+        };
+    }
     const invoked = collectInvokedRpcNames(handler.body);
     for (const call of invoked.dynamic) {
         logger.warn(`• ${pikkuFuncId} calls ${call} with a computed name — the deploy planner cannot bind its unit to the callee's, so the call fails with "No service binding" if the two are deployed apart. Use a literal RPC name.`);
@@ -1031,6 +1068,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
         workflowQueued: workflowQueued === true ? true : undefined,
         workflowRetries: workflowRetries ?? undefined,
         workflowTimeout: workflowTimeout ?? undefined,
+        compensate: compensateInitializer ? true : undefined,
         scenarioStepSurfaces,
         scenarioStepRequiresActor,
         // `persona` is the default reading of an unmarked step, so it is left off

package/dist/add/add-trigger.js

@@ -8,6 +8,7 @@ import { extractWireNames } from '../utils/post-process.js';
 import { resolveAddonName } from '../utils/resolve-addon-package.js';
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js';
 import { ErrorCode } from '../error-codes.js';
+import { webhookSecretCredentialName } from '@pikku/core/trigger';
 const WEBHOOK_SOURCE_STEPS = ['receive', 'check', 'setup', 'teardown'];
 export const addTrigger = (logger, node, checker, state, options) => {
     if (!ts.isCallExpression(node)) {
@@ -161,6 +162,21 @@ const addWireTriggerWebhookSource = (logger, node, checker, state, firstArg) =>
     };
     state.triggers.webhookSourceMeta[name] = meta;
     state.triggers.files.add(node.getSourceFile().fileName);
+    if (!getPropertyAssignmentInitializer(obj, 'verify', false, checker))
+        return;
+    const sourceFile = node.getSourceFile().fileName;
+    const credential = getPropertyValue(obj, 'credential') ??
+        webhookSecretCredentialName(name);
+    state.credentials.files.add(sourceFile);
+    state.credentials.definitions.push({
+        name: credential,
+        displayName: `${name} webhook secret`,
+        description: getPropertyValue(obj, 'credentialDescription') ??
+            undefined,
+        type: 'singleton',
+        schema: { type: 'string' },
+        sourceFile,
+    });
 };
 /**
  * A trigger named `<source>:<event>` must name an event its webhook source

package/dist/add/add-workflow.js

@@ -80,11 +80,6 @@ export function collectInvokedRPCs(steps, rpcs) {
     for (const step of steps) {
         if (step.type === 'rpc' && step.rpcName) {
             rpcs.add(step.rpcName);
-            // The compensation handler is invoked at runtime too, so it has to be
-            // wired like any other step.
-            if (step.options?.onError) {
-                rpcs.add(step.options.onError);
-            }
         }
         else if (step.type === 'scenarioStep' && step.stepFunc) {
             // Steps are bundled like RPCs — the runner calls them through

package/dist/inspector.js

@@ -7,6 +7,7 @@ import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
+import { toProgramPath } from './utils/program-path.js';
 import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
@@ -293,7 +294,7 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     const checker = program.getTypeChecker();
     logger.debug(`Got type checker in ${(performance.now() - startChecker).toFixed(2)}ms`);
     // Use provided rootDir or infer from source files
-    const rootDir = options.rootDir || findCommonAncestor(normalizedRouteFiles);
+    const rootDir = toProgramPath(options.rootDir || findCommonAncestor(normalizedRouteFiles));
     const startSourceFiles = performance.now();
     // node_modules under rootDir (e.g. a locally-installed addon) is a
     // dependency, not project source — scanning it double-counts the addon's

package/dist/utils/program-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A native path in the form a TypeScript program names its files: forward
+ * slashes on every platform. `sourceFile.fileName` is `D:/a/app/src/x.ts` on
+ * Windows while `path.resolve` gives `D:\a\app`, so comparing the two by
+ * prefix rejects every file unless one side is converted.
+ */
+export declare const toProgramPath: (nativePath: string, separator?: "/" | "\\") => string;

package/dist/utils/program-path.js

@@ -0,0 +1,8 @@
+import { sep } from 'path';
+/**
+ * A native path in the form a TypeScript program names its files: forward
+ * slashes on every platform. `sourceFile.fileName` is `D:/a/app/src/x.ts` on
+ * Windows while `path.resolve` gives `D:\a\app`, so comparing the two by
+ * prefix rejects every file unless one side is converted.
+ */
+export const toProgramPath = (nativePath, separator = sep) => nativePath.split(separator).join('/');

package/dist/utils/workflow/derive-workflow-plan.js

@@ -70,6 +70,12 @@ function collectNamedSteps(steps) {
                     displayName: reasonToLabel(step.reason),
                 });
                 break;
+            case 'milestone':
+                planned.push({
+                    stepName: `__milestone__:${step.name}`,
+                    displayName: reasonToLabel(step.name),
+                });
+                break;
             case 'approval':
                 // Same as suspend, but namespaced `__workflow_approval:` to match the
                 // runtime's separate step key.

package/dist/utils/workflow/dsl/deserialize-dsl-workflow.js

@@ -142,7 +142,9 @@ function fanoutBodyToCode(entryNodeId, nodes, indent, itemVar) {
             const stepName = node.stepName || `Call ${node.rpcName}`;
             const input = (node.input || {});
             const inputCode = inputToCode(input, indent, itemVar);
-            const options = node.options ? optionsToCode(node.options) : '';
+            const options = node.options || node.compensate === false
+                ? optionsToCode(node.options ?? {}, node.compensate === false ? false : undefined)
+                : '';
             const doCall = `await workflow.do('${escapeSingleQuotes(stepName)}', '${node.rpcName}', ${inputCode}${options ? `, ${options}` : ''})`;
             lines.push(node.outputVar
                 ? `${indent}const ${node.outputVar} = ${doCall}`
@@ -163,19 +165,6 @@ function fanoutBodyToCode(entryNodeId, nodes, indent, itemVar) {
  */
 function collectChildNodeIds(nodes) {
     const owned = new Set();
-    // An error handler belongs to the step that routes to it, not to the main
-    // flow — emitting it top-level would turn compensation into a step that
-    // always runs.
-    for (const node of Object.values(nodes)) {
-        const onError = node.onError;
-        if (typeof onError === 'string') {
-            owned.add(onError);
-        }
-        else if (Array.isArray(onError)) {
-            for (const handlerId of onError)
-                owned.add(handlerId);
-        }
-    }
     const walk = (entry, exit) => {
         const seen = new Set();
         let currentId = entry;
@@ -231,20 +220,6 @@ function bindingPrefix(outputVar) {
         ? `const ${outputVar} = `
         : '';
 }
-/**
- * Resolve a node's `onError` node id back to the rpc name the DSL author wrote.
- */
-function onErrorRpcNameOf(node, nodes) {
-    const onError = node.onError;
-    const handlerId = Array.isArray(onError) ? onError[0] : onError;
-    if (typeof handlerId !== 'string') {
-        return undefined;
-    }
-    const handler = nodes[handlerId];
-    return handler && 'rpcName' in handler
-        ? handler.rpcName
-        : undefined;
-}
 /**
  * A duration is `string | number` ('5s' or 5000). Quoting a number would change
  * the value the runtime parses, so only strings get quotes.
@@ -267,17 +242,17 @@ function caseValueToCode(value) {
 /**
  * Convert options to code
  */
-function optionsToCode(options, onErrorRpcName) {
+function optionsToCode(options, compensate) {
     const parts = [];
-    if (onErrorRpcName) {
-        parts.push(`onError: '${escapeSingleQuotes(onErrorRpcName)}'`);
-    }
     if (options.retries !== undefined) {
         parts.push(`retries: ${options.retries}`);
     }
     if (options.retryDelay !== undefined) {
         parts.push(`retryDelay: ${durationToCode(options.retryDelay)}`);
     }
+    if (compensate === false) {
+        parts.push('compensate: false');
+    }
     return parts.length > 0 ? `{ ${parts.join(', ')} }` : '';
 }
 /**
@@ -422,9 +397,9 @@ function nodeToCode(node, nodes, indent, conditionalVars = new Set(), isInsideBr
         const outputVar = node.outputVar;
         let doCall = `await workflow.do('${stepName}', '${node.rpcName}', ${inputCode}`;
         // Add options if present
-        const onErrorRpc = onErrorRpcNameOf(node, nodes);
-        if (node.options || onErrorRpc) {
-            const optCode = optionsToCode(node.options ?? {}, onErrorRpc);
+        const noCompensate = node.compensate === false ? false : undefined;
+        if (node.options || noCompensate === false) {
+            const optCode = optionsToCode(node.options ?? {}, noCompensate);
             if (optCode) {
                 doCall += `, ${optCode}`;
             }
@@ -459,6 +434,10 @@ function nodeToCode(node, nodes, indent, conditionalVars = new Set(), isInsideBr
                 lines.push(`${indent}await workflow.suspend('${escapeSingleQuotes(String(flowNode.reason ?? ''))}')`);
                 lines.push('');
                 break;
+            case 'milestone':
+                lines.push(`${indent}await workflow.milestone('${escapeSingleQuotes(String(flowNode.reason ?? ''))}')`);
+                lines.push('');
+                break;
             case 'approval': {
                 const approvalCall = `await workflow.approval('${escapeSingleQuotes(String(flowNode.reason ?? ''))}')`;
                 lines.push(flowNode.outputVar
@@ -537,8 +516,8 @@ function nodeToCode(node, nodes, indent, conditionalVars = new Set(), isInsideBr
                     const input = (childNode.input || {});
                     const inputCode = inputToCode(input, indent + '  ');
                     let call = `workflow.do('${stepName}', '${childNode.rpcName}', ${inputCode}`;
-                    if (childNode.options) {
-                        const optCode = optionsToCode(childNode.options);
+                    if (childNode.options || childNode.compensate === false) {
+                        const optCode = optionsToCode(childNode.options ?? {}, childNode.compensate === false ? false : undefined);
                         if (optCode) {
                             call += `, ${optCode}`;
                         }
@@ -1021,14 +1000,20 @@ export function deserializeGraphWorkflow(workflow, options = {}) {
                 configParts.push(`next: ${nextCode}`);
             }
         }
-        // onError, retries and retryDelay are all honoured by the graph runner,
-        // so dropping them here silently changes how the workflow behaves.
-        if ('onError' in node && node.onError) {
-            const onErrorCode = nextToCode(node.onError, workflow.nodes, flowNodeIds);
-            if (onErrorCode) {
-                configParts.push(`onError: ${onErrorCode}`);
+        // recover, compensate, retries and retryDelay are all honoured by the
+        // graph runner, so dropping them here silently changes how the workflow
+        // behaves.
+        if ('recover' in node && node.recover) {
+            const recoverCode = node.recover === 'ignore'
+                ? `'ignore'`
+                : nextToCode(node.recover, workflow.nodes, flowNodeIds);
+            if (recoverCode) {
+                configParts.push(`recover: ${recoverCode}`);
             }
         }
+        if ('compensate' in node && node.compensate === false) {
+            configParts.push('compensate: false');
+        }
         if ('options' in node && node.options) {
             const { retries, retryDelay } = node.options;
             if (retries !== undefined) {

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, isScenarioExpectationCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, isScenarioExpectationCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowMilestoneCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
 /**
@@ -518,6 +518,9 @@ function extractExpressionStatement(statement, context) {
         if (isWorkflowSuspendCall(call, context.checker)) {
             return extractSuspendStep(call, context);
         }
+        if (isWorkflowMilestoneCall(call, context.checker)) {
+            return extractMilestoneStep(call, context);
+        }
         if (isWorkflowApprovalCall(call, context.checker)) {
             const step = extractApprovalStep(call, context, outputVar);
             // Unlike suspend, an approval yields a value, so a downstream step can
@@ -696,13 +699,13 @@ function extractStepOptions(optionsNode, context) {
                     // Ignore extraction errors for retryDelay
                 }
             }
-            else if (propName === 'onError') {
-                if (ts.isStringLiteral(prop.initializer)) {
-                    options.onError = prop.initializer.text;
+            else if (propName === 'compensate') {
+                if (prop.initializer.kind === ts.SyntaxKind.FalseKeyword) {
+                    options.compensate = false;
                 }
                 else {
                     context.errors.push({
-                        message: 'onError must be a literal RPC name so it can be wired and drawn in the graph.',
+                        message: "compensate on a call site can only be `false`: a step's compensation is declared on the function itself.",
                         node: prop.initializer,
                     });
                 }
@@ -786,6 +789,27 @@ function extractSuspendStep(call, context) {
         return null;
     }
 }
+/**
+ * Extract milestone step from workflow.milestone() call
+ */
+function extractMilestoneStep(call, context) {
+    const args = call.arguments;
+    if (args.length < 1)
+        return null;
+    try {
+        return {
+            type: 'milestone',
+            name: extractStringLiteral(args[0], context.checker),
+        };
+    }
+    catch (error) {
+        context.errors.push({
+            message: `Failed to extract milestone step: ${error instanceof Error ? error.message : String(error)}`,
+            node: call,
+        });
+        return null;
+    }
+}
 /**
  * Extract approval step from workflow.approval() call
  */
@@ -1146,6 +1170,13 @@ function extractFanoutBodyStep(stmt, childContext, body) {
             }
             return;
         }
+        if (isWorkflowMilestoneCall(call, childContext.checker)) {
+            const milestoneStep = extractMilestoneStep(call, childContext);
+            if (milestoneStep) {
+                body.push(milestoneStep);
+            }
+            return;
+        }
         if (isScenarioStepCall(call)) {
             const scenarioStep = extractScenarioStep(call, childContext);
             if (scenarioStep) {

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -57,6 +57,10 @@ export declare function isWorkflowSleepCall(node: ts.CallExpression, checker: ts
  * Check if a call expression is workflow.suspend()
  */
 export declare function isWorkflowSuspendCall(node: ts.CallExpression, _checker: ts.TypeChecker): boolean;
+/**
+ * Check if a call expression is workflow.milestone()
+ */
+export declare function isWorkflowMilestoneCall(node: ts.CallExpression, _checker: ts.TypeChecker): boolean;
 /**
  * Check if a call expression is workflow.approval()
  */

package/dist/utils/workflow/dsl/patterns.js

@@ -133,6 +133,17 @@ export function isWorkflowSuspendCall(node, _checker) {
     return (propAccess.name.text === 'suspend' &&
         isWorkflowWireIdentifier(propAccess.expression));
 }
+/**
+ * Check if a call expression is workflow.milestone()
+ */
+export function isWorkflowMilestoneCall(node, _checker) {
+    if (!ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const propAccess = node.expression;
+    return (propAccess.name.text === 'milestone' &&
+        isWorkflowWireIdentifier(propAccess.expression));
+}
 /**
  * Check if a call expression is workflow.approval()
  */

package/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -85,21 +85,9 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                     retries: step.options.retries,
                     retryDelay: step.options.retryDelay,
                 };
-            }
-            // An onError handler is written as an rpc name, but the graph routes to
-            // node ids — materialise a node for it so the console has something to
-            // draw the error edge to, exactly as in a hand-authored graph.
-            if (step.options?.onError) {
-                const handlerId = `${nodeId}_onError`;
-                node.onError = handlerId;
-                return [
-                    node,
-                    {
-                        nodeId: handlerId,
-                        rpcName: step.options.onError,
-                        stepName: `${step.stepName} (on error)`,
-                    },
-                ];
+                if (step.options.compensate === false) {
+                    node.compensate = false;
+                }
             }
             return [node];
         }
@@ -161,6 +149,15 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
             };
             return [node];
         }
+        case 'milestone': {
+            const node = {
+                nodeId,
+                flow: 'milestone',
+                reason: step.name,
+                next: nextNodeId,
+            };
+            return [node];
+        }
         case 'approval': {
             // Unlike `suspend` — which has no output and so is deliberately absent
             // from the graph — an approval yields a value a later step can reference,

package/dist/utils/workflow/graph/serialize-workflow-graph.d.ts

@@ -18,7 +18,8 @@ export declare function serializeWorkflowGraph(definition: {
         } | ((ref: any) => unknown);
         mode?: 'parallel' | 'sequential';
         next?: string | string[] | Record<string, string | string[]>;
-        onError?: string | string[];
+        recover?: string | string[] | 'ignore';
+        compensate?: false;
         notes?: string;
     }>;
 }, options?: {
@@ -36,7 +37,8 @@ export declare function deserializeWorkflowGraph(serialized: SerializedWorkflowG
         rpcName: string;
         input: Record<string, unknown | DataRef>;
         next?: SerializedNext;
-        onError?: string | string[];
+        recover?: string | string[] | 'ignore';
+        compensate?: false;
     }>;
     entryNodeIds: string[];
 };

package/dist/utils/workflow/graph/serialize-workflow-graph.js

@@ -115,7 +115,8 @@ export function serializeWorkflowGraph(definition, options) {
             rpcName,
             input,
             next: serializeNext(node.next),
-            onError: node.onError,
+            recover: node.recover,
+            compensate: node.compensate,
         };
         const forEach = serializeForEach(node.forEach, createRef);
         if (forEach) {
@@ -158,7 +159,8 @@ export function deserializeWorkflowGraph(serialized) {
                 rpcName: funcNode.rpcName,
                 input: funcNode.input ?? {},
                 next: funcNode.next,
-                onError: funcNode.onError,
+                recover: funcNode.recover,
+                compensate: funcNode.compensate,
             };
         }
     }

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -66,7 +66,7 @@ export interface NodeOptions {
 /**
  * Flow node types for control flow (no RPC call)
  */
-export type FlowType = 'sleep' | 'suspend' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
+export type FlowType = 'sleep' | 'suspend' | 'milestone' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
 import type { ContextVariable, WorkflowContext, WorkflowPlannedStep } from '@pikku/core/workflow';
 import type { ScenarioStepPhase } from '@pikku/core/scenario';
 export type { ContextVariable, WorkflowContext };
@@ -80,8 +80,10 @@ interface BaseNode {
     stepName?: string;
     /** Next node(s) - simple, parallel, or conditional */
     next?: SerializedNext;
-    /** Error routing - node(s) to execute on error */
-    onError?: string | string[];
+    /** What to do when this node fails: run these nodes, or 'ignore' to carry on. */
+    recover?: string | string[] | 'ignore';
+    /** Leave this node out of the saga unwind. */
+    compensate?: false;
     /** Execution options */
     options?: NodeOptions;
     /** Free-text node documentation. Non-semantic — excluded from graphHash. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.96",
+  "version": "0.12.99",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -54,10 +54,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.130"
+    "@pikku/core": "^0.12.135"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.130",
+    "@pikku/core": "^0.12.135",
     "@types/node": "^24.13.3"
   },
   "engines": {