@pikku/core 0.12.67 → 0.12.70

package/dist/services/http-scenario-actors.js

@@ -1,4 +1,6 @@
+import { readScenarioHttpResponse } from './scenario-actors-service.js';
 import { runConversation } from '../wirings/actor-flow/run-conversation.js';
+import { createCookieJar, } from '../wirings/workflow/scenario-cookie-jar.js';
 import { getSingletonServices } from '../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../errors/errors.js';
 /**
@@ -13,26 +15,42 @@ export class HttpScenarioActor {
     name;
     actorConfig;
     config;
-    cookie = null;
-    origin;
+    jar;
+    /**
+     * Whether `login()` has succeeded since the last time the session was
+     * dropped. The jar cannot answer this — a target may set a cookie before
+     * anyone signs in, and it would then look like a session that was never
+     * established.
+     */
+    signedIn = false;
     constructor(name, actorConfig, config) {
         this.name = name;
         this.actorConfig = actorConfig;
         this.config = config;
-        this.origin = new URL(config.apiUrl).origin;
+        this.jar = createCookieJar(config.apiUrl);
     }
     get email() {
         return this.actorConfig.email;
     }
     async invoke(rpcName, data) {
-        const cookie = this.cookie ?? (await this.login());
-        const res = await this.postRpc(rpcName, data, cookie);
+        const res = await this.invokeRaw(rpcName, data);
+        if (!res.ok) {
+            throw new Error(`[scenario] '${rpcName}' as '${this.name}' returned ${res.status}: ${res.serialized.slice(0, 300)}`);
+        }
+        return res.body;
+    }
+    async invokeRaw(rpcName, data, options) {
+        if (!this.signedIn) {
+            await this.login();
+        }
+        let res = await this.postRpc(rpcName, data, options?.headers);
         if (res.status === 401) {
             // Session expired mid-run — re-login once and retry.
-            this.cookie = null;
-            return this.readRpcResponse(rpcName, await this.postRpc(rpcName, data, await this.login()));
+            this.signOut();
+            await this.login();
+            res = await this.postRpc(rpcName, data, options?.headers);
         }
-        return this.readRpcResponse(rpcName, res);
+        return readScenarioHttpResponse(res);
     }
     async converse(options) {
         const { aiAgentRunner } = getSingletonServices();
@@ -46,8 +64,8 @@ export class HttpScenarioActor {
         const threadId = globalThis.crypto.randomUUID();
         const resourceId = `actor:${this.name}`;
         return runConversation({
-            persona: this.actorConfig,
-            personaName: this.actorConfig.name ?? this.name,
+            actor: this.actorConfig,
+            actorName: this.actorConfig.name ?? this.name,
             agentName: options.agent,
             task: options.task,
             evaluate: options.evaluate,
@@ -88,19 +106,16 @@ export class HttpScenarioActor {
     async postAgent(subPath, body) {
         const rpcPath = this.config.rpcPath ?? '/rpc';
         const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
-        const send = (cookie) => fetch(url, {
+        const send = () => this.jar.fetch(url, {
             method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                origin: this.origin,
-                ...(cookie ? { cookie } : {}),
-            },
+            headers: { 'content-type': 'application/json' },
             body: JSON.stringify(body),
         });
-        let res = await send(this.cookie);
+        let res = await send();
         if (res.status === 401) {
-            this.cookie = null;
-            res = await send(await this.login());
+            this.signOut();
+            await this.login();
+            res = await send();
         }
         if (!res.ok) {
             const text = (await res.text().catch(() => '')).slice(0, 300);
@@ -111,33 +126,24 @@ export class HttpScenarioActor {
         const text = await res.text();
         return text ? JSON.parse(text) : undefined;
     }
-    async postRpc(rpcName, data, cookie) {
+    async postRpc(rpcName, data, extraHeaders) {
         const rpcPath = this.config.rpcPath ?? '/rpc';
-        return fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
+        return this.jar.fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
             method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                origin: this.origin,
-                cookie,
-            },
+            headers: { 'content-type': 'application/json', ...extraHeaders },
             body: JSON.stringify({ data }),
         });
     }
-    async readRpcResponse(rpcName, res) {
-        if (!res.ok) {
-            const body = (await res.text().catch(() => '')).slice(0, 300);
-            throw new Error(`[scenario] '${rpcName}' as '${this.name}' returned ${res.status}: ${body}`);
-        }
-        if (res.status === 204)
-            return undefined;
-        const text = await res.text();
-        return text ? JSON.parse(text) : undefined;
+    /** Drop the session, so the next call signs in again before it goes out. */
+    signOut() {
+        this.jar.clear();
+        this.signedIn = false;
     }
     async login() {
         const signInPath = this.config.signInPath ?? '/auth/sign-in/actor';
-        const res = await fetch(`${this.config.apiUrl}${signInPath}`, {
+        const res = await this.jar.fetch(`${this.config.apiUrl}${signInPath}`, {
             method: 'POST',
-            headers: { 'content-type': 'application/json', origin: this.origin },
+            headers: { 'content-type': 'application/json' },
             body: JSON.stringify({
                 email: this.actorConfig.email,
                 name: this.actorConfig.name ?? this.name,
@@ -148,16 +154,12 @@ export class HttpScenarioActor {
             const body = (await res.text().catch(() => '')).slice(0, 300);
             throw new Error(`[scenario] actor sign-in failed for '${this.name}' (${res.status}): ${body}`);
         }
-        const setCookies = res.headers.getSetCookie?.() ?? [];
-        const cookie = setCookies
-            .map((c) => c.split(';')[0])
-            .filter(Boolean)
-            .join('; ');
-        if (!cookie) {
+        // What proves a session was established is this response setting a cookie,
+        // not the jar being non-empty — the target may have set one earlier.
+        if (res.headers.getSetCookie().length === 0) {
             throw new Error(`[scenario] actor sign-in for '${this.name}' returned no session cookie`);
         }
-        this.cookie = cookie;
-        return cookie;
+        this.signedIn = true;
     }
 }
 /** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */

package/dist/services/in-memory-workflow-service.d.ts

@@ -1,6 +1,6 @@
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
 /**
  * In-memory implementation of WorkflowService for inline-only execution
  *
@@ -17,7 +17,7 @@ import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunW
  * ```
  */
 export declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
-    constructor();
+    constructor(options?: WorkflowQueueOptions);
     private sleepTimers;
     private runs;
     private steps;

package/dist/services/in-memory-workflow-service.js

@@ -17,8 +17,8 @@ import { isExpectedError } from '../errors/error-handler.js';
  * ```
  */
 export class InMemoryWorkflowService extends PikkuWorkflowService {
-    constructor() {
-        super({ wireQueues: false });
+    constructor(options = {}) {
+        super({ ...options, wireQueues: false });
     }
     sleepTimers = new Set();
     runs = new Map();

package/dist/services/index.d.ts

@@ -19,7 +19,8 @@ export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
-export type { ScenarioActor, ScenarioActorConfig, ScenarioActors, } from './scenario-actors-service.js';
+export type { ScenarioActor, ScenarioActorConfig, ScenarioActorOf, ScenarioActors, ScenarioInvokeOptions, ScenarioRpcMap, ScenarioHttpResponse, } from './scenario-actors-service.js';
+export { readScenarioHttpResponse } from './scenario-actors-service.js';
 export { HttpScenarioActor, createHttpScenarioActors, type HttpScenarioActorsConfig, } from './http-scenario-actors.js';
 export type { JWTService } from './jwt-service.js';
 export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';

package/dist/services/index.js

@@ -18,6 +18,7 @@ export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
+export { readScenarioHttpResponse } from './scenario-actors-service.js';
 export { HttpScenarioActor, createHttpScenarioActors, } from './http-scenario-actors.js';
 export { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';

package/dist/services/meta-service.d.ts

@@ -5,7 +5,7 @@ import type { ScheduledTasksMeta } from '../wirings/scheduler/scheduler.types.js
 import type { QueueWorkersMeta } from '../wirings/queue/queue.types.js';
 import type { CLIMeta } from '../wirings/cli/cli.types.js';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
-import type { WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
+import type { FeaturesMeta, WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
 import type { ScenarioActorConfig } from './scenario-actors-service.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
@@ -151,6 +151,7 @@ export interface MetaService {
     getRpcMeta(): Promise<RPCMetaRecord>;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
     getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>;
+    getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;
     getFunctionsMeta(): Promise<FunctionsMeta>;
@@ -183,6 +184,7 @@ export declare class LocalMetaService implements MetaService {
     private rpcMetaCache;
     private workflowMetaCache;
     private scenarioActorsMetaCache;
+    private featuresMetaCache;
     private triggerMetaCache;
     private triggerSourceMetaCache;
     private functionsMetaCache;
@@ -212,8 +214,10 @@ export declare class LocalMetaService implements MetaService {
     getMcpMeta(): Promise<MCPMeta>;
     getGatewayMeta(): Promise<GatewaysMeta>;
     getRpcMeta(): Promise<RPCMetaRecord>;
+    private readWorkflowMetaDir;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
     getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>;
+    getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;
     getFunctionsMeta(): Promise<FunctionsMeta>;

package/dist/services/meta-service.js

@@ -18,6 +18,7 @@ export class LocalMetaService {
     rpcMetaCache = null;
     workflowMetaCache = null;
     scenarioActorsMetaCache = null;
+    featuresMetaCache = null;
     triggerMetaCache = null;
     triggerSourceMetaCache = null;
     functionsMetaCache = null;
@@ -115,6 +116,7 @@ export class LocalMetaService {
         this.rpcMetaCache = null;
         this.workflowMetaCache = null;
         this.scenarioActorsMetaCache = null;
+        this.featuresMetaCache = null;
         this.triggerMetaCache = null;
         this.triggerSourceMetaCache = null;
         this.functionsMetaCache = null;
@@ -223,27 +225,36 @@ export class LocalMetaService {
             return this.rpcMetaCache;
         }
     }
+    async readWorkflowMetaDir(dir, into) {
+        const files = await this.readDir(dir);
+        const jsonFiles = files.filter((f) => f.endsWith('.gen.json'));
+        const verboseFiles = jsonFiles.filter((f) => f.includes('-verbose'));
+        const minimalFiles = jsonFiles.filter((f) => !f.includes('-verbose'));
+        const verboseNames = new Set(verboseFiles.map((f) => f.replace('-verbose.gen.json', '')));
+        const filesToRead = [
+            ...verboseFiles,
+            ...minimalFiles.filter((f) => !verboseNames.has(f.replace('.gen.json', ''))),
+        ];
+        await Promise.all(filesToRead.map(async (file) => {
+            const content = await this.readFile(`${dir}/${file}`);
+            if (content) {
+                const meta = JSON.parse(content);
+                into[meta.name] = meta;
+            }
+        }));
+    }
     async getWorkflowMeta() {
         if (this.workflowMetaCache)
             return this.workflowMetaCache;
         try {
-            const files = await this.readDir('workflow/meta');
-            const jsonFiles = files.filter((f) => f.endsWith('.gen.json'));
-            const verboseFiles = jsonFiles.filter((f) => f.includes('-verbose'));
-            const minimalFiles = jsonFiles.filter((f) => !f.includes('-verbose'));
-            const verboseNames = new Set(verboseFiles.map((f) => f.replace('-verbose.gen.json', '')));
-            const filesToRead = [
-                ...verboseFiles,
-                ...minimalFiles.filter((f) => !verboseNames.has(f.replace('.gen.json', ''))),
-            ];
             const result = {};
-            await Promise.all(filesToRead.map(async (file) => {
-                const content = await this.readFile(`workflow/meta/${file}`);
-                if (content) {
-                    const meta = JSON.parse(content);
-                    result[meta.name] = meta;
-                }
-            }));
+            // Scenarios keep their meta in `scenarios/meta` so nothing app-facing
+            // imports them, but they are still workflows to anything reading meta off
+            // disk — the console's scenario list among them.
+            await Promise.all([
+                this.readWorkflowMetaDir('workflow/meta', result),
+                this.readWorkflowMetaDir('scenarios/meta', result),
+            ]);
             this.workflowMetaCache = result;
             return this.workflowMetaCache;
         }
@@ -260,6 +271,13 @@ export class LocalMetaService {
         this.scenarioActorsMetaCache = content ? JSON.parse(content) : {};
         return this.scenarioActorsMetaCache;
     }
+    async getFeaturesMeta() {
+        if (this.featuresMetaCache)
+            return this.featuresMetaCache;
+        const content = await this.readFile('scenarios/features.gen.json');
+        this.featuresMetaCache = content ? JSON.parse(content) : {};
+        return this.featuresMetaCache;
+    }
     async getTriggerMeta() {
         if (this.triggerMetaCache)
             return this.triggerMetaCache;
@@ -277,8 +295,16 @@ export class LocalMetaService {
     async getFunctionsMeta() {
         if (this.functionsMetaCache)
             return this.functionsMetaCache;
-        const content = await this.readMetaJson('function', 'pikku-functions-meta');
-        this.functionsMetaCache = content ? JSON.parse(content) : {};
+        const [content, scenarioContent] = await Promise.all([
+            this.readMetaJson('function', 'pikku-functions-meta'),
+            // Scenario steps register only into the scenario bootstrap, but they are
+            // still functions to anything reading meta off disk.
+            this.readMetaJson('scenarios', 'pikku-scenario-functions-meta'),
+        ]);
+        this.functionsMetaCache = {
+            ...(content ? JSON.parse(content) : {}),
+            ...(scenarioContent ? JSON.parse(scenarioContent) : {}),
+        };
         return this.functionsMetaCache;
     }
     async getMiddlewareGroupsMeta() {

package/dist/services/scenario-actors-service.d.ts

@@ -1,12 +1,103 @@
 import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+/**
+ * What the transport answered, for a step that treats the status as data.
+ *
+ * An HTTP response with its body already drained: the stream can only be read
+ * once, and a step's return value crosses into the run record, so the response
+ * object itself cannot travel. This is the shape every caller ends up with.
+ */
+export interface ScenarioHttpResponse<T = unknown> {
+    status: number;
+    ok: boolean;
+    /**
+     * The parsed JSON body — or, when the body was not JSON, the raw text it was
+     * parsed from, so an HTML error page is still readable rather than lost.
+     * `undefined` for an empty response.
+     *
+     * `T` is a claim the caller makes, not one the transport checked: a step that
+     * knows the route's payload names it here instead of casting at every use.
+     */
+    body: T;
+    /**
+     * The whole body as text, so an assertion can search it without knowing the
+     * payload's shape — and so an error body that is HTML rather than JSON still
+     * says what went wrong.
+     */
+    serialized: string;
+}
+/**
+ * Drain a response into the shape a step can carry: the parsed body (an empty
+ * one counting as no body at all) alongside the text it was parsed from.
+ *
+ * `invokeRaw` returns this, and a step that has to reach past an actor — a
+ * route with no RPC, an identity no actor can hold — reaches for this rather
+ * than writing the same record by hand.
+ */
+export declare const readScenarioHttpResponse: <T = unknown>(res: Response) => Promise<ScenarioHttpResponse<T>>;
+/** How to send one JSON request, for `postScenarioJson`. */
+export interface ScenarioJsonRequest {
+    /** Serialised as the JSON body. Omit for a request that carries none. */
+    body?: unknown;
+    /** Sent alongside `content-type: application/json`, and may override it. */
+    headers?: Record<string, string>;
+    /** Defaults to `POST` — the method every scenario route here answers. */
+    method?: string;
+    /**
+     * The `fetch` to send it with. Pass a `ScenarioCookieJar`'s to keep the
+     * session; the global `fetch` otherwise, which is what a step asserting on a
+     * sessionless call wants.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
+ *
+ * Every scenario that reaches past an actor was writing this by hand — the same
+ * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
+ * drifted: some returned `res.json()`, which loses the status and throws
+ * outright when the target answers an empty body or an HTML error page. A
+ * refusal is the expected outcome of a permissions scenario, so it has to
+ * survive as data.
+ */
+export declare const postScenarioJson: <T = unknown>(url: string, { body, headers, method, fetch: send, }?: ScenarioJsonRequest) => Promise<ScenarioHttpResponse<T>>;
+/** Per-call transport options. */
+export interface ScenarioInvokeOptions {
+    /**
+     * Headers to send alongside the actor's own session. This is how a step
+     * expresses an identity the actor registry cannot — an impersonation header,
+     * or one of the header-shim principals a credential scenario invents.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * The RPC surface an actor can reach, as name → input/output. A project binds
+ * its generated exposed RPC map here; the default leaves every name open, which
+ * is what an actor built by hand (or by a third-party driver) gets.
+ */
+export type ScenarioRpcMap = Record<string, {
+    input: any;
+    output: any;
+}>;
+/**
+ * The actor a step wire carries, for a project whose actor registry is known.
+ * An empty registry keeps the open actor type rather than collapsing to
+ * `never` — a project may still build actors itself.
+ */
+export type ScenarioActorOf<TActors> = [keyof TActors] extends [never] ? ScenarioActor : TActors[keyof TActors];
 /** A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport */
-export interface ScenarioActor<TAgentName extends string = string> {
+export interface ScenarioActor<TAgentName extends string = string, TRpcMap extends ScenarioRpcMap = ScenarioRpcMap> {
     /** Stable actor name (the key in pikku.config.json's actor registry). */
     readonly name: string;
     /** The actor's user email — flows use it for invites/lookups. */
     readonly email: string;
     /** Invoke an exposed RPC as this actor over the real transport. */
-    invoke(rpcName: string, data: unknown): Promise<unknown>;
+    invoke<TName extends keyof TRpcMap & string>(rpcName: TName, data: TRpcMap[TName]['input']): Promise<TRpcMap[TName]['output']>;
+    /**
+     * The same call, reporting what the transport answered rather than throwing.
+     * A refusal is the expected outcome of a permissions or scopes scenario, and
+     * `invoke`'s error truncates the body that names which scope was missing.
+     */
+    invokeRaw<TName extends keyof TRpcMap & string>(rpcName: TName, data: TRpcMap[TName]['input'], options?: ScenarioInvokeOptions): Promise<ScenarioHttpResponse>;
     /** Converse with a Pikku AI agent in this actor's persona and return its verdict */
     converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>;
 }
@@ -16,6 +107,21 @@ export interface ScenarioActorConfig {
     name?: string;
     jobTitle?: string;
     personality?: string;
+    /**
+     * The persona this body is one of — the KIND of person, declared in
+     * `scenarios.personas`. Most personas have exactly one actor and it is
+     * materialised for them; a second body of the same persona is what tenant
+     * isolation and peer-sharing scenarios are made of.
+     */
+    persona?: string;
+    /**
+     * Scopes this actor holds, granted directly rather than through a role, and
+     * the roles it belongs to. Pikku carries them; it never applies them — which
+     * scope store exists and which roles have been created is the app's own, so
+     * the app's seed reads these back off `scenarioActorConfigs` and grants them.
+     */
+    scopes?: readonly string[];
+    roles?: readonly string[];
 }
 /** The injected `actors` service: actor name → actor. */
 export type ScenarioActors = Record<string, ScenarioActor>;

package/dist/services/scenario-actors-service.js

@@ -1 +1,40 @@
-export {};
+/**
+ * Drain a response into the shape a step can carry: the parsed body (an empty
+ * one counting as no body at all) alongside the text it was parsed from.
+ *
+ * `invokeRaw` returns this, and a step that has to reach past an actor — a
+ * route with no RPC, an identity no actor can hold — reaches for this rather
+ * than writing the same record by hand.
+ */
+export const readScenarioHttpResponse = async (res) => {
+    const text = res.status === 204 ? '' : await res.text().catch(() => '');
+    return {
+        status: res.status,
+        ok: res.ok,
+        body: (text ? parseJsonBody(text) : undefined),
+        serialized: text,
+    };
+};
+const parseJsonBody = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+/**
+ * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
+ *
+ * Every scenario that reaches past an actor was writing this by hand — the same
+ * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
+ * drifted: some returned `res.json()`, which loses the status and throws
+ * outright when the target answers an empty body or an HTML error page. A
+ * refusal is the expected outcome of a permissions scenario, so it has to
+ * survive as data.
+ */
+export const postScenarioJson = async (url, { body, headers, method = 'POST', fetch: send = fetch, } = {}) => readScenarioHttpResponse(await send(url, {
+    method,
+    headers: { 'content-type': 'application/json', ...headers },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+}));

package/dist/types/core.types.d.ts

@@ -12,6 +12,7 @@ import type { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js
 import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js';
 import type { PikkuCLI } from '../wirings/cli/cli.types.js';
 import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowService, WorkflowServiceConfig, WorkflowStepWire } from '../wirings/workflow/workflow.types.js';
+import type { PikkuBrowserWire, PikkuScenarioStepWire } from '../wirings/workflow/scenario-step.types.js';
 import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js';
 import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js';
 import type { PikkuGateway } from '../wirings/gateway/gateway.types.js';
@@ -19,7 +20,7 @@ import type { SchedulerService } from '../services/scheduler-service.js';
 import type { DeploymentService } from '../services/deployment-service.js';
 import type { AIStorageService } from '../services/ai-storage-service.js';
 import type { ContentService } from '../services/content-service.js';
-import type { ScenarioActors } from '../services/scenario-actors-service.js';
+import type { ScenarioActorOf, ScenarioActors } from '../services/scenario-actors-service.js';
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js';
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
@@ -85,6 +86,15 @@ export type FunctionRuntimeMeta = {
     scopes?: string[];
     expose?: boolean;
     remote?: boolean;
+    /**
+     * A step RPC: a name dispatched by a scenario run and refused everywhere
+     * else. It sits alongside `expose` (public) and `remote` as a kind of RPC
+     * rather than a separate concept — a step is invoked by name exactly as an
+     * RPC is, which is why a run records the step function in its `rpcName`.
+     * What makes it its own kind is that it is never network-callable: a step
+     * may drive a browser or assert against fixtures.
+     */
+    scenarioStep?: boolean;
     mcp?: boolean;
     readonly?: boolean;
     deploy?: 'serverless' | 'server' | 'auto';
@@ -95,6 +105,10 @@ export type FunctionRuntimeMeta = {
     workflowRetries?: number;
     /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
     workflowTimeout?: string;
+    /** Scenario steps only: this step drives a browser, so the runner must provision one and an actor is mandatory. */
+    scenarioStepBrowser?: boolean;
+    /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
+    scenarioStepTemplate?: string;
     version?: number;
     approvalRequired?: boolean;
     approvalDescription?: string;
@@ -306,7 +320,7 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 /**
  * Represents different forms of wire within Pikku and the outside world.
  */
-export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire> = {
+export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire, TypedActors extends ScenarioActors = ScenarioActors> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
 } & Partial<{
@@ -326,7 +340,11 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     cli: PikkuCLI;
     workflow: TypedWorkflow;
     scenario: TypedScenario;
-    actors: ScenarioActors;
+    actors: TypedActors;
+    /** Present on every scenario step invocation */
+    scenarioStep: PikkuScenarioStepWire<ScenarioActorOf<TypedActors>>;
+    /** Present only when the runner provisioned a browser for this step */
+    browser: PikkuBrowserWire;
     workflowStep: WorkflowStepWire;
     graph: PikkuGraphWire;
     trigger: PikkuTrigger<TriggerOutput>;

package/dist/types/state.types.d.ts

@@ -9,7 +9,7 @@ import type { CoreAIAgent, AIAgentMeta } from '../wirings/ai-agent/ai-agent.type
 import type { CoreGateway, GatewaysMeta } from '../wirings/gateway/gateway.types.js';
 import type { CoreQueueWorker, QueueWorkersMeta } from '../wirings/queue/queue.types.js';
 import type { CoreScheduledTask, ScheduledTasksMeta } from '../wirings/scheduler/scheduler.types.js';
-import type { CoreWorkflow, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.types.js';
+import type { CoreWorkflow, CoreFeature, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.types.js';
 import type { CoreTrigger, CoreTriggerSource, TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { FunctionsMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
@@ -77,6 +77,8 @@ export interface PikkuPackageState {
     };
     workflows: {
         registrations: Map<string, CoreWorkflow>;
+        /** Scenario groups declared with `pikkuFeature`, keyed by export name. */
+        features: Map<string, CoreFeature>;
         meta: WorkflowsRuntimeMeta;
     };
     trigger: {

package/dist/wirings/actor-flow/actor-flow.types.d.ts

@@ -20,7 +20,7 @@ export interface ConverseOptions<TAgentName extends string = string> {
     evaluate: string;
     /** How the actor answers the agent's tool-approval requests. Default `'in-persona'`. */
     approvals?: ActorFlowApprovalPolicy;
-    /** Model the persona uses for its own turns/decisions. Falls back to the actor service default. */
+    /** Model the actor uses for its own turns/decisions. Falls back to the actor service default. */
     model?: string;
     /** Hard cap on conversation turns before forcing evaluation. Default 12. */
     maxTurns?: number;

package/dist/wirings/actor-flow/index.d.ts

@@ -8,4 +8,4 @@
  * over HTTP.
  */
 export type { ActorFlowApprovalPolicy, ActorFlowVerdict, ConverseOptions, TargetAgentReply, TargetPendingApproval, TargetAgentDriver, } from './actor-flow.types.js';
-export { runConversation, type RunConversationParams, type PersonaLLM, } from './run-conversation.js';
+export { runConversation, type RunConversationParams, type ActorLLM, } from './run-conversation.js';