@pikku/core 0.12.71 → 0.12.74

package/src/services/credential-service.ts

@@ -1,57 +1,20 @@
 /**
- * Interface for managing dynamic/managed credentials.
- * Used for OAuth tokens, per-user API keys, and other credentials
- * that change at runtime (as opposed to SecretService which is for
- * static, developer-configured values).
+ * Dynamic credentials — OAuth tokens, per-user API keys — that change at
+ * runtime, as opposed to `SecretService`'s static developer-configured values.
+ * Throughout, an omitted `userId` means the platform-level credential.
  */
 export interface CredentialService {
-  /**
-   * Retrieves a credential by name and optional user ID.
-   * @param name - The credential name (e.g. 'stripe', 'google-sheets').
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   * @returns The credential value, or null if not found.
-   */
   get<T = unknown>(name: string, userId?: string): Promise<T | null>
 
-  /**
-   * Stores a credential.
-   * @param name - The credential name.
-   * @param value - The credential value to store.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   set(name: string, value: unknown, userId?: string): Promise<void>
 
-  /**
-   * Deletes a credential.
-   * @param name - The credential name.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   delete(name: string, userId?: string): Promise<void>
 
-  /**
-   * Checks if a credential exists.
-   * @param name - The credential name.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   has(name: string, userId?: string): Promise<boolean>
 
-  /**
-   * Retrieves all credentials for a user.
-   * @param userId - The user ID.
-   * @returns A record of credential name to value.
-   */
   getAll(userId: string): Promise<Record<string, unknown>>
 
-  /**
-   * Lists all user IDs that have a specific credential configured.
-   * @param name - The credential name.
-   * @returns Array of user IDs.
-   */
   getUsersWithCredential(name: string): Promise<string[]>
 
-  /**
-   * Lists all unique user IDs that have any credential configured.
-   * @returns Array of user IDs.
-   */
   getAllUsers(): Promise<string[]>
 }

package/src/services/credential-wire-service.test.ts

@@ -29,9 +29,7 @@ describe('PikkuCredentialWireService', () => {
   test('should return sync after first load (no credential service)', async () => {
     const service = new PikkuCredentialWireService()
     service.set('foo', 'bar')
-    // First call triggers lazy load (no-op without credentialService)
     await service.getAll()
-    // Second call should be sync
     const result = service.getAll()
     assert.ok(!(result instanceof Promise), 'expected sync return')
     assert.deepStrictEqual(result, { foo: 'bar' })

package/src/services/deployment-service.ts

@@ -19,15 +19,9 @@ export interface DeploymentService {
   start(config: DeploymentConfig): Promise<void>
   stop(): Promise<void>
   /**
-   * Dispatch a remote RPC call to a function.
-   * The deployment service owns the full transport:
-   * - Resolving the target (endpoint, service binding, etc.)
-   * - Session propagation (JWT signing, headers)
-   * - The actual network call
-   *
-   * @param funcName - The function to invoke
-   * @param data - Input data for the function
-   * @param session - User session to propagate (optional)
+   * The implementation owns the whole transport: resolving the target
+   * (endpoint, service binding), propagating the session (JWT signing,
+   * headers) and making the call. Callers supply no transport detail.
    */
   invoke(
     funcName: string,

package/src/services/gateway-service.ts

@@ -1,20 +1,5 @@
-/**
- * Abstract GatewayService interface.
- *
- * Implementations manage listener gateway lifecycle — initializing adapters
- * and delivering messages to handler functions.
- *
- * A `LocalGatewayService` starts all listeners unconditionally;
- * a distributed implementation could check leader election first.
- */
 export interface GatewayService {
-  /**
-   * Start all listener gateways
-   */
   start(): Promise<void>
 
-  /**
-   * Stop all listener gateways
-   */
   stop(): Promise<void>
 }

package/src/services/{http-scenario-actors-converse.test.ts → http-personas-converse.test.ts}

@@ -2,7 +2,7 @@ import { describe, test, after } from 'node:test'
 import assert from 'node:assert/strict'
 import { createServer, type Server } from 'node:http'
 
-import { createHttpScenarioActors } from './http-scenario-actors.js'
+import { createHttpPersonas } from './http-personas.js'
 import { pikkuState, resetPikkuState } from '../pikku-state.js'
 import type { AIAgentStepResult } from './ai-agent-runner-service.js'
 
@@ -139,7 +139,7 @@ const wireRunner = () => {
   } as any)
 }
 
-describe('HttpScenarioActor.converse', async () => {
+describe('HttpPersona.converse', async () => {
   const target = await startAgentTarget()
   after(() => {
     target.server.close()
@@ -150,12 +150,21 @@ describe('HttpScenarioActor.converse', async () => {
     wireRunner()
     target.reset()
 
-    const actors = createHttpScenarioActors({
+    const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
       secret: 'impersonation-secret',
       model: 'test/test-model',
-      actors: {
-        pm: { email: 'pm@actors.local', name: 'Priya', personality: 'concise' },
+      personas: {
+        pm: {
+          id: 'pm',
+          name: 'Priya',
+          email: 'pm@personas.invalid',
+          personality: 'concise',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
       },
     })
 
@@ -179,11 +188,21 @@ describe('HttpScenarioActor.converse', async () => {
     wireRunner()
     target.reset({ authRequired: true })
 
-    const actors = createHttpScenarioActors({
+    const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
       secret: 'impersonation-secret',
       model: 'test/test-model',
-      actors: { pm: { email: 'pm@actors.local' } },
+      personas: {
+        pm: {
+          id: 'pm',
+          name: 'Priya',
+          email: 'pm@personas.invalid',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
     })
 
     const verdict = await actors.pm!.converse({
@@ -208,11 +227,21 @@ describe('HttpScenarioActor.converse', async () => {
       },
     } as any)
 
-    const actors = createHttpScenarioActors({
+    const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
       secret: 'impersonation-secret',
       model: 'test/test-model',
-      actors: { pm: { email: 'pm@actors.local' } },
+      personas: {
+        pm: {
+          id: 'pm',
+          name: 'Priya',
+          email: 'pm@personas.invalid',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
     })
 
     await assert.rejects(

package/src/services/{http-scenario-actors.test.ts → http-personas.test.ts}

@@ -2,10 +2,10 @@ import { describe, test, after } from 'node:test'
 import assert from 'node:assert/strict'
 import { createServer, type Server } from 'node:http'
 
-import { createHttpScenarioActors } from './http-scenario-actors.js'
+import { createHttpPersonas } from './http-personas.js'
 
-// Minimal target app: actor sign-in endpoint + exposed RPC endpoint, session
-// via cookie. Mirrors the Better Auth actor plugin's contract.
+// Minimal target app mirroring the Better Auth actor plugin's contract:
+// sign-in endpoint, exposed RPC endpoint, session by cookie.
 const startTarget = async () => {
   let logins = 0
   let expireNext = false
@@ -78,29 +78,46 @@ const startTarget = async () => {
   }
 }
 
-describe('HttpScenarioActor', async () => {
+describe('HttpPersona', async () => {
   const target = await startTarget()
   after(() => target.server.close())
 
-  const makeActors = (secret = 'impersonation-secret') =>
-    createHttpScenarioActors({
+  const makePersonas = (secret = 'impersonation-secret') =>
+    createHttpPersonas({
       apiUrl: target.apiUrl,
       secret,
-      actors: {
-        customer: { email: 'customer@actors.local', jobTitle: 'Buyer' },
-        manager: { email: 'manager@actors.local' },
+      personas: {
+        customer: {
+          id: 'customer',
+          name: 'Customer',
+          email: 'customer@personas.invalid',
+          jobTitle: 'Buyer',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+        manager: {
+          id: 'manager',
+          name: 'Manager',
+          email: 'manager@personas.invalid',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
       },
     })
 
-  test('builds one lazy actor per config entry', () => {
-    const actors = makeActors()
+  test('builds one lazy persona per declaration', () => {
+    const actors = makePersonas()
     assert.deepEqual(Object.keys(actors).sort(), ['customer', 'manager'])
     assert.equal(actors.customer!.name, 'customer')
     assert.equal(target.loginCount(), 0, 'no login until first invoke')
   })
 
   test('logs in lazily once and replays the session cookie on RPCs', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
 
     const first = (await actors.customer!.invoke('createTodo', {
       title: 'x',
@@ -120,7 +137,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('re-logs-in once when the session expires mid-run', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     await actors.manager!.invoke('ping', {})
     const loginsBefore = target.loginCount()
 
@@ -132,7 +149,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw returns the status and body instead of throwing', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
 
     // 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.
@@ -147,7 +164,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw reports a success the same way', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw('listTodos', { page: 2 })
 
     assert.equal(res.status, 200)
@@ -156,7 +173,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw carries the response text so a step can search it', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.customer!.invokeRaw('forbidden', {})
 
     assert.match(res.serialized, /MissingScopeError/)
@@ -164,7 +181,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw keeps a non-JSON error body instead of failing to parse it', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw('html-error', {})
 
     assert.equal(res.status, 500)
@@ -174,14 +191,14 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw reports an empty body as an empty string', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw('listTodos', {})
 
     assert.equal(typeof res.serialized, 'string')
   })
 
   test('invokeRaw passes extra headers through', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw(
       'whoAmI',
       {},
@@ -192,7 +209,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invoke still throws on a refusal, naming the status and body', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     await assert.rejects(
       actors.customer!.invoke('forbidden', {}),
       /'forbidden' as 'customer' returned 403.*MissingScopeError/
@@ -200,10 +217,10 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('a wrong impersonation secret surfaces status and body', async () => {
-    const actors = makeActors('wrong-secret')
+    const actors = makePersonas('wrong-secret')
     await assert.rejects(
       actors.customer!.invoke('ping', {}),
-      /actor sign-in failed for 'customer' \(401\).*bad actor secret/
+      /persona sign-in failed for 'customer' \(401\).*bad actor secret/
     )
   })
 })

package/src/services/{http-scenario-actors.ts → http-personas.ts}

@@ -1,11 +1,11 @@
 import type {
-  ScenarioActor,
-  ScenarioActorConfig,
-  ScenarioActors,
+  ScenarioPersona,
+  ResolvedPersona,
+  ScenarioPersonas,
   ScenarioInvokeOptions,
   ScenarioHttpResponse,
-} from './scenario-actors-service.js'
-import { readScenarioHttpResponse } from './scenario-actors-service.js'
+} from './personas-service.js'
+import { readScenarioHttpResponse } from './personas-service.js'
 import type {
   ConverseOptions,
   ActorFlowVerdict,
@@ -19,42 +19,44 @@ import {
 import { getSingletonServices } from '../pikku-state.js'
 import { AIProviderNotConfiguredError } from '../errors/errors.js'
 
-export interface HttpScenarioActorsConfig {
+export interface HttpPersonasConfig {
   /**
    * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
-   * `https://app.example.com/api` or `http://localhost:4000/api`. Actor
-   * sign-in is reached at `${apiUrl}${signInPath}` and exposed RPCs at
+   * `https://app.example.com/api` or `http://localhost:4000/api`. Sign-in is
+   * reached at `${apiUrl}${signInPath}` and exposed RPCs at
    * `${apiUrl}${rpcPath}/:rpcName`.
    */
   apiUrl: string
   /**
-   * The actor impersonation secret. Sign-in only ever works for user rows
-   * flagged `actor: true` — knowing the secret never impersonates real users.
+   * The impersonation secret. Sign-in only ever works for user rows flagged
+   * `actor: true` — knowing the secret never impersonates real users.
    */
   secret: string
-  /** Actor name → config (usually from pikku.config.json's actor registry). */
-  actors: Record<string, ScenarioActorConfig>
+  /** Persona id → the declaration with its address filled in. */
+  personas: Record<string, ResolvedPersona>
   /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
   signInPath?: string
+  /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
+  sessionPath?: string
   /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
   rpcPath?: string
   /**
-   * Default model the persona uses when `actor.converse(...)` is called without
-   * an explicit `model`. The persona's own turns/approvals/evaluation run
-   * in-process via the configured `aiAgentRunner`.
+   * Default model a persona thinks with when `converse(...)` is called without
+   * an explicit `model`. Its own turns/approvals/evaluation run in-process via
+   * the configured `aiAgentRunner`.
    */
   model?: string
 }
 
 /**
- * Default HTTP-backed actor. Signs in lazily on first invoke via the Better
+ * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
  * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
  * the plugin upserts the actor-flagged user row and mints a session whose
  * `actor` flag flows into audits/analytics). Holds the session cookies for
  * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
  * outlive a session).
  */
-export class HttpScenarioActor implements ScenarioActor {
+export class HttpPersona implements ScenarioPersona {
   private jar: ScenarioCookieJar
   /**
    * Whether `login()` has succeeded since the last time the session was
@@ -66,14 +68,14 @@ export class HttpScenarioActor implements ScenarioActor {
 
   constructor(
     readonly name: string,
-    private actorConfig: ScenarioActorConfig,
-    private config: HttpScenarioActorsConfig
+    private persona: ResolvedPersona,
+    private config: HttpPersonasConfig
   ) {
     this.jar = createCookieJar(config.apiUrl)
   }
 
   get email(): string {
-    return this.actorConfig.email
+    return this.persona.email
   }
 
   async invoke(rpcName: string, data: unknown): Promise<unknown> {
@@ -112,15 +114,15 @@ export class HttpScenarioActor implements ScenarioActor {
     const model = options.model ?? this.config.model
     if (!model) {
       throw new Error(
-        `[scenario] actor '${this.name}' converse needs a model — pass options.model or set 'model' on the actors service`
+        `[scenario] persona '${this.name}' converse needs a model — pass options.model or set 'model' on the personas service`
       )
     }
     const threadId = globalThis.crypto.randomUUID()
-    const resourceId = `actor:${this.name}`
+    const resourceId = `persona:${this.name}`
 
     return runConversation({
-      actor: this.actorConfig,
-      actorName: this.actorConfig.name ?? this.name,
+      persona: this.persona,
+      personaId: this.name,
       agentName: options.agent,
       task: options.task,
       evaluate: options.evaluate,
@@ -137,7 +139,51 @@ export class HttpScenarioActor implements ScenarioActor {
     })
   }
 
-  /** Start/continue the target agent's run over HTTP as this actor. */
+  /**
+   * The roles the stage says this session holds.
+   *
+   * Read from better-auth's `get-session`, which is what most pikku apps are
+   * running and where its admin plugin puts `role` — on the user, as a
+   * comma-separated list. A target that answers something else returns `null`
+   * rather than an empty list, because "this stage does not report roles" and
+   * "this person has none" call for opposite responses from the caller.
+   */
+  async sessionRoles(): Promise<string[] | null> {
+    if (!this.signedIn) {
+      await this.login()
+    }
+    const sessionPath = this.config.sessionPath ?? '/auth/get-session'
+    const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`)
+    if (!res.ok) {
+      return null
+    }
+    const text = await res.text().catch(() => '')
+    if (!text) {
+      return null
+    }
+    let payload: unknown
+    try {
+      payload = JSON.parse(text)
+    } catch {
+      return null
+    }
+    const user = (payload as { user?: { role?: unknown } } | null)?.user
+    const role = user?.role
+    if (typeof role === 'string') {
+      return role
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean)
+    }
+    if (Array.isArray(role)) {
+      return role.filter((name): name is string => typeof name === 'string')
+    }
+    // The session came back and carried a user, but no role field — that is a
+    // stage reporting "none", not a stage that cannot report.
+    return user ? [] : null
+  }
+
+  /** Start/continue the target agent's run over HTTP as this persona. */
   private async agentRun(
     agentName: string,
     message: string,
@@ -165,13 +211,7 @@ export class HttpScenarioActor implements ScenarioActor {
     return normalizeAgentReply(raw)
   }
 
-  /**
-   * POST an agent HTTP route (raw body, not RPC-wrapped). Signs in lazily: the
-   * first call goes out with whatever cookie we hold (none, for a no-auth
-   * agent), and only a 401 triggers `login()` + one retry. This lets an actor
-   * converse with a no-auth agent without any sign-in wiring, while still
-   * authenticating against agents that require a session.
-   */
+  // knowledge: decisions/internals/scenario-agent-calls-sign-in-on-401-only.md
   private async postAgent(subPath: string, body: unknown): Promise<unknown> {
     const rpcPath = this.config.rpcPath ?? '/rpc'
     const url = `${this.config.apiUrl}${rpcPath}/${subPath}`
@@ -224,22 +264,22 @@ export class HttpScenarioActor implements ScenarioActor {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({
-        email: this.actorConfig.email,
-        name: this.actorConfig.name ?? this.name,
+        email: this.persona.email,
+        name: this.persona.name,
         secret: this.config.secret,
       }),
     })
     if (!res.ok) {
       const body = (await res.text().catch(() => '')).slice(0, 300)
       throw new Error(
-        `[scenario] actor sign-in failed for '${this.name}' (${res.status}): ${body}`
+        `[scenario] persona sign-in failed for '${this.name}' (${res.status}): ${body}`
       )
     }
     // 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`
+        `[scenario] persona sign-in for '${this.name}' returned no session cookie`
       )
     }
     this.signedIn = true
@@ -269,15 +309,15 @@ function normalizeAgentReply(raw: unknown): TargetAgentReply {
 }
 
 /**
- * Build the injected `actors` service from the config registry: actor name →
- * lazy HTTP actor. Wire the result as the `actors` singleton service.
+ * Build the injected `personas` service from the declared personas: id → lazy
+ * HTTP persona. Wire the result as the `personas` singleton service.
  */
-export function createHttpScenarioActors(
-  config: HttpScenarioActorsConfig
-): ScenarioActors {
-  const actors: ScenarioActors = {}
-  for (const [name, actorConfig] of Object.entries(config.actors)) {
-    actors[name] = new HttpScenarioActor(name, actorConfig, config)
+export function createHttpPersonas(
+  config: HttpPersonasConfig
+): ScenarioPersonas {
+  const personas: ScenarioPersonas = {}
+  for (const [id, persona] of Object.entries(config.personas)) {
+    personas[id] = new HttpPersona(id, persona, config)
   }
-  return actors
+  return personas
 }

package/src/services/in-memory-queue-service.ts

@@ -5,19 +5,7 @@ import type {
 } from '../wirings/queue/queue.types.js'
 import { runQueueJob } from '../wirings/queue/queue-runner.js'
 
-/**
- * In-process queue for local/dev runs. Schedules jobs on the macrotask queue
- * (setTimeout) so dispatch is genuinely asynchronous — the same timing shape as
- * 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.
- */
+// knowledge: decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md
 export class InMemoryQueueService implements QueueService {
   readonly supportsResults = false
   private jobCounter = 0
@@ -48,7 +36,6 @@ export class InMemoryQueueService implements QueueService {
         await runQueueJob({ job })
       } catch (e: any) {
         if (attemptsMade < maxAttempts) {
-          // Transient failure — redeliver with backoff, mirroring a real queue.
           setTimeout(
             runAttempt,
             this.backoffDelay(options?.backoff, attemptsMade)
@@ -68,7 +55,6 @@ export class InMemoryQueueService implements QueueService {
     return jobId
   }
 
-  /** Delay before the next redelivery, honoring the job's backoff policy. */
   private backoffDelay(
     backoff: JobOptions['backoff'],
     attemptsMade: number

package/src/services/in-memory-trigger-service.ts

@@ -1,24 +1,7 @@
 import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js'
 import { getSingletonServices } from '../pikku-state.js'
 
-/**
- * In-memory TriggerService implementation.
- *
- * Reads both `wireTrigger` declarations and `wireTriggerSource` registrations
- * from pikkuState. Only starts triggers that have both a declaration and a source.
- * On fire, invokes target via `ContextAwareRPCService`.
- *
- * Single owner — one process runs triggers, no distributed claiming.
- *
- * @example
- * ```typescript
- * const triggerService = new InMemoryTriggerService()
- * await triggerService.start()
- *
- * // On shutdown
- * await triggerService.stop()
- * ```
- */
+// knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
 export class InMemoryTriggerService extends PikkuTriggerService {
   async start(): Promise<void> {
     const singletonServices = getSingletonServices()