@pikku/core 0.12.69 → 0.12.70

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -0,0 +1,419 @@
+import { runPikkuFunc } from '../../function/function-runner.js';
+import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
+import { getDurationInMilliseconds } from '../../time-utils.js';
+import { closeWireServices } from '../../utils.js';
+import { PikkuError, addError } from '../../errors/error-handler.js';
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
+import { runScheduledTask } from '../scheduler/scheduler-runner.js';
+import { WorkflowStepNameNotString, } from './pikku-workflow-service.js';
+/**
+ * A workflow service with the scenario capability attached — the two lines
+ * `pikku scenario run` needs, in one call so no caller has to remember that the
+ * capability is installed rather than inherited.
+ *
+ * The in-memory service is the right engine because a scenario run is a single
+ * external process driving a deployed app over its real transport: there is
+ * nothing to persist and no second worker to resume it.
+ */
+export const createScenarioRunner = (options = {}) => {
+    const workflowService = new InMemoryWorkflowService(options);
+    const scenarioService = workflowService.setRunExtension((engine) => new PikkuScenarioService(engine));
+    return { workflowService, scenarioService };
+};
+/**
+ * A scenario's `before` or `after` hook threw. The original error is kept as
+ * the `cause` so the failure that actually happened is never lost behind the
+ * label saying which phase it happened in.
+ */
+export class ScenarioHookError extends PikkuError {
+    scenarioName;
+    phase;
+    constructor(scenarioName, phase, cause) {
+        super(`Scenario '${scenarioName}' ${phase} hook failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.scenarioName = scenarioName;
+        this.phase = phase;
+        this.cause = cause;
+    }
+}
+addError(ScenarioHookError, {
+    status: 500,
+    message: 'A scenario lifecycle hook failed.',
+});
+/**
+ * The scenario capability, layered onto a workflow service rather than being
+ * one.
+ *
+ * Every scenario affordance — steps, actors, lifecycle hooks, the browser
+ * provider, the assertion wire members — lives here rather than on
+ * `PikkuWorkflowService`, because a bundler drops an unused *module* but never
+ * an unused class member: anything declared on the workflow service ships in
+ * every server built on Pikku, along with everything it imports. Scenarios only
+ * ever run from `pikku scenario run`, so the whole surface stays behind an
+ * import only that runner makes.
+ *
+ * It is not a workflow service because a scenario is not a different kind of
+ * run — it is the same durable run with a step vocabulary on top. What it
+ * needs from the engine it gets through the narrow `WorkflowRunEngine` handle,
+ * which is why recording a step never became public API.
+ *
+ * ```ts
+ * const workflowService = new InMemoryWorkflowService()
+ * const scenarioService = workflowService.setRunExtension(
+ *   (engine) => new PikkuScenarioService(engine)
+ * )
+ * ```
+ */
+export class PikkuScenarioService {
+    engine;
+    // Scenario actors per run: live authenticated clients (cookie jars) are
+    // process-local by nature, so they ride this map, never the persisted wire.
+    runActors = new Map();
+    scenarioBrowserProvider;
+    scenarioEnvironment;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    /**
+     * Registered by `@pikku/playwright` (or any other driver) before a scenario
+     * runs. Absent means browser steps cannot run, which the CLI checks up front
+     * so a run fails fast rather than mid-flow.
+     */
+    setScenarioBrowserProvider(provider) {
+        this.scenarioBrowserProvider = provider;
+    }
+    getScenarioBrowserProvider() {
+        return this.scenarioBrowserProvider;
+    }
+    /**
+     * The environment scenario steps run against, set once by the runner. It is
+     * per-service rather than per-run because a runner process targets exactly
+     * one environment for every scenario it executes.
+     */
+    setScenarioEnvironment(env) {
+        this.scenarioEnvironment = env;
+    }
+    getScenarioEnvironment() {
+        return this.scenarioEnvironment;
+    }
+    async attachRunContext(runId, workflowMeta, options) {
+        const actors = options?.actors ??
+            (workflowMeta.source === 'scenario'
+                ? await this.resolveScenarioActors()
+                : undefined);
+        if (actors) {
+            this.runActors.set(runId, actors);
+        }
+    }
+    detachRunContext(runId) {
+        this.runActors.delete(runId);
+    }
+    decorateRunWire(wire, context) {
+        wire.scenario =
+            context.workflowMeta?.source === 'scenario'
+                ? context.workflowWire
+                : undefined;
+        wire.actors = this.runActors.get(context.runId);
+    }
+    async onBeforeRunFunc(context) {
+        const hooks = this.scenarioHooks(context);
+        if (!hooks?.before)
+            return;
+        await this.runScenarioHook('before', context.workflowMeta.name, hooks.before, context.wire, context.run.input, context.packageName);
+    }
+    async onAfterRunFunc(context, outcome, failure) {
+        if (outcome === 'interrupted')
+            return;
+        const hooks = this.scenarioHooks(context);
+        if (!hooks?.after)
+            return;
+        const { runId, run, workflowMeta } = context;
+        try {
+            await this.runScenarioHook('after', workflowMeta.name, hooks.after, context.wire, run.input, context.packageName);
+        }
+        catch (hookError) {
+            if (outcome === 'failed') {
+                // The scenario already failed for its own reason; a teardown failure is
+                // diagnostic context, never the headline.
+                if (failure instanceof Error && failure.cause === undefined) {
+                    failure.cause = hookError;
+                }
+                getSingletonServices()?.logger.error(`Scenario ${workflowMeta.name} (run ${runId}) failed, and its after hook also failed:`, hookError);
+            }
+            else {
+                await this.engine.updateRunStatus(runId, 'failed', undefined, {
+                    message: hookError.message,
+                    stack: hookError.stack,
+                    code: hookError.code,
+                });
+                await this.engine.onChildWorkflowFailed(run, hookError);
+                throw hookError;
+            }
+        }
+    }
+    /**
+     * Hooks are a scenario affordance only: a plain workflow is durable and
+     * resumable, so a callback that reruns on every replay has no honest meaning
+     * there.
+     */
+    scenarioHooks(context) {
+        return context.workflowMeta.source === 'scenario'
+            ? context.workflow.func
+            : undefined;
+    }
+    /**
+     * Run a scenario `before`/`after` hook.
+     *
+     * A hook is not a pikku function: it has no id, no meta and no schema, so it
+     * cannot go through `runPikkuFunc` and the runner records nothing for it. It
+     * gets exactly what the scenario body gets — the same wire (so `actors` is
+     * how it reaches the app), and singleton services composed with this
+     * invocation's wire services — and nothing else.
+     */
+    async runScenarioHook(phase, scenarioName, hook, wire, data, packageName) {
+        const singletonServices = getSingletonServices();
+        let createWireServices = getCreateWireServices();
+        if (packageName) {
+            const factories = pikkuState(packageName, 'package', 'factories');
+            if (factories?.createWireServices) {
+                createWireServices = factories.createWireServices;
+            }
+        }
+        let wireServices;
+        try {
+            wireServices = (await createWireServices?.(singletonServices, wire));
+            const services = wireServices && Object.keys(wireServices).length > 0
+                ? { ...singletonServices, ...wireServices }
+                : singletonServices;
+            await hook(services, data, wire);
+        }
+        catch (error) {
+            throw new ScenarioHookError(scenarioName, phase, error);
+        }
+        finally {
+            if (wireServices && Object.keys(wireServices).length > 0) {
+                await closeWireServices(singletonServices.logger, wireServices);
+            }
+        }
+    }
+    /**
+     * Build HTTP scenario actors for a run started without them; undefined when
+     * SCENARIO_ACTOR_SECRET or the API URL is missing.
+     *
+     * The actor client is imported lazily so that even a runner bundle only pays
+     * for the AI persona conversation loop it pulls in when a scenario actually
+     * signs an actor in.
+     */
+    async resolveScenarioActors() {
+        const services = getSingletonServices();
+        const variables = services?.variables;
+        const metaService = services?.metaService;
+        if (!variables || !metaService) {
+            return undefined;
+        }
+        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
+        const apiUrl = await variables.get('API_URL');
+        if (!secret || !apiUrl) {
+            services?.logger?.warn('A scenario was started without actors but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without actors.');
+            return undefined;
+        }
+        const actorsConfig = await metaService.getScenarioActorsMeta();
+        if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
+            return undefined;
+        }
+        const signInPath = (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
+            '/api/auth/sign-in/actor';
+        const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc';
+        // A run started outside the CLI still targets an environment — its own.
+        this.scenarioEnvironment ??= {
+            apiUrl,
+            appUrl: (await variables.get('APP_URL')) ?? undefined,
+        };
+        const { createHttpScenarioActors } = await import('../../services/http-scenario-actors.js');
+        return createHttpScenarioActors({
+            apiUrl,
+            secret,
+            actors: actorsConfig,
+            signInPath,
+            rpcPath,
+        });
+    }
+    decorateWorkflowWire(wire, context) {
+        const { name, runId, rpcService, addonNamespace } = context;
+        const workflowWire = wire;
+        const scenarioStepContext = () => ({
+            runId,
+            workflowName: name,
+            addonNamespace,
+            workflowWire,
+            rpcService,
+        });
+        Object.assign(workflowWire, {
+            // Durable polling step: invoke an RPC (as an actor when options.as is
+            // set) until the predicate passes or `within` elapses. The whole poll is
+            // ONE recorded step, so replay returns the cached outcome.
+            expectEventually: async (stepName, rpcName, data, predicate, options) => {
+                this.engine.verifyStepName(stepName);
+                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
+                    ? `${addonNamespace}:${rpcName}`
+                    : rpcName;
+                const within = getDurationInMilliseconds(options?.within ?? '30s');
+                const interval = getDurationInMilliseconds(options?.interval ?? '1s');
+                return await this.engine.inlineStep(runId, stepName, async () => {
+                    const deadline = Date.now() + within;
+                    let last;
+                    while (true) {
+                        last = options?.actor
+                            ? await options.actor.invoke(resolvedRpcName, data)
+                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
+                        if (predicate(last))
+                            return last;
+                        if (Date.now() + interval > deadline) {
+                            throw new Error(`[workflow] expectEventually '${stepName}' ('${resolvedRpcName}'` +
+                                `${options?.actor ? ` as '${options.actor.name}'` : ''}) did not pass within ${within}ms; ` +
+                                `last result: ${JSON.stringify(last)?.slice(0, 300)}`);
+                        }
+                        await new Promise((resolve) => setTimeout(resolve, interval));
+                    }
+                }, options);
+            },
+            expectError: async (stepName, rpcName, data, options) => {
+                this.engine.verifyStepName(stepName);
+                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
+                    ? `${addonNamespace}:${rpcName}`
+                    : rpcName;
+                return await this.engine.inlineStep(runId, stepName, async () => {
+                    let result;
+                    try {
+                        result = options?.actor
+                            ? await options.actor.invoke(resolvedRpcName, data)
+                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
+                    }
+                    catch (e) {
+                        const message = e?.message ?? String(e);
+                        if (options?.matches) {
+                            const matched = typeof options.matches === 'string'
+                                ? message.includes(options.matches)
+                                : options.matches.test(message);
+                            if (!matched) {
+                                throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`);
+                            }
+                        }
+                        return message;
+                    }
+                    throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`);
+                }, options);
+            },
+            expectService: async (stepName, serviceMethod, options) => {
+                this.engine.verifyStepName(stepName);
+                const [service, method] = serviceMethod.split('.');
+                if (!service || !method) {
+                    throw new Error(`[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`);
+                }
+                await this.engine.inlineStep(runId, stepName, async () => {
+                    const rpcName = 'pikkuScenarioGetStubCalls';
+                    const calls = options?.actor
+                        ? await options.actor.invoke(rpcName, { service })
+                        : await rpcService.rpcWithWire(rpcName, { service }, {});
+                    const matching = (calls ?? []).filter((c) => c.service === service &&
+                        c.method === method &&
+                        (options?.calledWith === undefined ||
+                            JSON.stringify(c.args?.[0]) ===
+                                JSON.stringify(options.calledWith)));
+                    const expected = options?.times;
+                    const ok = expected === undefined
+                        ? matching.length > 0
+                        : matching.length === expected;
+                    if (!ok) {
+                        const seen = (calls ?? [])
+                            .map((c) => `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`)
+                            .join('\n  ') || '(none)';
+                        throw new Error(`[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
+                            `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`);
+                    }
+                }, options);
+            },
+            // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
+            // `given`/`when`/`then` are pure sugar over `step` — the phase only
+            // changes the prose a reporter renders.
+            step: (stepName, stepFunc, data, options) => this.scenarioStep('step', scenarioStepContext(), stepName, stepFunc, data, options),
+            given: (stepName, stepFunc, data, options) => this.scenarioStep('given', scenarioStepContext(), stepName, stepFunc, data, options),
+            when: (stepName, stepFunc, data, options) => this.scenarioStep('when', scenarioStepContext(), stepName, stepFunc, data, options),
+            then: (stepName, stepFunc, data, options) => this.scenarioStep('then', scenarioStepContext(), stepName, stepFunc, data, options),
+            runScheduledTask: async (taskName) => {
+                await runScheduledTask({ name: taskName });
+            },
+        });
+    }
+    async scenarioStep(phase, context, stepName, stepFunc, data, options) {
+        const { runId, workflowName, addonNamespace, workflowWire, rpcService } = context;
+        // Also the guard for `then` being a wire member: an accidental
+        // `await scenario` calls it with a resolve function, which lands here as a
+        // loud, named error instead of a silent hang.
+        this.engine.verifyStepName(stepName);
+        if (typeof stepFunc !== 'string') {
+            throw new WorkflowStepNameNotString(stepFunc);
+        }
+        const packageName = addonNamespace && !stepFunc.includes(':') ? addonNamespace : null;
+        const resolvedStepFunc = addonNamespace && !stepFunc.includes(':')
+            ? `${addonNamespace}:${stepFunc}`
+            : stepFunc;
+        const actor = options?.actor;
+        const description = options?.description ??
+            this.scenarioStepDescription(packageName, resolvedStepFunc) ??
+            stepName;
+        return await this.engine.inlineStep(runId, stepName, async () => {
+            const wire = {
+                workflow: workflowWire,
+                scenario: workflowWire,
+                rpc: rpcService?.wire?.rpc,
+                session: rpcService?.wire?.session,
+                pikkuUserId: workflowWire.pikkuUserId,
+                actors: this.runActors.get(runId),
+                scenarioStep: {
+                    name: resolvedStepFunc,
+                    stepName,
+                    runId,
+                    phase,
+                    actor,
+                    env: this.scenarioEnvironment,
+                },
+            };
+            if (this.requiresBrowser(packageName, resolvedStepFunc)) {
+                if (!this.scenarioBrowserProvider) {
+                    throw new Error(`[scenario] step '${resolvedStepFunc}' declares 'browser: true' but no browser provider is registered. ` +
+                        `Install @pikku/playwright and register its provider, or run with --no-browser to skip browser steps.`);
+                }
+                if (!actor) {
+                    throw new Error(`[scenario] step '${resolvedStepFunc}' declares 'browser: true' but was called without an actor. ` +
+                        `Pass { actor: actors.<name> } so the browser signs in as that persona.`);
+                }
+                wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
+            }
+            return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
+                singletonServices: getSingletonServices(),
+                createWireServices: getCreateWireServices(),
+                data: () => data,
+                wire,
+                packageName: packageName ?? undefined,
+            });
+        }, {
+            description,
+            // Retrying a failed assertion is the wrong behaviour for a test
+            // primitive, so steps opt out of the workflow-wide retry default.
+            retries: options?.retries ?? 0,
+            retryDelay: options?.retryDelay,
+        }, data, resolvedStepFunc);
+    }
+    scenarioStepConfig(packageName, stepFunc) {
+        const localName = packageName && stepFunc.startsWith(`${packageName}:`)
+            ? stepFunc.slice(packageName.length + 1)
+            : stepFunc;
+        return pikkuState(packageName, 'function', 'functions').get(localName);
+    }
+    scenarioStepDescription(packageName, stepFunc) {
+        return this.scenarioStepConfig(packageName, stepFunc)?.description;
+    }
+    requiresBrowser(packageName, stepFunc) {
+        return this.scenarioStepConfig(packageName, stepFunc)?.browser === true;
+    }
+}

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,5 +1,5 @@
-import type { SerializedError } from '../../types/core.types.js';
-import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
+import type { PikkuWire, SerializedError } from '../../types/core.types.js';
+import type { ApprovalOutcome, CoreWorkflow, PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import type { ScenarioActors } from '../../services/scenario-actors-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
@@ -88,6 +88,72 @@ export declare class WorkflowServiceNotInitialized extends Error {
 export declare class WorkflowStepNameNotString extends Error {
     constructor(stepName: any);
 }
+/**
+ * Everything an extension needs to run something of its own around a run's
+ * function: the registration it was resolved from, the run itself (so `input`
+ * is the same object the function is called with), and the wire it is given.
+ */
+export interface RunLifecycleContext {
+    runId: string;
+    run: WorkflowRun;
+    workflowMeta: any;
+    workflow: CoreWorkflow;
+    wire: PikkuWire;
+    packageName: string | null;
+}
+/**
+ * The slice of the run engine an extension is allowed to drive, handed to it at
+ * construction. It exists so that recording a durable step stays available to
+ * an extension without `inlineStep` and friends becoming public API on every
+ * workflow service a production app instantiates.
+ */
+export interface WorkflowRunEngine {
+    inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, data?: any, funcName?: string): Promise<any>;
+    updateRunStatus(runId: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    onChildWorkflowFailed(run: WorkflowRun, error: unknown): Promise<void>;
+    verifyStepName(stepName: unknown): void;
+}
+/**
+ * A capability layered onto a run without being a workflow service itself.
+ *
+ * The engine names nothing about what an extension is for: a bundler drops an
+ * unused *module* but never an unused class member, so the alternative — a
+ * subclass carrying the capability — puts it in every server built on Pikku
+ * whether or not the app ever uses it. Scenarios are the one implementation
+ * today (`PikkuScenarioService` in `@pikku/core/scenario`).
+ */
+export interface WorkflowRunExtension {
+    /** Per-run state resolved once the run has an id. */
+    attachRunContext(runId: string, workflowMeta: any, options?: Record<string, any>): Promise<void>;
+    /** Release whatever `attachRunContext` stored. */
+    detachRunContext(runId: string): void;
+    /** Contribute extra members to the wire a run's function is invoked with. */
+    decorateRunWire(wire: PikkuWire, context: {
+        runId: string;
+        workflowMeta: any;
+        workflowWire: PikkuWorkflowWire;
+    }): void;
+    /** Contribute extra members to the workflow wire itself, in place. */
+    decorateWorkflowWire(workflowWire: PikkuWorkflowWire, context: {
+        name: string;
+        runId: string;
+        rpcService: any;
+        addonNamespace?: string | null;
+    }): void;
+    /**
+     * Called immediately before the run's function, inside the run lock. Throwing
+     * skips the function and fails the run.
+     */
+    onBeforeRunFunc(context: RunLifecycleContext): Promise<void>;
+    /**
+     * Called once the run reaches a terminal state, in a `finally`, so it runs
+     * whether the function passed or threw. `interrupted` means the run suspended
+     * or went async and is still mid-flight. Throwing here propagates, replacing
+     * a pending failure, so an extension that must not mask one handles that
+     * itself.
+     */
+    onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
+}
 /**
  * Abstract workflow state service
  * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
@@ -95,7 +161,7 @@ export declare class WorkflowStepNameNotString extends Error {
  */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private inlineRuns;
-    private runActors;
+    private runExtension?;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
     protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
@@ -179,7 +245,10 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * Creates pending step in both workflow_step and workflow_step_history
      * @param runId - Run ID
      * @param stepName - Step cache key
-     * @param rpcName - RPC function name
+     * @param rpcName - The name this step was dispatched by: an RPC for a
+     *   `workflow.do` step, a step function for a scenario step, null for a
+     *   closure. Nothing dispatches off this value — it is recorded so a reader
+     *   can join a step back to the function that ran it.
      * @param data - Step input data
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
@@ -382,18 +451,28 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      *   false to fall through to inline `setTimeout` behavior.
      */
     protected scheduleSleep(runId: string, stepId: string, duration: number | string): Promise<boolean>;
-    /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
-    private resolveScenarioActors;
+    /**
+     * Install the one extension a run may have, built from a handle onto the run
+     * engine so that `inlineStep` and friends stay protected rather than becoming
+     * public API. Returns the extension, so the caller keeps a typed reference to
+     * whatever it just built.
+     */
+    setRunExtension<T extends WorkflowRunExtension>(create: (engine: WorkflowRunEngine) => T): T;
+    getRunExtension(): WorkflowRunExtension | undefined;
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
      * @param options.inline - If true, execute workflow directly without queue service
      * @param options.startNode - Starting node ID for graph workflows (from wire config)
+     * @param options.onRunCreated - Called with the run id the moment the run exists.
+     * An inline run that fails throws instead of returning, so this is the only
+     * way a caller can still read that run back — its steps, and which one failed.
      */
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
         inline?: boolean;
         startNode?: string;
         actors?: ScenarioActors;
+        onRunCreated?: (runId: string) => void;
     }): Promise<{
         runId: string;
     }>;
@@ -416,7 +495,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     runWorkflowJob(runId: string, rpcService: any): Promise<void>;
     private runWorkflowJobInner;
     private onChildWorkflowCompleted;
-    private onChildWorkflowFailed;
+    protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
     private runVersionMismatchFallback;
     /**
      * Execute a single workflow step (called by worker)
@@ -455,7 +534,21 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     private runStepCompensation;
     private rpcStep;
-    private inlineStep;
+    protected inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, 
+    /**
+     * The input this step was called with, recorded on the run so a reporter can
+     * name the values under test. A closure step has none; a scenario step does.
+     */
+    data?: any, 
+    /**
+     * The name this step was dispatched by, for the kinds of inline step that
+     * have one. A closure step has no name; a scenario step is a step RPC, so
+     * it records the step function that ran — which is the only way to join a
+     * step back to its declaration when its durable name was built at runtime
+     * (a step called in a loop reaches the run as `sees @pikku/addon-todos`,
+     * declared as `sees ${packageName}`).
+     */
+    rpcName?: string | null): Promise<any>;
     private sleepStep;
     /**
      * Derive the durable step name for a suspend point from its `reason`, so each
@@ -507,8 +600,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
     private approvalStep;
-    createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuScenarioWire;
-    private verifyStepName;
+    createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuWorkflowWire;
+    protected verifyStepName(stepName: string): void;
     private getConfig;
     /**
      * Get the orchestrator queue name for a specific workflow.