@pikku/kysely 0.13.19 → 0.13.21

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

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

package/dist/src/schema/virtual-user.schema.js

@@ -1,6 +1,7 @@
 import { sql } from 'kysely';
 /**
- * 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
@@ -17,7 +18,8 @@ import { sql } from 'kysely';
  * week's does not depend on which database they were found in.
  */
 export const virtualUserSchema = {
-    name: 'virtualUser',
+    name: 'virtual-user',
+    ownedBy: ['virtualUserRunStore'],
     statements: [
         (db) => db.schema
             .createTable('virtualUserRun')
@@ -32,6 +34,10 @@ export const virtualUserSchema = {
             .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)')
@@ -50,5 +56,38 @@ export const virtualUserSchema = {
             .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',
+        ]),
     ],
 };

package/dist/src/schema/webhook.schema.js

@@ -2,6 +2,7 @@ import { sql } from 'kysely';
 /** Webhook deliveries and one row per delivery attempt. */
 export const webhookSchema = {
     name: 'webhook',
+    ownedBy: ['webhookService'],
     statements: [
         (db) => db.schema
             .createTable('webhookDelivery')

package/dist/src/schema/workflow.schema.js

@@ -16,6 +16,7 @@ import { sql } from 'kysely';
  */
 export const workflowSchema = {
     name: 'workflow',
+    ownedBy: ['workflowService', 'workflowRunService'],
     statements: [
         (db) => db.schema
             .createTable('workflowRuns')

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/coercion-plugin.ts","../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-agent-run-scores.ts","../src/kysely-agent-run-service.ts","../src/kysely-agent-run-state-service.ts","../src/kysely-agent-storage-service.ts","../src/kysely-audit-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-scope-service.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-virtual-user-run-store.ts","../src/kysely-webhook-service.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../src/schema/agent.schema.ts","../src/schema/audit.schema.ts","../src/schema/channel.schema.ts","../src/schema/credential.schema.ts","../src/schema/deployment.schema.ts","../src/schema/index.ts","../src/schema/pikku-schema.types.ts","../src/schema/scope.schema.ts","../src/schema/secret.schema.ts","../src/schema/session.schema.ts","../src/schema/virtual-user.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}
+{"root":["../src/coercion-plugin.ts","../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-agent-run-scores.ts","../src/kysely-agent-run-service.ts","../src/kysely-agent-run-state-service.ts","../src/kysely-agent-storage-service.ts","../src/kysely-audit-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-scope-service.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-virtual-user-run-store.ts","../src/kysely-virtual-user-schedule-store.ts","../src/kysely-webhook-service.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../src/schema/agent.schema.ts","../src/schema/audit.schema.ts","../src/schema/channel.schema.ts","../src/schema/credential.schema.ts","../src/schema/deployment.schema.ts","../src/schema/index.ts","../src/schema/pikku-schema.types.ts","../src/schema/scope.schema.ts","../src/schema/secret.schema.ts","../src/schema/session.schema.ts","../src/schema/virtual-user-schedule.schema.ts","../src/schema/virtual-user.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.19",
+  "version": "0.13.21",
   "description": "Kysely-backed Pikku services — workflow state, secrets, sessions, scopes and audit",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.87"
+    "@pikku/core": "^0.12.90"
   },
   "dependencies": {
     "kysely": "^0.29.5"

package/src/index.ts

@@ -18,6 +18,7 @@ export {
 } from './create-audited-kysely.js'
 export { KyselyAuditService } from './kysely-audit-service.js'
 export { KyselyVirtualUserRunStore } from './kysely-virtual-user-run-store.js'
+export { KyselyVirtualUserScheduleStore } from './kysely-virtual-user-schedule-store.js'
 
 export {
   SerializePlugin,
@@ -32,12 +33,22 @@ export {
   type CreateCoercionPluginOptions,
 } from './coercion-plugin.js'
 export {
+  agentSchema,
   auditSchema,
+  channelSchema,
+  credentialSchema,
+  deploymentSchema,
+  scopeSchema,
+  secretSchema,
+  sessionSchema,
+  virtualUserSchema,
+  webhookSchema,
+  workflowSchema,
   pikkuSchemas,
+  requiredPikkuSchemas,
   applyPikkuSchemas,
   compilePikkuSchemas,
-  ensurePikkuSchema,
-  type EnsureOutcome,
+  requirePikkuSchema,
   resolveRequirements,
   type PikkuSchema,
   type RequiredTypes,
@@ -51,4 +62,6 @@ export type { AgentRunService, AgentRunRow } from '@pikku/core/agent'
 export type {
   VirtualUserRunStore,
   VirtualUserRunRecord,
+  VirtualUserScheduleStore,
+  VirtualUserScheduleRecord,
 } from '@pikku/core/virtual-user'

package/src/kysely-agent-run-state-service.ts

@@ -9,7 +9,7 @@ import type {
   SaveScoreInput,
 } from '@pikku/core/services'
 import type { PendingApproval } from '@pikku/core/agent'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { agentSchema } from './schema/agent.schema.js'
 import { getRunScores, saveRunScore } from './kysely-agent-run-scores.js'
 
@@ -20,7 +20,7 @@ export class KyselyAgentRunStateService implements AgentRunStateService {
 
   async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, agentSchema)
+    await requirePikkuSchema(this.db, agentSchema)
     this.initialized = true
   }
 

package/src/kysely-agent-storage-service.ts

@@ -14,7 +14,7 @@ import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
 import { getRunScores, saveRunScore } from './kysely-agent-run-scores.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { agentSchema } from './schema/agent.schema.js'
 
 export class KyselyAgentStorageService
@@ -26,7 +26,7 @@ export class KyselyAgentStorageService
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, agentSchema)
+    await requirePikkuSchema(this.db, agentSchema)
     this.initialized = true
   }
 

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

@@ -309,21 +309,13 @@ describe('KyselyAuditService against a CamelCasePlugin connection', () => {
 })
 
 describe('KyselyAuditService.init', () => {
-  test('creates the audit table on a database that has none', async () => {
+  test('refuses to boot against a database that has none', async () => {
     const fresh = new Kysely<any>({
       dialect: new SqliteDialect({ database: new Database(':memory:') }),
       plugins: [new CamelCasePlugin()],
     })
     const freshService = new KyselyAuditService(fresh)
-    await freshService.init()
-    await freshService.write([
-      event({ eventId: 'e1', type: 't', occurredAt: '2026-01-01' }),
-    ])
-    const { events } = await freshService.query()
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e1']
-    )
+    await assert.rejects(freshService.init(), /pikku db generate/)
   })
 
   // Two boots against one database, and the second must not wipe the first.

package/src/kysely-audit-service.ts

@@ -6,7 +6,7 @@ import type {
   AuditQueryResult,
 } from '@pikku/core/services'
 import type { Kysely } from 'kysely'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { auditSchema } from './schema/audit.schema.js'
 
 const jsonOrNull = (v: unknown): string | null =>
@@ -103,7 +103,7 @@ export class KyselyAuditService implements AuditService {
    */
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, auditSchema)
+    await requirePikkuSchema(this.db, auditSchema)
     this.initialized = true
   }
 

package/src/kysely-channel-store.ts

@@ -3,7 +3,7 @@ import type { Channel } from '@pikku/core/channel'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { channelSchema } from './schema/channel.schema.js'
 
 export class KyselyChannelStore extends ChannelStore {
@@ -15,7 +15,7 @@ export class KyselyChannelStore extends ChannelStore {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, channelSchema)
+    await requirePikkuSchema(this.db, channelSchema)
     this.initialized = true
   }
 

package/src/kysely-credential-service.ts

@@ -8,7 +8,7 @@ import {
 import type { CredentialService } from '@pikku/core/services'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { credentialSchema } from './schema/credential.schema.js'
 
 export interface KyselyCredentialServiceConfig {
@@ -42,7 +42,7 @@ export class KyselyCredentialService implements CredentialService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, credentialSchema)
+    await requirePikkuSchema(this.db, credentialSchema)
     this.initialized = true
   }
 

package/src/kysely-deployment-service.ts

@@ -9,7 +9,7 @@ import type { SecretService } from '@pikku/core/services'
 import { getAllFunctionNames } from '@pikku/core/function'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { deploymentSchema } from './schema/deployment.schema.js'
 
 export class KyselyDeploymentService implements DeploymentService {
@@ -31,7 +31,7 @@ export class KyselyDeploymentService implements DeploymentService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, deploymentSchema)
+    await requirePikkuSchema(this.db, deploymentSchema)
     this.initialized = true
   }
 

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

@@ -5,6 +5,7 @@ import Database from 'better-sqlite3'
 import { SerializePlugin } from './serialize-plugin.js'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { KyselyScopeService } from './kysely-scope-service.js'
+import { applyPikkuSchemas, scopeSchema } from './schema/index.js'
 
 const SCOPES = [
   { id: 'admin' },
@@ -41,6 +42,7 @@ beforeEach(async () => {
     plugins: [new CamelCasePlugin(), new SerializePlugin()],
   })
   await createUserTable(db)
+  await applyPikkuSchemas(db, [scopeSchema])
   service = new KyselyScopeService(db)
   await service.init()
   await service.syncScopes(SCOPES)

package/src/kysely-scope-service.ts

@@ -8,7 +8,7 @@ import {
 } from '@pikku/core/errors'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { scopeSchema } from './schema/scope.schema.js'
 
 /**
@@ -30,7 +30,7 @@ export class KyselyScopeService implements ScopeService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, scopeSchema)
+    await requirePikkuSchema(this.db, scopeSchema)
     this.initialized = true
   }
 

package/src/kysely-secret-service.ts

@@ -10,7 +10,7 @@ import type { SecretService, SecretValues } from '@pikku/core/services'
 import type { SecretValue } from '@pikku/core/classification'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { secretSchema } from './schema/secret.schema.js'
 
 export interface KyselySecretServiceConfig {
@@ -44,7 +44,7 @@ export class KyselySecretService implements SecretService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, secretSchema)
+    await requirePikkuSchema(this.db, secretSchema)
     this.initialized = true
   }
 

package/src/kysely-services.test.ts

@@ -18,6 +18,30 @@ import { KyselyAgentRunService } from './kysely-agent-run-service.js'
 import { KyselySecretService } from './kysely-secret-service.js'
 import { KyselyCredentialService } from './kysely-credential-service.js'
 import { KyselySessionStore } from './kysely-session-store.js'
+import {
+  agentSchema,
+  applyPikkuSchemas,
+  channelSchema,
+  credentialSchema,
+  deploymentSchema,
+  secretSchema,
+  sessionSchema,
+  workflowSchema,
+} from './schema/index.js'
+
+/**
+ * Every schema the services under test boot against. They no longer create
+ * their own tables, so the harness stands in for `pikku db migrate`.
+ */
+const SERVICE_SCHEMAS = [
+  channelSchema,
+  workflowSchema,
+  deploymentSchema,
+  agentSchema,
+  secretSchema,
+  credentialSchema,
+  sessionSchema,
+]
 
 function createSqliteDb(): Kysely<KyselyPikkuDB> {
   return new Kysely<KyselyPikkuDB>({
@@ -345,6 +369,7 @@ describe('Kysely Services - SQLite', () => {
 
   before(async () => {
     db = createSqliteDb()
+    await applyPikkuSchemas(db, SERVICE_SCHEMAS)
   })
 
   after(async () => {
@@ -365,6 +390,7 @@ describe(
     before(async () => {
       db = createPostgresDb()!
       await dropAllTables(db)
+      await applyPikkuSchemas(db, SERVICE_SCHEMAS)
     })
 
     after(async () => {

package/src/kysely-session-store.ts

@@ -3,7 +3,7 @@ import type { CoreUserSession } from '@pikku/core/types'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { sessionSchema } from './schema/session.schema.js'
 
 export class KyselySessionStore implements SessionStore {
@@ -13,7 +13,7 @@ export class KyselySessionStore implements SessionStore {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, sessionSchema)
+    await requirePikkuSchema(this.db, sessionSchema)
     this.initialized = true
   }
 

package/src/kysely-tables.test.ts

@@ -5,15 +5,7 @@ import { join } from 'node:path'
 import { Kysely, SqliteDialect } from 'kysely'
 import Database from 'better-sqlite3'
 
-import { applyPikkuSchemas, ensurePikkuSchema } from './schema/index.js'
-import { virtualUserSchema } from './schema/virtual-user.schema.js'
-
-/**
- * Opt-in schemas that still have an interface in `KyselyPikkuDB`, so the drift
- * check covers them too. A table being opt-in says when it is created, not
- * whether its type is allowed to disagree with its DDL.
- */
-const OPTIONAL_SCHEMAS = [virtualUserSchema]
+import { applyPikkuSchemas } from './schema/index.js'
 
 /**
  * `KyselyPikkuDB` and the schema declaration describe the same tables, and
@@ -73,9 +65,6 @@ const declaredSchema = async (): Promise<Map<string, Set<string>>> => {
       .addColumn('id', 'text', (col) => col.primaryKey())
       .execute()
     await applyPikkuSchemas(db)
-    for (const schema of OPTIONAL_SCHEMAS) {
-      await ensurePikkuSchema(db, schema)
-    }
 
     const tables = await db.introspection.getTables()
     return new Map(

package/src/kysely-tables.ts

@@ -311,6 +311,7 @@ export interface VirtualUserRunTable {
   goals: Generated<string>
   memory: Generated<string>
   findings: Generated<string>
+  intents: Generated<string>
   tally: string | null
   stoppedBy: string | null
   error: string | null
@@ -324,6 +325,79 @@ export interface VirtualUserRunTable {
   finishedAt: Date | string | null
 }
 
+/**
+ * One audit event. Every column is text on every engine so a locally-run
+ * project and a deployed stage write rows the same reader can read; the JSON
+ * columns (`tables`, `changedCols`, `event`, `old`, `data`) are serialised by
+ * {@link KyselyAuditService} rather than by a plugin.
+ */
+export interface AuditTable {
+  auditId: string
+  /** ISO 8601, because string ordering is chronological ordering. */
+  occurredAt: string
+  type: string
+  source: Generated<string>
+  outcome: string | null
+  functionId: string | null
+  wireType: string | null
+  traceId: string | null
+  transactionId: string | null
+  queryId: string | null
+  userId: string | null
+  orgId: string | null
+  pikkuUserId: string | null
+  tables: string | null
+  changedCols: string | null
+  event: string | null
+  old: string | null
+  data: string | null
+}
+
+/**
+ * One turn of a run's transcript.
+ *
+ * Its own table rather than a column on {@link VirtualUserRunTable}: a run at a
+ * 500-step budget carries more transcript than every other column together, and
+ * the run list would pay for it on every row.
+ */
+export interface VirtualUserRunStepTable {
+  runId: string
+  /** The engine's step number. `stepIndex` because `index` is reserved in mysql. */
+  stepIndex: number
+  intentId: string | null
+  /** JSON: the action the engine scheduled, or the `invalid` shape. */
+  action: string
+  status: number | null
+  /** 0 or 1: not every driver in this package can bind a boolean. */
+  ok: number | null
+  /** JSON-encoded, so a brace-leading response is not read back as an object. */
+  response: string | null
+  /** JSON array, null when the turn produced no finding. */
+  findingKinds: string | null
+  tokensIn: Generated<number>
+  tokensOut: Generated<number>
+}
+
+/**
+ * One persona's cadence. Nullable timestamps and 0/1 flags for the same driver
+ * reasons as {@link VirtualUserRunTable}.
+ */
+export interface VirtualUserScheduleTable {
+  persona: string
+  /** 0 or 1: not every driver in this package can bind a boolean. */
+  enabled: Generated<number>
+  disposition: string
+  goals: Generated<string>
+  /** JSON, or null for the engine's own default budget. */
+  budget: string | null
+  /** BIGINT, so a driver may hand either back. */
+  minIntervalMs: string | number | bigint
+  maxIntervalMs: string | number | bigint
+  nextRunAt: Date | string
+  lastRunId: string | null
+  lastRunAt: Date | string | null
+}
+
 export interface KyselyPikkuDB {
   pikkuScopes: PikkuScopesTable
   pikkuRoles: PikkuRolesTable
@@ -354,4 +428,7 @@ export interface KyselyPikkuDB {
   webhookDelivery: WebhookDeliveryTable
   webhookDeliveryAttempt: WebhookDeliveryAttemptTable
   virtualUserRun: VirtualUserRunTable
+  virtualUserRunStep: VirtualUserRunStepTable
+  virtualUserSchedule: VirtualUserScheduleTable
+  audit: AuditTable
 }