@pikku/core 0.12.88 → 0.12.90

package/src/wirings/rpc/rpc-runner.test.ts

@@ -596,6 +596,106 @@ describe('ContextAwareRPCService.rpcWithWire', () => {
       ['missingRpc', { value: 2 }, { userId: 'user-2' }, 'trace-3'],
     ])
   })
+
+  test('a missing namespaced rpc still reaches deploymentService through rpcWithWire', async () => {
+    const remoteCalls: unknown[][] = []
+    pikkuState(null, 'addons', 'packages').set('stripe', {
+      package: '@addon/stripe',
+    } as never)
+
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      { traceId: 'trace-addon-wire' } as never,
+      {}
+    )
+
+    const result = await service.rpcWithWire(
+      'stripe:missingFunc',
+      { value: 3 },
+      { custom: 'wire' } as never
+    )
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(remoteCalls, [
+      ['stripe:missingFunc', { value: 3 }, undefined, 'trace-addon-wire'],
+    ])
+  })
+
+  test('an unknown namespace still falls through to the local/remote lookup', async () => {
+    const remoteCalls: unknown[][] = []
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      { traceId: 'trace-ns-wire' } as never,
+      {}
+    )
+
+    const result = await service.rpcWithWire(
+      'unknownNs:someFunc',
+      { value: 1 },
+      { custom: 'wire' } as never
+    )
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(remoteCalls, [
+      ['unknownNs:someFunc', { value: 1 }, undefined, 'trace-ns-wire'],
+    ])
+  })
+
+  test('the deployment fallback runs under the wire the caller passed, not the ambient one', async () => {
+    const remoteCalls: unknown[][] = []
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      {
+        traceId: 'ambient-trace',
+        session: { userId: 'ambient-user' },
+      } as never,
+      {}
+    )
+
+    const result = await service.rpcWithWire(
+      'unknownNs:someFunc',
+      { value: 1 },
+      {
+        traceId: 'caller-trace',
+        session: { userId: 'caller-user' },
+      } as never
+    )
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(
+      remoteCalls,
+      [
+        [
+          'unknownNs:someFunc',
+          { value: 1 },
+          { userId: 'caller-user' },
+          'caller-trace',
+        ],
+      ],
+      'the remote hop ran under the ambient wire, so an explicit wire is honoured locally but dropped across the deployment boundary'
+    )
+  })
 })
 
 describe('ContextAwareRPCService.startWorkflow', () => {
@@ -900,7 +1000,12 @@ describe('wireRemoteAddon dispatch', () => {
         calls[0]!.init.headers.authorization,
         'Bearer secret-value-for-REGISTRY_TOKEN'
       )
-      assert.equal(calls[0]!.init.headers['x-trace-id'], 'trace-r')
+      assert.equal(
+        calls[0]!.init.headers['x-request-id'],
+        'trace-r',
+        'a remote RPC must send the trace id under the header the receiving ' +
+          'runner reads, or the trace chain breaks at the hop'
+      )
     } finally {
       restoreFetch()
     }

package/src/wirings/rpc/rpc-runner.ts

@@ -356,7 +356,7 @@ export class ContextAwareRPCService {
       headers.authorization = `Bearer ${token}`
     }
     if (this.wire.traceId) {
-      headers['x-trace-id'] = this.wire.traceId
+      headers['x-request-id'] = this.wire.traceId
     }
 
     const base = serverUrl.replace(/\/+$/, '')
@@ -393,10 +393,13 @@ export class ContextAwareRPCService {
 
     if (rpcName.includes(':')) {
       const addonCall = this.resolveAddonFunction(rpcName)
-      if (addonCall === NOT_RESOLVED) {
-        throw new RPCNotFoundError(rpcName)
+      if (addonCall !== NOT_RESOLVED) {
+        return await this.executeAddonFunction<In, Out>(
+          addonCall,
+          data,
+          mergedWire
+        )
       }
-      return this.executeAddonFunction<In, Out>(addonCall, data, mergedWire)
     }
 
     let resolved: { pikkuFuncId: string; packageName: string | null }
@@ -404,12 +407,12 @@ export class ContextAwareRPCService {
       resolved = resolvePikkuFunction(rpcName, this.packageName)
     } catch (e) {
       if (e instanceof RPCNotFoundError && this.services.deploymentService) {
-        const session = await resolveWireSession(this.wire)
+        const session = await resolveWireSession(mergedWire)
         return this.services.deploymentService.invoke(
           rpcName,
           data,
           session,
-          this.wire.traceId
+          mergedWire.traceId
         ) as Promise<Out>
       }
       throw e

package/src/wirings/virtual-user/index.ts

@@ -18,7 +18,10 @@
  */
 export type {
   ApiCatalogueEntry,
+  IntentRecord,
   IntentSource,
+  StepRecord,
+  VirtualUserBudget,
   VirtualUserDisposition,
   VirtualUserFinding,
   VirtualUserRunResult,
@@ -40,6 +43,21 @@ export type {
   VirtualUserRunStart,
   VirtualUserRunStore,
 } from './virtual-user-run-store.js'
+export type {
+  VirtualUserScheduleInput,
+  VirtualUserScheduleRecord,
+  VirtualUserScheduleStore,
+} from './virtual-user-schedule-store.js'
+export {
+  DEFAULT_MAX_INTERVAL_MS,
+  DEFAULT_MIN_INTERVAL_MS,
+  isDue,
+  nextRunAt,
+  STALE_RUN_AFTER_MS,
+  tickVirtualUserSchedules,
+  type VirtualUserTickParams,
+  type VirtualUserTickResult,
+} from './virtual-user-schedule.js'
 export {
   DISPOSITIONS,
   dispositionProfile,

package/src/wirings/virtual-user/virtual-user-agents.test.ts

@@ -4,16 +4,13 @@ import { reachableAgents } from './virtual-user-agents.js'
 
 const AGENTS = {
   'router-agent': {
-    name: 'router-agent',
     description: 'Routes requests to the right domain agent',
   },
   'social-poster': {
-    name: 'social-poster',
     description: 'Drafts and schedules posts',
     scopes: ['content:write'],
   },
   'refund-agent': {
-    name: 'refund-agent',
     scopes: ['billing:write'],
   },
 }
@@ -58,7 +55,14 @@ describe('reachableAgents', () => {
     assert.deepEqual(refund, { name: 'refund-agent' })
   })
 
-  test('falls back to the declaration key when an agent has no name', () => {
+  test('offers the registration key, not the display name the agent declares', () => {
+    assert.deepEqual(
+      reachableAgents({ adminAgent: { description: 'Runs the place' } }),
+      [{ name: 'adminAgent', description: 'Runs the place' }]
+    )
+  })
+
+  test('an agent carrying nothing but a key is still offered under it', () => {
     assert.deepEqual(reachableAgents({ orphan: {} }), [{ name: 'orphan' }])
   })
 

package/src/wirings/virtual-user/virtual-user-agents.ts

@@ -16,7 +16,6 @@ import { hasScopes } from '../../scopes.js'
 
 /** The part of an agent's meta this needs. */
 export interface AgentReachability {
-  name?: string
   description?: string
   scopes?: readonly string[]
   auth?: boolean
@@ -29,7 +28,13 @@ export interface ReachableAgent {
 }
 
 /**
- * The agents to offer, keyed by the name they are declared under.
+ * The agents to offer, named by the key they are registered under.
+ *
+ * That key is the export's own name, which is what `addAgent` stores and what
+ * `resolveAgent` looks up. The `name` an agent declares in its config is a
+ * display label and is frequently something else entirely — offering that one
+ * hands the persona a name the server cannot resolve, and the run dies on a
+ * 500 the moment it takes the offer.
  *
  * Like {@link reachableCatalogue}, this narrows *what is offered* and never
  * what is enforced: the server decides who may talk to what, and an agent
@@ -52,6 +57,6 @@ export const reachableAgents = (
       return hasScopes(agent.scopes, scopes)
     })
     .map(([id, agent]) => ({
-      name: agent.name ?? id,
+      name: id,
       ...(agent.description ? { description: agent.description } : {}),
     }))

package/src/wirings/virtual-user/virtual-user-run-store.ts

@@ -1,4 +1,6 @@
 import type {
+  IntentRecord,
+  StepRecord,
   VirtualUserDisposition,
   VirtualUserFinding,
   VirtualUserTally,
@@ -39,6 +41,16 @@ export interface VirtualUserRunRecord {
    */
   memory: Record<string, string>
   findings: VirtualUserFinding[]
+  /**
+   * What the user set out to do and how far each one got, which is the spine a
+   * transcript hangs off — the steps alone are a list of calls with no account
+   * of what they were for.
+   *
+   * Small and bounded, so it rides on the run row rather than in a table of its
+   * own: a run has as many intents as the app has scenarios, and every read of
+   * the run wants them.
+   */
+  intents: IntentRecord[]
   tally: VirtualUserTally | null
   /** Which budget or stopping rule ended the run. */
   stoppedBy: string | null
@@ -69,6 +81,16 @@ export interface VirtualUserRunOutcome {
   tally: VirtualUserTally
   memory: Record<string, string>
   stoppedBy: string | null
+  intents: readonly IntentRecord[]
+  /**
+   * Every turn the run took. Kept because a finding is an assertion until you
+   * can see what the user did before it, and because a run that found nothing
+   * is only readable as work through its steps.
+   *
+   * Stored apart from the run — see {@link VirtualUserRunStore.steps} — so
+   * listing runs does not drag a budget's worth of turns along with it.
+   */
+  steps: readonly StepRecord[]
 }
 
 /**
@@ -95,4 +117,15 @@ export interface VirtualUserRunStore {
     limit?: number
     offset?: number
   }): Promise<VirtualUserRunRecord[]>
+  /**
+   * One run's turns, in the order they happened.
+   *
+   * Its own call rather than a field on the record: a run at a 500-step budget
+   * carries more transcript than every other column put together, and `list`
+   * would pay for it on every row.
+   */
+  steps(
+    runId: string,
+    options?: { limit?: number; offset?: number }
+  ): Promise<StepRecord[]>
 }

package/src/wirings/virtual-user/virtual-user-schedule-store.ts

@@ -0,0 +1,93 @@
+import type {
+  VirtualUserBudget,
+  VirtualUserDisposition,
+} from './virtual-user.types.js'
+
+/**
+ * One persona's standing instruction to keep using the app.
+ *
+ * A virtual user that runs once tells you about one afternoon. What an app
+ * actually wants to know is what a persona hits over a fortnight, and that is
+ * a cadence, not a longer run — a budget already caps how far a single run
+ * goes, and raising it only buys a more tired user.
+ *
+ * The row is the schedule. There is deliberately no timer, interval or
+ * in-memory loop anywhere near it: a process that holds the next run in its own
+ * heap forgets it on the next deploy, and a persona silently stops. Something
+ * outside asks which rows are due; the answer survives restarts because it is
+ * written down.
+ */
+export interface VirtualUserScheduleRecord {
+  persona: string
+  /**
+   * Off by default. A schedule that ran the moment it was written would start
+   * spending an app's model budget as a side effect of a migration.
+   */
+  enabled: boolean
+  disposition: VirtualUserDisposition
+  goals: string[]
+  budget: VirtualUserBudget | null
+  /**
+   * The gap to the next run is drawn between these, not fixed. A persona that
+   * appears at exactly 09:00 every day exercises one cache state and one cron
+   * neighbourhood; a real one does not keep an appointment.
+   */
+  minIntervalMs: number
+  maxIntervalMs: number
+  /** When this persona is next allowed to run. The whole schedule, in one field. */
+  nextRunAt: Date
+  lastRunId: string | null
+  lastRunAt: Date | null
+}
+
+/** A partial write — anything left out keeps whatever the row already had. */
+export interface VirtualUserScheduleInput {
+  persona: string
+  enabled?: boolean
+  disposition?: VirtualUserDisposition
+  goals?: readonly string[]
+  budget?: VirtualUserBudget | null
+  minIntervalMs?: number
+  maxIntervalMs?: number
+  nextRunAt?: Date
+}
+
+/**
+ * Where cadences are kept, alongside {@link VirtualUserRunStore} and separate
+ * from it: a host can want the history of runs it started by hand without
+ * wanting unattended ones, and wiring nothing is how it says so.
+ *
+ * SECURITY: writing a row here spends money on every future tick, without a
+ * caller present to see it happen. The scaffold gates writes behind a scope of
+ * their own for that reason — reading what the virtual users found is a much
+ * smaller permission than deciding they should keep going.
+ */
+export interface VirtualUserScheduleStore {
+  /** Creates or updates one persona's cadence. Returns the row as it now stands. */
+  set(schedule: VirtualUserScheduleInput): Promise<VirtualUserScheduleRecord>
+  get(persona: string): Promise<VirtualUserScheduleRecord | null>
+  list(): Promise<VirtualUserScheduleRecord[]>
+  /** Enabled rows whose `nextRunAt` has passed. */
+  due(now: Date): Promise<VirtualUserScheduleRecord[]>
+  /**
+   * Pushes the persona's next run out, and records which run this was.
+   *
+   * Called *before* the run is dispatched, so a tick that dies halfway does not
+   * leave a row due and get re-dispatched by the next one. The cost is that a
+   * dispatch which throws waits a full interval rather than retrying, which is
+   * the right way round: a persona that is failing to start should not be
+   * retried every minute for a week.
+   *
+   * `from` is the `nextRunAt` the caller read, and the write must match it to
+   * land — the claim is how a tick wins the persona, not just how it records
+   * winning. Two processes on the same cron read the same due row, and without
+   * the compare-and-set both would dispatch: the same user acting twice over,
+   * at twice the budget, producing findings neither run can reproduce. The
+   * loser is told `false` and leaves the persona to whoever got there first.
+   */
+  claim(
+    persona: string,
+    claim: { from: Date; nextRunAt: Date; runId: string | null; at: Date }
+  ): Promise<boolean>
+  remove(persona: string): Promise<void>
+}

package/src/wirings/virtual-user/virtual-user-schedule.test.ts

@@ -0,0 +1,280 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type {
+  VirtualUserRunRecord,
+  VirtualUserRunStore,
+} from './virtual-user-run-store.js'
+import type {
+  VirtualUserScheduleRecord,
+  VirtualUserScheduleStore,
+} from './virtual-user-schedule-store.js'
+import {
+  isDue,
+  nextRunAt,
+  STALE_RUN_AFTER_MS,
+  tickVirtualUserSchedules,
+} from './virtual-user-schedule.js'
+
+const HOUR = 60 * 60 * 1000
+const NOW = new Date('2026-01-01T12:00:00.000Z')
+
+const schedule = (
+  over: Partial<VirtualUserScheduleRecord> = {}
+): VirtualUserScheduleRecord => ({
+  persona: 'guest',
+  enabled: true,
+  disposition: 'realistic',
+  goals: [],
+  budget: null,
+  minIntervalMs: HOUR,
+  maxIntervalMs: 3 * HOUR,
+  nextRunAt: new Date(NOW.getTime() - 1000),
+  lastRunId: null,
+  lastRunAt: null,
+  ...over,
+})
+
+const run = (
+  over: Partial<VirtualUserRunRecord> = {}
+): VirtualUserRunRecord => ({
+  runId: 'run-1',
+  persona: 'guest',
+  disposition: 'realistic',
+  seed: 1,
+  status: 'completed',
+  goals: [],
+  memory: {},
+  findings: [],
+  intents: [],
+  tally: null,
+  stoppedBy: null,
+  error: null,
+  startedBy: null,
+  createdAt: NOW,
+  finishedAt: null,
+  ...over,
+})
+
+const stores = (
+  schedules: VirtualUserScheduleRecord[],
+  runs: VirtualUserRunRecord[]
+) => {
+  const claims: {
+    persona: string
+    from: Date
+    nextRunAt: Date
+    runId: string | null
+  }[] = []
+  const failed: { runId: string; error: string }[] = []
+  const scheduleStore = {
+    // Copies, as every real store hands back: a caller holding the row object
+    // itself would never see the value it read go stale underneath it.
+    due: async (now: Date) =>
+      schedules.filter((s) => isDue(s, now)).map((s) => ({ ...s })),
+    // The row is the lock, so the fake enforces the same compare-and-set the
+    // stores do: a claim lands only while the row still holds what was read.
+    claim: async (persona, claim) => {
+      const row = schedules.find((s) => s.persona === persona)
+      if (!row || row.nextRunAt.getTime() !== claim.from.getTime()) {
+        return false
+      }
+      row.nextRunAt = claim.nextRunAt
+      if (claim.runId) {
+        row.lastRunId = claim.runId
+        row.lastRunAt = claim.at
+      }
+      claims.push({ persona, ...claim })
+      return true
+    },
+  } as unknown as VirtualUserScheduleStore
+  const runStore = {
+    list: async ({ persona } = {}) =>
+      runs.filter((r) => !persona || r.persona === persona),
+    fail: async (runId: string, error: string) => {
+      failed.push({ runId, error })
+    },
+  } as unknown as VirtualUserRunStore
+  return { scheduleStore, runStore, claims, failed }
+}
+
+describe('virtual user schedule', () => {
+  test('a disabled persona is never due, however overdue it looks', () => {
+    const row = schedule({
+      enabled: false,
+      nextRunAt: new Date(NOW.getTime() - 1000 * HOUR),
+    })
+    assert.equal(isDue(row, NOW), false)
+  })
+
+  test('the next run lands somewhere inside the persona interval, not on the hour', () => {
+    const row = schedule({ minIntervalMs: HOUR, maxIntervalMs: 5 * HOUR })
+    const draws = [0, 0.25, 0.5, 0.99].map(
+      (value) => nextRunAt(row, NOW, () => value).getTime() - NOW.getTime()
+    )
+    for (const gap of draws) {
+      assert.ok(gap >= HOUR && gap <= 5 * HOUR, `outside the interval: ${gap}`)
+    }
+    assert.equal(new Set(draws).size, draws.length)
+  })
+
+  test('a fixed cadence is expressed by asking for the same bound twice', () => {
+    const row = schedule({ minIntervalMs: HOUR, maxIntervalMs: HOUR })
+    assert.equal(nextRunAt(row, NOW, () => 0.7).getTime() - NOW.getTime(), HOUR)
+  })
+
+  test('bounds the wrong way round read as a range rather than a negative gap', () => {
+    const row = schedule({ minIntervalMs: 5 * HOUR, maxIntervalMs: HOUR })
+    const gap = nextRunAt(row, NOW, () => 0).getTime() - NOW.getTime()
+    assert.equal(gap, HOUR)
+  })
+
+  test('a due persona is dispatched and pushed out before the run starts', async () => {
+    const { scheduleStore, runStore, claims } = stores([schedule()], [])
+    const order: string[] = []
+    const result = await tickVirtualUserSchedules({
+      schedules: {
+        ...scheduleStore,
+        claim: async (persona, claim) => {
+          order.push('claim')
+          return await scheduleStore.claim(persona, claim)
+        },
+      } as VirtualUserScheduleStore,
+      runs: runStore,
+      now: NOW,
+      random: () => 0.5,
+      dispatch: async () => {
+        order.push('dispatch')
+        return 'run-new'
+      },
+    })
+
+    assert.deepEqual(result.dispatched, [
+      { persona: 'guest', runId: 'run-new' },
+    ])
+    assert.deepEqual(order, ['claim', 'dispatch', 'claim'])
+    assert.ok(claims[0]!.nextRunAt.getTime() > NOW.getTime())
+    assert.equal(claims.at(-1)!.runId, 'run-new')
+  })
+
+  test('a persona already acting is left alone rather than doubled up', async () => {
+    const { scheduleStore, runStore, claims } = stores(
+      [schedule()],
+      [run({ status: 'running', createdAt: new Date(NOW.getTime() - 60_000) })]
+    )
+    let dispatched = 0
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async () => {
+        dispatched++
+        return 'run-new'
+      },
+    })
+
+    assert.equal(dispatched, 0)
+    assert.deepEqual(result.skipped, [
+      { persona: 'guest', reason: 'in-flight' },
+    ])
+    assert.deepEqual(claims, [])
+  })
+
+  test('a run stranded by a restart is failed, not waited on forever', async () => {
+    const { scheduleStore, runStore, failed } = stores(
+      [schedule()],
+      [
+        run({
+          status: 'running',
+          createdAt: new Date(NOW.getTime() - STALE_RUN_AFTER_MS - 1),
+        }),
+      ]
+    )
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async () => 'run-new',
+    })
+
+    assert.deepEqual(result.reaped, ['run-1'])
+    assert.equal(failed.length, 1)
+    assert.match(failed[0]!.error, /still running/)
+    assert.deepEqual(result.dispatched, [
+      { persona: 'guest', runId: 'run-new' },
+    ])
+  })
+
+  test('a persona that will not start waits its interval instead of spinning', async () => {
+    const { scheduleStore, runStore, claims } = stores([schedule()], [])
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async () => {
+        throw new Error('no target')
+      },
+    })
+
+    assert.deepEqual(result.dispatched, [])
+    assert.deepEqual(result.skipped, [
+      { persona: 'guest', reason: 'dispatch-failed' },
+    ])
+    assert.equal(claims.length, 1)
+    assert.ok(claims[0]!.nextRunAt.getTime() >= NOW.getTime() + HOUR)
+  })
+
+  test('two ticks racing over one persona produce a single run', async () => {
+    const row = schedule()
+    const { scheduleStore, runStore } = stores([row], [])
+    const dispatched: string[] = []
+    const tick = () =>
+      tickVirtualUserSchedules({
+        schedules: scheduleStore,
+        runs: runStore,
+        now: NOW,
+        random: () => 0.5,
+        dispatch: async ({ persona }) => {
+          const runId = `run-${dispatched.length + 1}`
+          dispatched.push(persona)
+          return runId
+        },
+      })
+
+    // Both read the row while it is still due — the state two cron processes
+    // are in the moment before either of them writes.
+    const [first, second] = await Promise.all([tick(), tick()])
+
+    assert.equal(dispatched.length, 1)
+    const [won, lost] =
+      first.dispatched.length > 0 ? [first, second] : [second, first]
+    assert.equal(won.dispatched.length, 1)
+    assert.deepEqual(lost.dispatched, [])
+    assert.deepEqual(lost.skipped, [
+      { persona: 'guest', reason: 'claimed-elsewhere' },
+    ])
+  })
+
+  test('one persona failing does not stop the others from running', async () => {
+    const { scheduleStore, runStore } = stores(
+      [schedule({ persona: 'guest' }), schedule({ persona: 'admin' })],
+      []
+    )
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async ({ persona }) => {
+        if (persona === 'guest') throw new Error('no target')
+        return 'run-admin'
+      },
+    })
+
+    assert.deepEqual(result.dispatched, [
+      { persona: 'admin', runId: 'run-admin' },
+    ])
+    assert.deepEqual(result.skipped, [
+      { persona: 'guest', reason: 'dispatch-failed' },
+    ])
+  })
+})