@pikku/inspector 0.12.35 → 0.12.37

package/CHANGELOG.md

@@ -1,3 +1,58 @@
+## 0.12.37
+
+### Patch Changes
+
+- efb0406: Add in-process V8 precise coverage (`pikku dev --coverage` / `pikku serve --coverage`) with per-scenario attribution.
+  - `@pikku/core`: new `V8CoverageService` (node:inspector precise coverage with snapshot + reset), exposed as the optional `coverageService` singleton service.
+  - `@pikku/inspector`: function meta now records `bodyStart`/`bodyEnd` body spans (verbose meta only) so coverage can be mapped without a runtime TypeScript dependency.
+  - `@pikku/cli`: `--coverage` on `pikku dev` and `pikku serve` starts the collector in-process; `pikku scenario run --coverage` resets/snapshots the server between flows and writes `.pikku/coverage/scenario-coverage.json` with per-scenario function coverage.
+  - `@pikku/addon-console`: new exposed `takeLiveCoverage` / `resetLiveCoverage` RPCs; V8 ranges are mapped through inline source maps to original TypeScript lines (offset-based, so esbuild/tsx single-line output keeps full resolution).
+
+- Updated dependencies [efb0406]
+- Updated dependencies [fe4f5ca]
+  - @pikku/core@0.12.53
+
+## 0.12.36
+
+### Patch Changes
+
+- 61c9ce9: Add `actor.converse(...)` — actor agents for user journeys (#850)
+
+  An actor can now hold a dynamic, LLM-driven conversation with a target Pikku AI
+  agent in its own persona:
+
+  ```ts
+  const verdict = await actors.pm.converse({
+    agent: 'todoBot',
+    task: 'Get a todo created for the launch',
+    evaluate: 'A todo about the launch now exists',
+  })
+  // verdict: { passed, reasoning, transcript }
+  // then assert deterministically as the same actor:
+  const todos = await actors.pm.invoke('listTodos', {})
+  ```
+
+  The actor drives the target over the real transport (the agent's own
+  `agentRun` / `agentApprove` HTTP routes, signed in as the actor), plays the
+  persona from its `pikku.config.json` config, answers the agent's tool-approval
+  requests in-persona (`approvals: 'in-persona' | 'always' | 'never'`), and
+  returns its verdict on whether the task was met. Deterministic checks stay the
+  caller's job — they already hold the actor.
+
+  The conversation engine is transport-agnostic (persona LLM + injected target
+  driver); the persona's own turns run in-process via the configured
+  `aiAgentRunner` (`model` from the call or the actors-service default).
+
+  `agent` is typed against the generated agent-name union (`keyof AgentMap`), so
+  it's author-time checked and autocompleted in a typed project.
+
+- 472a349: Rename the userflow concept to scenario (#862). `pikkuUserFlow` becomes `pikkuScenario`, `pikku userflow run/list` becomes `pikku scenario run/list`, the workflow meta flag `userFlow` becomes `scenario`, actor types are now `ScenarioActor`/`ScenarioActors`/`ScenarioActorConfig` (`createHttpScenarioActors`), pikku.config.json's `userFlows` key becomes `scenarios`, the generated actors file is `pikku-scenario-actors.gen.ts` (`createScenarioActors`), the actor sign-in secret env var is `SCENARIO_ACTOR_SECRET`, and the console's User Flows view is now Scenarios.
+- Updated dependencies [61c9ce9]
+- Updated dependencies [f1f39f8]
+- Updated dependencies [c45e98d]
+- Updated dependencies [472a349]
+  - @pikku/core@0.12.52
+
 ## 0.12.35
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -251,10 +251,10 @@ export const addFunctions = (logger, node, checker, state, options) => {
         return;
     }
     // Match identifiers that contain both "pikku" and "func" (case insensitive),
-    // plus pikkuUserFlow (a workflow wrapper without "func" in its name)
+    // plus pikkuScenario (a workflow wrapper without "func" in its name)
     const pikkuFuncPattern = /pikku.*func/i;
     if (!pikkuFuncPattern.test(expression.text) &&
-        expression.text !== 'pikkuUserFlow') {
+        expression.text !== 'pikkuScenario') {
         return;
     }
     // only handle calls like pikkuFunc(...)
@@ -727,6 +727,21 @@ export const addFunctions = (logger, node, checker, state, options) => {
         objectNode,
         isDirectFunction,
     });
+    const handlerSourceFile = handler.getSourceFile();
+    const bodySourceFile = handlerSourceFile.fileName !== sourceFile
+        ? handlerSourceFile.fileName
+        : undefined;
+    const lineOf = (pos) => handlerSourceFile.getLineAndCharacterOfPosition(pos).line + 1;
+    const handlerBody = handler.body;
+    const bodySpan = ts.isBlock(handlerBody) && handlerBody.statements.length > 0
+        ? {
+            bodyStart: lineOf(handlerBody.statements[0].getStart(handlerSourceFile)),
+            bodyEnd: lineOf(handlerBody.statements[handlerBody.statements.length - 1].getEnd()),
+        }
+        : {
+            bodyStart: lineOf(handlerBody.getStart(handlerSourceFile)),
+            bodyEnd: lineOf(handlerBody.getEnd()),
+        };
     state.functions.meta[pikkuFuncId] = {
         pikkuFuncId,
         functionType: 'user',
@@ -760,7 +775,9 @@ export const addFunctions = (logger, node, checker, state, options) => {
         permissions,
         isDirectFunction,
         sourceFile,
+        bodySourceFile,
         exportedName: exportedName || undefined,
+        ...bodySpan,
     };
     // Populate node metadata if node config is present
     if (nodeDisplayName && nodeCategory && nodeType) {

package/dist/add/add-workflow.d.ts

@@ -6,6 +6,6 @@ import type { WorkflowStepMeta } from '@pikku/core/workflow';
 export declare function collectInvokedRPCs(steps: WorkflowStepMeta[], rpcs: Set<string>): void;
 /**
  * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
- * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
+ * pikkuScenario() calls. Detects workflow registration and extracts metadata.
  */
 export declare const addWorkflow: AddWiring;

package/dist/add/add-workflow.js

@@ -19,6 +19,25 @@ function extractStepName(node, checker) {
         return getSourceText(node);
     }
 }
+/**
+ * Walk a function body for any `X.expectEventually(...)` call. Used to enforce
+ * that the durable-polling assertion is a scenario-only primitive — regular
+ * workflows must not carry test/assertion semantics.
+ */
+function containsExpectEventuallyCall(node) {
+    if (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === 'expectEventually') {
+        return true;
+    }
+    let found = false;
+    ts.forEachChild(node, (child) => {
+        if (!found && !ts.isFunctionDeclaration(child)) {
+            found = containsExpectEventuallyCall(child);
+        }
+    });
+    return found;
+}
 /**
  * Recursively check if any step has inline type (non-serializable)
  */
@@ -177,7 +196,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
 }
 /**
  * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
- * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
+ * pikkuScenario() calls. Detects workflow registration and extracts metadata.
  */
 export const addWorkflow = (logger, node, checker, state) => {
     if (!ts.isCallExpression(node)) {
@@ -196,10 +215,10 @@ export const addWorkflow = (logger, node, checker, state) => {
     else if (expression.text === 'pikkuWorkflowComplexFunc') {
         wrapperType = 'complex';
     }
-    else if (expression.text === 'pikkuUserFlow') {
-        // A user flow is a complex workflow whose steps run as actors over the
+    else if (expression.text === 'pikkuScenario') {
+        // A scenario is a complex workflow whose steps run as actors over the
         // real transport — same extraction rules as complex, distinct meta.
-        wrapperType = 'user-flow';
+        wrapperType = 'scenario';
     }
     else {
         return;
@@ -244,6 +263,13 @@ export const addWorkflow = (logger, node, checker, state) => {
         logger.critical(ErrorCode.MISSING_FUNC, `Could not resolve workflow function for '${workflowName}'.`);
         return;
     }
+    if (wrapperType !== 'scenario' &&
+        containsExpectEventuallyCall(resolvedFunc)) {
+        logger.critical(ErrorCode.EXPECT_EVENTUALLY_SCENARIO_ONLY, `Workflow '${workflowName}' calls workflow.expectEventually(), which is only ` +
+            `available in scenarios (pikkuScenario). Move it into a scenario, or drive ` +
+            `the assertion outside the workflow.`);
+        return;
+    }
     // Track workflow file for wiring generation
     if (exportedName) {
         state.workflows.files.set(pikkuFuncId, {
@@ -308,8 +334,8 @@ export const addWorkflow = (logger, node, checker, state) => {
         const sink = steps.length > 0 ? [] : steps;
         getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink);
     }
-    // Actor names the flow's steps run as (user flows) — powers the console
-    // personas view and the User Flow graph badges.
+    // Actor names the flow's steps run as (scenarios) — powers the console
+    // personas view and the Scenario graph badges.
     const actorNames = [
         ...new Set(steps
             .map((s) => ('actor' in s ? s.actor : undefined))
@@ -327,19 +353,19 @@ export const addWorkflow = (logger, node, checker, state) => {
         errors,
         tags,
         expose,
-        userFlow: wrapperType === 'user-flow' ? true : undefined,
+        scenario: wrapperType === 'scenario' ? true : undefined,
         actors: actorNames.length > 0 ? actorNames : undefined,
     };
-    // User flows are pure stories of remote RPCs (same rule as client-side CLI
+    // Scenarios are pure stories of remote RPCs (same rule as client-side CLI
     // renderers): the func may only destructure logger/config — everything else
     // must go through actor steps so the flow runs against the TARGET
     // environment, never local services.
     const funcMeta = state.functions.meta[pikkuFuncId];
-    if (wrapperType === 'user-flow' && funcMeta?.services) {
+    if (wrapperType === 'scenario' && funcMeta?.services) {
         const disallowed = funcMeta.services.services.filter((svc) => svc !== 'logger' && svc !== 'config');
         if (disallowed.length > 0) {
-            logger.critical(ErrorCode.USER_FLOW_HAS_SERVICES, `User flow '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
-                `User flows may only use 'logger'/'config' — drive everything else through ` +
+            logger.critical(ErrorCode.SCENARIO_HAS_SERVICES, `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+                `Scenarios may only use 'logger'/'config' — drive everything else through ` +
                 `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
                 `runs against the target environment.`);
             return;

package/dist/error-codes.d.ts

@@ -19,7 +19,8 @@ export declare enum ErrorCode {
     MISSING_QUEUE_NAME = "PKU384",
     MISSING_CHANNEL_NAME = "PKU400",
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
-    USER_FLOW_HAS_SERVICES = "PKU673",
+    SCENARIO_HAS_SERVICES = "PKU673",
+    EXPECT_EVENTUALLY_SCENARIO_ONLY = "PKU675",
     DYNAMIC_STEP_NAME = "PKU529",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",

package/dist/error-codes.js

@@ -21,7 +21,8 @@ export var ErrorCode;
     ErrorCode["MISSING_QUEUE_NAME"] = "PKU384";
     ErrorCode["MISSING_CHANNEL_NAME"] = "PKU400";
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
-    ErrorCode["USER_FLOW_HAS_SERVICES"] = "PKU673";
+    ErrorCode["SCENARIO_HAS_SERVICES"] = "PKU673";
+    ErrorCode["EXPECT_EVENTUALLY_SCENARIO_ONLY"] = "PKU675";
     ErrorCode["DYNAMIC_STEP_NAME"] = "PKU529";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -4,7 +4,7 @@ import * as ts from 'typescript';
  */
 /**
  * Check if a call expression is workflow.do() or workflow.expectEventually()
- * (both are RPC steps; expectEventually is the polling variant used by user flows)
+ * (both are RPC steps; expectEventually is the polling variant used by scenarios)
  */
 export declare function isWorkflowDoCall(node: ts.CallExpression, checker: ts.TypeChecker): boolean;
 /**

package/dist/utils/workflow/dsl/patterns.js

@@ -4,7 +4,7 @@ import * as ts from 'typescript';
  */
 /**
  * Check if a call expression is workflow.do() or workflow.expectEventually()
- * (both are RPC steps; expectEventually is the polling variant used by user flows)
+ * (both are RPC steps; expectEventually is the polling variant used by scenarios)
  */
 export function isWorkflowDoCall(node, checker) {
     if (!ts.isPropertyAccessExpression(node.expression)) {

package/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -298,11 +298,11 @@ export function convertDslToGraph(workflowName, meta) {
     }
     const entryNodeIds = nodes.length > 0 ? [nodes[0].nodeId] : [];
     // Determine source type:
-    // - userFlow: complex workflow whose steps run as actors (user flow)
+    // - scenario: complex workflow whose steps run as actors (scenario)
     // - dsl === true: pure DSL workflow, can be serialized
     // - dsl === false: complex workflow with inline steps, not serializable
-    const source = meta.userFlow
-        ? 'user-flow'
+    const source = meta.scenario
+        ? 'scenario'
         : meta.dsl === false
             ? 'complex'
             : 'dsl';

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -96,9 +96,9 @@ export interface FunctionNode extends BaseNode {
     outputVar?: string;
     /** Hash of nodeId + RPC input/output schemas for version detection */
     stepHash?: string;
-    /** User-flow actor name this step runs as (workflow.do {actor: actors.x}) */
+    /** Scenario actor name this step runs as (workflow.do {actor: actors.x}) */
     actor?: string;
-    /** True for workflow.expectEventually polling steps (user flows) */
+    /** True for workflow.expectEventually polling steps (scenarios) */
     expectEventually?: boolean;
 }
 /**
@@ -127,9 +127,9 @@ export declare const isFlowNode: (node: SerializedGraphNode) => node is FlowNode
  * - 'dsl': Pure DSL workflow (pikkuWorkflowFunc) - can be round-tripped to code
  * - 'complex': Complex workflow (pikkuWorkflowComplexFunc) - contains inline steps, not serializable
  * - 'graph': Graph-based workflow (pikkuWorkflowGraph)
- * - 'user-flow': User flow (pikkuUserFlow) - complex workflow whose steps run as actors
+ * - 'scenario': Scenario (pikkuScenario) - complex workflow whose steps run as actors
  */
-export type WorkflowSourceType = 'dsl' | 'complex' | 'graph' | 'user-flow';
+export type WorkflowSourceType = 'dsl' | 'complex' | 'graph' | 'scenario';
 /**
  * Serialized workflow graph - the canonical JSON format
  */
@@ -146,7 +146,7 @@ export interface SerializedWorkflowGraph {
     description?: string;
     /** Tags for organization */
     tags?: string[];
-    /** Actor names a user flow's steps run as */
+    /** Actor names a scenario's steps run as */
     actors?: string[];
     /** If true, workflow always executes inline without queues */
     inline?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.35",
+  "version": "0.12.37",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.51",
+    "@pikku/core": "^0.12.53",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "2.9.1-next.16",

package/src/add/add-functions.ts

@@ -358,11 +358,11 @@ export const addFunctions: AddWiring = (
   }
 
   // Match identifiers that contain both "pikku" and "func" (case insensitive),
-  // plus pikkuUserFlow (a workflow wrapper without "func" in its name)
+  // plus pikkuScenario (a workflow wrapper without "func" in its name)
   const pikkuFuncPattern = /pikku.*func/i
   if (
     !pikkuFuncPattern.test(expression.text) &&
-    expression.text !== 'pikkuUserFlow'
+    expression.text !== 'pikkuScenario'
   ) {
     return
   }
@@ -494,9 +494,15 @@ export const addFunctions: AddWiring = (
     approvalRequired = getPropertyValue(firstArg, 'approvalRequired') as
       | boolean
       | undefined
-    workflowQueued = getPropertyValue(firstArg, 'workflowQueued') as boolean | undefined
-    workflowRetries = getPropertyValue(firstArg, 'workflowRetries') as number | undefined
-    workflowTimeout = getPropertyValue(firstArg, 'workflowTimeout') as string | undefined
+    workflowQueued = getPropertyValue(firstArg, 'workflowQueued') as
+      | boolean
+      | undefined
+    workflowRetries = getPropertyValue(firstArg, 'workflowRetries') as
+      | number
+      | undefined
+    workflowTimeout = getPropertyValue(firstArg, 'workflowTimeout') as
+      | string
+      | undefined
 
     // Extract approvalDescription identifier reference
     for (const prop of firstArg.properties) {
@@ -1016,6 +1022,29 @@ export const addFunctions: AddWiring = (
     isDirectFunction,
   })
 
+  const handlerSourceFile = handler.getSourceFile()
+  const bodySourceFile =
+    handlerSourceFile.fileName !== sourceFile
+      ? handlerSourceFile.fileName
+      : undefined
+  const lineOf = (pos: number) =>
+    handlerSourceFile.getLineAndCharacterOfPosition(pos).line + 1
+  const handlerBody = handler.body
+  const bodySpan =
+    ts.isBlock(handlerBody) && handlerBody.statements.length > 0
+      ? {
+          bodyStart: lineOf(
+            handlerBody.statements[0].getStart(handlerSourceFile)
+          ),
+          bodyEnd: lineOf(
+            handlerBody.statements[handlerBody.statements.length - 1].getEnd()
+          ),
+        }
+      : {
+          bodyStart: lineOf(handlerBody.getStart(handlerSourceFile)),
+          bodyEnd: lineOf(handlerBody.getEnd()),
+        }
+
   state.functions.meta[pikkuFuncId] = {
     pikkuFuncId,
     functionType: 'user',
@@ -1049,7 +1078,9 @@ export const addFunctions: AddWiring = (
     permissions,
     isDirectFunction,
     sourceFile,
+    bodySourceFile,
     exportedName: exportedName || undefined,
+    ...bodySpan,
   }
 
   // Populate node metadata if node config is present

package/src/add/add-workflow.ts

@@ -34,6 +34,28 @@ function extractStepName(node: ts.Node, checker: ts.TypeChecker): string {
   }
 }
 
+/**
+ * Walk a function body for any `X.expectEventually(...)` call. Used to enforce
+ * that the durable-polling assertion is a scenario-only primitive — regular
+ * workflows must not carry test/assertion semantics.
+ */
+function containsExpectEventuallyCall(node: ts.Node): boolean {
+  if (
+    ts.isCallExpression(node) &&
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'expectEventually'
+  ) {
+    return true
+  }
+  let found = false
+  ts.forEachChild(node, (child) => {
+    if (!found && !ts.isFunctionDeclaration(child)) {
+      found = containsExpectEventuallyCall(child)
+    }
+  })
+  return found
+}
+
 /**
  * Recursively check if any step has inline type (non-serializable)
  */
@@ -155,7 +177,9 @@ function getWorkflowInvocations(
               stepName,
               rpcName,
               expectEventually: true,
-              actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+              actor: extractActorFromOptions(
+                args.length >= 5 ? args[4] : undefined
+              ),
             })
             state.rpc.invokedFunctions.add(rpcName)
           }
@@ -194,7 +218,7 @@ function getWorkflowInvocations(
 
 /**
  * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
- * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
+ * pikkuScenario() calls. Detects workflow registration and extracts metadata.
  */
 export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   if (!ts.isCallExpression(node)) {
@@ -209,15 +233,15 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     return
   }
 
-  let wrapperType: 'dsl' | 'complex' | 'user-flow' | null = null
+  let wrapperType: 'dsl' | 'complex' | 'scenario' | null = null
   if (expression.text === 'pikkuWorkflowFunc') {
     wrapperType = 'dsl'
   } else if (expression.text === 'pikkuWorkflowComplexFunc') {
     wrapperType = 'complex'
-  } else if (expression.text === 'pikkuUserFlow') {
-    // A user flow is a complex workflow whose steps run as actors over the
+  } else if (expression.text === 'pikkuScenario') {
+    // A scenario is a complex workflow whose steps run as actors over the
     // real transport — same extraction rules as complex, distinct meta.
-    wrapperType = 'user-flow'
+    wrapperType = 'scenario'
   } else {
     return
   }
@@ -292,6 +316,19 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     return
   }
 
+  if (
+    wrapperType !== 'scenario' &&
+    containsExpectEventuallyCall(resolvedFunc)
+  ) {
+    logger.critical(
+      ErrorCode.EXPECT_EVENTUALLY_SCENARIO_ONLY,
+      `Workflow '${workflowName}' calls workflow.expectEventually(), which is only ` +
+        `available in scenarios (pikkuScenario). Move it into a scenario, or drive ` +
+        `the assertion outside the workflow.`
+    )
+    return
+  }
+
   // Track workflow file for wiring generation
   if (exportedName) {
     state.workflows.files.set(pikkuFuncId, {
@@ -368,8 +405,8 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink)
   }
 
-  // Actor names the flow's steps run as (user flows) — powers the console
-  // personas view and the User Flow graph badges.
+  // Actor names the flow's steps run as (scenarios) — powers the console
+  // personas view and the Scenario graph badges.
   const actorNames = [
     ...new Set(
       steps
@@ -390,24 +427,24 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     errors,
     tags,
     expose,
-    userFlow: wrapperType === 'user-flow' ? true : undefined,
+    scenario: wrapperType === 'scenario' ? true : undefined,
     actors: actorNames.length > 0 ? actorNames : undefined,
   }
 
-  // User flows are pure stories of remote RPCs (same rule as client-side CLI
+  // Scenarios are pure stories of remote RPCs (same rule as client-side CLI
   // renderers): the func may only destructure logger/config — everything else
   // must go through actor steps so the flow runs against the TARGET
   // environment, never local services.
   const funcMeta = state.functions.meta[pikkuFuncId]
-  if (wrapperType === 'user-flow' && funcMeta?.services) {
+  if (wrapperType === 'scenario' && funcMeta?.services) {
     const disallowed = funcMeta.services.services.filter(
       (svc) => svc !== 'logger' && svc !== 'config'
     )
     if (disallowed.length > 0) {
       logger.critical(
-        ErrorCode.USER_FLOW_HAS_SERVICES,
-        `User flow '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
-          `User flows may only use 'logger'/'config' — drive everything else through ` +
+        ErrorCode.SCENARIO_HAS_SERVICES,
+        `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+          `Scenarios may only use 'logger'/'config' — drive everything else through ` +
           `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
           `runs against the target environment.`
       )

package/src/add/expect-eventually-scenario-only.test.ts

@@ -0,0 +1,108 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { InspectorLogger } from '../types.js'
+
+function makeLogger(
+  criticals: Array<{ code: string; message: string }>
+): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: any, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+}
+
+const stepFile = (dir: string) => join(dir, 'my.steps.ts')
+const stepSource = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const getTodos = pikkuSessionlessFunc({',
+  '  func: async ({ logger }) => [{ done: true }],',
+  '})',
+].join('\n')
+
+describe('expectEventually is scenario-only', () => {
+  test('pikkuWorkflowFunc calling expectEventually is a critical error pointing at pikkuScenario', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-ee-wf-'))
+    const wfFile = join(rootDir, 'my.workflow.ts')
+    await writeFile(stepFile(rootDir), stepSource)
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const badWorkflow = pikkuWorkflowFunc(async (_, _input, { workflow }) => {',
+        "  await workflow.expectEventually('Wait', 'getTodos', {}, (todos: any) => todos.length > 0)",
+        '  return { ok: true }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      await inspect(makeLogger(criticals), [stepFile(rootDir), wfFile], {
+        rootDir,
+      })
+      const pku675 = criticals.find((c) => c.code === 'PKU675')
+      assert.ok(
+        pku675,
+        `expected a PKU675 critical, got: ${JSON.stringify(criticals)}`
+      )
+      assert.ok(
+        pku675.message.includes('pikkuScenario'),
+        `PKU675 should point users at pikkuScenario, got: ${pku675.message}`
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('pikkuScenario calling expectEventually is allowed and flagged as a scenario', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-ee-sc-'))
+    const wfFile = join(rootDir, 'my.scenario.ts')
+    await writeFile(stepFile(rootDir), stepSource)
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuScenario } from '@pikku/core/workflow'",
+        'declare const actors: Record<string, any>',
+        'export const goodFlow = pikkuScenario(async (_, _input, { workflow }) => {',
+        "  await workflow.expectEventually('Wait', 'getTodos', {}, (todos: any) => todos.length > 0, { actor: actors.pm })",
+        '  return { ok: true }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      const state = await inspect(
+        makeLogger(criticals),
+        [stepFile(rootDir), wfFile],
+        { rootDir }
+      )
+      assert.ok(
+        !criticals.some((c) => c.code === 'PKU675'),
+        `scenarios may use expectEventually; got: ${JSON.stringify(criticals)}`
+      )
+      const meta = (state.workflows.meta as any).goodFlow
+      assert.ok(meta, 'pikkuScenario export should register a workflow')
+      assert.equal(
+        meta.scenario,
+        true,
+        `scenario meta flag should be true, got: ${JSON.stringify(meta)}`
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})