@pikku/core 0.12.69 → 0.12.70

package/src/services/meta-service.test.ts

@@ -0,0 +1,79 @@
+import { describe, test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { LocalMetaService } from './meta-service.js'
+
+/**
+ * Scenarios and their steps are generated into `.pikku/scenarios/` so that no
+ * app-facing module imports them. Everything that reads meta off disk — the
+ * console's scenario list among them — must still see them.
+ */
+describe('LocalMetaService reads the scenario meta alongside the app meta', () => {
+  let pikkuDir: string
+
+  before(async () => {
+    pikkuDir = await mkdtemp(join(tmpdir(), 'pikku-meta-'))
+    await mkdir(join(pikkuDir, 'workflow', 'meta'), { recursive: true })
+    await mkdir(join(pikkuDir, 'scenarios', 'meta'), { recursive: true })
+    await mkdir(join(pikkuDir, 'function'), { recursive: true })
+    await mkdir(join(pikkuDir, 'scenarios'), { recursive: true })
+
+    await writeFile(
+      join(pikkuDir, 'workflow', 'meta', 'orderWorkflow.gen.json'),
+      JSON.stringify({ name: 'orderWorkflow', source: 'dsl' })
+    )
+    await writeFile(
+      join(pikkuDir, 'scenarios', 'meta', 'codeEditorScenario.gen.json'),
+      JSON.stringify({ name: 'codeEditorScenario', source: 'scenario' })
+    )
+    await writeFile(
+      join(pikkuDir, 'function', 'pikku-functions-meta.gen.json'),
+      JSON.stringify({ createTodo: { pikkuFuncId: 'createTodo' } })
+    )
+    await writeFile(
+      join(pikkuDir, 'scenarios', 'pikku-scenario-functions-meta.gen.json'),
+      JSON.stringify({
+        opensPage: { pikkuFuncId: 'opensPage', scenarioStep: true },
+      })
+    )
+  })
+
+  after(async () => {
+    await rm(pikkuDir, { recursive: true, force: true })
+  })
+
+  test('a scenario is still a workflow to whoever reads the meta', async () => {
+    const meta = await new LocalMetaService(pikkuDir).getWorkflowMeta()
+    assert.deepEqual(Object.keys(meta).sort(), [
+      'codeEditorScenario',
+      'orderWorkflow',
+    ])
+    assert.equal(meta['codeEditorScenario']!.source, 'scenario')
+  })
+
+  test('a scenario step is still a function to whoever reads the meta', async () => {
+    const meta = await new LocalMetaService(pikkuDir).getFunctionsMeta()
+    assert.deepEqual(Object.keys(meta).sort(), ['createTodo', 'opensPage'])
+    assert.equal(meta['opensPage']!.scenarioStep, true)
+  })
+
+  test('a project with no scenarios reads exactly what it has', async () => {
+    const empty = await mkdtemp(join(tmpdir(), 'pikku-meta-empty-'))
+    await mkdir(join(empty, 'workflow', 'meta'), { recursive: true })
+    await writeFile(
+      join(empty, 'workflow', 'meta', 'orderWorkflow.gen.json'),
+      JSON.stringify({ name: 'orderWorkflow', source: 'dsl' })
+    )
+
+    const service = new LocalMetaService(empty)
+    assert.deepEqual(Object.keys(await service.getWorkflowMeta()), [
+      'orderWorkflow',
+    ])
+    assert.deepEqual(Object.keys(await service.getFunctionsMeta()), [])
+
+    await rm(empty, { recursive: true, force: true })
+  })
+})

package/src/services/meta-service.ts

@@ -13,7 +13,10 @@ import type {
   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,
@@ -186,6 +189,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>
@@ -226,6 +230,7 @@ export class LocalMetaService implements MetaService {
   private workflowMetaCache: WorkflowsMeta | null = null
   private scenarioActorsMetaCache: Record<string, ScenarioActorConfig> | null =
     null
+  private featuresMetaCache: FeaturesMeta | null = null
   private triggerMetaCache: TriggerMeta | null = null
   private triggerSourceMetaCache: TriggerSourceMeta | null = null
   private functionsMetaCache: FunctionsMeta | null = null
@@ -328,6 +333,7 @@ export class LocalMetaService implements MetaService {
     this.rpcMetaCache = null
     this.workflowMetaCache = null
     this.scenarioActorsMetaCache = null
+    this.featuresMetaCache = null
     this.triggerMetaCache = null
     this.triggerSourceMetaCache = null
     this.functionsMetaCache = null
@@ -456,34 +462,47 @@ export class LocalMetaService implements MetaService {
     }
   }
 
+  private async readWorkflowMetaDir(
+    dir: string,
+    into: WorkflowsMeta
+  ): Promise<void> {
+    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(): Promise<WorkflowsMeta> {
     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: WorkflowsMeta = {}
-      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
@@ -502,6 +521,14 @@ export class LocalMetaService implements MetaService {
     return this.scenarioActorsMetaCache!
   }
 
+  async getFeaturesMeta(): Promise<FeaturesMeta> {
+    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(): Promise<TriggerMeta> {
     if (this.triggerMetaCache) return this.triggerMetaCache
 
@@ -527,8 +554,16 @@ export class LocalMetaService implements MetaService {
   async getFunctionsMeta(): Promise<FunctionsMeta> {
     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!
   }
 

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

@@ -3,14 +3,154 @@ import type {
   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 const readScenarioHttpResponse = async <T = unknown>(
+  res: Response
+): Promise<ScenarioHttpResponse<T>> => {
+  const text = res.status === 204 ? '' : await res.text().catch(() => '')
+  return {
+    status: res.status,
+    ok: res.ok,
+    body: (text ? parseJsonBody(text) : undefined) as T,
+    serialized: text,
+  }
+}
+
+const parseJsonBody = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+/** 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 const postScenarioJson = async <T = unknown>(
+  url: string,
+  {
+    body,
+    headers,
+    method = 'POST',
+    fetch: send = fetch,
+  }: ScenarioJsonRequest = {}
+): Promise<ScenarioHttpResponse<T>> =>
+  readScenarioHttpResponse<T>(
+    await send(url, {
+      method,
+      headers: { 'content-type': 'application/json', ...headers },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    })
+  )
+
+/** 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>
 }
@@ -21,6 +161,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. */

package/src/types/core.types.ts

@@ -22,6 +22,10 @@ import type {
   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'
@@ -30,7 +34,10 @@ 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'
@@ -123,6 +130,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'
@@ -133,6 +149,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
@@ -380,6 +400,7 @@ export type PikkuWire<
   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
@@ -402,7 +423,11 @@ export type PikkuWire<
   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/src/types/state.types.ts

@@ -40,6 +40,7 @@ import type {
 } from '../wirings/scheduler/scheduler.types.js'
 import type {
   CoreWorkflow,
+  CoreFeature,
   WorkflowsRuntimeMeta,
 } from '../wirings/workflow/workflow.types.js'
 import type {
@@ -129,6 +130,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/src/wirings/actor-flow/actor-flow.types.ts

@@ -21,7 +21,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/src/wirings/actor-flow/index.ts

@@ -18,5 +18,5 @@ export type {
 export {
   runConversation,
   type RunConversationParams,
-  type PersonaLLM,
+  type ActorLLM,
 } from './run-conversation.js'

package/src/wirings/actor-flow/run-conversation.test.ts

@@ -1,7 +1,7 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { runConversation, type PersonaLLM } from './run-conversation.js'
+import { runConversation, type ActorLLM } from './run-conversation.js'
 import type {
   TargetAgentDriver,
   TargetAgentReply,
@@ -23,10 +23,10 @@ const scriptedLLM = (script: {
   turns: Array<{ message: string; done: boolean }>
   decisions: Array<{ toolCallId: string; approved: boolean }>
   evaluation: { passed: boolean; reasoning: string }
-}): { llm: PersonaLLM; calls: string[] } => {
+}): { llm: ActorLLM; calls: string[] } => {
   let turn = 0
   const calls: string[] = []
-  const llm: PersonaLLM = async (params) => {
+  const llm: ActorLLM = async (params) => {
     const props =
       (params.outputSchema as { properties?: Record<string, unknown> })
         ?.properties ?? {}
@@ -109,8 +109,8 @@ const alwaysSuspendingTarget = (): {
 }
 
 const base = {
-  persona: { email: 'pm@example.com', name: 'Priya', personality: 'concise' },
-  personaName: 'Priya',
+  actor: { email: 'pm@example.com', name: 'Priya', personality: 'concise' },
+  actorName: 'Priya',
   agentName: 'todoBot',
   task: 'Get a todo created',
   evaluate: 'A todo now exists',
@@ -168,7 +168,13 @@ describe('runConversation', () => {
     const { target, approveCalls } = alwaysSuspendingTarget()
 
     await assert.rejects(
-      runConversation({ ...base, approvals: 'always', maxApprovalRounds: 3, llm, target }),
+      runConversation({
+        ...base,
+        approvals: 'always',
+        maxApprovalRounds: 3,
+        llm,
+        target,
+      }),
       /approval rounds/
     )
     assert.equal(approveCalls(), 3)