@pikku/core 0.12.51 → 0.12.53

package/src/services/{http-user-flow-actors.test.ts → http-scenario-actors.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 { createHttpUserFlowActors } from './http-user-flow-actors.js'
+import { createHttpScenarioActors } from './http-scenario-actors.js'
 
 // Minimal target app: actor sign-in endpoint + exposed RPC endpoint, session
 // via cookie. Mirrors the Better Auth actor plugin's contract.
@@ -13,10 +13,14 @@ const startTarget = async () => {
     const chunks: Buffer[] = []
     req.on('data', (c) => chunks.push(c))
     req.on('end', () => {
-      const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : {}
+      const body = chunks.length
+        ? JSON.parse(Buffer.concat(chunks).toString())
+        : {}
       if (req.url === '/api/auth/sign-in/actor') {
         if (body.secret !== 'impersonation-secret') {
-          res.writeHead(401).end(JSON.stringify({ message: 'bad actor secret' }))
+          res
+            .writeHead(401)
+            .end(JSON.stringify({ message: 'bad actor secret' }))
           return
         }
         logins++
@@ -58,12 +62,12 @@ const startTarget = async () => {
   }
 }
 
-describe('HttpUserFlowActor', async () => {
+describe('HttpScenarioActor', async () => {
   const target = await startTarget()
   after(() => target.server.close())
 
   const makeActors = (secret = 'impersonation-secret') =>
-    createHttpUserFlowActors({
+    createHttpScenarioActors({
       apiUrl: target.apiUrl,
       secret,
       actors: {
@@ -82,14 +86,20 @@ describe('HttpUserFlowActor', async () => {
   test('logs in lazily once and replays the session cookie on RPCs', async () => {
     const actors = makeActors()
 
-    const first = (await actors.customer!.invoke('createTodo', { title: 'x' })) as any
+    const first = (await actors.customer!.invoke('createTodo', {
+      title: 'x',
+    })) as any
     const second = (await actors.customer!.invoke('listTodos', {})) as any
 
     assert.equal(first.rpcName, 'createTodo')
     assert.deepEqual(first.echoed, { title: 'x' })
     assert.match(first.cookie, /session=s1/)
     assert.match(first.cookie, /csrf=c1/)
-    assert.match(second.cookie, /session=s1/, 'session is cached, not re-minted')
+    assert.match(
+      second.cookie,
+      /session=s1/,
+      'session is cached, not re-minted'
+    )
     assert.equal(target.loginCount(), 1)
   })
 

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

@@ -0,0 +1,269 @@
+import type {
+  ScenarioActor,
+  ScenarioActorConfig,
+  ScenarioActors,
+} from './scenario-actors-service.js'
+import type {
+  ConverseOptions,
+  ActorFlowVerdict,
+  TargetAgentReply,
+} from '../wirings/actor-flow/actor-flow.types.js'
+import { runConversation } from '../wirings/actor-flow/run-conversation.js'
+import { getSingletonServices } from '../pikku-state.js'
+import { AIProviderNotConfiguredError } from '../errors/errors.js'
+
+export interface HttpScenarioActorsConfig {
+  /**
+   * 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
+   * `${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.
+   */
+  secret: string
+  /** Actor name → config (usually from pikku.config.json's actor registry). */
+  actors: Record<string, ScenarioActorConfig>
+  /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
+  signInPath?: 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`.
+   */
+  model?: string
+}
+
+/**
+ * Default HTTP-backed actor. 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 {
+  private cookie: string | null = null
+  private origin: string
+
+  constructor(
+    readonly name: string,
+    private actorConfig: ScenarioActorConfig,
+    private config: HttpScenarioActorsConfig
+  ) {
+    this.origin = new URL(config.apiUrl).origin
+  }
+
+  get email(): string {
+    return this.actorConfig.email
+  }
+
+  async invoke(rpcName: string, data: unknown): Promise<unknown> {
+    const cookie = this.cookie ?? (await this.login())
+    const res = await this.postRpc(rpcName, data, cookie)
+    if (res.status === 401) {
+      // Session expired mid-run — re-login once and retry.
+      this.cookie = null
+      return this.readRpcResponse(
+        rpcName,
+        await this.postRpc(rpcName, data, await this.login())
+      )
+    }
+    return this.readRpcResponse(rpcName, res)
+  }
+
+  async converse(options: ConverseOptions): Promise<ActorFlowVerdict> {
+    const { aiAgentRunner } = getSingletonServices()
+    if (!aiAgentRunner) {
+      throw new AIProviderNotConfiguredError()
+    }
+    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`
+      )
+    }
+    const threadId = globalThis.crypto.randomUUID()
+    const resourceId = `actor:${this.name}`
+
+    return runConversation({
+      persona: this.actorConfig,
+      personaName: this.actorConfig.name ?? this.name,
+      agentName: options.agent,
+      task: options.task,
+      evaluate: options.evaluate,
+      approvals: options.approvals,
+      model,
+      maxTurns: options.maxTurns,
+      llm: (params) => aiAgentRunner.run(params),
+      target: {
+        run: (message) =>
+          this.agentRun(options.agent, message, threadId, resourceId),
+        approve: (runId, decisions) =>
+          this.agentApprove(options.agent, runId, decisions),
+      },
+    })
+  }
+
+  /** Start/continue the target agent's run over HTTP as this actor. */
+  private async agentRun(
+    agentName: string,
+    message: string,
+    threadId: string,
+    resourceId: string
+  ): Promise<TargetAgentReply> {
+    const raw = await this.postAgent(`agent/${agentName}`, {
+      message,
+      threadId,
+      resourceId,
+    })
+    return normalizeAgentReply(raw)
+  }
+
+  /** Answer the target agent's pending approvals over HTTP and continue. */
+  private async agentApprove(
+    agentName: string,
+    runId: string,
+    decisions: { toolCallId: string; approved: boolean }[]
+  ): Promise<TargetAgentReply> {
+    const raw = await this.postAgent(`agent/${agentName}/approve`, {
+      runId,
+      approvals: decisions,
+    })
+    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.
+   */
+  private async postAgent(subPath: string, body: unknown): Promise<unknown> {
+    const rpcPath = this.config.rpcPath ?? '/rpc'
+    const url = `${this.config.apiUrl}${rpcPath}/${subPath}`
+    const send = (cookie: string | null) =>
+      fetch(url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          origin: this.origin,
+          ...(cookie ? { cookie } : {}),
+        },
+        body: JSON.stringify(body),
+      })
+
+    let res = await send(this.cookie)
+    if (res.status === 401) {
+      this.cookie = null
+      res = await send(await this.login())
+    }
+    if (!res.ok) {
+      const text = (await res.text().catch(() => '')).slice(0, 300)
+      throw new Error(
+        `[scenario] agent call '${subPath}' as '${this.name}' returned ${res.status}: ${text}`
+      )
+    }
+    if (res.status === 204) return undefined
+    const text = await res.text()
+    return text ? JSON.parse(text) : undefined
+  }
+
+  private async postRpc(rpcName: string, data: unknown, cookie: string) {
+    const rpcPath = this.config.rpcPath ?? '/rpc'
+    return fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        origin: this.origin,
+        cookie,
+      },
+      body: JSON.stringify({ data }),
+    })
+  }
+
+  private async readRpcResponse(rpcName: string, res: Response) {
+    if (!res.ok) {
+      const body = (await res.text().catch(() => '')).slice(0, 300)
+      throw new Error(
+        `[scenario] '${rpcName}' as '${this.name}' returned ${res.status}: ${body}`
+      )
+    }
+    if (res.status === 204) return undefined
+    const text = await res.text()
+    return text ? JSON.parse(text) : undefined
+  }
+
+  private async login(): Promise<string> {
+    const signInPath = this.config.signInPath ?? '/auth/sign-in/actor'
+    const res = await fetch(`${this.config.apiUrl}${signInPath}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', origin: this.origin },
+      body: JSON.stringify({
+        email: this.actorConfig.email,
+        name: this.actorConfig.name ?? this.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}`
+      )
+    }
+    const setCookies = res.headers.getSetCookie?.() ?? []
+    const cookie = setCookies
+      .map((c) => c.split(';')[0]!)
+      .filter(Boolean)
+      .join('; ')
+    if (!cookie) {
+      throw new Error(
+        `[scenario] actor sign-in for '${this.name}' returned no session cookie`
+      )
+    }
+    this.cookie = cookie
+    return cookie
+  }
+}
+
+/** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */
+function normalizeAgentReply(raw: unknown): TargetAgentReply {
+  const r = (raw ?? {}) as Record<string, unknown>
+  const pending = Array.isArray(r.pendingApprovals)
+    ? (r.pendingApprovals as Array<Record<string, unknown>>).map((p) => ({
+        toolCallId: String(p.toolCallId),
+        toolName: String(p.toolName),
+        args: p.args,
+        reason: typeof p.reason === 'string' ? p.reason : undefined,
+      }))
+    : undefined
+  return {
+    text: typeof r.text === 'string' ? r.text : '',
+    runId: typeof r.runId === 'string' ? r.runId : '',
+    status:
+      r.status === 'completed' || r.status === 'suspended'
+        ? r.status
+        : undefined,
+    pendingApprovals: pending,
+  }
+}
+
+/**
+ * Build the injected `actors` service from the config registry: actor name →
+ * lazy HTTP actor. Wire the result as the `actors` 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)
+  }
+  return actors
+}

package/src/services/index.ts

@@ -37,15 +37,15 @@ export type {
   CopyFileArgs,
 } from './content-service.js'
 export type {
-  UserFlowActor,
-  UserFlowActorConfig,
-  UserFlowActors,
-} from './user-flow-actors-service.js'
+  ScenarioActor,
+  ScenarioActorConfig,
+  ScenarioActors,
+} from './scenario-actors-service.js'
 export {
-  HttpUserFlowActor,
-  createHttpUserFlowActors,
-  type HttpUserFlowActorsConfig,
-} from './http-user-flow-actors.js'
+  HttpScenarioActor,
+  createHttpScenarioActors,
+  type HttpScenarioActorsConfig,
+} from './http-scenario-actors.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,
@@ -154,3 +154,22 @@ export type {
   EmailTemplateLocaleMeta,
   EmailTemplateAssets,
 } from './meta-service.js'
+export {
+  V8CoverageService,
+  type CoverageService,
+  type CoverageSnapshot,
+  type LineHits,
+  type ScriptCoverage,
+  type FunctionCoverage,
+  type CoverageRange,
+} from './v8-coverage-service.js'
+export { IstanbulCoverageService } from './istanbul-coverage-service.js'
+export {
+  StubTracker,
+  createStubProxy,
+  getStubTracker,
+  isTestRun,
+  stub,
+  spy,
+  type StubCall,
+} from './stub-tracker.js'

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

@@ -0,0 +1,66 @@
+import { describe, test, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { IstanbulCoverageService } from './istanbul-coverage-service.js'
+
+const FILE = '/proj/src/things.function.ts'
+
+const seedCoverage = () => {
+  ;(globalThis as any).__coverage__ = {
+    [FILE]: {
+      path: FILE,
+      statementMap: {
+        '0': { start: { line: 2, column: 2 }, end: { line: 2, column: 20 } },
+        '1': { start: { line: 3, column: 4 }, end: { line: 3, column: 30 } },
+        '2': { start: { line: 5, column: 2 }, end: { line: 6, column: 18 } },
+      },
+      s: { '0': 3, '1': 0, '2': 3 },
+      branchMap: {},
+      b: {},
+      fnMap: {},
+      f: {},
+    },
+  }
+}
+
+afterEach(() => {
+  delete (globalThis as any).__coverage__
+})
+
+describe('IstanbulCoverageService', () => {
+  test('takeCoverage converts __coverage__ statement counts into line hits', async () => {
+    seedCoverage()
+    const service = new IstanbulCoverageService()
+    await service.start()
+    const snapshot = await service.takeCoverage()
+    assert.equal(snapshot.kind, 'line-hits')
+    if (snapshot.kind !== 'line-hits') return
+    const hits = snapshot.lineHits.get(FILE)
+    assert.ok(hits, 'file should have line hits')
+    assert.equal(hits.get(2), 3)
+    assert.equal(hits.get(3), 0)
+    assert.equal(hits.get(5), 3)
+    assert.equal(
+      hits.get(6),
+      undefined,
+      'counts attach to statement start lines only'
+    )
+  })
+
+  test('reset zeroes counters so per-scenario attribution is possible', async () => {
+    seedCoverage()
+    const service = new IstanbulCoverageService()
+    await service.reset()
+    const snapshot = await service.takeCoverage()
+    if (snapshot.kind !== 'line-hits') return assert.fail('expected line-hits')
+    const hits = snapshot.lineHits.get(FILE)
+    assert.equal(hits?.get(2), 0)
+    assert.equal(hits?.get(5), 0)
+  })
+
+  test('takeCoverage with no __coverage__ global returns an empty snapshot', async () => {
+    const service = new IstanbulCoverageService()
+    const snapshot = await service.takeCoverage()
+    if (snapshot.kind !== 'line-hits') return assert.fail('expected line-hits')
+    assert.equal(snapshot.lineHits.size, 0)
+  })
+})

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

@@ -0,0 +1,65 @@
+import type {
+  CoverageService,
+  CoverageSnapshot,
+  LineHits,
+} from './v8-coverage-service.js'
+
+interface IstanbulStatementLocation {
+  start: { line: number }
+  end: { line: number }
+}
+
+interface IstanbulFileCoverage {
+  path: string
+  statementMap: Record<string, IstanbulStatementLocation>
+  s: Record<string, number>
+  b: Record<string, number[]>
+  f: Record<string, number>
+}
+
+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).
+ */
+export class IstanbulCoverageService implements CoverageService {
+  async start(): Promise<void> {}
+
+  async takeCoverage(): Promise<CoverageSnapshot> {
+    const coverage = getCoverageGlobal()
+    const lineHits: LineHits = new Map()
+    for (const file of Object.values(coverage ?? {})) {
+      let hits = lineHits.get(file.path)
+      if (!hits) {
+        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).
+      for (const [id, location] of Object.entries(file.statementMap)) {
+        const count = file.s[id] ?? 0
+        const line = location.start.line
+        hits.set(line, Math.max(hits.get(line) ?? 0, count))
+      }
+    }
+    return { kind: 'line-hits', lineHits }
+  }
+
+  async reset(): Promise<void> {
+    for (const file of Object.values(getCoverageGlobal() ?? {})) {
+      for (const id of Object.keys(file.s)) file.s[id] = 0
+      for (const id of Object.keys(file.f)) file.f[id] = 0
+      for (const id of Object.keys(file.b)) {
+        file.b[id] = file.b[id]!.map(() => 0)
+      }
+    }
+  }
+
+  async stop(): Promise<void> {}
+}

package/src/services/meta-service.ts

@@ -12,7 +12,7 @@ import type {
   MCPPromptMeta,
 } from '../wirings/mcp/mcp.types.js'
 import type { WorkflowsMeta } from '../wirings/workflow/workflow.types.js'
-import type { UserFlowActorConfig } from './user-flow-actors-service.js'
+import type { ScenarioActorConfig } from './scenario-actors-service.js'
 import type {
   TriggerMeta,
   TriggerSourceMeta,
@@ -171,7 +171,7 @@ export interface MetaService {
   getGatewayMeta(): Promise<GatewaysMeta>
   getRpcMeta(): Promise<RPCMetaRecord>
   getWorkflowMeta(): Promise<WorkflowsMeta>
-  getUserFlowActorsMeta(): Promise<Record<string, UserFlowActorConfig>>
+  getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>
   getTriggerMeta(): Promise<TriggerMeta>
   getTriggerSourceMeta(): Promise<TriggerSourceMeta>
   getFunctionsMeta(): Promise<FunctionsMeta>
@@ -210,7 +210,7 @@ export class LocalMetaService implements MetaService {
   private gatewayMetaCache: GatewaysMeta | null = null
   private rpcMetaCache: RPCMetaRecord | null = null
   private workflowMetaCache: WorkflowsMeta | null = null
-  private userFlowActorsMetaCache: Record<string, UserFlowActorConfig> | null =
+  private scenarioActorsMetaCache: Record<string, ScenarioActorConfig> | null =
     null
   private triggerMetaCache: TriggerMeta | null = null
   private triggerSourceMetaCache: TriggerSourceMeta | null = null
@@ -262,7 +262,7 @@ export class LocalMetaService implements MetaService {
     this.gatewayMetaCache = null
     this.rpcMetaCache = null
     this.workflowMetaCache = null
-    this.userFlowActorsMetaCache = null
+    this.scenarioActorsMetaCache = null
     this.triggerMetaCache = null
     this.triggerSourceMetaCache = null
     this.functionsMetaCache = null
@@ -429,12 +429,12 @@ export class LocalMetaService implements MetaService {
     }
   }
 
-  async getUserFlowActorsMeta(): Promise<Record<string, UserFlowActorConfig>> {
-    if (this.userFlowActorsMetaCache) return this.userFlowActorsMetaCache
+  async getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>> {
+    if (this.scenarioActorsMetaCache) return this.scenarioActorsMetaCache
 
-    const content = await this.readFile('workflow/user-flow-actors.gen.json')
-    this.userFlowActorsMetaCache = content ? JSON.parse(content) : {}
-    return this.userFlowActorsMetaCache!
+    const content = await this.readFile('workflow/scenario-actors.gen.json')
+    this.scenarioActorsMetaCache = content ? JSON.parse(content) : {}
+    return this.scenarioActorsMetaCache!
   }
 
   async getTriggerMeta(): Promise<TriggerMeta> {

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

@@ -0,0 +1,27 @@
+import type {
+  ConverseOptions,
+  ActorFlowVerdict,
+} from '../wirings/actor-flow/actor-flow.types.js'
+
+/** A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport */
+export interface ScenarioActor<TAgentName extends string = string> {
+  /** 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>
+  /** Converse with a Pikku AI agent in this actor's persona and return its verdict */
+  converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>
+}
+
+/** Display/config metadata for an actor (from pikku.config.json) */
+export interface ScenarioActorConfig {
+  email: string
+  name?: string
+  jobTitle?: string
+  personality?: string
+}
+
+/** The injected `actors` service: actor name → actor. */
+export type ScenarioActors = Record<string, ScenarioActor>