@pikku/core 0.12.107 → 0.12.111

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

@@ -1,93 +0,0 @@
-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

@@ -1,280 +0,0 @@
-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' },
-    ])
-  })
-})

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

@@ -1,156 +0,0 @@
-import type { VirtualUserRunStore } from './virtual-user-run-store.js'
-import type {
-  VirtualUserScheduleRecord,
-  VirtualUserScheduleStore,
-} from './virtual-user-schedule-store.js'
-
-/**
- * How long a run may sit at `running` before it is read as dead rather than
- * busy.
- *
- * A run holds no process across a restart — see {@link VirtualUserRunRecord} —
- * so a deploy mid-run strands the record, and a stranded record would block its
- * persona's schedule for good. Twice the longest duration budget anyone sets in
- * practice, because the failure this guards against is cheap to recover from
- * and expensive to trigger early: reaping a run that was still working loses
- * its findings.
- */
-export const STALE_RUN_AFTER_MS = 2 * 60 * 60 * 1000
-
-/**
- * The cadence a schedule gets when it is written without one: roughly a run a
- * day, at an hour nobody can predict.
- *
- * Sparse on purpose. Every tick spends model budget with no caller present to
- * notice, so the default is the one an app can leave switched on and forget,
- * not the one that finds the most.
- */
-export const DEFAULT_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000
-export const DEFAULT_MAX_INTERVAL_MS = 24 * 60 * 60 * 1000
-
-/** Whether a row is the tick's business, for stores that cannot ask in a query. */
-export const isDue = (schedule: VirtualUserScheduleRecord, now: Date) =>
-  schedule.enabled && schedule.nextRunAt.getTime() <= now.getTime()
-
-/**
- * When this persona should next appear, drawn from its own interval.
- *
- * Uniform between the two bounds. Reversed bounds are read as a range rather
- * than rejected, because a schedule is configuration and a swapped pair is a
- * typo, not an attack.
- */
-export const nextRunAt = (
-  schedule: Pick<VirtualUserScheduleRecord, 'minIntervalMs' | 'maxIntervalMs'>,
-  now: Date,
-  random: () => number
-) => {
-  const low = Math.max(
-    0,
-    Math.min(schedule.minIntervalMs, schedule.maxIntervalMs)
-  )
-  const high = Math.max(
-    0,
-    Math.max(schedule.minIntervalMs, schedule.maxIntervalMs)
-  )
-  return new Date(now.getTime() + low + random() * (high - low))
-}
-
-export type VirtualUserSkipReason =
-  'in-flight' | 'dispatch-failed' | 'claimed-elsewhere'
-
-export interface VirtualUserTickResult {
-  dispatched: { persona: string; runId: string }[]
-  skipped: { persona: string; reason: VirtualUserSkipReason }[]
-  /** Runs found stranded at `running` and marked failed. */
-  reaped: string[]
-}
-
-export interface VirtualUserTickParams {
-  schedules: VirtualUserScheduleStore
-  runs: VirtualUserRunStore
-  /** Starts one run and answers with its id. Nothing here knows how. */
-  dispatch: (schedule: VirtualUserScheduleRecord) => Promise<string>
-  now?: Date
-  random?: () => number
-  staleAfterMs?: number
-}
-
-/**
- * Acts on whichever personas are due, once.
- *
- * The whole cadence lives in this one call, so what schedules it is the host's
- * choice — a cron wiring, a platform scheduler, or a person clicking a button.
- * Pikku does not start a timer on an app's behalf; a scaffold that did would
- * begin spending model budget the moment a project ran `pikku all`.
- *
- * A persona is skipped, not queued, while its previous run is still going. Two
- * copies of the same user acting at once is not a heavier test, it is a
- * different one, and every finding it produces is unreproducible. Two ticks
- * running at once are held to the same rule by the claim, which only lands for
- * whichever of them still sees the `nextRunAt` it read.
- */
-export const tickVirtualUserSchedules = async ({
-  schedules,
-  runs,
-  dispatch,
-  now = new Date(),
-  random = Math.random,
-  staleAfterMs = STALE_RUN_AFTER_MS,
-}: VirtualUserTickParams): Promise<VirtualUserTickResult> => {
-  const result: VirtualUserTickResult = {
-    dispatched: [],
-    skipped: [],
-    reaped: [],
-  }
-
-  for (const schedule of await schedules.due(now)) {
-    const [latest] = await runs.list({ persona: schedule.persona, limit: 1 })
-    if (latest?.status === 'running') {
-      if (now.getTime() - latest.createdAt.getTime() < staleAfterMs) {
-        result.skipped.push({ persona: schedule.persona, reason: 'in-flight' })
-        continue
-      }
-      await runs.fail(
-        latest.runId,
-        `Abandoned: still running ${Math.round((now.getTime() - latest.createdAt.getTime()) / 60000)}m after it started, which is longer than any budget allows.`
-      )
-      result.reaped.push(latest.runId)
-    }
-
-    const due = nextRunAt(schedule, now, random)
-    const acquired = await schedules.claim(schedule.persona, {
-      from: schedule.nextRunAt,
-      nextRunAt: due,
-      runId: null,
-      at: now,
-    })
-    if (!acquired) {
-      result.skipped.push({
-        persona: schedule.persona,
-        reason: 'claimed-elsewhere',
-      })
-      continue
-    }
-
-    let runId: string
-    try {
-      runId = await dispatch(schedule)
-    } catch {
-      result.skipped.push({
-        persona: schedule.persona,
-        reason: 'dispatch-failed',
-      })
-      continue
-    }
-
-    await schedules.claim(schedule.persona, {
-      from: due,
-      nextRunAt: due,
-      runId,
-      at: now,
-    })
-    result.dispatched.push({ persona: schedule.persona, runId })
-  }
-
-  return result
-}

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

@@ -1,47 +0,0 @@
-import type { ScenarioPersona } from '../../services/personas-service.js'
-import type { VirtualUserTarget } from './virtual-user.types.js'
-
-export interface PersonaTargetOptions {
-  /** Model the persona uses for its side of a conversation with an agent. */
-  model?: string
-  /** Agents this user may talk to. Omit to leave `talkTo` unavailable. */
-  agents?: readonly string[]
-}
-
-/**
- * Drive a virtual user through a signed-in persona.
- *
- * This is the only place the engine meets the network. A persona already signs
- * in as a real user over the app's own auth, keeps its cookies, re-logs-in when
- * a session expires mid-run and reports a status as data rather than throwing —
- * everything a user imitating a user needs, and none of it worth building twice.
- *
- * `invokeRaw` rather than `invoke` matters: to a virtual user a 403 is not an
- * error, it is the system saying no, which is information it should be allowed
- * to act on.
- */
-export const personaVirtualUserTarget = (
-  persona: ScenarioPersona,
-  { model, agents }: PersonaTargetOptions = {}
-): VirtualUserTarget => ({
-  call: (rpcName, args) => persona.invokeRaw(rpcName, args),
-  talkTo: agents?.length
-    ? async (agent, task) => {
-        if (!agents.includes(agent)) {
-          return {
-            passed: false,
-            reasoning: `There is no assistant called '${agent}'.`,
-            transcript: [],
-          }
-        }
-        return persona.converse({
-          agent,
-          task,
-          // A user asking for something judges the answer by whether they got
-          // what they asked for. There is no separate criterion to hold it to.
-          evaluate: `The assistant did what was asked: ${task}`,
-          model,
-        })
-      }
-    : undefined,
-})