@pikku/kysely 0.13.20 → 0.13.22

package/src/kysely-virtual-user-schedule-store.test.ts

@@ -0,0 +1,187 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import Database from 'better-sqlite3'
+import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
+
+import { KyselyVirtualUserScheduleStore } from './kysely-virtual-user-schedule-store.js'
+import { SerializePlugin } from './serialize-plugin.js'
+import { applyPikkuSchemas, virtualUserScheduleSchema } from './schema/index.js'
+import type { KyselyPikkuDB } from './kysely-tables.js'
+
+// With the plugin, because most projects in this package run with it and it is
+// the harder case: it deserialises columns the store has already stringified.
+const withPlugin = () =>
+  new Kysely<KyselyPikkuDB>({
+    dialect: new SqliteDialect({ database: new Database(':memory:') }),
+    plugins: [new CamelCasePlugin(), new SerializePlugin()],
+  })
+
+const bare = () =>
+  new Kysely<KyselyPikkuDB>({
+    dialect: new SqliteDialect({ database: new Database(':memory:') }),
+    plugins: [new CamelCasePlugin()],
+  })
+
+const HOUR = 60 * 60 * 1000
+
+describe('KyselyVirtualUserScheduleStore', () => {
+  let db: Kysely<KyselyPikkuDB>
+  let store: KyselyVirtualUserScheduleStore
+
+  beforeEach(async () => {
+    db = withPlugin()
+    await applyPikkuSchemas(db, [virtualUserScheduleSchema])
+    store = new KyselyVirtualUserScheduleStore(db)
+  })
+
+  test('a persona given a cadence is not running until someone says so', async () => {
+    const written = await store.set({ persona: 'guest' })
+    assert.equal(written.enabled, false)
+    assert.deepEqual(await store.due(new Date(Date.now() + 1000)), [])
+    assert.equal((await store.get('guest'))?.enabled, false)
+  })
+
+  test('a schedule written without an interval gets one, sparse by default', async () => {
+    const written = await store.set({ persona: 'guest' })
+    assert.ok(written.minIntervalMs >= HOUR)
+    assert.ok(written.maxIntervalMs >= written.minIntervalMs)
+    const stored = await store.get('guest')
+    assert.equal(stored?.minIntervalMs, written.minIntervalMs)
+    assert.equal(stored?.maxIntervalMs, written.maxIntervalMs)
+  })
+
+  test('setting one field leaves the rest of the schedule alone', async () => {
+    await store.set({
+      persona: 'guest',
+      enabled: true,
+      disposition: 'adversarial',
+      goals: ['book a room'],
+      budget: { steps: 40 },
+      minIntervalMs: HOUR,
+      maxIntervalMs: 2 * HOUR,
+    })
+    await store.set({ persona: 'guest', enabled: false })
+
+    const stored = await store.get('guest')
+    assert.equal(stored?.enabled, false)
+    assert.equal(stored?.disposition, 'adversarial')
+    assert.deepEqual(stored?.goals, ['book a room'])
+    assert.deepEqual(stored?.budget, { steps: 40 })
+    assert.equal(stored?.minIntervalMs, HOUR)
+  })
+
+  test('only enabled personas whose time has come come back as due', async () => {
+    const now = new Date()
+    await store.set({
+      persona: 'due',
+      enabled: true,
+      nextRunAt: new Date(now.getTime() - HOUR),
+    })
+    await store.set({
+      persona: 'later',
+      enabled: true,
+      nextRunAt: new Date(now.getTime() + HOUR),
+    })
+    await store.set({
+      persona: 'off',
+      enabled: false,
+      nextRunAt: new Date(now.getTime() - HOUR),
+    })
+
+    assert.deepEqual(
+      (await store.due(now)).map((row) => row.persona),
+      ['due']
+    )
+  })
+
+  test('claiming pushes the persona out of the due list', async () => {
+    const now = new Date()
+    const due = new Date(now.getTime() - HOUR)
+    await store.set({ persona: 'guest', enabled: true, nextRunAt: due })
+    const acquired = await store.claim('guest', {
+      from: due,
+      nextRunAt: new Date(now.getTime() + HOUR),
+      runId: 'run-1',
+      at: now,
+    })
+
+    assert.equal(acquired, true)
+
+    assert.deepEqual(await store.due(now), [])
+    const stored = await store.get('guest')
+    assert.equal(stored?.lastRunId, 'run-1')
+    assert.equal(stored?.lastRunAt?.getTime(), now.getTime())
+  })
+
+  test('the claim written before a run starts does not blank the last run', async () => {
+    const now = new Date()
+    const written = await store.set({ persona: 'guest', enabled: true })
+    await store.claim('guest', {
+      from: written.nextRunAt,
+      nextRunAt: now,
+      runId: 'run-1',
+      at: now,
+    })
+    await store.claim('guest', {
+      from: now,
+      nextRunAt: new Date(now.getTime() + HOUR),
+      runId: null,
+      at: now,
+    })
+
+    assert.equal((await store.get('guest'))?.lastRunId, 'run-1')
+  })
+
+  test('only one of two ticks holding the same due row can claim it', async () => {
+    const now = new Date()
+    const due = new Date(now.getTime() - HOUR)
+    await store.set({ persona: 'guest', enabled: true, nextRunAt: due })
+
+    const [first] = await store.due(now)
+    const [second] = await store.due(now)
+    assert.equal(first?.nextRunAt.getTime(), second?.nextRunAt.getTime())
+
+    const won = await store.claim('guest', {
+      from: first!.nextRunAt,
+      nextRunAt: new Date(now.getTime() + HOUR),
+      runId: 'run-1',
+      at: now,
+    })
+    const lost = await store.claim('guest', {
+      from: second!.nextRunAt,
+      nextRunAt: new Date(now.getTime() + 2 * HOUR),
+      runId: 'run-2',
+      at: now,
+    })
+
+    assert.deepEqual([won, lost], [true, false])
+    assert.equal((await store.get('guest'))?.lastRunId, 'run-1')
+  })
+
+  test('a cadence survives a store with no serialize plugin', async () => {
+    const plainDb = bare()
+    await applyPikkuSchemas(plainDb, [virtualUserScheduleSchema])
+    const plain = new KyselyVirtualUserScheduleStore(plainDb)
+    await plain.set({
+      persona: 'guest',
+      enabled: true,
+      goals: ['book a room'],
+      budget: { steps: 40, duration: '30m' },
+      minIntervalMs: HOUR,
+      maxIntervalMs: 2 * HOUR,
+    })
+
+    const stored = await plain.get('guest')
+    assert.equal(stored?.enabled, true)
+    assert.deepEqual(stored?.goals, ['book a room'])
+    assert.deepEqual(stored?.budget, { steps: 40, duration: '30m' })
+    assert.ok(stored?.nextRunAt instanceof Date)
+  })
+
+  test('a persona can be taken off the clock entirely', async () => {
+    await store.set({ persona: 'guest', enabled: true })
+    await store.remove('guest')
+    assert.equal(await store.get('guest'), null)
+    assert.deepEqual(await store.list(), [])
+  })
+})

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

@@ -0,0 +1,187 @@
+import type { Kysely, Selectable } from 'kysely'
+import type {
+  VirtualUserBudget,
+  VirtualUserDisposition,
+  VirtualUserScheduleInput,
+  VirtualUserScheduleRecord,
+  VirtualUserScheduleStore,
+} from '@pikku/core/virtual-user'
+import {
+  DEFAULT_MAX_INTERVAL_MS,
+  DEFAULT_MIN_INTERVAL_MS,
+} from '@pikku/core/virtual-user'
+import type {
+  KyselyPikkuDB,
+  VirtualUserScheduleTable,
+} from './kysely-tables.js'
+import { parseJson } from './kysely-json.js'
+import { requirePikkuSchema } from './schema/index.js'
+import { virtualUserScheduleSchema } from './schema/virtual-user-schedule.schema.js'
+
+/**
+ * Keeps each persona's cadence in a `virtualUserSchedule` table.
+ *
+ * Wiring this is what turns virtual users from something a person triggers into
+ * something that happens: without it, {@link KyselyVirtualUserRunStore} still
+ * records every run, and every run still had someone behind it. Two services
+ * rather than one so that an app can want the history without wanting the bill.
+ *
+ * Reads and writes the same way the run store does — JSON as text, timestamps
+ * as ISO strings, flags as 0/1 — so a project on SQLite and one on Postgres
+ * hold the same bytes and `SerializePlugin` is optional on both.
+ */
+export class KyselyVirtualUserScheduleStore implements VirtualUserScheduleStore {
+  private initialized = false
+
+  constructor(private db: Kysely<KyselyPikkuDB>) {}
+
+  public async init(): Promise<void> {
+    if (this.initialized) return
+    await requirePikkuSchema(this.db, virtualUserScheduleSchema)
+    this.initialized = true
+  }
+
+  async set(
+    schedule: VirtualUserScheduleInput
+  ): Promise<VirtualUserScheduleRecord> {
+    await this.init()
+    // Read-then-write rather than a partial upsert: a schedule is configuration
+    // written by a person, and the alternative is two dialects of "leave the
+    // columns I did not mention alone".
+    const existing = await this.get(schedule.persona)
+    const merged: VirtualUserScheduleRecord = {
+      persona: schedule.persona,
+      enabled: schedule.enabled ?? existing?.enabled ?? false,
+      disposition: schedule.disposition ?? existing?.disposition ?? 'realistic',
+      goals: [...(schedule.goals ?? existing?.goals ?? [])],
+      budget:
+        schedule.budget === undefined
+          ? (existing?.budget ?? null)
+          : schedule.budget,
+      minIntervalMs:
+        schedule.minIntervalMs ??
+        existing?.minIntervalMs ??
+        DEFAULT_MIN_INTERVAL_MS,
+      maxIntervalMs:
+        schedule.maxIntervalMs ??
+        existing?.maxIntervalMs ??
+        DEFAULT_MAX_INTERVAL_MS,
+      // A new schedule is due immediately. Enabling one is a deliberate act, and
+      // waiting a random half-day to find out whether it works is not a feature.
+      nextRunAt: schedule.nextRunAt ?? existing?.nextRunAt ?? new Date(),
+      lastRunId: existing?.lastRunId ?? null,
+      lastRunAt: existing?.lastRunAt ?? null,
+    }
+
+    const values = {
+      persona: merged.persona,
+      enabled: merged.enabled ? 1 : 0,
+      disposition: merged.disposition,
+      goals: JSON.stringify(merged.goals),
+      budget: merged.budget ? JSON.stringify(merged.budget) : null,
+      minIntervalMs: String(merged.minIntervalMs),
+      maxIntervalMs: String(merged.maxIntervalMs),
+      nextRunAt: merged.nextRunAt.toISOString(),
+    }
+
+    await this.db
+      .insertInto('virtualUserSchedule')
+      .values(values)
+      .onConflict((oc) =>
+        oc.column('persona').doUpdateSet({
+          enabled: values.enabled,
+          disposition: values.disposition,
+          goals: values.goals,
+          budget: values.budget,
+          minIntervalMs: values.minIntervalMs,
+          maxIntervalMs: values.maxIntervalMs,
+          nextRunAt: values.nextRunAt,
+        })
+      )
+      .execute()
+
+    return merged
+  }
+
+  async get(persona: string): Promise<VirtualUserScheduleRecord | null> {
+    await this.init()
+    const row = await this.db
+      .selectFrom('virtualUserSchedule')
+      .selectAll()
+      .where('persona', '=', persona)
+      .executeTakeFirst()
+    return row ? this.toRecord(row) : null
+  }
+
+  async list(): Promise<VirtualUserScheduleRecord[]> {
+    await this.init()
+    const rows = await this.db
+      .selectFrom('virtualUserSchedule')
+      .selectAll()
+      .orderBy('persona', 'asc')
+      .execute()
+    return rows.map((row) => this.toRecord(row))
+  }
+
+  async due(now: Date): Promise<VirtualUserScheduleRecord[]> {
+    await this.init()
+    const rows = await this.db
+      .selectFrom('virtualUserSchedule')
+      .selectAll()
+      .where('enabled', '=', 1)
+      .where('nextRunAt', '<=', now.toISOString())
+      .orderBy('nextRunAt', 'asc')
+      .execute()
+    return rows.map((row) => this.toRecord(row))
+  }
+
+  async claim(
+    persona: string,
+    claim: { from: Date; nextRunAt: Date; runId: string | null; at: Date }
+  ): Promise<boolean> {
+    await this.init()
+    const result = await this.db
+      .updateTable('virtualUserSchedule')
+      .set({
+        nextRunAt: claim.nextRunAt.toISOString(),
+        // A claim with no run id is the one written before dispatch, and must
+        // not blank out which run this persona last managed to start.
+        ...(claim.runId
+          ? { lastRunId: claim.runId, lastRunAt: claim.at.toISOString() }
+          : {}),
+      })
+      .where('persona', '=', persona)
+      // The compare-and-set: whoever writes first moves `nextRunAt`, and every
+      // other tick holding the value they read matches nothing.
+      .where('nextRunAt', '=', claim.from.toISOString())
+      .executeTakeFirst()
+    return Number(result.numUpdatedRows ?? 0) > 0
+  }
+
+  async remove(persona: string): Promise<void> {
+    await this.init()
+    await this.db
+      .deleteFrom('virtualUserSchedule')
+      .where('persona', '=', persona)
+      .execute()
+  }
+
+  private toRecord(
+    row: Selectable<VirtualUserScheduleTable>
+  ): VirtualUserScheduleRecord {
+    return {
+      persona: row.persona,
+      enabled: Boolean(row.enabled),
+      disposition: row.disposition as VirtualUserDisposition,
+      goals: parseJson(row.goals) ?? [],
+      budget: row.budget
+        ? ((parseJson(row.budget) ?? null) as VirtualUserBudget | null)
+        : null,
+      minIntervalMs: Number(row.minIntervalMs),
+      maxIntervalMs: Number(row.maxIntervalMs),
+      nextRunAt: new Date(row.nextRunAt),
+      lastRunId: row.lastRunId,
+      lastRunAt: row.lastRunAt ? new Date(row.lastRunAt) : null,
+    }
+  }
+}

package/src/kysely-workflow-service.test.ts

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict'
 import { CamelCasePlugin, Kysely, SqliteDialect, sql } from 'kysely'
 import Database from 'better-sqlite3'
 
-import type { StepState } from '@pikku/core/ecosystem/workflow'
+import type { StepState } from '@pikku/core/workflow'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { SerializePlugin } from './serialize-plugin.js'
 import { KyselyWorkflowService } from './kysely-workflow-service.js'

package/src/schema/index.ts

@@ -17,6 +17,7 @@ import { sessionSchema } from './session.schema.js'
 import { webhookSchema } from './webhook.schema.js'
 import { workflowSchema } from './workflow.schema.js'
 import { virtualUserSchema } from './virtual-user.schema.js'
+import { virtualUserScheduleSchema } from './virtual-user-schedule.schema.js'
 
 export type {
   PikkuSchema,
@@ -59,6 +60,7 @@ export const pikkuSchemas: PikkuSchema[] = [
   scopeSchema,
   auditSchema,
   virtualUserSchema,
+  virtualUserScheduleSchema,
 ]
 
 export { agentSchema } from './agent.schema.js'
@@ -70,6 +72,7 @@ export { scopeSchema } from './scope.schema.js'
 export { secretSchema } from './secret.schema.js'
 export { sessionSchema } from './session.schema.js'
 export { virtualUserSchema } from './virtual-user.schema.js'
+export { virtualUserScheduleSchema } from './virtual-user-schedule.schema.js'
 export { webhookSchema } from './webhook.schema.js'
 export { workflowSchema } from './workflow.schema.js'
 

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

@@ -0,0 +1,48 @@
+import type { PikkuSchema } from './pikku-schema.types.js'
+
+/**
+ * The `virtualUserSchedule` table {@link KyselyVirtualUserScheduleStore} writes
+ * to: one row per persona that keeps using the app on its own.
+ *
+ * Its own schema rather than a third table in {@link virtualUserSchema}, and
+ * owned by its own store: recording what a persona did and deciding that it
+ * keeps going on its own are separate opt-ins, and a project that only wants
+ * the first should not be handed a cadence table it never writes to.
+ *
+ * `persona` is the primary key: a persona has one cadence, and a second row for
+ * the same one would mean two copies of the same user acting at once — not a
+ * heavier test, a different and unreproducible one.
+ */
+export const virtualUserScheduleSchema: PikkuSchema = {
+  name: 'virtual-user-schedule',
+  ownedBy: ['virtualUserScheduleStore'],
+  statements: [
+    (db) =>
+      db.schema
+        .createTable('virtualUserSchedule')
+        .addColumn('persona', 'varchar(255)', (col) => col.primaryKey())
+        // 0 or 1 rather than a boolean, matching the run tables: a bare sqlite
+        // driver cannot bind one, and `SerializePlugin` is not installed
+        // everywhere. Off by default, so creating the table spends nothing.
+        .addColumn('enabled', 'integer', (col) => col.defaultTo(0).notNull())
+        .addColumn('disposition', 'varchar(50)', (col) => col.notNull())
+        .addColumn('goals', 'text', (col) => col.defaultTo('[]').notNull())
+        .addColumn('budget', 'text')
+        // The gap to the next run is drawn between these rather than fixed, so
+        // the persona does not keep an appointment.
+        .addColumn('minIntervalMs', 'bigint', (col) => col.notNull())
+        .addColumn('maxIntervalMs', 'bigint', (col) => col.notNull())
+        // The entire schedule. Written before a run is dispatched, so a tick
+        // that dies halfway cannot leave the row due for the next one.
+        .addColumn('nextRunAt', 'timestamp', (col) => col.notNull())
+        .addColumn('lastRunId', 'varchar(36)')
+        .addColumn('lastRunAt', 'timestamp'),
+
+    // The only read that matters at speed: which rows are due, on every tick.
+    (db) =>
+      db.schema
+        .createIndex('idx_virtual_user_schedule_due')
+        .on('virtualUserSchedule')
+        .columns(['enabled', 'nextRunAt']),
+  ],
+}

package/src/schema/virtual-user.schema.ts

@@ -2,7 +2,8 @@ import { sql } from 'kysely'
 import type { PikkuSchema } from './pikku-schema.types.js'
 
 /**
- * The `virtualUserRun` table {@link KyselyVirtualUserRunStore} writes to.
+ * The `virtualUserRun` and `virtualUserRunStep` tables
+ * {@link KyselyVirtualUserRunStore} writes to.
  *
  * Deliberately not in `pikkuSchemas`: the runtime never needs this table, only
  * a project that runs virtual users does, and creating it for everyone would
@@ -38,6 +39,10 @@ export const virtualUserSchema: PikkuSchema = {
         .addColumn('goals', 'text', (col) => col.defaultTo('[]').notNull())
         .addColumn('memory', 'text', (col) => col.defaultTo('{}').notNull())
         .addColumn('findings', 'text', (col) => col.defaultTo('[]').notNull())
+        // What the user set out to do and how far each one got. On the run row
+        // rather than beside the steps: there are a handful of them, and every
+        // read of the run wants them.
+        .addColumn('intents', 'text', (col) => col.defaultTo('[]').notNull())
         // Counts the engine kept: steps, calls, mutations, tokens, elapsed.
         .addColumn('tally', 'text')
         .addColumn('stoppedBy', 'varchar(255)')
@@ -62,5 +67,40 @@ export const virtualUserSchema: PikkuSchema = {
         .createIndex('idx_virtual_user_run_persona')
         .on('virtualUserRun')
         .columns(['persona', 'createdAt']),
+
+    // One row per turn, kept out of `virtualUserRun` so that listing runs does
+    // not drag a budget's worth of transcript along with it. No foreign key
+    // onto the run for the same reason `persona` is not one: this table is
+    // created by the store at boot on whatever engine the project uses, and a
+    // cascade that half the engines enforce differently is worse than the read
+    // rule that a step with no run is orphaned.
+    (db) =>
+      db.schema
+        .createTable('virtualUserRunStep')
+        .addColumn('runId', 'varchar(36)', (col) => col.notNull())
+        // The engine's own step number, which is what the intent records point
+        // at — not a surrogate key, so a transcript reads the same after paging.
+        // Spelled `stepIndex` because `index` is a reserved word in mysql.
+        .addColumn('stepIndex', 'integer', (col) => col.notNull())
+        .addColumn('intentId', 'varchar(255)')
+        // The action as the engine scheduled it, including the `invalid` shape
+        // for a turn the model got wrong — that turn is the interesting one.
+        .addColumn('action', 'text', (col) => col.notNull())
+        .addColumn('status', 'integer')
+        // 0 or 1 rather than a boolean, because a bare sqlite driver cannot
+        // bind one at all and `SerializePlugin` is not installed everywhere.
+        .addColumn('ok', 'integer')
+        // Already truncated by the engine, and stored JSON-encoded rather than
+        // raw: a truncated API response usually starts with a brace, which
+        // `SerializePlugin` would read back as an object rather than the string
+        // the engine actually saw.
+        .addColumn('response', 'text')
+        .addColumn('findingKinds', 'text')
+        .addColumn('tokensIn', 'integer', (col) => col.defaultTo(0).notNull())
+        .addColumn('tokensOut', 'integer', (col) => col.defaultTo(0).notNull())
+        .addPrimaryKeyConstraint('pk_virtual_user_run_step', [
+          'runId',
+          'stepIndex',
+        ]),
   ],
 }