@segmentstream-cloud/ontology 0.13.0 → 0.15.0

package/dist/migrate/plan.js

@@ -1,7 +1,7 @@
 import { isValueMatched, } from "../manifest.js";
 import { BLOB_TABLES_DDL } from "../storage/tables.js";
 import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
-import { CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, OAUTH_TABLES, OAUTH_TABLES_DDL, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, blobForeignKey, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
+import { AGENT_TABLES, AGENT_TABLES_DDL, CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, OAUTH_TABLES, OAUTH_TABLES_DDL, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, blobForeignKey, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
 const GLOBAL_KINDS = new Set(["table", "type", "index"]);
 function step(input) {
     return {
@@ -70,17 +70,29 @@ export function planMigration(input) {
         draft.runtimeTables.push(step({
             kind: "createCatalog",
             classification: "additive",
-            description: "Create the runtime's role assignment, API key and OAuth tables.",
+            description: "Create the runtime's role assignment, API key, OAuth and agent tables.",
             sql: RUNTIME_TABLES_DDL,
         }));
     }
-    else if (OAUTH_TABLES.some((table) => input.existingTables?.has(table) === false)) {
-        draft.runtimeTables.push(step({
-            kind: "createCatalog",
-            classification: "additive",
-            description: "Create the runtime's OAuth tables, which connect agents to the MCP server.",
-            sql: OAUTH_TABLES_DDL,
-        }));
+    else {
+        // A database an earlier SDK migrated lacks the tables added since; each set arrives on its own.
+        const lacks = (tables) => tables.some((table) => input.existingTables?.has(table) === false);
+        if (lacks(OAUTH_TABLES)) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the runtime's OAuth tables, which connect agents to the MCP server.",
+                sql: OAUTH_TABLES_DDL,
+            }));
+        }
+        if (lacks(AGENT_TABLES)) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the runtime's agent tables, which pair channel accounts with members.",
+                sql: AGENT_TABLES_DDL,
+            }));
+        }
     }
     if (storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob")) &&
         !current?.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))) {

package/dist/migrate/storage.d.ts

@@ -164,6 +164,18 @@ export declare const OAUTH_TOKENS_TABLE = "_oauth_tokens";
 export declare const OAUTH_TABLES: ReadonlyArray<string>;
 /** The OAuth tables of the MCP server's authorization server. Every statement is idempotent. */
 export declare const OAUTH_TABLES_DDL: ReadonlyArray<string>;
+/** Channel accounts waiting, for ten minutes, for a member to claim them with a short code. */
+export declare const AGENT_PAIRINGS_TABLE = "_agent_pairings";
+/** Channel accounts paired with members: the app's agent acts as the member for their messages. */
+export declare const AGENT_IDENTITIES_TABLE = "_agent_identities";
+/** The agent's tables, in the order they are created. */
+export declare const AGENT_TABLES: ReadonlyArray<string>;
+/**
+ * The tables of the app's agent: pairing codes, stored only as SHA-256 hashes, and the identities
+ * they create. An account and a member each have at most one live identity per provider. Every
+ * statement is idempotent.
+ */
+export declare const AGENT_TABLES_DDL: ReadonlyArray<string>;
 /**
  * The runtime's own tables beside the catalog. They are created with it, after the entity tables
  * because they refer to the built-in user table, and every statement is idempotent.

package/dist/migrate/storage.js

@@ -524,6 +524,53 @@ export const OAUTH_TABLES_DDL = [
     `CREATE INDEX IF NOT EXISTS "${OAUTH_TOKENS_TABLE}_grant_id_idx" ` +
         `ON ${quoteIdentifier(OAUTH_TOKENS_TABLE)} ("grant_id")`,
 ];
+/** Channel accounts waiting, for ten minutes, for a member to claim them with a short code. */
+export const AGENT_PAIRINGS_TABLE = "_agent_pairings";
+/** Channel accounts paired with members: the app's agent acts as the member for their messages. */
+export const AGENT_IDENTITIES_TABLE = "_agent_identities";
+/** The agent's tables, in the order they are created. */
+export const AGENT_TABLES = [AGENT_PAIRINGS_TABLE, AGENT_IDENTITIES_TABLE];
+/**
+ * The tables of the app's agent: pairing codes, stored only as SHA-256 hashes, and the identities
+ * they create. An account and a member each have at most one live identity per provider. Every
+ * statement is idempotent.
+ */
+export const AGENT_TABLES_DDL = [
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(AGENT_PAIRINGS_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "code_hash" text NOT NULL,`,
+        `  "provider" text NOT NULL,`,
+        `  "external_id" text NOT NULL,`,
+        `  "display" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  "consumed_at" timestamptz,`,
+        `  CONSTRAINT "${AGENT_PAIRINGS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${AGENT_PAIRINGS_TABLE}_code_hash_key" UNIQUE ("code_hash")`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "provider" text NOT NULL,`,
+        `  "external_id" text NOT NULL,`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "display" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "revoked_at" timestamptz,`,
+        `  CONSTRAINT "${AGENT_IDENTITIES_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${AGENT_IDENTITIES_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE UNIQUE INDEX IF NOT EXISTS "${AGENT_IDENTITIES_TABLE}_account_key" ` +
+        `ON ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} ("provider", "external_id") ` +
+        `WHERE "revoked_at" IS NULL`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS "${AGENT_IDENTITIES_TABLE}_member_key" ` +
+        `ON ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} ("user_id", "provider") ` +
+        `WHERE "revoked_at" IS NULL`,
+];
 /**
  * The runtime's own tables beside the catalog. They are created with it, after the entity tables
  * because they refer to the built-in user table, and every statement is idempotent.
@@ -556,6 +603,7 @@ export const RUNTIME_TABLES_DDL = [
     ].join("\n"),
     `CREATE INDEX IF NOT EXISTS "${API_KEYS_TABLE}_user_id_idx" ON ${quoteIdentifier(API_KEYS_TABLE)} ("user_id")`,
     ...OAUTH_TABLES_DDL,
+    ...AGENT_TABLES_DDL,
 ];
 export function columnDefinition(column) {
     const parts = [quoteIdentifier(column.name), column.type];

package/dist/names.d.ts

@@ -23,7 +23,7 @@ export declare const RESERVED_MEMBER_NAMES: readonly ["and", "or", "not"];
 /** The ontology service's route for aggregates across entities: `/api/ontology/aggregate`. */
 export declare const AGGREGATE_ROUTE = "aggregate";
 /** Routes of the ontology service under `/api/ontology/`, which an entity's routes would shadow. */
-export declare const RESERVED_ENTITY_NAMES: readonly ["aggregate", "graph", "status", "describe", "openapi", "docs", "mcp", "me", "oauth"];
+export declare const RESERVED_ENTITY_NAMES: readonly ["aggregate", "graph", "status", "describe", "openapi", "docs", "mcp", "me", "oauth", "agent"];
 /** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
 export declare const MCP_READ_TOOLS: readonly ["find", "get", "history"];
 /** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */

package/dist/names.js

@@ -61,6 +61,7 @@ export const RESERVED_ENTITY_NAMES = [
     "mcp",
     "me",
     "oauth",
+    "agent",
 ];
 /** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
 export const MCP_READ_TOOLS = ["find", "get", "history"];

package/dist/permissions.d.ts

@@ -2,12 +2,18 @@
  * Permissions are `<entity>:<verb>` strings. The verbs are `read`, the generated `create`, `update`,
  * `delete`, `link` and `unlink`, and the snake_case name of an authored action. A role may use `*` for
  * the entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
- * holds a wildcard.
+ * holds a wildcard. A wildcard entity does not cover the entities in {@link EXPLICIT_GRANT_ENTITIES}.
  */
 /** Any entity or any verb, in a role's permissions. */
 export declare const WILDCARD = "*";
 /** The verb of every read: lists, queries, records, history, traversals and `include`. */
 export declare const READ_VERB = "read";
+/**
+ * Entities only a permission that names them covers: `*:read` or `*:*` grant nothing on them. The
+ * built-in agent chat is in every ontology, and member's default `*:read` would otherwise show anyone
+ * who signs in the workspace's chats and who is in them; `agent_chat:read` or `agent_chat:*` does.
+ */
+export declare const EXPLICIT_GRANT_ENTITIES: ReadonlySet<string>;
 /** What the built-in `member` role holds when `defineOntology` does not say: reading everything. */
 export declare const DEFAULT_MEMBER_PERMISSIONS: ReadonlyArray<string>;
 export interface ParsedPermission {
@@ -20,7 +26,10 @@ export interface ParsedPermission {
 export declare function parsePermission(value: unknown): ParsedPermission | undefined;
 /** `lead:changeStatus`. */
 export declare function permissionOf(entity: string, verb: string): string;
-/** Whether a granted permission, which may hold wildcards, covers the required one. */
+/**
+ * Whether a granted permission, which may hold wildcards, covers the required one. A wildcard entity
+ * covers every entity but those in {@link EXPLICIT_GRANT_ENTITIES}.
+ */
 export declare function grants(granted: string, required: string): boolean;
 /** Anything that holds permissions: a principal, or the reader of a catalog. */
 export interface PermissionHolder {

package/dist/permissions.js

@@ -3,12 +3,18 @@ import { GENERATED_UPSERT_PREFIX, toSnakeCase } from "./names.js";
  * Permissions are `<entity>:<verb>` strings. The verbs are `read`, the generated `create`, `update`,
  * `delete`, `link` and `unlink`, and the snake_case name of an authored action. A role may use `*` for
  * the entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
- * holds a wildcard.
+ * holds a wildcard. A wildcard entity does not cover the entities in {@link EXPLICIT_GRANT_ENTITIES}.
  */
 /** Any entity or any verb, in a role's permissions. */
 export const WILDCARD = "*";
 /** The verb of every read: lists, queries, records, history, traversals and `include`. */
 export const READ_VERB = "read";
+/**
+ * Entities only a permission that names them covers: `*:read` or `*:*` grant nothing on them. The
+ * built-in agent chat is in every ontology, and member's default `*:read` would otherwise show anyone
+ * who signs in the workspace's chats and who is in them; `agent_chat:read` or `agent_chat:*` does.
+ */
+export const EXPLICIT_GRANT_ENTITIES = new Set(["agent_chat"]);
 /** What the built-in `member` role holds when `defineOntology` does not say: reading everything. */
 export const DEFAULT_MEMBER_PERMISSIONS = [`${WILDCARD}:${READ_VERB}`];
 /** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
@@ -25,14 +31,20 @@ export function parsePermission(value) {
 export function permissionOf(entity, verb) {
     return `${entity}:${verb}`;
 }
-/** Whether a granted permission, which may hold wildcards, covers the required one. */
+/**
+ * Whether a granted permission, which may hold wildcards, covers the required one. A wildcard entity
+ * covers every entity but those in {@link EXPLICIT_GRANT_ENTITIES}.
+ */
 export function grants(granted, required) {
     const held = parsePermission(granted);
     const wanted = parsePermission(required);
     if (held === undefined || wanted === undefined) {
         return false;
     }
-    return ((held.entity === WILDCARD || toSnakeCase(held.entity) === toSnakeCase(wanted.entity)) &&
+    const entity = toSnakeCase(wanted.entity);
+    return ((held.entity === WILDCARD
+        ? !EXPLICIT_GRANT_ENTITIES.has(entity)
+        : toSnakeCase(held.entity) === entity) &&
         (held.verb === WILDCARD || toSnakeCase(held.verb) === toSnakeCase(wanted.verb)));
 }
 /**

package/dist/replication/baseline.js

@@ -23,7 +23,7 @@ export const createReplicationBaseline = (sql, input) => sql.withTransaction(Eff
     yield* Effect.sync(() => validateReplicationSelection(manifest, input.selection));
     // Drain older SDK transactions that started before the compatibility fence was enabled.
     const tables = manifest.entities
-        .filter((e) => e.source === undefined && e.name !== "user")
+        .filter((e) => e.source === undefined && !e.builtIn)
         .flatMap((e) => [
         tableName(e.name),
         ...e.relationships

package/dist/replication/model.js

@@ -69,7 +69,7 @@ export function validateReplicationSelection(manifest, selection) {
     };
     for (const item of selection) {
         const entity = manifest.entities.find((e) => e.id === item.entityId);
-        if (!entity || entity.name === "user" || entity.source !== undefined) {
+        if (!entity || entity.builtIn || entity.source !== undefined) {
             throw new Error(`Only stored business entities can be replicated: ${item.entityId}.`);
         }
         addView(entity.name);
@@ -82,7 +82,7 @@ export function validateReplicationSelection(manifest, selection) {
             const target = manifest.entities.find((e) => e.name === relationship?.to);
             if (relationship?.cardinality !== "many" ||
                 !target ||
-                target.name === "user" ||
+                target.builtIn ||
                 !selection.some((s) => s.entityId === target.id)) {
                 throw new Error(`Replication of ${entity.name}.${name} requires both business entities.`);
             }

package/dist/replication/schema.js

@@ -55,7 +55,7 @@ export function snapshotExpression(entity, alias) {
 /** History is the durable source. Triggers also reject old writers while capture is enabled. */
 export function replicationEntityDdl(manifest) {
     return manifest.entities
-        .filter((e) => e.source === undefined && e.name !== "user")
+        .filter((e) => e.source === undefined && !e.builtIn)
         .flatMap((entity) => {
         const history = qi(historyTableName(entity.name));
         const table = qi(tableName(entity.name));

package/dist/runtime/agents.d.ts

@@ -0,0 +1,10 @@
+import { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import type { AgentStore } from "../service/runtime-contract.js";
+/**
+ * The agent store on the runtime's agent tables, as `ontology_app`. Expiry is the database's
+ * `now()`; a pairing is consumed with one `UPDATE … WHERE "consumed_at" IS NULL`, so two concurrent
+ * approvals cannot both succeed. Ids that are not UUIDs find nothing rather than fail the cast.
+ * Chats the agent sees are `agent_chat` records, written as the platform with history.
+ */
+export declare function sqlAgentStore(ontology: Ontology, sql: SqlClient.SqlClient): AgentStore;

package/dist/runtime/agents.js

@@ -0,0 +1,305 @@
+import { randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { AgentChat } from "../agent-chat.js";
+import { AGENT_IDENTITIES_TABLE, AGENT_PAIRINGS_TABLE, USER_TABLE } from "../migrate/storage.js";
+import { MAX_QUERY_LIMIT } from "../query.js";
+import { beginReplicationWrite } from "../replication/transaction.js";
+import { resolveMemberById } from "./principals.js";
+import { isRecordId } from "./records.js";
+import { makeOntologyRuntime } from "./sql-runtime.js";
+const PAIRINGS = `"${AGENT_PAIRINGS_TABLE}"`;
+const IDENTITIES = `"${AGENT_IDENTITIES_TABLE}"`;
+const USERS = `"${USER_TABLE}"`;
+/** A timestamp as epoch milliseconds, which every driver returns as a plain number. */
+function epochMs(column) {
+    return `(extract(epoch from ${column}) * 1000)::double precision`;
+}
+const PAIRING_COLUMNS = `"id"::text AS "id", "provider", "external_id", "display", ` +
+    `${epochMs(`"expires_at"`)} AS "expires_at"`;
+const IDENTITY_COLUMNS = `"id"::text AS "id", "provider", "external_id", "user_id"::text AS "user_id", "display", ` +
+    `${epochMs(`"created_at"`)} AS "created_at", ${epochMs(`"revoked_at"`)} AS "revoked_at"`;
+/**
+ * How often a chat's `last_message_at` is recorded: each record is a history row, and a busy chat
+ * would otherwise add one per message.
+ */
+const CHAT_MESSAGE_RECORD_INTERVAL_MS = 15 * 60 * 1000;
+/** Whether a chat's latest message is recorded: it has none yet, or none this interval. */
+function messageDue(lastMessageAt, now) {
+    const last = typeof lastMessageAt === "string" ? Date.parse(lastMessageAt) : Number.NaN;
+    return Number.isNaN(last) || now.getTime() - last >= CHAT_MESSAGE_RECORD_INTERVAL_MS;
+}
+function nullableText(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+function pairingOf(row) {
+    return {
+        id: String(row.id),
+        provider: String(row.provider),
+        externalId: String(row.external_id),
+        display: nullableText(row.display),
+        expiresAt: new Date(Number(row.expires_at)),
+    };
+}
+function identityOf(row) {
+    return {
+        id: String(row.id),
+        provider: String(row.provider),
+        externalId: String(row.external_id),
+        userId: String(row.user_id),
+        display: nullableText(row.display),
+        createdAt: new Date(Number(row.created_at)),
+        revokedAt: row.revoked_at === null ? null : new Date(Number(row.revoked_at)),
+    };
+}
+/**
+ * The agent store on the runtime's agent tables, as `ontology_app`. Expiry is the database's
+ * `now()`; a pairing is consumed with one `UPDATE … WHERE "consumed_at" IS NULL`, so two concurrent
+ * approvals cannot both succeed. Ids that are not UUIDs find nothing rather than fail the cast.
+ * Chats the agent sees are `agent_chat` records, written as the platform with history.
+ */
+export function sqlAgentStore(ontology, sql) {
+    const rows = (statement, values = []) => sql.unsafe(statement, values).pipe(Effect.orDie);
+    const memberPrincipal = (userId) => resolveMemberById(ontology, userId).pipe(Effect.provideService(SqlClient.SqlClient, sql));
+    return {
+        savePairing: (pairing) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${PAIRINGS} WHERE "expires_at" <= now()`);
+            const inserted = yield* rows([
+                `INSERT INTO ${PAIRINGS}`,
+                `  ("id", "code_hash", "provider", "external_id", "display", "expires_at")`,
+                `VALUES ($1::uuid, $2, $3, $4, $5, $6::timestamptz)`,
+                `ON CONFLICT ("code_hash") DO NOTHING`,
+                `RETURNING "id"`,
+            ].join("\n"), [
+                pairing.id,
+                pairing.codeHash,
+                pairing.provider,
+                pairing.externalId,
+                pairing.display,
+                pairing.expiresAt.toISOString(),
+            ]);
+            return inserted.length > 0;
+        }))
+            .pipe(Effect.orDie),
+        findPairing: (codeHash) => rows([
+            `SELECT ${PAIRING_COLUMNS}`,
+            `FROM ${PAIRINGS}`,
+            `WHERE "code_hash" = $1 AND "consumed_at" IS NULL AND "expires_at" > now()`,
+        ].join("\n"), [codeHash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : pairingOf(row)))),
+        approvePairing: ({ codeHash, userId, identityId }) => sql
+            .withTransaction(Effect.gen(function* () {
+            const [consumed] = yield* rows([
+                `UPDATE ${PAIRINGS} SET "consumed_at" = now()`,
+                `WHERE "code_hash" = $1 AND "consumed_at" IS NULL AND "expires_at" > now()`,
+                `RETURNING ${PAIRING_COLUMNS}`,
+            ].join("\n"), [codeHash]);
+            if (consumed === undefined) {
+                return undefined;
+            }
+            const pairing = pairingOf(consumed);
+            // Two approvals that replace the same account's or the same member's identity run one
+            // after the other, so the partial unique indexes never refuse a valid one.
+            yield* rows(`SELECT pg_advisory_xact_lock(hashtext($1)), pg_advisory_xact_lock(hashtext($2))`, [
+                `account:${pairing.provider}:${pairing.externalId}`,
+                `member:${userId}:${pairing.provider}`,
+            ]);
+            yield* rows([
+                `UPDATE ${IDENTITIES} SET "revoked_at" = now()`,
+                `WHERE "revoked_at" IS NULL AND "provider" = $1`,
+                `  AND ("external_id" = $2 OR "user_id" = $3::uuid)`,
+            ].join("\n"), [pairing.provider, pairing.externalId, userId]);
+            const [created] = yield* rows([
+                `INSERT INTO ${IDENTITIES} ("id", "provider", "external_id", "user_id", "display")`,
+                `VALUES ($1::uuid, $2, $3, $4::uuid, $5)`,
+                `RETURNING ${IDENTITY_COLUMNS}`,
+            ].join("\n"), [identityId, pairing.provider, pairing.externalId, userId, pairing.display]);
+            return created === undefined ? undefined : identityOf(created);
+        }))
+            .pipe(Effect.orDie),
+        findIdentity: ({ provider, externalId }) => rows([
+            `SELECT ${IDENTITY_COLUMNS}`,
+            `FROM ${IDENTITIES}`,
+            `WHERE "provider" = $1 AND "external_id" = $2`,
+            `ORDER BY "revoked_at" IS NOT NULL, "revoked_at" DESC`,
+            `LIMIT 1`,
+        ].join("\n"), [provider, externalId]).pipe(Effect.map(([row]) => (row === undefined ? undefined : identityOf(row)))),
+        listIdentities: (userId) => isRecordId(userId)
+            ? rows([
+                `SELECT ${IDENTITY_COLUMNS}`,
+                `FROM ${IDENTITIES}`,
+                `WHERE "user_id" = $1::uuid AND "revoked_at" IS NULL`,
+                `ORDER BY "created_at", "id"`,
+            ].join("\n"), [userId]).pipe(Effect.map((found) => found.map(identityOf)))
+            : Effect.succeed([]),
+        revokeIdentity: ({ id, userId }) => isRecordId(id) && isRecordId(userId)
+            ? rows([
+                `UPDATE ${IDENTITIES} SET "revoked_at" = now()`,
+                `WHERE "id" = $1::uuid AND "user_id" = $2::uuid AND "revoked_at" IS NULL`,
+                `RETURNING "id"`,
+            ].join("\n"), [id, userId]).pipe(Effect.map((revoked) => revoked.length > 0))
+            : Effect.succeed(false),
+        member: (userId) => Effect.gen(function* () {
+            if (!isRecordId(userId)) {
+                return undefined;
+            }
+            const principal = yield* memberPrincipal(userId);
+            if (principal === undefined) {
+                return undefined;
+            }
+            const [user] = yield* rows(`SELECT "name" FROM ${USERS} WHERE "id" = $1::uuid`, [userId]);
+            return { name: String(user?.name ?? ""), principal };
+        }),
+        actingMember: (userId) => Effect.gen(function* () {
+            if (!isRecordId(userId)) {
+                return undefined;
+            }
+            const [paired] = yield* rows(`SELECT 1 FROM ${IDENTITIES} WHERE "user_id" = $1::uuid AND "revoked_at" IS NULL LIMIT 1`, [userId]);
+            return paired === undefined ? undefined : yield* memberPrincipal(userId);
+        }),
+        seeChat: ({ provider, externalId, title, memberId, leftMemberId, agentLeft, migratedFrom }) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            const previous = migratedFrom === undefined || migratedFrom === externalId ? undefined : migratedFrom;
+            // Calls for one chat run one after the other: the first creates it, the rest find it. A
+            // migration locks both chats, in one order, so that two calls never wait on each other.
+            for (const id of [externalId, ...(previous === undefined ? [] : [previous])].sort()) {
+                yield* rows(`SELECT pg_advisory_xact_lock(hashtext($1))`, [`chat:${provider}:${id}`]);
+            }
+            const runtime = makeOntologyRuntime(ontology, sql, {
+                action: `${AgentChat.name}.seen`,
+                actionId: randomUUID(),
+                principalId: null,
+            });
+            const now = new Date();
+            const chatOf = (id) => runtime
+                .find({
+                entity: AgentChat.name,
+                options: { where: { provider, external_id: id }, limit: 1, forUpdate: true },
+            })
+                .pipe(Effect.map(([chat]) => chat));
+            const membersOf = (id) => runtime
+                .related({
+                entity: AgentChat.name,
+                id,
+                relationship: "members",
+                query: { limit: MAX_QUERY_LIMIT },
+            })
+                .pipe(Effect.map((page) => page.items.map((member) => String(member.id))));
+            // Unlinks every member of the chat, linking each to `to` first when given. Each page
+            // unlinked is gone, so the first page is read until it is empty.
+            const releaseMembers = (id, to) => Effect.gen(function* () {
+                for (;;) {
+                    const members = yield* membersOf(id);
+                    if (members.length === 0) {
+                        return;
+                    }
+                    for (const targetId of members) {
+                        if (to !== undefined) {
+                            yield* runtime.link({
+                                entity: AgentChat.name,
+                                relationship: "members",
+                                id: to,
+                                targetId,
+                            });
+                        }
+                        yield* runtime.unlink({
+                            entity: AgentChat.name,
+                            relationship: "members",
+                            id,
+                            targetId,
+                        });
+                    }
+                }
+            });
+            let found = yield* chatOf(externalId);
+            if (previous !== undefined) {
+                const old = yield* chatOf(previous);
+                if (old !== undefined && found === undefined) {
+                    // The group became a supergroup: the chat keeps its record under its new id.
+                    found = yield* runtime.update({
+                        entity: AgentChat.name,
+                        id: String(old.id),
+                        values: { external_id: externalId },
+                    });
+                }
+                else if (old !== undefined && found !== undefined) {
+                    // Both were recorded: the new one keeps what members said and gains the members,
+                    // and the old one is deleted.
+                    const kept = {};
+                    for (const key of ["purpose", "when_to_use"]) {
+                        if (nullableText(found[key]) === null && nullableText(old[key]) !== null) {
+                            kept[key] = old[key];
+                        }
+                    }
+                    if (Object.keys(kept).length > 0) {
+                        found = yield* runtime.update({
+                            entity: AgentChat.name,
+                            id: String(found.id),
+                            values: kept,
+                        });
+                    }
+                    yield* releaseMembers(String(old.id), String(found.id));
+                    yield* runtime.delete({ entity: AgentChat.name, id: String(old.id) });
+                }
+            }
+            const changes = {
+                ...(found?.title === title ? {} : { title }),
+                ...(messageDue(found?.last_message_at, now)
+                    ? { last_message_at: now.toISOString() }
+                    : {}),
+            };
+            const chat = found === undefined
+                ? yield* runtime.create({
+                    entity: AgentChat.name,
+                    values: { provider, external_id: externalId, ...changes },
+                })
+                : Object.keys(changes).length === 0
+                    ? found
+                    : yield* runtime.update({
+                        entity: AgentChat.name,
+                        id: String(found.id),
+                        values: changes,
+                    });
+            if (memberId !== undefined && isRecordId(memberId)) {
+                const [member] = yield* rows(`SELECT 1 FROM ${USERS} WHERE "id" = $1::uuid AND "kind"::text = 'member' AND "active"`, [memberId]);
+                // A link already there changes nothing and records no history.
+                if (member !== undefined) {
+                    yield* runtime.link({
+                        entity: AgentChat.name,
+                        relationship: "members",
+                        id: String(chat.id),
+                        targetId: memberId,
+                    });
+                }
+            }
+            if (leftMemberId !== undefined && isRecordId(leftMemberId)) {
+                const [user] = yield* rows(`SELECT 1 FROM ${USERS} WHERE "id" = $1::uuid`, [
+                    leftMemberId,
+                ]);
+                // Whatever their state now; a member who is not linked changes nothing and records no
+                // history.
+                if (user !== undefined) {
+                    yield* runtime.unlink({
+                        entity: AgentChat.name,
+                        relationship: "members",
+                        id: String(chat.id),
+                        targetId: leftMemberId,
+                    });
+                }
+            }
+            if (agentLeft === true) {
+                // The agent left: no member is in the chat with it any more. The chat stays; members
+                // link again when they write after the agent is back.
+                yield* releaseMembers(String(chat.id));
+            }
+            return {
+                id: String(chat.id),
+                title: String(chat.title),
+                purpose: nullableText(chat.purpose),
+                whenToUse: nullableText(chat.when_to_use),
+            };
+        }))
+            .pipe(Effect.orDie),
+    };
+}

package/dist/runtime/generated-actions.d.ts

@@ -12,7 +12,8 @@ export declare function upsertActionName(property: string): string;
  * are ordinary actions and run through the same pipeline. Their `permission` is unset: each requires
  * the permission named after it (`lead:create`), and `upsert_by_<property>` both `create` and `update`,
  * as `generatedActionPermissions` says. The built-in User has none: members are created by sign-in
- * and services by the app or the CLI.
+ * and services by the app or the CLI. The built-in agent chat has only `update`, for its unmanaged
+ * properties: the agent records chats and their members.
  */
 export declare function generatedActions(ontology: Ontology, entityName: string): GeneratedActions;
 /** An action's input as JSON Schema (draft 2020-12), as the manifest describes authored actions. */