@segmentstream-cloud/ontology 0.13.0 → 0.14.0

package/README.md

@@ -28,6 +28,9 @@ one Effect version.
 `ontology/` is a package of its own. The SDK is an ES module, so `ontology/package.json`
 must set `"type": "module"`.
 
+SDK 0.14.0 lets the app's own agent call the service as a paired member (see
+[Agents](#agents)). Its migration adds the agent's runtime tables.
+
 SDK 0.12.0 adds warehouse replication enabled by default for all stored business entities,
 fields and business relationships. Existing history captures immutable snapshots and the
 service wakes the publisher after commits. Upgrade and redeploy to activate it; workspace
@@ -211,9 +214,12 @@ one is missing or invalid, and never repeats the database URL.
 | `NEON_AUTH_BASE_URL`                  | Optional. The workspace's Neon Auth URL; its origin issues users' tokens.                    |
 | `NEON_AUTH_JWKS_URL`                  | Optional, set with the base URL. The keys that verify those tokens.                          |
 | `SEGMENTSTREAM_APP_CREDENTIAL`        | Optional. The workspace app credential; without it, aggregates answer 503.                   |
+| `SEGMENTSTREAM_RUNTIME_OIDC_ISSUER`   | Optional. The team's Vercel OIDC issuer, for the app's agent.                                |
+| `SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE` | Optional, set with the issuer. The audience of the team's tokens.                            |
 
 The platform sets these variables in the workspace deployment, the Neon Auth pair once the
-workspace has Neon Auth.
+workspace has Neon Auth and the runtime pair on deployments with an agent. With the runtime
+pair, Vercel's `VERCEL_PROJECT_ID` must be set too.
 
 ### Authentication
 
@@ -249,6 +255,37 @@ address (`x-real-ip`, else the first `x-forwarded-for` hop) ten checks a minute,
 answers 429 `rate_limited` with `retry-after`. `checkSignIn(ontology, email)` is the same
 lookup for code that holds a SQL client.
 
+## Agents
+
+The app's own agent runs in the same Vercel project as the service and calls it as the
+deployment: `Authorization: Bearer <Vercel OIDC token>`. The service accepts the token when it
+is RS256 from `SEGMENTSTREAM_RUNTIME_OIDC_ISSUER` (keys at `<issuer>/.well-known/jwks`), for
+`SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE`, with `project_id` equal to `VERCEL_PROJECT_ID` and
+`environment` `production`. Without the issuer and audience such tokens are a 401.
+
+The agent acts for a member by adding `X-SegmentStream-Act-As: <user id>` on any route,
+`/mcp` included: the request runs with the member's current roles and history names the
+member, as if they had called. A member who is inactive or has no live pairing is a 403.
+Without the header the agent may call only the agent routes:
+
+| Route                                                         | Caller | Does                                                                 |
+| ------------------------------------------------------------- | ------ | -------------------------------------------------------------------- |
+| `POST /api/ontology/agent/pairings`                           | agent  | `{ provider, external_id, display? }` → `{ code, expires_at }`       |
+| `GET /api/ontology/agent/pairings/{code}`                     | member | `{ provider, display, expires_at }`, for the connect page            |
+| `POST /api/ontology/agent/pairings/{code}/approve`            | member | Pairs the account with the member → `{ identity }`                   |
+| `GET /api/ontology/agent/identities/{provider}/{external_id}` | agent  | `{ user: { id, name }, roles }`; 404 unpaired, 403 revoked, inactive |
+| `GET /api/ontology/agent/identities`                          | member | `{ identities }`: the member's live identities                       |
+| `DELETE /api/ontology/agent/identities/{id}`                  | member | Revokes one of them: 204                                             |
+
+A pairing code is eight characters without look-alikes (no 0, O, 1, I or L), stored as its
+SHA-256, valid ten minutes and used once. Each instance allows a client address 60 new
+pairings a minute. An account and a member each have one live identity per provider:
+approving a code revokes the account's earlier identity and the member's earlier one on the
+same provider. Member routes take a Neon Auth session or token and refuse API keys and the
+agent, even acting as a member, so only members pair. Pairings and identities live in the
+runtime tables `_agent_pairings` and `_agent_identities`; the migration creates them in a
+database an earlier SDK migrated.
+
 ## The `segmentstream-ontology` binary
 
 Run the binary in the `ontology/` folder. The entry defaults to `./index.ts`. The binary

package/dist/index.d.ts

@@ -52,11 +52,14 @@ export type { DeriveApiOptions, OntologyApi } from "./service/api.js";
 export { CurrentPrincipal } from "./service/authentication.js";
 export { deployedConnections, LocalConnectionContextError, localConnections, OIDC_TOKEN_HEADER, parseLocalConnectionContext, readLocalConnectionContext, RUNTIME_CONTEXT_FD, } from "./service/connections.js";
 export type { ConnectionAudit, ConnectionTransportFactory, LocalConnection, LocalConnectionContext, } from "./service/connections.js";
-export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, } from "./service/config.js";
+export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES, } from "./service/config.js";
 export type { ActionCommitted, AfterCommitHook, NeonAuthEnvironment, OntologyEnvironment, OntologyServiceConfig, } from "./service/config.js";
 export { NotInvited, OntologyBackend } from "./service/runtime-contract.js";
-export type { GeneratedActionsProvider, IdentityProvider, OAuthClient, OAuthClientAuthMethod, OAuthGrant, OAuthRequest, OAuthStore, OAuthToken, OAuthTokenKind, OntologyServiceRuntime, RunActionInput, SignInIdentity, UsedOAuthToken, } from "./service/runtime-contract.js";
+export type { AgentIdentity, AgentMember, AgentPairing, AgentStore, GeneratedActionsProvider, IdentityProvider, OAuthClient, OAuthClientAuthMethod, OAuthGrant, OAuthRequest, OAuthStore, OAuthToken, OAuthTokenKind, OntologyServiceRuntime, RunActionInput, SignInIdentity, UsedOAuthToken, } from "./service/runtime-contract.js";
 export { createOntologyService, ONTOLOGY_HASH_HEADER, REQUEST_ID_HEADER, } from "./service/service.js";
+export { AGENT_PATH } from "./service/agent/server.js";
+export { ACT_AS_HEADER } from "./service/runtime-identity.js";
+export type { RuntimeIdentityConfig } from "./service/runtime-identity.js";
 export { MCP_PATH, MCP_PROTOCOL_VERSIONS } from "./service/mcp/server.js";
 export { MCP_TOOL_NAME_MAX_LENGTH, mcpToolName } from "./names.js";
 export type { OntologyService } from "./service/service.js";

package/dist/index.js

@@ -31,9 +31,12 @@ export { makeOntologyRuntime } from "./runtime/sql-runtime.js";
 export { BASE_PATH, deriveApi } from "./service/api.js";
 export { CurrentPrincipal } from "./service/authentication.js";
 export { deployedConnections, LocalConnectionContextError, localConnections, OIDC_TOKEN_HEADER, parseLocalConnectionContext, readLocalConnectionContext, RUNTIME_CONTEXT_FD, } from "./service/connections.js";
-export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, } from "./service/config.js";
+export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES, } from "./service/config.js";
 export { NotInvited, OntologyBackend } from "./service/runtime-contract.js";
 export { createOntologyService, ONTOLOGY_HASH_HEADER, REQUEST_ID_HEADER, } from "./service/service.js";
+// The app's own agent: pairing channel accounts with members, and acting as them.
+export { AGENT_PATH } from "./service/agent/server.js";
+export { ACT_AS_HEADER } from "./service/runtime-identity.js";
 // The MCP server the service serves beside the HTTP API.
 export { MCP_PATH, MCP_PROTOCOL_VERSIONS } from "./service/mcp/server.js";
 export { MCP_TOOL_NAME_MAX_LENGTH, mcpToolName } from "./names.js";

package/dist/migrate/apply.js

@@ -7,7 +7,7 @@ import { planMigration } from "./plan.js";
 import { REPLICATION_DDL, REPLICATION_SCHEMA_VERSION, replicationEntityDdl, } from "../replication/schema.js";
 import { createReplicationBaseline } from "../replication/baseline.js";
 import { resolveReplicationSelection } from "../replication/model.js";
-import { API_KEYS_TABLE, CATALOG_TABLE, OAUTH_TABLES, USER_ROLES_TABLE, quoteIdentifier, quoteLiteral, } from "./storage.js";
+import { AGENT_TABLES, API_KEYS_TABLE, CATALOG_TABLE, OAUTH_TABLES, USER_ROLES_TABLE, quoteIdentifier, quoteLiteral, } from "./storage.js";
 const CATALOG = quoteIdentifier(CATALOG_TABLE);
 /** Serializes migrations of one database; transaction-scoped, so it ends with the transaction. */
 const MIGRATION_LOCK = "segmentstream.ontology.migration";
@@ -171,6 +171,7 @@ export const RUNTIME_TABLES = [
     USER_ROLES_TABLE,
     API_KEYS_TABLE,
     ...OAUTH_TABLES,
+    ...AGENT_TABLES,
 ];
 /**
  * The runtime tables the database has, for `planMigration`'s `existingTables`: a database that an

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/runtime/agents.d.ts

@@ -0,0 +1,9 @@
+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.
+ */
+export declare function sqlAgentStore(ontology: Ontology, sql: SqlClient.SqlClient): AgentStore;

package/dist/runtime/agents.js

@@ -0,0 +1,145 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { AGENT_IDENTITIES_TABLE, AGENT_PAIRINGS_TABLE, USER_TABLE } from "../migrate/storage.js";
+import { resolveMemberById } from "./principals.js";
+import { isRecordId } from "./records.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"`;
+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.
+ */
+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);
+        }),
+    };
+}

package/dist/runtime/service-binding.js

@@ -6,6 +6,7 @@ import { maintainBlobStorage } from "../storage/maintenance.js";
 import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
+import { sqlAgentStore } from "./agents.js";
 import { generatedActions } from "./generated-actions.js";
 import { sqlOAuthStore } from "./oauth.js";
 import { runAction } from "./pipeline.js";
@@ -69,6 +70,7 @@ export function backendLayer(ontology, blobStorage) {
                 return state?.enabled === true;
             }).pipe(Effect.orDie),
             oauth: sqlOAuthStore(ontology, sql),
+            agents: sqlAgentStore(ontology, sql),
         });
     }));
 }

package/dist/service/agent/protocol.d.ts

@@ -0,0 +1,47 @@
+import { Schema } from "effect";
+import type { Principal } from "../../runtime.js";
+import type { AgentIdentity } from "../runtime-contract.js";
+/** How long a member has to open the connect link, sign in and approve the pairing. */
+export declare const PAIRING_TTL_MS: number;
+/**
+ * The letters and digits a pairing code uses: no 0/O, 1/I/L, so that a code read aloud or typed from
+ * a phone comes out right. 31 symbols, 8 of them: about 40 bits, against ten minutes of guessing by
+ * signed-in members only.
+ */
+export declare const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+export declare const PAIRING_CODE_LENGTH = 8;
+/** A new pairing code, from the operating system's random source without modulo bias. */
+export declare function newPairingCode(): string;
+/**
+ * A code as the member's browser sends it, in the canonical form it was hashed in: upper case,
+ * without the spaces or dashes someone may type between groups. `undefined` when it cannot be one.
+ */
+export declare function canonicalPairingCode(value: string): string | undefined;
+/** A channel's name: `telegram`, `slack`. It is part of a URL path and of every identity. */
+export declare const Provider: Schema.String;
+/** `POST /api/ontology/agent/pairings`: the account an unknown sender writes from. */
+export declare const PairingRequest: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly external_id: Schema.String;
+    readonly display: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>;
+export type PairingRequest = typeof PairingRequest.Type;
+/** An identity on the wire, as the member's connect page and settings show it. */
+export declare function identityForWire(identity: AgentIdentity): {
+    id: string;
+    provider: string;
+    external_id: string;
+    display: string | null;
+    created_at: string;
+};
+/** The member the agent acts for, as `GET …/identities/{provider}/{external_id}` answers. */
+export declare function memberForWire(input: {
+    readonly name: string;
+    readonly principal: Principal;
+}): {
+    user: {
+        id: string;
+        name: string;
+    };
+    roles: readonly string[];
+};

package/dist/service/agent/protocol.js

@@ -0,0 +1,59 @@
+import { randomInt } from "node:crypto";
+import { Schema } from "effect";
+/** How long a member has to open the connect link, sign in and approve the pairing. */
+export const PAIRING_TTL_MS = 10 * 60 * 1000;
+/**
+ * The letters and digits a pairing code uses: no 0/O, 1/I/L, so that a code read aloud or typed from
+ * a phone comes out right. 31 symbols, 8 of them: about 40 bits, against ten minutes of guessing by
+ * signed-in members only.
+ */
+export const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+export const PAIRING_CODE_LENGTH = 8;
+const PAIRING_CODE = new RegExp(`^[${PAIRING_CODE_ALPHABET}]{${PAIRING_CODE_LENGTH}}$`);
+/** A new pairing code, from the operating system's random source without modulo bias. */
+export function newPairingCode() {
+    let code = "";
+    for (let index = 0; index < PAIRING_CODE_LENGTH; index++) {
+        code += PAIRING_CODE_ALPHABET[randomInt(PAIRING_CODE_ALPHABET.length)];
+    }
+    return code;
+}
+/**
+ * A code as the member's browser sends it, in the canonical form it was hashed in: upper case,
+ * without the spaces or dashes someone may type between groups. `undefined` when it cannot be one.
+ */
+export function canonicalPairingCode(value) {
+    const code = value.replace(/[\s-]/g, "").toUpperCase();
+    return PAIRING_CODE.test(code) ? code : undefined;
+}
+const MAX_EXTERNAL_ID_LENGTH = 256;
+const MAX_DISPLAY_LENGTH = 200;
+/** A channel's name: `telegram`, `slack`. It is part of a URL path and of every identity. */
+export const Provider = Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9_-]{0,31}$/)).annotate({
+    description: "The channel, such as telegram: lower case letters, digits, - and _.",
+});
+/** `POST /api/ontology/agent/pairings`: the account an unknown sender writes from. */
+export const PairingRequest = Schema.Struct({
+    provider: Provider,
+    external_id: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_EXTERNAL_ID_LENGTH)).annotate({ description: "The account's id on the channel." }),
+    display: Schema.optionalKey(Schema.NullOr(Schema.String.check(Schema.isMaxLength(MAX_DISPLAY_LENGTH))).annotate({
+        description: "How the channel names the account, shown to the member who approves.",
+    })),
+});
+/** An identity on the wire, as the member's connect page and settings show it. */
+export function identityForWire(identity) {
+    return {
+        id: identity.id,
+        provider: identity.provider,
+        external_id: identity.externalId,
+        display: identity.display,
+        created_at: identity.createdAt.toISOString(),
+    };
+}
+/** The member the agent acts for, as `GET …/identities/{provider}/{external_id}` answers. */
+export function memberForWire(input) {
+    return {
+        user: { id: input.principal.id, name: input.name },
+        roles: input.principal.roles,
+    };
+}

package/dist/service/agent/server.d.ts

@@ -0,0 +1,27 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type SessionExchange, type TokenVerifier } from "../authentication.js";
+import { RequestId } from "../errors.js";
+import { type RateLimit } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+/** The agent's endpoints, under the ontology service's path. */
+export declare const AGENT_PATH = "/api/ontology/agent";
+/**
+ * Pairings one client address may start per minute; each one is a row in the database. The agent's
+ * functions share a few egress addresses, so the limit leaves room for a busy channel.
+ */
+export declare const PAIRING_LIMIT: RateLimit;
+export interface AgentServerOptions {
+    readonly verifyToken: TokenVerifier;
+    /** The deployment's runtime tokens; `undefined` while runtime authentication is disabled. */
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+    readonly exchangeSession: SessionExchange | undefined;
+}
+/**
+ * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
+ * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
+ * Without the agent tables, it serves nothing.
+ */
+export declare function agentLayer(options: AgentServerOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;