@pikku/core 0.12.72 → 0.12.74

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()

package/src/services/in-memory-workflow-service.test.ts

@@ -91,7 +91,6 @@ describe('InMemoryWorkflowService', () => {
 
     test('should handle non-existent run gracefully', async () => {
       await service.updateRunStatus('non-existent', 'failed')
-      // Should not throw
     })
   })
 
@@ -258,18 +257,6 @@ describe('InMemoryWorkflowService', () => {
       assert.deepStrictEqual(state.failedNodeIds, [])
     })
 
-    test('should find nodes without steps', async () => {
-      const runId = await service.createRun('wf', {}, true, 'h', {} as any)
-      await service.insertStepState(runId, 'node1', null, {})
-
-      const missing = await service.getNodesWithoutSteps(runId, [
-        'node1',
-        'node2',
-        'node3',
-      ])
-      assert.deepStrictEqual(missing, ['node2', 'node3'])
-    })
-
     test('should get node results', async () => {
       const runId = await service.createRun('wf', {}, true, 'h', {} as any)
       const step1 = await service.insertStepState(runId, 'node1', null, {})

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

@@ -21,21 +21,7 @@ interface InternalStepData {
   stepName: string
 }
 
-/**
- * In-memory implementation of WorkflowService for inline-only execution
- *
- * This is a lightweight workflow service that stores all state in memory.
- * It only supports inline execution (no queue workers) and is ideal for:
- * - CLI tools that need workflow-like step orchestration
- * - Testing and development
- * - Single-process applications without persistence requirements
- *
- * @example
- * ```typescript
- * const workflowService = new InMemoryWorkflowService()
- * await workflowService.startWorkflow('myWorkflow', input, { type: 'cli' }, rpc, { inline: true })
- * ```
- */
+// knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
 export class InMemoryWorkflowService
   extends PikkuWorkflowService
   implements WorkflowRunService
@@ -169,7 +155,7 @@ export class InMemoryWorkflowService
     this.steps.set(key, step)
     this.stepData.set(stepId, { rpcName, data, stepName })
 
-    // Add to history (same reference so mutations are reflected)
+    // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
     const history = this.stepHistory.get(runId) || []
     history.push(step)
     this.stepHistory.set(runId, history)
@@ -262,7 +248,6 @@ export class InMemoryWorkflowService
     failedStepId: string,
     status: 'pending' | 'running'
   ): Promise<StepState> {
-    // Find the failed step
     let failedStep: StepState | undefined
     let runId: string | undefined
     let stepName: string | undefined
@@ -304,12 +289,11 @@ export class InMemoryWorkflowService
     const key = `${runId}:${stepName}`
     this.steps.set(key, newStep)
 
-    // Copy step data to new step
     if (failedStepData) {
       this.stepData.set(newStepId, { ...failedStepData })
     }
 
-    // Add to history (same reference so mutations are reflected)
+    // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
     const history = this.stepHistory.get(runId) || []
     history.push(newStep)
     this.stepHistory.set(runId, history)
@@ -380,7 +364,7 @@ export class InMemoryWorkflowService
   }
 
   async withRunLock<T>(_id: string, fn: () => Promise<T>): Promise<T> {
-    // In-memory service doesn't need locking for inline execution
+    // knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
     return fn()
   }
 
@@ -389,7 +373,6 @@ export class InMemoryWorkflowService
     _stepName: string,
     fn: () => Promise<T>
   ): Promise<T> {
-    // In-memory service doesn't need locking for inline execution
     return fn()
   }
 
@@ -398,7 +381,6 @@ export class InMemoryWorkflowService
       clearTimeout(timer)
     }
     this.sleepTimers.clear()
-    // Clear all in-memory state
     this.runs.clear()
     this.steps.clear()
     this.stepData.clear()
@@ -408,8 +390,6 @@ export class InMemoryWorkflowService
     this.workflowVersions.clear()
   }
 
-  // Graph workflow methods
-
   async getCompletedGraphState(runId: string): Promise<{
     completedNodeIds: string[]
     failedNodeIds: string[]
@@ -442,20 +422,6 @@ export class InMemoryWorkflowService
     return { completedNodeIds, failedNodeIds, branchKeys }
   }
 
-  async getNodesWithoutSteps(
-    runId: string,
-    nodeIds: string[]
-  ): Promise<string[]> {
-    const existingSteps = new Set<string>()
-    const prefix = `${runId}:`
-    for (const [key] of this.steps.entries()) {
-      if (key.startsWith(prefix)) {
-        existingSteps.add(key.substring(prefix.length))
-      }
-    }
-    return nodeIds.filter((id) => !existingSteps.has(id))
-  }
-
   protected override async listStepStates(
     runId: string
   ): Promise<Array<StepState & { stepName: string }>> {

package/src/services/index.ts

@@ -1,7 +1,3 @@
-/**
- * @module @pikku/core
- */
-
 export { LogLevel } from './logger.js'
 export { ScopedSecretService } from './scoped-secret-service.js'
 export {
@@ -41,20 +37,19 @@ export type {
   CopyFileArgs,
 } from './content-service.js'
 export type {
-  ScenarioActor,
-  ScenarioActorConfig,
-  ScenarioActorOf,
-  ScenarioActors,
+  ScenarioPersona,
+  ResolvedPersona,
+  ScenarioPersonaOf,
+  ScenarioPersonas,
   ScenarioInvokeOptions,
   ScenarioRpcMap,
   ScenarioHttpResponse,
-} from './scenario-actors-service.js'
-export { readScenarioHttpResponse } from './scenario-actors-service.js'
-export {
-  HttpScenarioActor,
-  createHttpScenarioActors,
-  type HttpScenarioActorsConfig,
-} from './http-scenario-actors.js'
+} from './personas-service.js'
+// The persona runtime — `HttpPersona`, `createHttpPersonas`,
+// `readScenarioHttpResponse`, `postScenarioJson` — is exported from
+// `@pikku/core/persona`, not from here. Types are free; those are values, and
+// they reach the actor-flow and agent runners, which no production server runs.
+export type { HttpPersonasConfig } from './http-personas.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,
@@ -137,6 +132,12 @@ export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
 export type { ScopeService, Role } from './scope-service.js'
+export {
+  assertRoleIsMutable,
+  assertRoleNameAvailable,
+  roleLockReason,
+} from './system-role-guard.js'
+export type { IsSystemRole } from './system-role-guard.js'
 export {
   NoopAuditService,
   createInvocationAudit,
@@ -200,3 +201,7 @@ export {
   spy,
   type StubCall,
 } from './stub-tracker.js'
+export {
+  SecretHostNotAllowedError,
+  assertSecretAllowedForHost,
+} from './secret-host-binding.js'

package/src/services/istanbul-coverage-service.ts

@@ -22,11 +22,7 @@ type IstanbulCoverageGlobal = Record<string, IstanbulFileCoverage>
 const getCoverageGlobal = (): IstanbulCoverageGlobal | undefined =>
   (globalThis as { __coverage__?: IstanbulCoverageGlobal }).__coverage__
 
-/**
- * Reads istanbul-instrumented counters from the `__coverage__` global —
- * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
- * where source files are instrumented at load time by a Bun loader plugin).
- */
+/** The coverage backend for runtimes without V8 precise coverage, e.g. Bun. */
 export class IstanbulCoverageService implements CoverageService {
   async start(): Promise<void> {}
 
@@ -39,9 +35,7 @@ export class IstanbulCoverageService implements CoverageService {
         hits = new Map()
         lineHits.set(file.path, hits)
       }
-      // istanbul line semantics: a statement's count belongs to its start
-      // line only, so an enclosing multi-line statement never masks an
-      // unexecuted inner statement (e.g. a throw inside a taken if).
+      // knowledge: decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md
       for (const [id, location] of Object.entries(file.statementMap)) {
         const count = file.s[id] ?? 0
         const line = location.start.line

package/src/services/jwt-service.ts

@@ -1,27 +1,12 @@
 import type { RelativeTimeInput } from '../time-utils.js'
 
-/**
- * Interface for handling JSON Web Tokens (JWT).
- */
 export interface JWTService {
-  /**
-   * Encodes a payload into a JWT.
-   * @param expiresIn - The expiration time of the token.
-   * @param payload - The payload to encode.
-   * @returns A promise that resolves to the encoded JWT.
-   */
   encode: <T extends any>(
     expiresIn: RelativeTimeInput,
     payload: T
   ) => Promise<string>
 
-  /**
-   * Decodes a JWT into its payload.
-   * @param hash - The JWT to decode.
-   * @param invalidHashError - An optional error to throw if the hash is invalid.
-   * @param debug - An optional flag for debugging.
-   * @returns A promise that resolves to the decoded payload.
-   */
+  /** `invalidHashError` replaces the implementation's own error when the hash does not verify. */
   decode: <T>(
     hash: string,
     invalidHashError?: Error,