@pikku/core 0.12.51 → 0.12.53

package/src/services/stub-tracker.test.ts

@@ -0,0 +1,104 @@
+import { describe, test, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  StubTracker,
+  stub,
+  spy,
+  isTestRun,
+  getStubTracker,
+} from './stub-tracker.js'
+
+describe('StubTracker', () => {
+  test('records calls and exposes them via getCalls', () => {
+    const tracker = new StubTracker()
+    tracker.record('email', 'send', [{ to: 'a@b.c' }])
+    tracker.record('payments', 'charge', [{ amount: 5 }])
+
+    assert.equal(tracker.getCalls().length, 2)
+    const emailCalls = tracker.getCalls('email')
+    assert.equal(emailCalls.length, 1)
+    assert.deepEqual(emailCalls[0], {
+      service: 'email',
+      method: 'send',
+      args: [{ to: 'a@b.c' }],
+    })
+  })
+
+  test('reset clears recorded calls and strict-mode touches', () => {
+    const tracker = new StubTracker()
+    tracker.record('email', 'send', [])
+    tracker.reset()
+    assert.equal(tracker.getCalls().length, 0)
+    tracker.verify()
+  })
+
+  test('legacy stub() proxy records through the same tracker', async () => {
+    const tracker = new StubTracker()
+    const email = tracker.stub<{ send: (msg: unknown) => Promise<void> }>(
+      'email'
+    )
+    await email.send({ to: 'x@y.z' })
+    assert.deepEqual(tracker.getCalls('email')[0]?.args, [{ to: 'x@y.z' }])
+    tracker.assert('email', 'send')
+  })
+})
+
+describe('stub/spy core utils', () => {
+  beforeEach(() => getStubTracker().reset())
+
+  test('stub() records into the default tracker and uses the implementation', async () => {
+    const email = stub<{ send: (msg: unknown) => Promise<{ ok: boolean }> }>(
+      'email',
+      { send: async () => ({ ok: true }) }
+    )
+    const result = await email.send({ to: 'a@b.c' })
+    assert.deepEqual(result, { ok: true })
+    assert.deepEqual(getStubTracker().getCalls('email')[0], {
+      service: 'email',
+      method: 'send',
+      args: [{ to: 'a@b.c' }],
+    })
+  })
+
+  test('stub() without an implementation resolves undefined', async () => {
+    const payments = stub<{ charge: (x: unknown) => Promise<unknown> }>(
+      'payments'
+    )
+    assert.equal(await payments.charge({ amount: 5 }), undefined)
+    assert.equal(getStubTracker().getCalls('payments').length, 1)
+  })
+
+  test('spy() records calls and passes through to the real service', async () => {
+    let realCalled = 0
+    const real = {
+      config: { retries: 3 },
+      send: async (msg: { to: string }) => {
+        realCalled++
+        return { delivered: msg.to }
+      },
+    }
+    const email = spy('email', real)
+
+    assert.deepEqual(await email.send({ to: 'a@b.c' }), {
+      delivered: 'a@b.c',
+    })
+    assert.equal(realCalled, 1)
+    assert.equal(email.config.retries, 3)
+    assert.equal(getStubTracker().getCalls('email').length, 1)
+  })
+})
+
+describe('isTestRun', () => {
+  const original = process.env.PIKKU_TEST_RUN
+  afterEach(() => {
+    if (original === undefined) delete process.env.PIKKU_TEST_RUN
+    else process.env.PIKKU_TEST_RUN = original
+  })
+
+  test('reflects the PIKKU_TEST_RUN environment variable', () => {
+    delete process.env.PIKKU_TEST_RUN
+    assert.equal(isTestRun(), false)
+    process.env.PIKKU_TEST_RUN = 'true'
+    assert.equal(isTestRun(), true)
+  })
+})

package/src/services/stub-tracker.ts

@@ -0,0 +1,185 @@
+export type StubCall = { service: string; method: string; args: unknown[] }
+
+type Call = { method: string; args: unknown[]; verified: boolean }
+
+/**
+ * Tracks calls made to stubbed services and enforces strict mode:
+ * once a scenario asserts any call on a service, every recorded call on that
+ * service must be verified by end of scenario — otherwise the After hook fails.
+ * Services never touched by an assertion stay lenient.
+ */
+export class StubTracker {
+  private readonly calls = new Map<string, Call[]>()
+  private readonly touched = new Set<string>()
+
+  record(service: string, method: string, args: unknown[]): void {
+    const list = this.calls.get(service) ?? []
+    list.push({ method, args, verified: false })
+    this.calls.set(service, list)
+  }
+
+  getCalls(service?: string): StubCall[] {
+    const result: StubCall[] = []
+    for (const [name, list] of this.calls) {
+      if (service && name !== service) continue
+      for (const call of list) {
+        result.push({ service: name, method: call.method, args: call.args })
+      }
+    }
+    return result
+  }
+
+  reset(): void {
+    this.calls.clear()
+    this.touched.clear()
+  }
+
+  stub<T>(service: string): T {
+    const self = this
+    return new Proxy(Object.create(null) as object, {
+      get(_, method: string) {
+        return (...args: unknown[]) => {
+          self.record(service, method, args)
+          return Promise.resolve()
+        }
+      },
+    }) as unknown as T
+  }
+
+  assert(service: string, method: string): void {
+    this.touched.add(service)
+    const list = this.calls.get(service) ?? []
+    const idx = list.findIndex((c) => c.method === method && !c.verified)
+    if (idx === -1) {
+      const seen = list.map((c) => c.method).join(', ') || '(none)'
+      throw new Error(
+        `Expected "${service}.${method}" to have been called. Recorded: ${seen}`
+      )
+    }
+    list[idx]!.verified = true
+  }
+
+  assertCall(
+    service: string,
+    method: string,
+    predicate: (args: unknown[]) => boolean,
+    description: string
+  ): void {
+    this.touched.add(service)
+    const list = this.calls.get(service) ?? []
+    const idx = list.findIndex(
+      (c) => c.method === method && !c.verified && predicate(c.args)
+    )
+    if (idx === -1) {
+      const seen =
+        list
+          .filter((c) => c.method === method)
+          .map((c) => JSON.stringify(c.args[0]))
+          .join('\n  ') || '(none)'
+      throw new Error(`Expected ${description} but found:\n  ${seen}`)
+    }
+    list[idx]!.verified = true
+  }
+
+  assertNoCalls(
+    service: string,
+    method?: string,
+    predicate?: (args: unknown[]) => boolean,
+    description?: string
+  ): void {
+    this.touched.add(service)
+    const list = this.calls.get(service) ?? []
+    const relevant = (
+      method ? list.filter((c) => c.method === method) : list
+    ).filter((c) => !predicate || predicate(c.args))
+    if (relevant.length > 0) {
+      const calls = relevant
+        .map(
+          (c) =>
+            `${c.method}(${c.args.map((a) => JSON.stringify(a)).join(', ')})`
+        )
+        .join('\n  ')
+      const what = description ?? `"${service}${method ? '.' + method : ''}"`
+      throw new Error(`Expected no ${what} calls but got:\n  ${calls}`)
+    }
+  }
+
+  verify(): void {
+    const errors: string[] = []
+    for (const service of this.touched) {
+      const unverified = (this.calls.get(service) ?? []).filter(
+        (c) => !c.verified
+      )
+      for (const c of unverified) {
+        const argStr = c.args.map((a) => JSON.stringify(a)).join(', ')
+        errors.push(`  ${service}.${c.method}(${argStr})`)
+      }
+    }
+    if (errors.length) {
+      throw new Error(
+        `Unexpected stub calls — assert them in the scenario or remove the side effect:\n${errors.join('\n')}`
+      )
+    }
+  }
+}
+
+/**
+ * Creates a Proxy suitable for passing as `existingServices` to
+ * `createSingletonServices`. Every property returns `tracker.stub(prop)`
+ * EXCEPT `schema`, which returns `undefined` so the service factory creates
+ * a real schema service. Stubbing the schema makes validation a no-op —
+ * required fields pass silently and tests validate nothing.
+ */
+export function createStubProxy(tracker: StubTracker): Record<string, unknown> {
+  return new Proxy({} as Record<string, unknown>, {
+    get(_, prop: string) {
+      if (prop === 'schema') return undefined
+      return tracker.stub(prop)
+    },
+  })
+}
+
+const defaultStubTracker = new StubTracker()
+
+/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+export const getStubTracker = (): StubTracker => defaultStubTracker
+
+/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+export const isTestRun = (): boolean =>
+  (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env?.PIKKU_TEST_RUN === 'true'
+
+/**
+ * Creates a recording fake for a service. Methods present on `impl` run and
+ * their result is returned; missing methods resolve `undefined`. Every call
+ * is recorded so scenarios can assert via workflow.expectService().
+ */
+export function stub<T = any>(service: string, impl?: Partial<T>): T {
+  return new Proxy((impl ?? {}) as object, {
+    get(target: any, method: string | symbol) {
+      if (typeof method === 'symbol') return target[method]
+      const real = target[method]
+      if (typeof real !== 'function' && real !== undefined) return real
+      return (...args: unknown[]) => {
+        defaultStubTracker.record(service, method, args)
+        return real ? real.apply(target, args) : Promise.resolve(undefined)
+      }
+    },
+  }) as T
+}
+
+/** Wraps a real service so every method call is recorded and passed through */
+export function spy<T extends object>(service: string, real: T): T {
+  return new Proxy(real, {
+    get(target: any, method: string | symbol) {
+      const value = target[method]
+      if (typeof method === 'symbol' || typeof value !== 'function') {
+        return value
+      }
+      return (...args: unknown[]) => {
+        defaultStubTracker.record(service, method, args)
+        return value.apply(target, args)
+      }
+    },
+  }) as T
+}

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

@@ -0,0 +1,69 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { V8CoverageService } from './v8-coverage-service.js'
+
+const service = new V8CoverageService()
+
+function coveredProbe(n: number): number {
+  return n * 2
+}
+
+describe('V8CoverageService', () => {
+  after(async () => {
+    await service.stop()
+  })
+
+  test('start + takeCoverage reports call counts for functions invoked after start', async () => {
+    await service.start()
+    coveredProbe(21)
+
+    const snapshot = await service.takeCoverage()
+    assert.equal(snapshot.kind, 'v8-scripts')
+    if (snapshot.kind !== 'v8-scripts') return
+    const own = snapshot.scripts.find((s) =>
+      s.url.includes('v8-coverage-service.test')
+    )
+    assert.ok(own, 'own test script should appear in precise coverage')
+    const probe = own.functions.find((f) =>
+      f.functionName.includes('coveredProbe')
+    )
+    assert.ok(probe, 'coveredProbe should be tracked')
+    assert.ok(
+      probe.ranges[0].count >= 1,
+      `coveredProbe should have been counted, got ${probe.ranges[0].count}`
+    )
+  })
+
+  test('reset clears call counts so attribution per run is possible', async () => {
+    coveredProbe(1)
+    await service.reset()
+    const snapshot = await service.takeCoverage()
+    if (snapshot.kind !== 'v8-scripts') return assert.fail('expected scripts')
+    const own = snapshot.scripts.find((s) =>
+      s.url.includes('v8-coverage-service.test')
+    )
+    const probe = own?.functions.find((f) =>
+      f.functionName.includes('coveredProbe')
+    )
+    const count = probe?.ranges[0].count ?? 0
+    assert.equal(
+      count,
+      0,
+      `after reset coveredProbe count should be 0, got ${count}`
+    )
+  })
+
+  test('getScriptSource returns the executed source for mapping', async () => {
+    const snapshot = await service.takeCoverage()
+    if (snapshot.kind !== 'v8-scripts') return assert.fail('expected scripts')
+    const own = snapshot.scripts.find((s) =>
+      s.url.includes('v8-coverage-service.test')
+    )
+    assert.ok(own)
+    const source = await snapshot.getScriptSource(own.scriptId)
+    assert.ok(
+      source.includes('coveredProbe'),
+      'script source should contain the probe function'
+    )
+  })
+})

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

@@ -0,0 +1,121 @@
+// node:inspector is imported lazily inside start() so this module stays
+// loadable on runtimes without it (e.g. Cloudflare Workers).
+
+export interface CoverageRange {
+  startOffset: number
+  endOffset: number
+  count: number
+}
+
+export interface FunctionCoverage {
+  functionName: string
+  isBlockCoverage: boolean
+  ranges: CoverageRange[]
+}
+
+export interface ScriptCoverage {
+  scriptId: string
+  url: string
+  functions: FunctionCoverage[]
+}
+
+export type LineHits = Map<string, Map<number, number>>
+
+export type CoverageSnapshot =
+  | {
+      kind: 'v8-scripts'
+      scripts: ScriptCoverage[]
+      getScriptSource: (scriptId: string) => Promise<string>
+    }
+  | { kind: 'line-hits'; lineHits: LineHits }
+
+export interface CoverageService {
+  start(): Promise<void>
+  takeCoverage(): Promise<CoverageSnapshot>
+  reset(): Promise<void>
+  stop(): Promise<void>
+}
+
+type InspectorSession = {
+  connect(): void
+  disconnect(): void
+  post(
+    method: string,
+    params?: unknown,
+    callback?: (err: Error | null, result?: any) => void
+  ): void
+}
+
+export class V8CoverageService implements CoverageService {
+  private session: InspectorSession | null = null
+  private startPromise: Promise<void> | null = null
+
+  private post<T>(method: string, params?: unknown): Promise<T> {
+    const session = this.session
+    if (!session) {
+      throw new Error('V8CoverageService not started — call start() first')
+    }
+    return new Promise<T>((resolve, reject) => {
+      session.post(method, params, (err, result) =>
+        err ? reject(err) : resolve(result as T)
+      )
+    })
+  }
+
+  start(): Promise<void> {
+    this.startPromise ??= this.doStart()
+    return this.startPromise
+  }
+
+  private async doStart(): Promise<void> {
+    const inspector = await import('node:inspector')
+    this.session = new inspector.Session() as unknown as InspectorSession
+    this.session.connect()
+    await this.post('Profiler.enable')
+    await this.post('Debugger.enable')
+    await this.post('Profiler.startPreciseCoverage', {
+      callCount: true,
+      detailed: true,
+    })
+  }
+
+  async takeCoverage(): Promise<CoverageSnapshot> {
+    const { result } = await this.post<{ result: ScriptCoverage[] }>(
+      'Profiler.takePreciseCoverage'
+    )
+    return {
+      kind: 'v8-scripts',
+      scripts: result.filter((script) => script.url.startsWith('file://')),
+      getScriptSource: (scriptId) => this.getScriptSource(scriptId),
+    }
+  }
+
+  async getScriptSource(scriptId: string): Promise<string> {
+    const { scriptSource } = await this.post<{ scriptSource: string }>(
+      'Debugger.getScriptSource',
+      { scriptId }
+    )
+    return scriptSource
+  }
+
+  async reset(): Promise<void> {
+    await this.post('Profiler.stopPreciseCoverage')
+    await this.post('Profiler.startPreciseCoverage', {
+      callCount: true,
+      detailed: true,
+    })
+  }
+
+  async stop(): Promise<void> {
+    if (!this.session) return
+    try {
+      await this.post('Profiler.stopPreciseCoverage')
+      await this.post('Profiler.disable')
+      await this.post('Debugger.disable')
+    } finally {
+      this.session.disconnect()
+      this.session = null
+      this.startPromise = null
+    }
+  }
+}

package/src/types/core.types.ts

@@ -29,7 +29,7 @@ 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 { UserFlowActors } from '../services/user-flow-actors-service.js'
+import type { ScenarioActors } from '../services/scenario-actors-service.js'
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
 import type { AIRunStateService } from '../services/ai-run-state-service.js'
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js'
@@ -38,6 +38,7 @@ import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { EmailService } from '../services/email-service.js'
 import type { MetaService } from '../services/meta-service.js'
+import type { CoverageService } from '../services/v8-coverage-service.js'
 import type { SessionStore } from '../services/session-store.js'
 import type {
   AuditDurability,
@@ -150,6 +151,12 @@ export type FunctionMeta = FunctionRuntimeMeta &
       isDirectFunction: boolean
       sourceFile: string
       exportedName: string
+      /** File containing the handler body when it differs from sourceFile (imported handlers) */
+      bodySourceFile?: string
+      /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
+      bodyStart: number
+      /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
+      bodyEnd: number
     } & CommonWireMeta
   >
 
@@ -244,7 +251,7 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
 export interface CoreUserSession {
   userId?: string
   orgId?: string
-  /** True when the session belongs to a synthetic user-flow actor — lets audits/analytics address synthetic traffic */
+  /** True when the session belongs to a synthetic scenario actor — lets audits/analytics address synthetic traffic */
   actor?: boolean
 }
 
@@ -293,6 +300,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   emailService?: EmailService
   /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
   metaService?: MetaService
+  /** V8 precise-coverage collector (`pikku dev --coverage` only) */
+  coverageService?: CoverageService
   /** Audit service for durable or staged audit event capture */
   audit?: AuditService
   /**
@@ -339,8 +348,8 @@ export type PikkuWire<
   queue: PikkuQueue
   cli: PikkuCLI
   workflow: TypedWorkflow
-  /** User-flow actor registry (user-flow runs only) — pass into workflow.do as `{ actor: actors.x }` */
-  actors: UserFlowActors
+  /** Scenario actor registry (scenario runs only) — pass into workflow.do as `{ actor: actors.x }` */
+  actors: ScenarioActors
   workflowStep: WorkflowStepWire
   graph: PikkuGraphWire
   trigger: PikkuTrigger<TriggerOutput>

package/src/wirings/actor-flow/actor-flow.types.ts

@@ -0,0 +1,73 @@
+/**
+ * How an actor agent answers the target agent's tool-approval requests during
+ * a conversation.
+ * - `'in-persona'` — the actor agent decides as the persona would (default).
+ * - `'always'` — approve every request (stress the happy path).
+ * - `'never'` — deny every request (exercise refusal handling).
+ */
+export type ActorFlowApprovalPolicy = 'in-persona' | 'always' | 'never'
+
+/**
+ * Options for `actor.converse(...)` — a dynamic conversation an actor holds
+ * with a target Pikku AI agent, in the actor's own persona. `TAgentName` is
+ * bound to the generated union of agent names in a typed project.
+ */
+export interface ConverseOptions<TAgentName extends string = string> {
+  /** Target Pikku AI agent name to converse with. */
+  agent: TAgentName
+  /** What the actor is trying to get the agent to accomplish. */
+  task: string
+  /** Natural-language success criterion the actor evaluates at the end. */
+  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?: string
+  /** Hard cap on conversation turns before forcing evaluation. Default 12. */
+  maxTurns?: number
+}
+
+/**
+ * The verdict a conversation produces: the persona's LLM self-evaluation of
+ * whether the task was met. Deterministic checks are the caller's job — they
+ * already hold the actor and can `actor.invoke(...)` afterwards.
+ */
+export interface ActorFlowVerdict {
+  /** Whether the actor judged the task accomplished. */
+  passed: boolean
+  /** The actor's reasoning for its verdict. */
+  reasoning: string
+  /** The conversation transcript, for debugging/reporting. */
+  transcript: string[]
+}
+
+/** A pending tool-approval request surfaced by the target agent. */
+export interface TargetPendingApproval {
+  toolCallId: string
+  toolName: string
+  args: unknown
+  reason?: string
+}
+
+/** A normalized reply from the target agent, independent of transport. */
+export interface TargetAgentReply {
+  text: string
+  runId: string
+  status?: 'completed' | 'suspended'
+  pendingApprovals?: TargetPendingApproval[]
+}
+
+/**
+ * Drives the target agent. In production this is HTTP-backed (the actor's
+ * `agentRun` / `agentApprove` calls as the signed-in actor); the conversation
+ * engine only sees this transport-agnostic contract.
+ */
+export interface TargetAgentDriver {
+  /** Send a message, starting or continuing the target agent's run. */
+  run(message: string): Promise<TargetAgentReply>
+  /** Answer the target agent's pending approvals and continue its run. */
+  approve(
+    runId: string,
+    decisions: { toolCallId: string; approved: boolean }[]
+  ): Promise<TargetAgentReply>
+}

package/src/wirings/actor-flow/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Actor flow module exports.
+ *
+ * An actor holds a dynamic conversation with a target Pikku AI agent via
+ * `actor.converse(...)` — playing its own persona, approving the agent's tool
+ * requests in-persona, and evaluating whether the task was accomplished. The
+ * conversation engine here is transport-agnostic; the actor drives the target
+ * over HTTP.
+ */
+export type {
+  ActorFlowApprovalPolicy,
+  ActorFlowVerdict,
+  ConverseOptions,
+  TargetAgentReply,
+  TargetPendingApproval,
+  TargetAgentDriver,
+} from './actor-flow.types.js'
+export {
+  runConversation,
+  type RunConversationParams,
+  type PersonaLLM,
+} from './run-conversation.js'