@pikku/core 0.12.88 → 0.12.90

package/CHANGELOG.md

@@ -1,3 +1,199 @@
+## 0.12.90
+
+### Patch Changes
+
+- 3c0012c: Gate console agent-thread reads and deletes on thread ownership, claim MongoDB workflow steps atomically, and reach the deployment fallback from `rpcWithWire`
+
+  `getAgentThreadMessages` and `deleteAgentThread` in the console addon took a
+  caller-supplied `threadId` straight to storage, while their siblings
+  `getAgentThreads` and `getAgentThreadRuns` already filtered to what the session
+  owns. Both now carry an `isThreadOwner` permission: an admin reaches any thread,
+  everyone else only their own, and a missing thread is refused rather than 404'd
+  so it is indistinguishable from someone else's.
+
+  `MongoDBWorkflowService` claimed a step by reading its status and then writing
+  it, under a `withStepLock` that is a pass-through — so two dispatches racing for
+  the same step could both proceed and run a side-effecting step twice. The claim
+  is now a single status-guarded update, atomic on one document.
+
+  `rpcWithWire` threw `RPCNotFoundError` for any unresolved namespaced call
+  instead of falling through to the deployment service, so a namespaced RPC that
+  `rpc()` would have dispatched remotely failed when called with an explicit wire.
+
+- 05e47cf: fix(personas): sign a persona in before it converses, not after a 401
+
+  `HttpPersona.converse` left authentication to `postAgent`'s 401-retry, which
+  only fires on a route that refuses an anonymous caller. An agent route wired
+  without `auth: true` never refuses one: turn one is accepted and the thread is
+  minted under a fresh anonymous id, turn two arrives under a different anonymous
+  id, and the persona is told the thread belongs to somebody else — intermittently,
+  because it depends on which turn the retry happened to run on.
+
+  The persona now logs in before the first turn if it has not already. A persona
+  is a declared account with real credentials in every case, so there was never a
+  run where conversing as nobody was what was wanted; the sign-in is the same one
+  `call` has always done, just no longer conditional on the server pushing back.
+
+- cfd364a: Remove the last `@pikku/core/ecosystem` references and guard against new ones
+
+  `@pikku/kysely`'s workflow-service test still imported `StepState` from
+  `@pikku/core/ecosystem/workflow`, a subpath that no longer exists in
+  `@pikku/core`'s `exports`. Nothing caught it: the import is type-only, so tsx
+  erases it before it can fail at runtime, and the package tsconfig excludes
+  `**/*.test.ts`, so `yarn tsc` never saw it either. It now imports from
+  `@pikku/core/workflow`.
+
+  A new guard test in `@pikku/core` scans the repository for the dead specifier
+  and fails if one comes back, so the next stale import is a red test rather than
+  a silent `any`.
+
+- 05e47cf: fix(virtual-user): offer agents under the name the server can resolve
+
+  `reachableAgents` named each offered agent `agent.name ?? id`, where `id` is the
+  key the agent is registered under and `agent.name` is the display label from its
+  config. Those are the same string only by coincidence. `addAgent` stores the
+  export's own name and `resolveAgent` looks the call up by it, so an agent
+  exported as `adminAgent` and declaring `name: 'admin-agent'` was advertised to a
+  virtual user as `admin-agent` — a name nothing has ever registered. The persona
+  took the offer on its first turn, the stage answered
+  `500 AI agent not found: admin-agent`, and the run died there. Every fixture in
+  the tests happened to use one string for both, so nothing caught it.
+
+  The offered name is now always the registration key. `AgentReachability.name` is
+  gone rather than ignored, so there is no longer a display label sitting in the
+  shape inviting the same mistake.
+
+- 05e47cf: feat(virtual-user): keep the transcript a run already produced
+
+  The engine returns `intents` and `steps` on every run — what the user set out
+  to do, and every turn it took getting there — and `VirtualUserRunOutcome` kept
+  neither. The record held counts and findings, so the one question anybody
+  actually asks of a completed run ("what did it _do_?") had no answer anywhere,
+  even though the answer had been computed and thrown away a moment earlier.
+
+  `VirtualUserRunOutcome` now carries both, and `VirtualUserRunStore` gains a
+  `steps(runId, options?)` read. Intents ride on the run record: there are a
+  handful of them and every read of the run wants them. Steps get their own
+  `virtualUserRunStep` table, because a run at a 500-step budget carries more
+  transcript than every other column together and `list()` would pay for it on
+  every row.
+
+  Three things the kysely store had to get right, all of them driver differences
+  rather than design:
+
+  - steps are inserted in chunks of 50, because a bare sqlite driver binds at
+    most 999 variables per statement and ten columns times a 500-step budget is
+    five thousand — an un-chunked insert fails on long runs, which are the
+    interesting ones;
+  - `ok` is stored as 0 or 1, since a bare driver cannot bind a boolean at all
+    and `SerializePlugin` is not installed everywhere;
+  - `response` is stored JSON-encoded, because a truncated API response usually
+    starts with a brace and `SerializePlugin` would otherwise read it back as an
+    object rather than the string the engine saw.
+
+  Completing a run that does not exist no longer writes steps: there is no
+  foreign key to refuse them and nothing would ever read or reap them.
+
+  **This adds a table to the `virtualUser` schema**, and the runtime creates
+  nothing: a database that already has `virtualUserRun` gets the store's own
+  refusal at startup until `pikku db generate` writes the migration and
+  `pikku db migrate` applies it. Landing it now costs nothing, because
+  `scaffold.virtualUser` is not yet switched on anywhere.
+
+- 05e47cf: feat(virtual-user): put each persona on its own clock
+
+  A budget says where one run stops. Nothing said how often a persona should use
+  the application, so in practice each one ran whenever somebody remembered — and
+  what actually tells you about a product is the same user coming back over a
+  fortnight.
+
+  Each persona now gets a row rather than a bigger budget. `virtualUserSchedule`
+  holds `enabled`, the disposition and goals to run with, an interval **range**,
+  and `nextRunAt`. `tickVirtualUserSchedules` acts on whichever rows are due:
+
+  ```ts
+  wireScheduler({
+    name: 'virtualUsers',
+    schedule: '0 * * * *',
+    func: tickVirtualUserSchedules,
+  })
+  ```
+
+  The tick is generated and wired by nobody, deliberately. A scaffolded
+  `wireScheduler` would start spending an application's model budget the moment
+  somebody ran `pikku all`, on a host that may not run schedulers at all. Tick
+  resolution bounds how late a due persona is, never how often it runs.
+
+  Three things it does that are easy to leave out:
+
+  - The next due time is written **before** the run is dispatched, so a tick that
+    dies halfway cannot hand the same persona to the next one. A dispatch that
+    throws waits a full interval instead of retrying every minute for a week.
+    That write is a compare-and-set against the `nextRunAt` the tick read, so it
+    is also how a tick _wins_ the persona: two processes on the same cron see the
+    same due row, and only the one whose claim lands dispatches.
+  - A persona whose previous run is still `running` is skipped, not queued. Two
+    copies of the same user acting at once is a different test, and its findings
+    do not reproduce.
+  - A run still `running` after two hours is failed. Without that, one restart
+    mid-run blocks that persona's schedule permanently — which is where the
+    stranded-record cost of not using a queue finally gets paid.
+
+  Reschedule-on-completion was the other candidate and is worse in exactly one
+  way, fatally: a crash between finishing and scheduling ends the persona forever,
+  and the evidence is an absence.
+
+  New: `VirtualUserScheduleStore` in core (with the tick, `isDue` and `nextRunAt`
+  as pure functions), `KyselyVirtualUserScheduleStore` and its own schema —
+  its own rather than a third table in `virtualUserSchema`, and owned by its own
+  store, so a project that records runs and never wants them unattended carries no
+  cadence table. `scaffold.virtualUser` gains `setVirtualUserSchedule`,
+  `listVirtualUserSchedules` and the tick, behind a new `virtualUser:schedule`
+  scope: starting a run spends money once with a caller watching, while writing a
+  schedule spends it repeatedly with nobody there.
+
+  The console's Virtual Users screen gains a **Run now** button beside a persona's
+  run history, gated on `pikku:console:virtualUsers:run`. It dispatches the
+  project's own `runVirtualUser` rather than starting a run itself, so a run the
+  application would refuse — an acted-upon persona, a non-accountable disposition
+  in production — is still refused.
+
+## 0.12.89
+
+### Patch Changes
+
+- 32616af: Carry the trace id across a remote RPC hop
+
+  `ContextAwareRPCService` sent the wire's trace id as `x-trace-id`, but the HTTP
+  runner on the receiving end reads `x-request-id` — the header every other sender
+  uses, including `buildRemoteHeaders`, which every deployment service goes
+  through. The receiving side therefore ignored the incoming id and generated a
+  fresh one, so a trace broke at each remote RPC boundary instead of spanning it.
+  Remote RPC now sends `x-request-id` too.
+
+- 6848cd9: fix(workflow): back off the stalled-run sweep, and skip runs that cannot move
+
+  `sweepUndispatchedSteps` has always consulted a per-run backoff so a genuine
+  queue backlog is not amplified by a tick that keeps firing at the steps the
+  backlog is already delaying. `sweepStalledRuns` — its sibling, doing the same
+  re-drive through the same orchestrator queue — had none, and re-resumed every
+  stalled run on every tick. A resume does not clear whatever wedged a run, so
+  the same runs came back on the next tick and the next: in production seven
+  permanently stuck runs refilled a purged orchestrator queue at seven messages a
+  minute, and a backlog of six thousand could never drain because each pass added
+  work the previous pass had not finished. It now takes the same backoff, and
+  both sweeps share one instance — the record belongs to the re-drive, not to the
+  signal that asked for it, so a run the relay nudged a moment ago is not nudged
+  again by the sweep.
+
+  `runWorkflowJob` also now returns immediately for a run in a terminal state
+  instead of taking the run lock and replaying the workflow body. The orchestrator
+  queue is at-least-once and the relay re-dispatches on purpose, so a message for
+  a run that already settled is routine — and replaying one could park the body on
+  a wait that nothing would ever satisfy, holding the run lock, and the pooled
+  connection under it, until something external gave up. `suspended` is
+  deliberately not included: it ends a pass, not the run.
+
 ## 0.12.88
 
 ### Patch Changes

package/dist/services/http-personas.js

@@ -57,6 +57,14 @@ export class HttpPersona {
         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(`[scenario] persona '${this.name}' converse needs a model — pass options.model or set 'model' on the personas service`);

package/dist/types/core.types.d.ts

@@ -29,6 +29,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';
@@ -135,6 +136,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;
@@ -182,7 +189,7 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
      * sets it; services that log fall back to the singleton logger.
      */
     logger: Logger;
-    /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
+    /** Trace ID for distributed tracing — propagated across remote RPC calls via the x-request-id header */
     traceId: string;
     functionId: string;
     addonNamespace: string;

package/dist/wirings/rpc/rpc-runner.js

@@ -245,7 +245,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(/\/+$/, '');
         const res = await fetch(`${base}/remote/rpc/${encodeURIComponent(remoteFn)}`, {
@@ -270,10 +270,9 @@ 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(addonCall, data, mergedWire);
             }
-            return this.executeAddonFunction(addonCall, data, mergedWire);
         }
         let resolved;
         try {
@@ -281,8 +280,8 @@ export class ContextAwareRPCService {
         }
         catch (e) {
             if (e instanceof RPCNotFoundError && this.services.deploymentService) {
-                const session = await resolveWireSession(this.wire);
-                return this.services.deploymentService.invoke(rpcName, data, session, this.wire.traceId);
+                const session = await resolveWireSession(mergedWire);
+                return this.services.deploymentService.invoke(rpcName, data, session, mergedWire.traceId);
             }
             throw e;
         }

package/dist/wirings/virtual-user/index.d.ts

@@ -16,11 +16,13 @@
  * {@link VirtualUserTarget}, which in production is an `HttpPersona`
  * signed in as a real user against staging or production.
  */
-export type { ApiCatalogueEntry, IntentSource, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTarget, } from './virtual-user.types.js';
+export type { ApiCatalogueEntry, IntentRecord, IntentSource, StepRecord, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTarget, } from './virtual-user.types.js';
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, type RunVirtualUserParams, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
 export type { VirtualUserRunOutcome, VirtualUserRunRecord, 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, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';

package/dist/wirings/virtual-user/index.js

@@ -1,6 +1,7 @@
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
+export { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, isDue, nextRunAt, STALE_RUN_AFTER_MS, tickVirtualUserSchedules, } from './virtual-user-schedule.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { IntentStack, intentsForPersona } from './virtual-user-intents.js';

package/dist/wirings/virtual-user/virtual-user-agents.d.ts

@@ -13,7 +13,6 @@
  */
 /** The part of an agent's meta this needs. */
 export interface AgentReachability {
-    name?: string;
     description?: string;
     scopes?: readonly string[];
     auth?: boolean;
@@ -24,7 +23,13 @@ export interface ReachableAgent {
     description?: string;
 }
 /**
- * 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

package/dist/wirings/virtual-user/virtual-user-agents.js

@@ -1,6 +1,12 @@
 import { hasScopes } from '../../scopes.js';
 /**
- * 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
@@ -19,6 +25,6 @@ export const reachableAgents = (agents, scopes) => Object.entries(agents)
     return hasScopes(agent.scopes, scopes);
 })
     .map(([id, agent]) => ({
-    name: agent.name ?? id,
+    name: id,
     ...(agent.description ? { description: agent.description } : {}),
 }));

package/dist/wirings/virtual-user/virtual-user-run-store.d.ts

@@ -1,4 +1,4 @@
-import type { VirtualUserDisposition, VirtualUserFinding, VirtualUserTally } from './virtual-user.types.js';
+import type { IntentRecord, StepRecord, VirtualUserDisposition, VirtualUserFinding, VirtualUserTally } from './virtual-user.types.js';
 /**
  * One recorded run: who ran, what they were told, and what came back.
  *
@@ -34,6 +34,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;
@@ -62,6 +72,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[];
 }
 /**
  * Where runs are kept. Declared here rather than in a database package so the
@@ -87,4 +107,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/dist/wirings/virtual-user/virtual-user-schedule-store.d.ts

@@ -0,0 +1,89 @@
+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/dist/wirings/virtual-user/virtual-user-schedule-store.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/virtual-user/virtual-user-schedule.d.ts

@@ -0,0 +1,71 @@
+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 declare const STALE_RUN_AFTER_MS: number;
+/**
+ * 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 declare const DEFAULT_MIN_INTERVAL_MS: number;
+export declare const DEFAULT_MAX_INTERVAL_MS: number;
+/** Whether a row is the tick's business, for stores that cannot ask in a query. */
+export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) => boolean;
+/**
+ * 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 declare const nextRunAt: (schedule: Pick<VirtualUserScheduleRecord, "minIntervalMs" | "maxIntervalMs">, now: Date, random: () => number) => Date;
+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 declare const tickVirtualUserSchedules: ({ schedules, runs, dispatch, now, random, staleAfterMs, }: VirtualUserTickParams) => Promise<VirtualUserTickResult>;