@pikku/core 0.12.67 → 0.12.70

package/dist/wirings/actor-flow/run-conversation.d.ts

@@ -1,20 +1,20 @@
 import type { ActorFlowApprovalPolicy, ActorFlowVerdict, TargetAgentDriver } from './actor-flow.types.js';
 import type { ScenarioActorConfig } from '../../services/scenario-actors-service.js';
 import type { AIAgentRunnerParams, AIAgentStepResult } from '../../services/ai-agent-runner-service.js';
-/** The LLM call the persona uses for its own turns/decisions/evaluation. */
-export type PersonaLLM = (params: AIAgentRunnerParams) => Promise<AIAgentStepResult>;
+/** The LLM call the actor uses for its own turns/decisions/evaluation. */
+export type ActorLLM = (params: AIAgentRunnerParams) => Promise<AIAgentStepResult>;
 export interface RunConversationParams {
-    /** Persona config (personality/jobTitle/name) that shapes how the actor talks. */
-    persona: ScenarioActorConfig;
-    /** Stable persona name (for transcript labelling). */
-    personaName: string;
+    /** The actor's own config (personality/jobTitle/name), which shapes how it talks. */
+    actor: ScenarioActorConfig;
+    /** Stable actor name (for transcript labelling). */
+    actorName: string;
     /** What the actor is trying to get the target agent to accomplish. */
     task: string;
     /** Natural-language success criterion the actor evaluates at the end. */
     evaluate: string;
     /** How the actor answers the target agent's tool-approval requests. */
     approvals?: ActorFlowApprovalPolicy;
-    /** Model the persona uses for its own turns/decisions. */
+    /** Model the actor uses for its own turns/decisions. */
     model: string;
     /** Hard cap on conversation turns. Default 12. */
     maxTurns?: number;
@@ -22,13 +22,13 @@ export interface RunConversationParams {
     maxApprovalRounds?: number;
     /** Transport that drives the target agent (HTTP in production). */
     target: TargetAgentDriver;
-    /** The persona's own LLM. */
-    llm: PersonaLLM;
+    /** The actor's own LLM. */
+    llm: ActorLLM;
     /** Display name of the target agent (transcript labelling). */
     agentName: string;
 }
 /**
- * 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.

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/ai-agent/ai-agent-prepare.d.ts

@@ -168,7 +168,24 @@ export type ScopedChannel = AIStreamChannel & {
     }>;
 };
 export declare function createScopedChannel(parent: AIStreamChannel, agentName: string, session: string): ScopedChannel;
-export declare function buildToolDefs(params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[], agentMode?: 'delegate' | 'supervise'): Promise<{
+/**
+ * Build the run input for a delegated sub-agent.
+ *
+ * `context` is the PARENT run's identifier block (the "Current context" text
+ * with organizationId, project/stage ids). A sub-agent's tool-call schema only
+ * carries { message, session }, so unless the sub-agent inherits the parent's
+ * context it never sees the authoritative ids — it depends on the model
+ * re-typing them into `message`, which weak models botch, causing
+ * schema/permission rejections and retry loops. Forwarding it here is the
+ * regression this seam guards.
+ */
+export declare function buildSubAgentRunInput(message: string, threadId: string, resourceId: string, parentContext?: string): {
+    message: string;
+    threadId: string;
+    resourceId: string;
+    context?: string;
+};
+export declare function buildToolDefs(params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[], agentMode?: 'delegate' | 'supervise', parentContext?: string): Promise<{
     tools: AIAgentToolDef[];
     missingRpcs: string[];
 }>;

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -325,7 +325,29 @@ export function createScopedChannel(parent, agentName, session) {
         clearState: () => parent.clearState(),
     };
 }
-export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode) {
+/**
+ * Build the run input for a delegated sub-agent.
+ *
+ * `context` is the PARENT run's identifier block (the "Current context" text
+ * with organizationId, project/stage ids). A sub-agent's tool-call schema only
+ * carries { message, session }, so unless the sub-agent inherits the parent's
+ * context it never sees the authoritative ids — it depends on the model
+ * re-typing them into `message`, which weak models botch, causing
+ * schema/permission rejections and retry loops. Forwarding it here is the
+ * regression this seam guards.
+ */
+export function buildSubAgentRunInput(message, threadId, resourceId, parentContext) {
+    return { message, threadId, resourceId, context: parentContext };
+}
+export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode, 
+// The parent run's `context` (the "Current context" identifier block). A
+// delegated sub-agent's tool-call input schema only carries { message,
+// session }, so without inheriting this the sub-agent never sees the
+// authoritative ids (organizationId, project/stage ids) — it depends on the
+// model re-typing them into `message`, which weak models botch, causing
+// schema/permission rejections and retry loops. Forward it so the sub-agent
+// gets the same context block in its instructions.
+parentContext) {
     const singletonServices = getSingletonServices();
     const tools = [];
     const missingRpcs = [];
@@ -505,7 +527,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     subChannel.send(event);
                                 },
                             };
-                        const resultText = await streamAIAgent(subAgentName, { message, threadId, resourceId }, effectiveChannel, params, agentSessionMap, streamContext.options);
+                        const resultText = await streamAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), effectiveChannel, params, agentSessionMap, streamContext.options);
                         if (subChannel.approvals.length > 0) {
                             return {
                                 [APPROVAL_REQUIRED]: true,
@@ -525,7 +547,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                         return resultText;
                     }
                     // No stream context: sub-agent runs non-streaming
-                    const result = await runAIAgent(subAgentName, { message, threadId, resourceId }, params, agentSessionMap);
+                    const result = await runAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), params, agentSessionMap);
                     if (result.status === 'suspended' &&
                         result.pendingApprovals?.length) {
                         return {
@@ -731,7 +753,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const allMessages = [...contextMessages, ...messages, userMessage];
     const trimmedMessages = trimMessages(allMessages);
     const aiMiddlewares = agent.aiMiddleware ?? [];
-    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode);
+    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode, input.context);
     let instructions = await buildInstructions(resolvedName, packageName);
     if (input.context) {
         instructions = `${instructions}\n\nCurrent context (use these identifiers directly in tool calls — do not ask the user for them):\n${input.context}`;

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/queue/index.d.ts

@@ -1,4 +1,4 @@
-export type { ConfigValidationResult, CoreQueueWorker, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
+export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, JobGroup, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
 export { wireQueueWorker, runQueueJob, getQueueWorkers, removeQueueWorker, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export { validateWorkerConfig } from './validate-worker-config.js';
 export type { QueueConfigMapping } from './validate-worker-config.js';

package/dist/wirings/queue/queue.types.d.ts

@@ -30,6 +30,34 @@ export interface PikkuWorkerConfig {
     maxStalledCount?: number;
     /** Condition to start processor at instance creation */
     autorun?: boolean;
+    /**
+     * Cap how many jobs of any one group ({@link JobOptions.group}) may run at
+     * once, so a single group can't occupy the whole worker. Lets one shared
+     * queue stay fair across producers instead of splitting it into one queue
+     * per producer — which multiplies polling cost on pull-based backends.
+     * Must not exceed {@link batchSize}.
+     */
+    groupConcurrency?: number | GroupConcurrencyConfig;
+}
+/**
+ * Per-group concurrency limits, optionally varied by tier so slow groups can
+ * be allowed more (or fewer) slots than the default.
+ */
+export interface GroupConcurrencyConfig {
+    /** Limit applied to any group without a matching tier */
+    default: number;
+    /** Per-tier overrides, keyed by {@link JobGroup.tier} */
+    tiers?: Record<string, number>;
+}
+/**
+ * Fairness key for a job. Jobs sharing an `id` count against the same
+ * {@link PikkuWorkerConfig.groupConcurrency} limit.
+ */
+export interface JobGroup {
+    /** Group this job belongs to (e.g. a workflow name) */
+    id: string;
+    /** Optional tier selecting a per-tier limit */
+    tier?: string;
 }
 /**
  * Configuration for individual jobs - how jobs behave
@@ -106,6 +134,8 @@ export interface JobOptions {
     jobId?: string;
     /** Pikku user ID to propagate to the queue worker for credential resolution */
     pikkuUserId?: string;
+    /** Fairness key — counts against the worker's {@link PikkuWorkerConfig.groupConcurrency} */
+    group?: JobGroup;
 }
 /**
  * Queue provider interface for job publishing operations

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, 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';