@pikku/core 0.12.69 → 0.12.70

package/dist/wirings/actor-flow/run-conversation.js

@@ -1,5 +1,5 @@
-/** One turn the persona takes: the message to send and whether it's finished. */
-const PERSONA_TURN_SCHEMA = {
+/** One turn the actor takes: the message to send and whether it's finished. */
+const ACTOR_TURN_SCHEMA = {
     type: 'object',
     properties: {
         message: { type: 'string' },
@@ -7,7 +7,7 @@ const PERSONA_TURN_SCHEMA = {
     },
     required: ['message', 'done'],
 };
-/** The persona's approve/deny decision for each pending tool request. */
+/** The actor's approve/deny decision for each pending tool request. */
 const APPROVAL_DECISION_SCHEMA = {
     type: 'object',
     properties: {
@@ -26,7 +26,7 @@ const APPROVAL_DECISION_SCHEMA = {
     },
     required: ['decisions'],
 };
-/** The persona's final verdict on whether the task was accomplished. */
+/** The actor's final verdict on whether the task was accomplished. */
 const EVALUATION_SCHEMA = {
     type: 'object',
     properties: {
@@ -60,13 +60,13 @@ function readObject(result) {
     }
     return null;
 }
-function personaInstructions(persona, task) {
+function actorInstructions(actor, task) {
     return [
         `You are role-playing a real user interacting with an AI assistant. Stay in character at all times — you are the user, not the assistant.`,
-        persona.name ? `Your name is ${persona.name}.` : '',
-        persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
-        persona.personality
-            ? `Your personality and communication style: ${persona.personality}. Match this tone, vocabulary, and level of detail exactly.`
+        actor.name ? `Your name is ${actor.name}.` : '',
+        actor.jobTitle ? `Your role: ${actor.jobTitle}.` : '',
+        actor.personality
+            ? `Your personality and communication style: ${actor.personality}. Match this tone, vocabulary, and level of detail exactly.`
             : '',
         `Your goal in this conversation: ${task}.`,
         `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
@@ -74,7 +74,7 @@ function personaInstructions(persona, task) {
         .filter(Boolean)
         .join('\n');
 }
-/** Route the target agent's pending tool approvals through the persona. */
+/** Route the target agent's pending tool approvals through the actor. */
 async function decideApprovals(params, instructions, pending) {
     const policy = params.approvals ?? 'in-persona';
     if (policy === 'always') {
@@ -88,7 +88,7 @@ async function decideApprovals(params, instructions, pending) {
         .join('\n');
     const result = await params.llm({
         model: params.model,
-        instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this persona, would allow each one.`,
+        instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this actor, would allow each one.`,
         messages: [
             msg('user', `The assistant wants to run these tools:\n${summary}\nApprove or deny each toolCallId.`),
         ],
@@ -104,7 +104,7 @@ async function decideApprovals(params, instructions, pending) {
         return { toolCallId: p.toolCallId, approved: match?.approved ?? false };
     });
 }
-/** Drive the target to a non-suspended reply, routing approvals to the persona. */
+/** Drive the target to a non-suspended reply, routing approvals to the actor. */
 async function converseWithTarget(params, instructions, message) {
     const maxRounds = params.maxApprovalRounds ?? DEFAULT_MAX_APPROVAL_ROUNDS;
     let reply = await params.target.run(message);
@@ -122,40 +122,40 @@ async function converseWithTarget(params, instructions, message) {
     return reply;
 }
 /**
- * Run a conversation: an LLM-driven persona holds a real multi-turn exchange
+ * Run a conversation: an LLM-driven actor holds a real multi-turn exchange
  * with a target agent (driven via the injected transport), answers the target's
  * tool-approval requests in-persona, then evaluates whether the task was met.
  * Deterministic checks are the caller's responsibility.
  */
 export async function runConversation(params) {
     const maxTurns = params.maxTurns ?? DEFAULT_MAX_TURNS;
-    const instructions = personaInstructions(params.persona, params.task);
-    // Seed a kickoff so the very first persona turn has a non-empty message list
-    // (providers reject an empty prompt). It's an instruction TO the persona, so
+    const instructions = actorInstructions(params.actor, params.task);
+    // Seed a kickoff so the very first actor turn has a non-empty message list
+    // (providers reject an empty prompt). It's an instruction TO the actor, so
     // it never appears in the transcript.
-    const personaMessages = [
+    const actorMessages = [
         msg('user', 'Begin the conversation now — send your first message to the assistant to work towards your goal.'),
     ];
     const transcript = [];
     for (let turn = 0; turn < maxTurns; turn++) {
-        const personaResult = await params.llm({
+        const actorResult = await params.llm({
             model: params.model,
             instructions,
-            messages: personaMessages,
+            messages: actorMessages,
             tools: [],
             maxSteps: 1,
             toolChoice: 'none',
-            outputSchema: PERSONA_TURN_SCHEMA,
+            outputSchema: ACTOR_TURN_SCHEMA,
         });
-        const turnData = readObject(personaResult);
-        const personaMessage = turnData?.message?.trim();
-        if (!personaMessage) {
+        const turnData = readObject(actorResult);
+        const actorMessage = turnData?.message?.trim();
+        if (!actorMessage) {
             break;
         }
-        personaMessages.push(msg('assistant', personaMessage));
-        transcript.push(`${params.personaName}: ${personaMessage}`);
-        const reply = await converseWithTarget(params, instructions, personaMessage);
-        personaMessages.push(msg('user', reply.text ?? ''));
+        actorMessages.push(msg('assistant', actorMessage));
+        transcript.push(`${params.actorName}: ${actorMessage}`);
+        const reply = await converseWithTarget(params, instructions, actorMessage);
+        actorMessages.push(msg('user', reply.text ?? ''));
         transcript.push(`${params.agentName}: ${reply.text ?? ''}`);
         if (turnData?.done) {
             break;

package/dist/wirings/cli/command-parser.js

@@ -150,8 +150,18 @@ export function parseCLIArguments(args, programName, allMeta) {
         const arg = args[currentIndex];
         if (arg.startsWith('--')) {
             // Long option (--from-plan → fromPlan)
+            const negatedKey = arg.startsWith('--no-')
+                ? toCamelCase(arg.slice(5))
+                : undefined;
             const equalIndex = arg.indexOf('=');
-            if (equalIndex > 0) {
+            if (negatedKey &&
+                typeof availableOptions[negatedKey]?.default === 'boolean') {
+                // --no-<flag> turns a boolean option off. Only options that declare a
+                // boolean default can be negated, so a literal `--no-something` option
+                // name still parses as itself.
+                optionArgs[negatedKey] = false;
+            }
+            else if (equalIndex > 0) {
                 // --option=value format
                 const key = toCamelCase(arg.slice(2, equalIndex));
                 const optionDef = availableOptions[key];

package/dist/wirings/rpc/rpc-runner.js

@@ -129,7 +129,7 @@ export class ContextAwareRPCService {
         if (!functionMeta) {
             throw new RPCNotFoundError(funcName);
         }
-        if (!functionMeta.expose) {
+        if (!functionMeta.expose || functionMeta.scenarioStep) {
             throw new RPCNotFoundError(funcName);
         }
         return await this.rpc(funcName, data);

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -5,6 +5,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { WorkflowRun } from '../workflow.types.js';
 import type { ScenarioActor } from '../../../services/scenario-actors-service.js';
+import type { ScenarioStepOptions, ScenarioStepPhase } from '../scenario-step.types.js';
 /**
  * Workflow step options
  */
@@ -60,6 +61,13 @@ export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(stepName: string,
  * Type signature for workflow.do() inline form - used by inspector
  */
 export type WorkflowWireDoInline = <T>(stepName: string, fn: () => Promise<T> | T, options?: WorkflowStepOptions) => Promise<T>;
+/**
+ * Type signature for scenario.step/given/when/then - used by inspector.
+ *
+ * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
+ * an imported symbol, so the extractor reads it as a literal.
+ */
+export type ScenarioStepInvocation = <TOutput = any, TInput = any>(stepName: string, stepFunc: string, data?: TInput, options?: ScenarioStepOptions) => Promise<TOutput>;
 /**
  * Type signature for workflow.sleep() - used by inspector
  */
@@ -172,6 +180,33 @@ export interface RpcStepMeta {
     /** True for workflow.expectEventually polling steps */
     expectEventually?: boolean;
 }
+/**
+ * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ *
+ * Distinct from RpcStepMeta on purpose: a step runs locally through
+ * runPikkuFunc and must never be treated as dispatchable on the queue/replay
+ * path, nor registered as a callable RPC (a browser-driving step must not be
+ * network-invocable).
+ */
+export interface ScenarioStepMeta {
+    type: 'scenarioStep';
+    /** Cache key (first argument), ordinal-suffixed by the engine when repeated */
+    stepName: string;
+    /** Registered name of the step function being run */
+    stepFunc: string;
+    /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+    phase: ScenarioStepPhase;
+    /** Output variable name (if assigned) */
+    outputVar?: string;
+    /** Input source mappings, or 'passthrough' when entire data is passed */
+    inputs?: Record<string, InputSource> | 'passthrough';
+    /** Step options */
+    options?: WorkflowStepOptions;
+    /** Scenario actor name this step runs as ({ actor: actors.x }) */
+    actor?: string;
+    /** Mirrors the step function's `browser: true` declaration */
+    browser?: boolean;
+}
 /**
  * Simple condition expression (leaf node)
  */
@@ -214,7 +249,7 @@ export interface BranchStepMeta {
 export interface ParallelGroupStepMeta {
     type: 'parallel';
     /** Child steps to execute in parallel */
-    children: RpcStepMeta[];
+    children: Array<RpcStepMeta | ScenarioStepMeta>;
 }
 /**
  * Fanout step metadata (parallel or sequential iteration)
@@ -234,7 +269,7 @@ export interface FanoutStepMeta {
     /** Execution mode */
     mode: 'parallel' | 'sequential';
     /** Steps to execute inline per iteration, in order */
-    body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>;
+    body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta | ScenarioStepMeta>;
     /** Time between iterations (sequential mode only) */
     timeBetween?: string;
 }
@@ -385,7 +420,7 @@ export interface ArrayPredicateStepMeta {
 /**
  * Workflow step metadata (extracted by inspector)
  */
-export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | ApprovalStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
+export type WorkflowStepMeta = RpcStepMeta | ScenarioStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | ApprovalStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
 /**
  * Workflow step wire context for RPC functions
  * Provides step-level metadata including retry attempt tracking
@@ -448,5 +483,19 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     expectError: <TInput = any>(stepName: string, rpcName: string, data: TInput, options?: WorkflowExpectErrorOptions) => Promise<string>;
     /** Stub-assertion step: asserts `service.method` was called on the target server */
     expectService: (stepName: string, serviceMethod: string, options?: WorkflowExpectServiceOptions) => Promise<void>;
+    /**
+     * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
+     * `(stepName, target, data, options)` — so the inspector reads the target as
+     * a string literal rather than resolving an imported symbol.
+     *
+     * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
+     */
+    step(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
+    /** `step` with a "Given" prefix in the rendered prose */
+    given(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
+    /** `step` with a "When" prefix in the rendered prose */
+    when(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
+    /** `step` with a "Then" prefix in the rendered prose */
+    then(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
     runScheduledTask: (name: string) => Promise<unknown>;
 }

package/dist/wirings/workflow/feature.d.ts

@@ -0,0 +1,28 @@
+import type { CoreFeature, CoreWorkflow, FeaturePlanEntry } from './workflow.types.js';
+/**
+ * Register a feature under the name it is exported as. Called from generated
+ * wiring, the same way `addWorkflow` is.
+ */
+export declare const addFeature: (featureId: string, feature: CoreFeature, packageName?: string | null) => void;
+/**
+ * Resolve every feature's scenario references back to the names their
+ * scenarios are registered under.
+ *
+ * Matching is by **object identity**: `pikkuScenario` returns its config
+ * verbatim and `addWorkflow` registers that same object, so a feature holding
+ * the imported identifier holds the very object that was registered. Nothing
+ * is matched by shape, by name, or by any other guess — which is also why a
+ * scenario built inline inside a feature (and therefore never registered)
+ * comes back as unresolved rather than silently running as something else.
+ *
+ * Entries are returned in declaration order, features in registration order.
+ * A scenario's effective tags are its own plus the containing feature's, so
+ * `--tags credential` selects through the feature.
+ */
+export declare const resolveFeatureScenarios: (features: Map<string, CoreFeature>, registrations: Map<string, CoreWorkflow>) => {
+    entries: FeaturePlanEntry[];
+    unresolved: Array<{
+        featureId: string;
+        index: number;
+    }>;
+};

package/dist/wirings/workflow/feature.js

@@ -0,0 +1,57 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Register a feature under the name it is exported as. Called from generated
+ * wiring, the same way `addWorkflow` is.
+ */
+export const addFeature = (featureId, feature, packageName = null) => {
+    pikkuState(packageName, 'workflows', 'features').set(featureId, feature);
+};
+/**
+ * Resolve every feature's scenario references back to the names their
+ * scenarios are registered under.
+ *
+ * Matching is by **object identity**: `pikkuScenario` returns its config
+ * verbatim and `addWorkflow` registers that same object, so a feature holding
+ * the imported identifier holds the very object that was registered. Nothing
+ * is matched by shape, by name, or by any other guess — which is also why a
+ * scenario built inline inside a feature (and therefore never registered)
+ * comes back as unresolved rather than silently running as something else.
+ *
+ * Entries are returned in declaration order, features in registration order.
+ * A scenario's effective tags are its own plus the containing feature's, so
+ * `--tags credential` selects through the feature.
+ */
+export const resolveFeatureScenarios = (features, registrations) => {
+    const nameByConfig = new Map();
+    for (const [name, registration] of registrations) {
+        nameByConfig.set(registration.func, name);
+    }
+    const entries = [];
+    const unresolved = [];
+    for (const [featureId, feature] of features) {
+        const scenarios = feature.scenarios ?? [];
+        for (let index = 0; index < scenarios.length; index++) {
+            const entry = scenarios[index];
+            const paired = typeof entry === 'object' && entry !== null && 'scenario' in entry;
+            const config = paired ? entry.scenario : entry;
+            const scenarioName = nameByConfig.get(config);
+            if (!scenarioName) {
+                unresolved.push({ featureId, index });
+                continue;
+            }
+            entries.push({
+                featureId,
+                featureName: feature.name ?? featureId,
+                scenarioName,
+                data: paired ? entry.data : undefined,
+                tags: [
+                    ...new Set([
+                        ...(registrations.get(scenarioName)?.func?.tags ?? []),
+                        ...(feature.tags ?? []),
+                    ]),
+                ],
+            });
+        }
+    }
+    return { entries, unresolved };
+};

package/dist/wirings/workflow/index.d.ts

@@ -2,14 +2,25 @@
  * Workflow module exports
  */
 export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension, } from './pikku-workflow-service.js';
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 export type { RunTimeline, RunTimelineEvent, ReconstructedRunState, ReconstructedStep, RunPhase, } from './run-timeline.js';
 export { addWorkflow } from './dsl/workflow-runner.js';
+export { addFeature, resolveFeatureScenarios } from './feature.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
 export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, CoreFeature, CoreFeatureScenario, FeatureMeta, FeatureMetaEntry, FeaturesMeta, FeaturePlanEntry, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
+export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, } from './scenario-step.types.js';
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+export { pollUntil, type PollOptions } from './scenario-poll.js';
+export { createCookieJar } from './scenario-cookie-jar.js';
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js';
+export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/scenario-actors-service.js';
+export { readScenarioHttpResponse, postScenarioJson, } from '../../services/scenario-actors-service.js';
+export type { PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

package/dist/wirings/workflow/index.js

@@ -7,6 +7,7 @@ export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 // Internal registration functions (used by generated code)
 export { addWorkflow } from './dsl/workflow-runner.js';
+export { addFeature, resolveFeatureScenarios } from './feature.js';
 // Graph helpers (template, pikkuWorkflowGraph)
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
@@ -14,3 +15,17 @@ export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
 export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 // Queue worker functions (registered by codegen, executed at runtime)
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
+// Narrows the optional halves of the step wire, with a message that says what to do
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+// Waits for the target to catch up, without every step writing the loop again
+export { pollUntil } from './scenario-poll.js';
+// Persists cookies across a step's requests, the way a browser would
+export { createCookieJar } from './scenario-cookie-jar.js';
+export { readScenarioHttpResponse, postScenarioJson, } from '../../services/scenario-actors-service.js';
+/* ------------------------------------------------------------------ *
+ * Scenarios — reporting a run
+ *
+ * Used by the CLI reporter and the console, so the two render the same
+ * sentence for the same step. A step body needs none of it.
+ * ------------------------------------------------------------------ */
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

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

@@ -0,0 +1,121 @@
+import { PikkuError } from '../../errors/error-handler.js';
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
+import { type RunLifecycleContext, type WorkflowRunEngine, type WorkflowRunExtension } from './pikku-workflow-service.js';
+import type { PikkuWire } from '../../types/core.types.js';
+import type { ScenarioActors } from '../../services/scenario-actors-service.js';
+import type { ScenarioBrowserProvider, ScenarioEnvironment } from './scenario-step.types.js';
+import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.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 declare const createScenarioRunner: (options?: WorkflowQueueOptions) => {
+    workflowService: InMemoryWorkflowService;
+    scenarioService: PikkuScenarioService;
+};
+/**
+ * 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 declare class ScenarioHookError extends PikkuError {
+    readonly scenarioName: string;
+    readonly phase: 'before' | 'after';
+    constructor(scenarioName: string, phase: 'before' | 'after', cause: unknown);
+}
+/**
+ * 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 declare class PikkuScenarioService implements WorkflowRunExtension {
+    private readonly engine;
+    private runActors;
+    private scenarioBrowserProvider?;
+    private scenarioEnvironment?;
+    constructor(engine: WorkflowRunEngine);
+    /**
+     * 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: ScenarioBrowserProvider | undefined): void;
+    getScenarioBrowserProvider(): ScenarioBrowserProvider | undefined;
+    /**
+     * 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: ScenarioEnvironment | undefined): void;
+    getScenarioEnvironment(): ScenarioEnvironment | undefined;
+    attachRunContext(runId: string, workflowMeta: any, options?: {
+        actors?: ScenarioActors;
+    }): Promise<void>;
+    detachRunContext(runId: string): void;
+    decorateRunWire(wire: PikkuWire, context: {
+        runId: string;
+        workflowMeta: any;
+        workflowWire: PikkuWorkflowWire;
+    }): void;
+    onBeforeRunFunc(context: RunLifecycleContext): Promise<void>;
+    onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
+    /**
+     * 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.
+     */
+    private scenarioHooks;
+    /**
+     * 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.
+     */
+    private runScenarioHook;
+    /**
+     * 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.
+     */
+    resolveScenarioActors(): Promise<ScenarioActors | undefined>;
+    decorateWorkflowWire(wire: PikkuWorkflowWire, context: {
+        name: string;
+        runId: string;
+        rpcService: any;
+        addonNamespace?: string | null;
+    }): void;
+    private scenarioStep;
+    private scenarioStepConfig;
+    private scenarioStepDescription;
+    private requiresBrowser;
+}