@pikku/core 0.12.69 → 0.12.71

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

@@ -5,6 +5,12 @@ import type { QueueService, JobOptions } from '../wirings/queue/queue.types.js';
  * a real queue — and redelivers a failed job up to `options.attempts` times with
  * backoff, so a transiently-failing workflow step recovers exactly as it would
  * on pg-boss/bullmq instead of being silently dropped on its first error.
+ *
+ * Payloads are JSON round-tripped on the way in, because every real backend
+ * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
+ * therefore never sees the caller's live object. Doing it here keeps dev
+ * behaviour honest, and keeps the callers — who cannot know which backend they
+ * are talking to — from having to serialise defensively.
  */
 export declare class InMemoryQueueService implements QueueService {
     readonly supportsResults = false;

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

@@ -5,6 +5,12 @@ import { runQueueJob } from '../wirings/queue/queue-runner.js';
  * a real queue — and redelivers a failed job up to `options.attempts` times with
  * backoff, so a transiently-failing workflow step recovers exactly as it would
  * on pg-boss/bullmq instead of being silently dropped on its first error.
+ *
+ * Payloads are JSON round-tripped on the way in, because every real backend
+ * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
+ * therefore never sees the caller's live object. Doing it here keeps dev
+ * behaviour honest, and keeps the callers — who cannot know which backend they
+ * are talking to — from having to serialise defensively.
  */
 export class InMemoryQueueService {
     supportsResults = false;
@@ -14,12 +20,13 @@ export class InMemoryQueueService {
         const maxAttempts = Math.max(1, options?.attempts ?? 1);
         let attemptsMade = 0;
         const createdAt = new Date();
+        const payload = data === undefined ? data : JSON.parse(JSON.stringify(data));
         const runAttempt = async () => {
             attemptsMade++;
             const job = {
                 id: jobId,
                 queueName,
-                data,
+                data: payload,
                 status: () => 'active',
                 metadata: () => ({ attemptsMade, maxAttempts, createdAt }),
                 pikkuUserId: options?.pikkuUserId,

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

@@ -66,6 +66,9 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         branchKeys: Record<string, string>;
     }>;
     getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
+    protected listStepStates(runId: string): Promise<Array<StepState & {
+        stepName: string;
+    }>>;
     getStepInstances(runId: string): Promise<Array<{
         stepName: string;
         status: StepStatus;
@@ -82,9 +85,4 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         graph: any;
         source: string;
     } | null>;
-    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
 }

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

@@ -324,6 +324,16 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
         return nodeIds.filter((id) => !existingSteps.has(id));
     }
+    async listStepStates(runId) {
+        const prefix = `${runId}:`;
+        const steps = [];
+        for (const [key, step] of this.steps.entries()) {
+            if (!key.startsWith(prefix))
+                continue;
+            steps.push({ ...step, stepName: key.substring(prefix.length) });
+        }
+        return steps;
+    }
     async getStepInstances(runId) {
         const prefix = `${runId}:`;
         const instances = [];
@@ -387,23 +397,4 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             return null;
         return { graph: version.graph, source: version.source };
     }
-    async getAIGeneratedWorkflows(agentName) {
-        const results = [];
-        const prefix = agentName ? `ai:${agentName}:` : 'ai:';
-        for (const [key, value] of this.workflowVersions) {
-            if (value.source !== 'ai-agent' || value.status !== 'active')
-                continue;
-            const separatorIdx = key.lastIndexOf(':');
-            const wfName = key.substring(0, separatorIdx);
-            const hash = key.substring(separatorIdx + 1);
-            if (wfName.startsWith(prefix)) {
-                results.push({
-                    workflowName: wfName,
-                    graphHash: hash,
-                    graph: value.graph,
-                });
-            }
-        }
-        return results;
-    }
 }

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/services/workflow-service.d.ts

@@ -35,6 +35,13 @@ export interface WorkflowService {
     }): Promise<{
         runId: string;
     }>;
+    /**
+     * Start a run and wait for it to end.
+     *
+     * `pollIntervalMs` is the ceiling on the wait between reads of the run, not a
+     * fixed cadence: polling starts far shorter than this and widens towards it,
+     * so a run that finishes quickly is not held for a whole interval.
+     */
     runToCompletion<I>(name: string, input: I, rpcService: any, options?: {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
@@ -60,9 +67,4 @@ export interface WorkflowService {
         graph: any;
         source: string;
     } | null>;
-    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
 }