@pikku/core 0.12.89 → 0.12.90

package/knowledge/decisions/internals/a-virtual-user-cadence-is-a-row-not-a-timer.md

@@ -0,0 +1,66 @@
+---
+type: decision
+title: A virtual user cadence is a row, not a timer
+description: How often a persona runs is stored as a due time per persona and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
+tags: virtual-user, storage, scheduling
+---
+
+# A virtual user cadence is a row, not a timer
+
+A run has a budget; a persona has a cadence. The two get confused because both
+answer "how often", and neither answers the other's question: a budget caps one
+outing, and raising it only buys a more tired user. What tells you about a
+product is the same person coming back over a fortnight.
+
+That cadence is one row per persona in `virtualUserSchedule`, holding
+`nextRunAt`. `tickVirtualUserSchedules` acts on whichever rows are due. There is
+no timer, no interval, and no in-memory loop.
+
+**Not a timer**, because a process holding the next run in its own heap forgets
+it on the next deploy, and the persona silently stops — with nothing anywhere
+saying it used to run. The row survives restarts, and any instance can act on
+it.
+
+**Not reschedule-on-completion**, which is the tempting shape: finish a run,
+draw a delay, schedule the next. It has exactly one failure mode and it is
+fatal — a crash between the two ends the persona forever, and the evidence is an
+absence. A due time written down before the run starts cannot be lost by the run
+failing.
+
+**Not a scaffolded cron.** The tick is generated as an ordinary function and
+wired by nobody. A `wireScheduler` emitted by codegen would start spending an
+application's model budget the moment somebody ran `pikku all`, on a host that
+may not even run schedulers. One line in the project turns it on:
+
+```ts
+wireScheduler({ name: 'virtualUsers', schedule: '0 * * * *', func: tickVirtualUserSchedules })
+```
+
+Tick resolution bounds how *late* a due persona is, never how often it runs — a
+persona due at 09:07 under an hourly tick starts at 10:00. Running the tick more
+often costs one indexed query and changes no cadence.
+
+Three rules make a tick safe to run at any resolution, from any number of
+instances:
+
+- **The due time is written before the run is dispatched**, so a tick that dies
+  halfway cannot leave the row due for the next one to pick up again. A dispatch
+  that throws therefore waits a full interval, which is the right way round: a
+  persona failing to start should not be retried every minute for a week.
+- **A persona whose previous run is still `running` is skipped, not queued.**
+  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.
+- **A run still `running` after `STALE_RUN_AFTER_MS` is failed and the persona
+  runs again.** This is where the stranded-record cost of
+  [a virtual user run being neither a workflow nor a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md)
+  gets paid: without it, one restart mid-run would block that persona's schedule
+  permanently.
+
+The interval is a range (`minIntervalMs`, `maxIntervalMs`), drawn per run. A
+user who arrives at exactly 09:00 every day exercises one cache state and one
+cron neighbourhood; a real one does not keep an appointment.
+
+**What this rules out:** a `setTimeout` or interval anywhere in the run path;
+the engine scheduling its own next run; a scaffolded scheduled task; a queue
+holding the next run; and a cadence that lives only in a config file, which
+cannot record when the persona last actually went.

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md

@@ -37,9 +37,14 @@ left at `running` is neither.
 
 The cost is real and is stated on the type: **a restart mid-run strands a record
 at `running` with nothing left to finish it.** A run older than its budget
-window and still `running` is dead, not working — that is a read-side rule, and
-it is cheaper than the two dependencies avoided. Nothing retries; a stranded run
-is started again, with its seed if the caller wants the same exploration.
+window and still `running` is dead, not working — a read-side rule, and cheaper
+than the two dependencies avoided. Nothing retries; a stranded run is started
+again, with its seed if the caller wants the same exploration.
+
+Where that rule is actually applied is
+[the schedule tick](a-virtual-user-cadence-is-a-row-not-a-timer.md), which has
+to: a record stuck at `running` would otherwise block its persona's cadence
+forever.
 
 **What this rules out:** dispatching the run through `startWorkflow`; a
 scaffolded queue worker; awaiting the engine inside the request (a run takes

package/knowledge/decisions/internals/index.md

@@ -16,6 +16,7 @@ caller is entitled to assume.
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
 - [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
 - [A virtual user decides whether to trust its notes once per turn, by one roll](a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md) — The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
+- [A virtual user cadence is a row, not a timer](a-virtual-user-cadence-is-a-row-not-a-timer.md) — how often a persona runs is stored as a due time per persona and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
 - [A virtual user run is not a workflow and not a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md) — runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
 - [A wall-clock threshold is a load test in disguise](a-wall-clock-threshold-is-a-load-test-in-disguise.md) — The KEK derivation test asserted a fixed 50ms budget for work that took 10ms, which went red about one run in five once the suite was large enough to compete for the machine
 - [A workflow's wire is built from the run record, not from the RPC service](a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md) — The RPC service exposes no wire, so every rpcService.wire read was undefined; the run record is the only thing that carries the caller across a step boundary

package/knowledge/decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md

@@ -32,12 +32,13 @@ The stability distinction the split was built to express is now carried by
 exports. Moving a symbol across an area boundary is still a visible diff; it
 just no longer requires a parallel tree of re-export files to be visible.
 
-Two modules survive at the old specifiers and are not entry points:
-`bootstrap-compat/root.ts` and `bootstrap-compat/ecosystem.ts` exist because
-`packages/cli` is generated by the published CLI pinned in its `build.sh`, which
-still emits `@pikku/core/ecosystem` and a bare `@pikku/core`. A test pins their
-exact contents so neither can grow, and both go when the pin moves to a CLI
-released from this branch.
+One module survives at an old specifier and is not an entry point:
+`bootstrap-compat/root.ts` exists because `packages/cli` is generated by the
+published CLI pinned in its `build.sh`, which still emits a bare `@pikku/core`.
+The matching `bootstrap-compat/ecosystem.ts` has already gone, along with every
+`@pikku/core/ecosystem` import in the repo — a guard test now fails if one comes
+back. A test pins the root shim's exact contents so it cannot grow, and it goes
+when the pin moves to a CLI released from this branch.
 
 **What this rules out:** re-introducing any specifier that re-exports another
 subpath's names. A curated facade over a module that is already published is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.89",
+  "version": "0.12.90",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -28,8 +28,8 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
 /**
  * Membership is discovered, not listed: every directory holding a
  * `pikku.config.json` is a Pikku project, so a project added later arrives
- * guarded rather than invisible. Listing them by hand is how the ecosystem
- * guard reported green on four packages it had never scanned.
+ * guarded rather than invisible. Listing them by hand is how an earlier
+ * version of this guard reported green on four packages it had never scanned.
  */
 const skipped = new Set([
   'node_modules',

package/src/ecosystem-tier-removed.test.ts

@@ -0,0 +1,69 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, relative } from 'node:path'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+const skipped = new Set([
+  'node_modules',
+  'dist',
+  '.pikku',
+  '.next',
+  'build',
+  '.git',
+  '.deploy',
+  'coverage',
+])
+
+const collectSourceFiles = (
+  directory: string,
+  out: string[] = []
+): string[] => {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!skipped.has(entry.name)) {
+        collectSourceFiles(join(directory, entry.name), out)
+      }
+    } else if (/\.(ts|tsx|js|mjs|mts|cts)$/.test(entry.name)) {
+      out.push(join(directory, entry.name))
+    }
+  }
+  return out
+}
+
+/**
+ * A stale compiled `.test.js` next to this file would otherwise read as an
+ * offender of its own scan, which is how a sibling removal guard in this
+ * directory reports a phantom failure on a dirty tree. Comparing paths with
+ * the extension dropped excludes this file and its build artifacts without
+ * excluding a neighbour that merely shares the prefix.
+ */
+const withoutExtension = (file: string): string =>
+  file.replace(/\.(ts|tsx|js|mjs|mts|cts)$/, '')
+
+/**
+ * The `@pikku/core/ecosystem/*` tier was deleted in favour of one door per
+ * name. Nothing resolves those specifiers any more, but a dead one is easy to
+ * miss: a type-only import is erased before it can fail at runtime, and the
+ * service packages exclude `**\/*.test.ts` from their tsconfig, so neither the
+ * test run nor `yarn tsc` reports it.
+ */
+describe('the ecosystem entry-point tier is gone', () => {
+  test('no source file imports from @pikku/core/ecosystem', () => {
+    const self = withoutExtension(fileURLToPath(import.meta.url))
+    const offenders = collectSourceFiles(repoRoot)
+      .filter(
+        (file) =>
+          withoutExtension(file) !== self &&
+          /@pikku\/core\/ecosystem/.test(readFileSync(file, 'utf-8'))
+      )
+      .map((file) => relative(repoRoot, file))
+    assert.deepEqual(
+      offenders,
+      [],
+      `@pikku/core/ecosystem imports found in:\n${offenders.join('\n')}`
+    )
+  })
+})

package/src/public-surface.json

@@ -97,21 +97,27 @@
   "./workflow/types": [],
   "./actor-flow": ["runConversation"],
   "./virtual-user": [
+    "DEFAULT_MAX_INTERVAL_MS",
+    "DEFAULT_MIN_INTERVAL_MS",
     "DISPOSITIONS",
     "IntentStack",
     "PRODUCTION_DISPOSITION",
+    "STALE_RUN_AFTER_MS",
     "catalogueClassification",
     "catalogueLookup",
     "deriveCatalogue",
     "deriveIntents",
     "dispositionProfile",
     "intentsForPersona",
+    "isDue",
     "isReadOnly",
+    "nextRunAt",
     "personaScopes",
     "personaVirtualUserTarget",
     "prepareVirtualUserRun",
     "reachableCatalogue",
     "runVirtualUser",
+    "tickVirtualUserSchedules",
     "unreachableCatalogue"
   ],
   "./channel/local": [

package/src/services/http-personas-converse.test.ts

@@ -17,6 +17,7 @@ const startAgentTarget = async () => {
   let logins = 0
   let authRequired = false
   let approvalsSeen: unknown[] = []
+  let firstAgentRequestAuthed: boolean | null = null
   const server: Server = createServer((req, res) => {
     const chunks: Buffer[] = []
     req.on('data', (c) => chunks.push(c))
@@ -37,6 +38,11 @@ const startAgentTarget = async () => {
       }
 
       const isAgentRoute = req.url?.startsWith('/api/rpc/agent/')
+      if (isAgentRoute && firstAgentRequestAuthed === null) {
+        firstAgentRequestAuthed = (req.headers.cookie ?? '').includes(
+          'session='
+        )
+      }
       if (
         isAgentRoute &&
         authRequired &&
@@ -85,10 +91,13 @@ const startAgentTarget = async () => {
     apiUrl: `http://127.0.0.1:${port}/api`,
     loginCount: () => logins,
     approvalsSeen: () => approvalsSeen,
+    /** Whether the very first agent call carried a session, not merely that one was minted. */
+    firstAgentRequestAuthed: () => firstAgentRequestAuthed,
     reset: (opts?: { authRequired?: boolean }) => {
       agentRuns = 0
       logins = 0
       approvalsSeen = []
+      firstAgentRequestAuthed = null
       authRequired = opts?.authRequired ?? false
     },
   }
@@ -180,8 +189,13 @@ describe('HttpPersona.converse', async () => {
     assert.deepEqual(target.approvalsSeen(), [
       [{ toolCallId: 'tc1', approved: true }],
     ])
-    // No-auth agent → converse never signs in (lazy login).
-    assert.equal(target.loginCount(), 0)
+    // Signed in even though the agent route is public: a thread minted under a
+    // fresh anonymous id per request belongs to nobody, so turn two comes back
+    // as somebody else's. A persona is a real account either way — and it is
+    // the *first* call that has to carry the session, which a login count
+    // alone would not show.
+    assert.equal(target.loginCount(), 1)
+    assert.equal(target.firstAgentRequestAuthed(), true)
   })
 
   test('signs in lazily and retries once when an agent route returns 401', async () => {

package/src/services/http-personas.ts

@@ -111,6 +111,14 @@ export class HttpPersona implements ScenarioPersona {
     if (!agentRunner) {
       throw new AIProviderNotConfiguredError()
     }
+    // Signed in here rather than left to postAgent's 401 retry, which a public
+    // agent route never triggers. An unowned thread is minted under a fresh
+    // anonymous id per request, so turn one succeeds and turn two is refused as
+    // somebody else's — and a persona is a real account with real credentials,
+    // so there is no case where conversing as nobody is the intent.
+    if (!this.signedIn) {
+      await this.login()
+    }
     const model = options.model ?? this.config.model
     if (!model) {
       throw new Error(

package/src/types/core.types.ts

@@ -41,6 +41,7 @@ import type { AgentRunService } from '../wirings/agent/agent.types.js'
 import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
 import type { PermissionMetadata } from '../function/function-meta.types.js'
 import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js'
+import type { VirtualUserScheduleStore } from '../wirings/virtual-user/virtual-user-schedule-store.js'
 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'
@@ -173,6 +174,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
    * {@link VirtualUserRunStore}.
    */
   virtualUserRunStore?: VirtualUserRunStore
+  /**
+   * Each persona's cadence, for apps that want their virtual users to keep
+   * going without being asked. Separate from the run store on purpose: wiring
+   * nothing is how an app says it only wants the runs it starts itself.
+   */
+  virtualUserScheduleStore?: VirtualUserScheduleStore
   /** V8 precise-coverage collector (`pikku dev --coverage` only) */
   coverageService?: CoverageService
   audit?: AuditService

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', () => {

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

@@ -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[]>
 }