@pikku/core 0.12.69 → 0.12.70

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -0,0 +1,148 @@
+import type { ScenarioActor } from '../../services/scenario-actors-service.js';
+/**
+ * Scenario steps: named, typed units of scenario behaviour.
+ *
+ * A step's body is an ordinary pikku function, so it may drive a browser, call
+ * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
+ * `step` — they only change the prose the reporter renders.
+ */
+/**
+ * Which Gherkin-style keyword the reporter prefixes this step with. `step`
+ * renders no prefix at all.
+ */
+export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then';
+/**
+ * Options accepted by `scenario.step/given/when/then`.
+ *
+ * Note the retry default differs from an ordinary workflow step: retrying a
+ * failed assertion is the wrong behaviour for a test primitive, so steps
+ * default to no retries.
+ */
+export interface ScenarioStepOptions {
+    /** The actor this step runs as. Required for steps declaring `browser: true`. */
+    actor?: unknown;
+    /** Overrides the step's own `description` for this call site only. */
+    description?: string;
+    /** Defaults to 0 for steps — a failed assertion must not be retried. */
+    retries?: number;
+    retryDelay?: number | string;
+}
+/**
+ * The environment a scenario run targets, as declared in pikku.config.json
+ * under `scenarios.environments`.
+ */
+export interface ScenarioEnvironment {
+    /** Base API URL of the target app, INCLUDING the HTTP prefix. */
+    apiUrl: string;
+    /** Base URL of the app's UI, for environments with browser steps. */
+    appUrl?: string;
+}
+/**
+ * The `scenarioStep` wire, present on every scenario step invocation.
+ *
+ * `TActor` is the project's own actor type, so a step reaches only the RPCs its
+ * actors can actually call. It defaults to the open `ScenarioActor` for a
+ * project that declares no registry.
+ */
+export interface PikkuScenarioStepWire<TActor = ScenarioActor> {
+    /** Registered step name (also its pikkuFuncId) */
+    name: string;
+    /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
+    stepName: string;
+    runId: string;
+    phase: ScenarioStepPhase;
+    /**
+     * The actor this step runs as, when one was given. Call RPCs through it
+     * (`actor.invoke(...)`) so they run against the target environment as that
+     * persona.
+     */
+    actor?: TActor;
+    /**
+     * The environment this run targets. A step runs in the CLI process, where
+     * there is no `variables` service — this is how a raw-HTTP step learns the
+     * target's URL without reaching for `process.env`.
+     */
+    env?: ScenarioEnvironment;
+}
+/**
+ * How a browser step names an element.
+ *
+ * A `data-testid` on its own is rarely enough to name exactly one: `where`
+ * matches the element's own data attributes (so a step asserts a status
+ * without reading translated copy back to the app), `prefix` matches a family
+ * of ids, `containing` picks the match holding a piece of text, and `within`
+ * scopes the lookup to one row or section.
+ *
+ * Declared here so a step's input type is structural; the driver
+ * (`@pikku/playwright`) is what resolves it against a real page.
+ */
+export interface TestIdSelector {
+    testId: string;
+    /** Match every test id beginning with `testId`, e.g. every `flow-card-*`. */
+    prefix?: boolean;
+    /** Data attributes the element must also carry, e.g. `{ 'data-open': 'true' }`. */
+    where?: Record<string, string>;
+    /** Narrow to the one match holding this text. */
+    containing?: string;
+    /** Scope the lookup to one enclosing element, e.g. the row for one user. */
+    within?: TestIdSelector;
+}
+/**
+ * Structural browser handle, present only when the runner provisioned a
+ * browser for this step (`browser: true` on the step config).
+ *
+ * `@pikku/core` deliberately never imports playwright — it must stay
+ * dependency-free for edge runtimes. `@pikku/playwright` augments this
+ * interface via `declare module`, so `wire.browser.page` is a fully typed
+ * Playwright `Page` in a project that installs it.
+ */
+export interface PikkuBrowserWire {
+    /** The actor whose browser context this is */
+    readonly actor: string;
+    goto(url: string): Promise<void>;
+    screenshot(name?: string): Promise<Uint8Array>;
+}
+/**
+ * What one actor's window looked like at the moment a scenario failed.
+ *
+ * A browser step fails with a selector timeout that says nothing about *why*
+ * the page never rendered. The answer is almost always in the page's own
+ * errors, which the driver has been collecting all along.
+ */
+export interface ScenarioBrowserFailure {
+    /** The actor whose window this is. */
+    actor: string;
+    /** Where the window was pointed, when the driver can still report it. */
+    url?: string;
+    /** Path the screenshot was written to; absent when none could be taken. */
+    screenshot?: string;
+    consoleErrors: string[];
+    pageErrors: string[];
+    failedRequests: string[];
+    apiErrors: string[];
+}
+/**
+ * Supplied by `@pikku/playwright` (or any other driver) and consumed by the
+ * scenario runner. Declared here so the CLI depends only on core.
+ *
+ * `reset` and `captureFailure` are optional so a driver written against an
+ * earlier version keeps compiling; the runner treats a driver without them as
+ * one that simply offers no isolation and no diagnostics.
+ */
+export interface ScenarioBrowserProvider {
+    /** Resolve — creating on first use — the browser session for an actor. */
+    sessionFor(actorName: string): Promise<PikkuBrowserWire>;
+    /**
+     * Discard every actor's per-scenario state — cookies, storage, open pages —
+     * while keeping the browser itself. Called between scenarios, so one
+     * scenario cannot leave the next signed in as somebody else.
+     */
+    reset?(): Promise<void>;
+    /**
+     * Snapshot every open window for a failed scenario. `label` identifies the
+     * scenario in artifact filenames. Never throws: a failure to capture must
+     * not replace the failure being captured.
+     */
+    captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>;
+    close(): Promise<void>;
+}

package/dist/wirings/workflow/scenario-step.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,8 +1,9 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
-import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
+import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, 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 './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, 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 './dsl/workflow-dsl.types.js';
+export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, PikkuBrowserWire, ScenarioBrowserProvider, } from './scenario-step.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -235,6 +236,77 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     /** Tags for organization and filtering */
     tags?: string[];
 };
+/**
+ * A scenario as a feature references it: either the scenario itself, or the
+ * scenario paired with the input to run it with. The paired form is gherkin's
+ * `Examples:` — the same scenario run once per row, written as an ordinary
+ * loop rather than a table.
+ */
+export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
+    scenario: CorePikkuFunctionConfig<any, any, any>;
+    data: unknown;
+};
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * Hooks run **once around the whole group** (`before → a → b → c → after`),
+ * not per scenario — per-scenario setup is the scenario's own `before`. That
+ * is the one thing a feature deliberately cannot express: gherkin's
+ * `Background:` runs per scenario.
+ */
+export type CoreFeature = {
+    /** Human-readable name. The export identifier is the id. */
+    name: string;
+    description?: string;
+    tags?: string[];
+    /** Readonly because `pikkuFeature`'s `const` generic infers a readonly tuple. */
+    scenarios: readonly CoreFeatureScenario[];
+    before?: CorePikkuFunctionHook;
+    after?: CorePikkuFunctionHook;
+};
+/** One entry of a feature's scenario list, as extracted from the source. */
+export type FeatureMetaEntry = {
+    /** The scenario's declared export name — its key in `WorkflowsMeta`. */
+    scenario: string;
+    /** The input this entry runs the scenario with — gherkin's `Examples:`. */
+    data?: unknown;
+};
+/**
+ * A feature as the console reads it: the document structure around a group of
+ * scenarios. Generated to `scenarios/features.gen.json` and read off disk, so
+ * nothing app-facing has to import the scenario bootstrap to describe one.
+ */
+export type FeatureMeta = {
+    /** The export identifier. */
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    /** In declared order — a feature's reading order is its declaration order. */
+    entries: FeatureMetaEntry[];
+    /**
+     * Entries that could not be read statically (a spread, a `.map()`). Their
+     * membership is only known once the scenario bootstrap has been evaluated,
+     * so a non-zero count means this listing is partial.
+     */
+    unresolvedEntries: number;
+    /** Hooks are runtime-only; only their presence is knowable from meta. */
+    hasBefore: boolean;
+    hasAfter: boolean;
+};
+export type FeaturesMeta = Record<string, FeatureMeta>;
+/** One planned scenario run, resolved from a feature's scenario list. */
+export type FeaturePlanEntry = {
+    featureId: string;
+    featureName: string;
+    scenarioName: string;
+    /** The input this entry runs the scenario with, if the feature supplied one. */
+    data?: unknown;
+    /** The scenario's own tags unioned with the containing feature's. */
+    tags: string[];
+};
 /**
  * Workflow client interface
  */
@@ -274,6 +346,13 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     expose?: boolean;
     /** True for pikkuScenario workflows (complex + actor steps). */
     scenario?: boolean;
+    /**
+     * Why a scenario is held out of a default run. Stating the reason in code
+     * keeps the quarantine next to the scenario it applies to, rather than in
+     * a CI invocation nobody reads. Naming the scenario with `--flows` runs it
+     * regardless.
+     */
+    skip?: string;
     /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[];
 }>;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.69",
+  "version": "0.12.70",
+  "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -22,6 +23,7 @@
     "./function": "./dist/function/index.js",
     "./channel": "./dist/wirings/channel/index.js",
     "./workflow": "./dist/wirings/workflow/index.js",
+    "./scenario": "./dist/wirings/workflow/pikku-scenario-service.js",
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
     "./actor-flow": "./dist/wirings/actor-flow/index.js",

package/src/function/functions.types.ts

@@ -248,6 +248,17 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
   | Record<string, PikkuPermission | PikkuPermission[]>
   | undefined
 
+/**
+ * A lifecycle hook: the same call signature as the function it hangs off, but
+ * its return value is discarded. A hook is setup/teardown, not a step — it has
+ * no id, no meta and no schema, so it is never recorded and never replayed.
+ */
+export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (
+  services: Services,
+  data: Data,
+  wire: Wire
+) => Promise<void> | void
+
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
     | CorePikkuFunction<any, any, any, any, any>
@@ -282,6 +293,8 @@ export type CorePikkuFunctionConfig<
   workflowRetries?: number
   /** Timeout for this function when 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 before calling it. */
+  browser?: boolean
   audit?:
     | boolean
     | {
@@ -289,6 +302,25 @@ export type CorePikkuFunctionConfig<
       }
   approvalDescription?: any
   func: PikkuFunction
+  /**
+   * Scenarios only: runs before the scenario body, with the scenario's own
+   * signature. Throwing skips the body and fails the run, but `after` still
+   * runs.
+   */
+  before?: CorePikkuFunctionHook
+  /**
+   * Scenarios only: always runs after the scenario body, in a `finally`.
+   * Throwing fails a run that would otherwise have passed; on an
+   * already-failed run it attaches as the `cause` and never replaces the
+   * original error.
+   */
+  after?: CorePikkuFunctionHook
+  /**
+   * Scenarios only: why this scenario is held out of a default run. It is
+   * reported as skipped rather than quietly omitted, and naming it directly
+   * with `--flows` runs it anyway.
+   */
+  skip?: string
   auth?: boolean
   /**
    * Scopes the session must hold to run this function. All of them are

package/src/index.ts

@@ -55,6 +55,7 @@ export type {
   CorePikkuAuthConfig,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
+  CorePikkuFunctionHook,
   CorePikkuPermission,
   CorePikkuPermissionConfig,
   CorePikkuPermissionFactory,

package/src/internal.ts

@@ -1,4 +1,8 @@
-export { pikkuState, resetPikkuState } from './pikku-state.js'
+export {
+  pikkuState,
+  resetPikkuState,
+  getAllPackageStates,
+} from './pikku-state.js'
 export { httpRouter } from './wirings/http/routers/http-router.js'
 export type {
   CreateSingletonServices,

package/src/pikku-state.ts

@@ -104,6 +104,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   },
   workflows: {
     registrations: new Map(),
+    features: new Map(),
     meta: {},
   },
   trigger: {

package/src/services/http-scenario-actors.test.ts

@@ -38,11 +38,27 @@ const startTarget = async () => {
           res.writeHead(401).end()
           return
         }
+        const rpcName = req.url.slice('/api/rpc/'.length)
+        if (rpcName === 'html-error') {
+          res
+            .writeHead(500, { 'content-type': 'text/html' })
+            .end('<html><body>Gateway blew up</body></html>')
+          return
+        }
+        if (rpcName === 'forbidden') {
+          res
+            .writeHead(403, { 'content-type': 'application/json' })
+            .end(
+              JSON.stringify({ message: 'MissingScopeError', scope: 'admin' })
+            )
+          return
+        }
         res.writeHead(200, { 'content-type': 'application/json' }).end(
           JSON.stringify({
-            rpcName: req.url.slice('/api/rpc/'.length),
+            rpcName,
             echoed: body.data,
             cookie,
+            userHeader: req.headers['x-user-id'] ?? null,
           })
         )
         return
@@ -115,6 +131,74 @@ describe('HttpScenarioActor', async () => {
     assert.match(result.cookie, new RegExp(`session=s${loginsBefore + 1}`))
   })
 
+  test('invokeRaw returns the status and body instead of throwing', async () => {
+    const actors = makeActors()
+
+    // A refusal is the expected outcome of a permissions scenario, so the
+    // status and the payload that names the missing scope both have to survive.
+    const res = await actors.customer!.invokeRaw('forbidden', {})
+
+    assert.equal(res.status, 403)
+    assert.equal(res.ok, false)
+    assert.deepEqual(res.body, {
+      message: 'MissingScopeError',
+      scope: 'admin',
+    })
+  })
+
+  test('invokeRaw reports a success the same way', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw('listTodos', { page: 2 })
+
+    assert.equal(res.status, 200)
+    assert.equal(res.ok, true)
+    assert.deepEqual((res.body as any).echoed, { page: 2 })
+  })
+
+  test('invokeRaw carries the response text so a step can search it', async () => {
+    const actors = makeActors()
+    const res = await actors.customer!.invokeRaw('forbidden', {})
+
+    assert.match(res.serialized, /MissingScopeError/)
+    assert.match(res.serialized, /admin/)
+  })
+
+  test('invokeRaw keeps a non-JSON error body instead of failing to parse it', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw('html-error', {})
+
+    assert.equal(res.status, 500)
+    assert.equal(res.ok, false)
+    assert.equal(res.body, '<html><body>Gateway blew up</body></html>')
+    assert.match(res.serialized, /Gateway blew up/)
+  })
+
+  test('invokeRaw reports an empty body as an empty string', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw('listTodos', {})
+
+    assert.equal(typeof res.serialized, 'string')
+  })
+
+  test('invokeRaw passes extra headers through', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw(
+      'whoAmI',
+      {},
+      { headers: { 'x-user-id': 'impersonated-1' } }
+    )
+
+    assert.equal((res.body as any).userHeader, 'impersonated-1')
+  })
+
+  test('invoke still throws on a refusal, naming the status and body', async () => {
+    const actors = makeActors()
+    await assert.rejects(
+      actors.customer!.invoke('forbidden', {}),
+      /'forbidden' as 'customer' returned 403.*MissingScopeError/
+    )
+  })
+
   test('a wrong impersonation secret surfaces status and body', async () => {
     const actors = makeActors('wrong-secret')
     await assert.rejects(

package/src/services/http-scenario-actors.ts

@@ -2,13 +2,20 @@ import type {
   ScenarioActor,
   ScenarioActorConfig,
   ScenarioActors,
+  ScenarioInvokeOptions,
+  ScenarioHttpResponse,
 } from './scenario-actors-service.js'
+import { readScenarioHttpResponse } from './scenario-actors-service.js'
 import type {
   ConverseOptions,
   ActorFlowVerdict,
   TargetAgentReply,
 } from '../wirings/actor-flow/actor-flow.types.js'
 import { runConversation } from '../wirings/actor-flow/run-conversation.js'
+import {
+  createCookieJar,
+  type ScenarioCookieJar,
+} from '../wirings/workflow/scenario-cookie-jar.js'
 import { getSingletonServices } from '../pikku-state.js'
 import { AIProviderNotConfiguredError } from '../errors/errors.js'
 
@@ -48,15 +55,21 @@ export interface HttpScenarioActorsConfig {
  * outlive a session).
  */
 export class HttpScenarioActor implements ScenarioActor {
-  private cookie: string | null = null
-  private origin: string
+  private jar: ScenarioCookieJar
+  /**
+   * 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.
+   */
+  private signedIn = false
 
   constructor(
     readonly name: string,
     private actorConfig: ScenarioActorConfig,
     private config: HttpScenarioActorsConfig
   ) {
-    this.origin = new URL(config.apiUrl).origin
+    this.jar = createCookieJar(config.apiUrl)
   }
 
   get email(): string {
@@ -64,17 +77,31 @@ export class HttpScenarioActor implements ScenarioActor {
   }
 
   async invoke(rpcName: string, data: unknown): Promise<unknown> {
-    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: string,
+    data: unknown,
+    options?: ScenarioInvokeOptions
+  ): Promise<ScenarioHttpResponse> {
+    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: ConverseOptions): Promise<ActorFlowVerdict> {
@@ -92,8 +119,8 @@ export class HttpScenarioActor implements ScenarioActor {
     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,
@@ -148,21 +175,18 @@ export class HttpScenarioActor implements ScenarioActor {
   private async postAgent(subPath: string, body: unknown): Promise<unknown> {
     const rpcPath = this.config.rpcPath ?? '/rpc'
     const url = `${this.config.apiUrl}${rpcPath}/${subPath}`
-    const send = (cookie: string | null) =>
-      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)
@@ -175,36 +199,30 @@ export class HttpScenarioActor implements ScenarioActor {
     return text ? JSON.parse(text) : undefined
   }
 
-  private async postRpc(rpcName: string, data: unknown, cookie: string) {
+  private async postRpc(
+    rpcName: string,
+    data: unknown,
+    extraHeaders?: Record<string, string>
+  ) {
     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 }),
     })
   }
 
-  private async readRpcResponse(rpcName: string, res: Response) {
-    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. */
+  private signOut(): void {
+    this.jar.clear()
+    this.signedIn = false
   }
 
-  private async login(): Promise<string> {
+  private async login(): Promise<void> {
     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,
@@ -217,18 +235,14 @@ export class HttpScenarioActor implements ScenarioActor {
         `[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
   }
 }
 

package/src/services/index.ts

@@ -43,8 +43,13 @@ export type {
 export type {
   ScenarioActor,
   ScenarioActorConfig,
+  ScenarioActorOf,
   ScenarioActors,
+  ScenarioInvokeOptions,
+  ScenarioRpcMap,
+  ScenarioHttpResponse,
 } from './scenario-actors-service.js'
+export { readScenarioHttpResponse } from './scenario-actors-service.js'
 export {
   HttpScenarioActor,
   createHttpScenarioActors,