@onkeiki/agents 0.1.0

package/src/Entity.ts

@@ -0,0 +1,543 @@
+import { Effect, Schema } from 'effect'
+import { defineTool, type ToolDefinition } from './Tool.js'
+import type { PluginDbService, PluginMigration } from './services/PluginDb.js'
+import { StorageError } from './services/Storage.js'
+
+/**
+ * Entities — typed, tenant-scoped persistence for agents.
+ *
+ * An entity is a named, schema-validated collection stored in the plugin
+ * database. Declaring an entity gives you:
+ *
+ * - A migration creating its table (`entityMigrations`)
+ * - Bounded, tenant-scoped CRUD tools for the model (`entityTools`)
+ * - A typed database API for codemode / programmatic use (`createEntityDb`)
+ *
+ * The model never sees SQL: every read and write goes through generated
+ * tools that validate against the schema and are scoped to the current
+ * user (phone). Rows are soft-deleted, versioned for optimistic
+ * concurrency, and audited.
+ *
+ * The generated SQL targets Postgres (JSONB, GIN indexes,
+ * `gen_random_uuid()`); other storage adapters are not supported yet.
+ *
+ * @example
+ * ```ts
+ * const reminders = defineEntity({
+ *   name: 'reminders',
+ *   description: 'Scheduled reminders for the user',
+ *   schema: Schema.Struct({
+ *     text: Schema.String,
+ *     dueAt: Schema.String,
+ *     done: Schema.Boolean,
+ *   }),
+ *   indexes: ['dueAt'],
+ * })
+ * ```
+ */
+export type EntityDefinition<A extends Record<string, unknown> = Record<string, unknown>> = {
+  /** Unique entity name — lowercase snake_case (becomes part of the table name). */
+  readonly name: string
+  /** What this entity stores, shown to the model in generated tool descriptions. */
+  readonly description: string
+  /** Effect Schema describing a row's data. Validated on every write. */
+  readonly schema: Schema.Schema<A, any>
+  /** Field names to index for query filters (expression indexes on the JSONB data). */
+  readonly indexes?: ReadonlyArray<string>
+  /** Maximum rows per user. Creates beyond this fail. Default 10 000. */
+  readonly maxRowsPerUser?: number
+}
+
+export function defineEntity<A extends Record<string, unknown>>(
+  def: EntityDefinition<A>
+): EntityDefinition<A> {
+  if (!/^[a-z][a-z0-9_]*$/.test(def.name)) {
+    throw new Error(`Entity name must be lowercase snake_case: ${def.name}`)
+  }
+  for (const field of def.indexes ?? []) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(field) || field.length > 40) {
+      throw new Error(`Entity index field must be a short identifier: ${field}`)
+    }
+  }
+  return def
+}
+
+/** A stored entity row, as returned to the model and codemode. */
+export type EntityRow<A> = {
+  readonly id: string
+  readonly version: number
+  readonly createdAt: string
+  readonly updatedAt: string
+  readonly data: A
+}
+
+const DEFAULT_MAX_ROWS = 10_000
+const MAX_QUERY_LIMIT = 100
+const DEFAULT_QUERY_LIMIT = 25
+
+function tableName(entity: string): string {
+  return `smskit_entity_${entity}`
+}
+
+function entityVersion(name: string, startVersion: number): number {
+  let hash = 2166136261
+  for (let i = 0; i < name.length; i++) {
+    hash ^= name.charCodeAt(i)
+    hash = Math.imul(hash, 16777619)
+  }
+  return startVersion + 1 + ((hash >>> 0) % 1_000_000_000)
+}
+
+/**
+ * Build the plugin migrations for a set of entities. Pass the result to a
+ * plugin's `migrations` (or spread into an existing list). Each entity's
+ * migration version is derived from its name, so the list can be reordered
+ * or extended freely without shifting versions of already-applied entities.
+ */
+export function entityMigrations(
+  entities: ReadonlyArray<EntityDefinition<any>>,
+  startVersion = 1
+): PluginMigration[] {
+  const versions = new Map<number, string>()
+  const migrations: PluginMigration[] = [
+    {
+      version: startVersion,
+      name: 'entity-audit-log',
+      up: `CREATE TABLE IF NOT EXISTS smskit_entity_audit (
+        id BIGSERIAL PRIMARY KEY,
+        entity TEXT NOT NULL,
+        row_id TEXT NOT NULL,
+        phone TEXT NOT NULL,
+        op TEXT NOT NULL,
+        patch JSONB,
+        at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )`,
+    },
+  ]
+  for (const entity of entities) {
+    defineEntity(entity)
+    const version = entityVersion(entity.name, startVersion)
+    const clash = versions.get(version)
+    if (clash) {
+      throw new Error(`Entity migration version collision between ${clash} and ${entity.name}; rename one of them`)
+    }
+    versions.set(version, entity.name)
+    const table = tableName(entity.name)
+    const indexes = (entity.indexes ?? [])
+      .map(
+        (field) =>
+          `CREATE INDEX IF NOT EXISTS ${table}_${field}_idx ON ${table} ((data->>'${field}'))`
+      )
+      .join('; ')
+    migrations.push({
+      version,
+      name: `entity-${entity.name}`,
+      up: `CREATE TABLE IF NOT EXISTS ${table} (
+        id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+        phone TEXT NOT NULL,
+        data JSONB NOT NULL,
+        version INT NOT NULL DEFAULT 1,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        deleted_at TIMESTAMPTZ
+      );
+      CREATE INDEX IF NOT EXISTS ${table}_phone_idx ON ${table} (phone) WHERE deleted_at IS NULL;
+      CREATE INDEX IF NOT EXISTS ${table}_data_gin_idx ON ${table} USING GIN (data jsonb_path_ops)${indexes ? '; ' + indexes : ''}`,
+    })
+  }
+  return migrations
+}
+
+/** Raw stored row shape exchanged with an {@link EntityStore}. */
+export type EntityStoreRow = {
+  id: string
+  version: number
+  created_at: string
+  updated_at: string
+  data: unknown
+}
+
+type RawRow = EntityStoreRow
+
+/**
+ * Storage backend for entity rows. `makeAccessor` handles validation,
+ * quotas, merge semantics and audit *decisions*; a store only persists.
+ * Two implementations exist: `sqlEntityStore` (direct SQL over the plugin
+ * database, used by SDK-local execution) and the actor host bridge (cloud
+ * bundle execution, proxied through the platform's actor-runtime API).
+ * Promise-based so it can cross the actor host boundary unchanged.
+ */
+export interface EntityStore {
+  get(entityName: string, phone: string, id: string): Promise<EntityStoreRow | null>
+  query(
+    entityName: string,
+    phone: string,
+    opts: {
+      filter?: Record<string, unknown>
+      limit: number
+      orderBy?: { field: string; direction: 'asc' | 'desc' }
+    }
+  ): Promise<EntityStoreRow[]>
+  count(entityName: string, phone: string): Promise<number>
+  insert(entityName: string, phone: string, data: Record<string, unknown>): Promise<EntityStoreRow>
+  /** Full-row replace with version bump. Returns null when the row is gone or `expectedVersion` no longer matches. */
+  update(
+    entityName: string,
+    phone: string,
+    id: string,
+    data: Record<string, unknown>,
+    expectedVersion?: number
+  ): Promise<EntityStoreRow | null>
+  softDelete(entityName: string, phone: string, id: string): Promise<boolean>
+  audit(entityName: string, phone: string, rowId: string, op: string, patch?: unknown): Promise<void>
+}
+
+/** EntityStore over the plugin database (the per-entity `smskit_entity_*` tables). */
+export function sqlEntityStore(db: PluginDbService): EntityStore {
+  const run = <T>(effect: Effect.Effect<T, StorageError>): Promise<T> => Effect.runPromise(effect)
+  return {
+    get: (entityName, phone, id) =>
+      run(
+        db.queryOne<RawRow>(
+          `SELECT id, version, created_at, updated_at, data FROM ${tableName(entityName)}
+           WHERE id = $1 AND phone = $2 AND deleted_at IS NULL`,
+          [id, phone]
+        )
+      ),
+    query: (entityName, phone, opts) => {
+      const params: unknown[] = [phone]
+      let where = `phone = $1 AND deleted_at IS NULL`
+      if (opts.filter && Object.keys(opts.filter).length > 0) {
+        params.push(JSON.stringify(opts.filter))
+        where += ` AND data @> $${params.length}::jsonb`
+      }
+      let order = `updated_at DESC`
+      if (opts.orderBy) {
+        order = `data->>'${opts.orderBy.field}' ${opts.orderBy.direction === 'asc' ? 'ASC' : 'DESC'}`
+      }
+      params.push(opts.limit)
+      return run(
+        db.query<RawRow>(
+          `SELECT id, version, created_at, updated_at, data FROM ${tableName(entityName)}
+           WHERE ${where} ORDER BY ${order} LIMIT $${params.length}`,
+          params
+        )
+      )
+    },
+    count: async (entityName, phone) => {
+      const row = await run(
+        db.queryOne<{ n: string }>(
+          `SELECT count(*)::text AS n FROM ${tableName(entityName)} WHERE phone = $1 AND deleted_at IS NULL`,
+          [phone]
+        )
+      )
+      return row ? Number(row.n) : 0
+    },
+    insert: async (entityName, phone, data) => {
+      const raw = await run(
+        db.queryOne<RawRow>(
+          `INSERT INTO ${tableName(entityName)} (phone, data) VALUES ($1, $2)
+           RETURNING id, version, created_at, updated_at, data`,
+          [phone, JSON.stringify(data)]
+        )
+      )
+      if (!raw) throw new Error('Insert returned no row')
+      return raw
+    },
+    update: (entityName, phone, id, data, expectedVersion) => {
+      const versionClause = expectedVersion !== undefined ? ` AND version = $4` : ''
+      const params: unknown[] = [JSON.stringify(data), id, phone]
+      if (expectedVersion !== undefined) params.push(expectedVersion)
+      return run(
+        db.queryOne<RawRow>(
+          `UPDATE ${tableName(entityName)} SET data = $1, version = version + 1, updated_at = now()
+           WHERE id = $2 AND phone = $3 AND deleted_at IS NULL${versionClause}
+           RETURNING id, version, created_at, updated_at, data`,
+          params
+        )
+      )
+    },
+    softDelete: async (entityName, phone, id) => {
+      const raw = await run(
+        db.queryOne<{ id: string }>(
+          `UPDATE ${tableName(entityName)} SET deleted_at = now()
+           WHERE id = $1 AND phone = $2 AND deleted_at IS NULL RETURNING id`,
+          [id, phone]
+        )
+      )
+      return raw !== null
+    },
+    audit: (entityName, phone, rowId, op, patch) =>
+      run(
+        db
+          .execute(
+            `INSERT INTO smskit_entity_audit (entity, row_id, phone, op, patch) VALUES ($1, $2, $3, $4, $5)`,
+            [entityName, rowId, phone, op, patch === undefined ? null : JSON.stringify(patch)]
+          )
+          .pipe(Effect.catchAll(() => Effect.void))
+      ),
+  }
+}
+
+function toRow<A extends Record<string, unknown>>(
+  entity: EntityDefinition<A>,
+  raw: RawRow
+): Effect.Effect<EntityRow<A>, EntityError> {
+  return Schema.decodeUnknown(entity.schema)(raw.data).pipe(
+    Effect.mapError(
+      (e) => new EntityError(`Stored ${entity.name} row ${raw.id} no longer matches its schema: ${e.message}`, 'validation')
+    ),
+    Effect.map((data) => ({
+      id: raw.id,
+      version: raw.version,
+      createdAt: toIso(raw.created_at),
+      updatedAt: toIso(raw.updated_at),
+      data: data as A,
+    }))
+  )
+}
+
+function toIso(value: unknown): string {
+  return value instanceof Date ? value.toISOString() : String(value)
+}
+
+export class EntityError extends Error {
+  constructor(
+    message: string,
+    readonly code: 'not_found' | 'conflict' | 'quota' | 'validation'
+  ) {
+    super(message)
+    this.name = 'EntityError'
+  }
+}
+
+/**
+ * Tenant-scoped typed accessor for one entity. All operations are scoped
+ * to a single user (phone), bounded, soft-deleting, and audited.
+ *
+ * Representation convention: write inputs (`create` data, `update` patch)
+ * and `query` filters are in the schema's ENCODED (JSON) representation —
+ * what the model produces and what is stored. Returned rows carry the
+ * DECODED representation in `data`.
+ */
+export type EntityAccessError = EntityError | StorageError
+
+export type EntityAccessor<A extends Record<string, unknown>> = {
+  readonly get: (id: string) => Effect.Effect<EntityRow<A> | null, EntityAccessError>
+  /** Equality filters on indexed fields; bounded to 100 rows. */
+  readonly query: (opts?: {
+    readonly filter?: Partial<A>
+    readonly limit?: number
+    readonly orderBy?: { readonly field: string; readonly direction?: 'asc' | 'desc' }
+  }) => Effect.Effect<EntityRow<A>[], EntityAccessError>
+  readonly create: (data: A) => Effect.Effect<EntityRow<A>, EntityAccessError>
+  /**
+   * Merge-patch a row. If `expectedVersion` is given the update fails with
+   * a conflict error when the row has changed since it was read.
+   */
+  readonly update: (
+    id: string,
+    patch: Partial<A>,
+    opts?: { readonly expectedVersion?: number }
+  ) => Effect.Effect<EntityRow<A>, EntityAccessError>
+  /** Soft-delete a row. */
+  readonly delete: (id: string) => Effect.Effect<boolean, EntityAccessError>
+}
+
+export type EntityDb<E extends Record<string, EntityDefinition<any>>> = {
+  readonly [K in keyof E]: E[K] extends EntityDefinition<infer A>
+    ? EntityAccessor<A & Record<string, unknown>>
+    : never
+}
+
+function storeCall<T>(what: string, run: () => Promise<T>): Effect.Effect<T, StorageError> {
+  return Effect.tryPromise({
+    try: run,
+    catch: (e) => new StorageError(`Entity store ${what} failed: ${e instanceof Error ? e.message : String(e)}`, e),
+  })
+}
+
+function makeAccessor<A extends Record<string, unknown>>(
+  entity: EntityDefinition<A>,
+  store: EntityStore,
+  phone: string
+): EntityAccessor<A> {
+  defineEntity(entity)
+  // Validate then persist the ENCODED form, so transforming schemas
+  // (NumberFromString, date transforms, ...) round-trip through storage.
+  const validateToStored = (data: unknown): Effect.Effect<unknown, EntityError> =>
+    Schema.decodeUnknown(entity.schema)(data).pipe(
+      Effect.flatMap((decoded) => Schema.encode(entity.schema)(decoded)),
+      Effect.mapError((e) => new EntityError(`Invalid ${entity.name} data: ${e.message}`, 'validation'))
+    )
+  const audit = (rowId: string, op: string, patch?: unknown) =>
+    storeCall('audit', () => store.audit(entity.name, phone, rowId, op, patch)).pipe(
+      Effect.catchAll(() => Effect.void)
+    )
+
+  return {
+    get: (id) =>
+      storeCall('get', () => store.get(entity.name, phone, id)).pipe(
+        Effect.flatMap((raw) => (raw ? toRow(entity, raw) : Effect.succeed(null)))
+      ),
+
+    query: (opts) =>
+      Effect.gen(function* () {
+        const limit = Math.min(Math.max(opts?.limit ?? DEFAULT_QUERY_LIMIT, 1), MAX_QUERY_LIMIT)
+        let orderBy: { field: string; direction: 'asc' | 'desc' } | undefined
+        if (opts?.orderBy) {
+          if (!/^[a-zA-Z0-9_]+$/.test(opts.orderBy.field)) {
+            return yield* Effect.fail(new EntityError(`Invalid order field`, 'validation'))
+          }
+          orderBy = { field: opts.orderBy.field, direction: opts.orderBy.direction === 'asc' ? 'asc' : 'desc' }
+        }
+        const rows = yield* storeCall('query', () =>
+          store.query(entity.name, phone, {
+            filter: opts?.filter as Record<string, unknown> | undefined,
+            limit,
+            orderBy,
+          })
+        )
+        return yield* Effect.all(rows.map((raw) => toRow(entity, raw)))
+      }),
+
+    create: (data) =>
+      Effect.gen(function* () {
+        const stored = yield* validateToStored(data)
+        const max = entity.maxRowsPerUser ?? DEFAULT_MAX_ROWS
+        const count = yield* storeCall('count', () => store.count(entity.name, phone))
+        if (count >= max) {
+          return yield* Effect.fail(
+            new EntityError(`Row quota reached for ${entity.name} (${max})`, 'quota')
+          )
+        }
+        const raw = yield* storeCall('insert', () =>
+          store.insert(entity.name, phone, stored as Record<string, unknown>)
+        )
+        yield* audit(raw.id, 'create', stored)
+        return yield* toRow(entity, raw)
+      }),
+
+    update: (id, patch, opts) =>
+      Effect.gen(function* () {
+        const existing = yield* storeCall('get', () => store.get(entity.name, phone, id))
+        if (!existing) {
+          return yield* Effect.fail(new EntityError(`${entity.name} row not found: ${id}`, 'not_found'))
+        }
+        // Merge in the encoded representation: stored JSON + encoded patch.
+        const merged = yield* validateToStored({
+          ...(existing.data as Record<string, unknown>),
+          ...patch,
+        })
+        const raw = yield* storeCall('update', () =>
+          store.update(entity.name, phone, id, merged as Record<string, unknown>, opts?.expectedVersion)
+        )
+        if (!raw) {
+          return yield* Effect.fail(
+            new EntityError(`${entity.name} row ${id} changed since it was read`, 'conflict')
+          )
+        }
+        yield* audit(id, 'update', patch)
+        return yield* toRow(entity, raw)
+      }),
+
+    delete: (id) =>
+      Effect.gen(function* () {
+        const deleted = yield* storeCall('delete', () => store.softDelete(entity.name, phone, id))
+        if (deleted) yield* audit(id, 'delete')
+        return deleted
+      }),
+  }
+}
+
+/**
+ * Build the typed entity database for a user. This is what codemode and
+ * loops use: `db.reminders.query({ filter: { done: false } })`.
+ */
+export function createEntityDb<E extends Record<string, EntityDefinition<any>>>(
+  entities: E,
+  db: PluginDbService | EntityStore,
+  phone: string
+): EntityDb<E> {
+  const store = isEntityStore(db) ? db : sqlEntityStore(db)
+  const out: Record<string, EntityAccessor<any>> = {}
+  for (const [key, entity] of Object.entries(entities)) {
+    out[key] = makeAccessor(entity, store, phone)
+  }
+  return out as EntityDb<E>
+}
+
+function isEntityStore(db: PluginDbService | EntityStore): db is EntityStore {
+  return 'softDelete' in db
+}
+
+/**
+ * The entity store for a tool context: the actor host bridge when the tool is
+ * running as a cloud bundle, otherwise direct SQL over the plugin database.
+ */
+export function contextEntityStore(ctx: { entityStore?: EntityStore; db: PluginDbService }): EntityStore {
+  return ctx.entityStore ?? sqlEntityStore(ctx.db)
+}
+
+/**
+ * Generate the model-facing CRUD tools for an entity:
+ * `<name>_query`, `<name>_create`, `<name>_update`, `<name>_delete`.
+ * All are tenant-scoped to the current user and bounded.
+ */
+export function entityTools<A extends Record<string, unknown>>(
+  entity: EntityDefinition<A>
+): ToolDefinition<any, any>[] {
+  const jsonSchema = Schema.Record({ key: Schema.String, value: Schema.Unknown })
+
+  const query = defineTool({
+    name: `${entity.name}_query`,
+    description: `Query ${entity.name}. ${entity.description} Returns up to ${MAX_QUERY_LIMIT} rows for the current user, newest first. Filter is an equality match on fields.`,
+    input: Schema.Struct({
+      filter: Schema.optional(jsonSchema),
+      limit: Schema.optional(Schema.Number),
+    }),
+    execute: (input, ctx) =>
+      makeAccessor(entity, contextEntityStore(ctx), ctx.phone)
+        .query({ filter: input.filter as Partial<A> | undefined, limit: input.limit })
+        .pipe(Effect.catchAll((e) => Effect.succeed({ error: e.message }))),
+  })
+
+  const create = defineTool({
+    name: `${entity.name}_create`,
+    description: `Create a ${entity.name} row for the current user. ${entity.description}`,
+    input: Schema.Struct({ data: jsonSchema }),
+    execute: (input, ctx) =>
+      makeAccessor(entity, contextEntityStore(ctx), ctx.phone)
+        .create(input.data as A)
+        .pipe(Effect.catchAll((e) => Effect.succeed({ error: e.message }))),
+  })
+
+  const update = defineTool({
+    name: `${entity.name}_update`,
+    description: `Update a ${entity.name} row by id (merge-patch). Fails if the row was changed since read when expectedVersion is provided.`,
+    input: Schema.Struct({
+      id: Schema.String,
+      patch: jsonSchema,
+      expectedVersion: Schema.optional(Schema.Number),
+    }),
+    execute: (input, ctx) =>
+      makeAccessor(entity, contextEntityStore(ctx), ctx.phone)
+        .update(input.id, input.patch as Partial<A>, { expectedVersion: input.expectedVersion })
+        .pipe(Effect.catchAll((e) => Effect.succeed({ error: e.message }))),
+  })
+
+  const del = defineTool({
+    name: `${entity.name}_delete`,
+    description: `Delete a ${entity.name} row by id (soft delete).`,
+    input: Schema.Struct({ id: Schema.String }),
+    execute: (input, ctx) =>
+      makeAccessor(entity, contextEntityStore(ctx), ctx.phone)
+        .delete(input.id)
+        .pipe(
+          Effect.map((deleted) => ({ deleted })),
+          Effect.catchAll((e) => Effect.succeed({ error: e.message }))
+        ),
+  })
+
+  return [query, create, update, del]
+}