@segmentstream-cloud/ontology 0.14.0 → 0.15.0

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

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

@@ -1,8 +1,13 @@
+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}"`;
@@ -14,6 +19,16 @@ 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);
 }
@@ -41,6 +56,7 @@ function identityOf(row) {
  * 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);
@@ -141,5 +157,149 @@ export function sqlAgentStore(ontology, sql) {
             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. */

package/dist/runtime/generated-actions.js

@@ -64,7 +64,7 @@ function valueFields(entity, { mode }) {
                 ? target
                 : Schema.optionalKey(link.optional ? Schema.NullOr(target) : target);
         }
-        else if (link.via === "join" && !link.inverse) {
+        else if (link.via === "join" && !link.inverse && !entity.resolved.builtIn) {
             fields[link.name] = Schema.optionalKey(Schema.Array(reference(link, `The id of a ${link.target} record.`)).annotate({
                 description: `${relationshipDescription(entity, link)} The list replaces the current links.`,
             }));
@@ -87,7 +87,8 @@ function valuesOf(input, omit) {
  * 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 function generatedActions(ontology, entityName) {
     if (ontology.manifest.entities.find((e) => e.name === entityName)?.source !== undefined) {
@@ -101,7 +102,7 @@ export function generatedActions(ontology, entityName) {
 }
 function buildGeneratedActions(ontology, entityName) {
     const entity = entityModel(ontologyModel(ontology), entityName);
-    if (entity.resolved.builtIn) {
+    if (entity.resolved.builtIn && entity.resolved.permissions.update === undefined) {
         return {};
     }
     const label = entity.label.toLowerCase();
@@ -109,22 +110,26 @@ function buildGeneratedActions(ontology, entityName) {
     const managed = entity.fields
         .filter((field) => field.property?.definition.managed === true)
         .map((field) => field.name);
+    const update = action({
+        description: `Change ${article(label)}'s properties and relationships; omitted values stay as they are.` +
+            (managed.length > 0 ? ` ${managed.join(", ")} change only through other actions.` : ""),
+        input: Schema.Struct({ id: id("change"), ...valueFields(entity, { mode: "update" }) }),
+        handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.update({
+            entity: entityName,
+            id: input.id,
+            values: valuesOf(input, ["id"]),
+        })),
+    });
+    if (entity.resolved.builtIn) {
+        return { update };
+    }
     const actions = {
         create: action({
             description: `Create ${article(label)}.`,
             input: Schema.Struct(valueFields(entity, { mode: "create" })),
             handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.create({ entity: entityName, values: input })),
         }),
-        update: action({
-            description: `Change ${article(label)}'s properties and relationships; omitted values stay as they are.` +
-                (managed.length > 0 ? ` ${managed.join(", ")} change only through other actions.` : ""),
-            input: Schema.Struct({ id: id("change"), ...valueFields(entity, { mode: "update" }) }),
-            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.update({
-                entity: entityName,
-                id: input.id,
-                values: valuesOf(input, ["id"]),
-            })),
-        }),
+        update,
         delete: action({
             description: `Delete ${article(label)}. Records that refer to it are deleted, cleared or protect it, ` +
                 "as each relationship's onDelete says.",

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

@@ -0,0 +1,16 @@
+import { AgentChannel } from "../../agent-chat.js";
+import type { AgentStore } from "../runtime-contract.js";
+/** The agent's route for messages the ontology asks it to deliver, on the production deployment. */
+export declare const AGENT_MESSAGES_PATH = "/eve/v1/telegram/messages";
+/** The agent of one action request: its token and the agent tables. */
+export type AgentChannelFactory = (input: {
+    /** The deployment's Vercel OIDC token, from the request or the environment. */
+    readonly identityToken: string | undefined;
+    readonly store: AgentStore | undefined;
+}) => AgentChannel["Service"];
+/**
+ * The agent of a deployment that has one, at `https://<VERCEL_PROJECT_PRODUCTION_URL>`. Each message
+ * goes to {@link AGENT_MESSAGES_PATH} with the deployment's Vercel OIDC token, which the agent
+ * verifies as its own project's. A member's private chat is their live Telegram identity.
+ */
+export declare function deployedAgentChannel(agentUrl: string, fetchImpl?: typeof fetch): AgentChannelFactory;

package/dist/service/agent/channel.js

@@ -0,0 +1,88 @@
+import { Effect, Option, Schema } from "effect";
+import { TELEGRAM } from "../../agent-chat.js";
+import { ActionRejected } from "../../errors.js";
+import { describeError } from "../aggregate-platform.js";
+/** The agent's route for messages the ontology asks it to deliver, on the production deployment. */
+export const AGENT_MESSAGES_PATH = "/eve/v1/telegram/messages";
+/** How long the agent may take to accept a message; it answers once the message is queued. */
+const DELIVERY_TIMEOUT_MS = 30_000;
+/** The agent's error body: `{ "error": "channels_disabled" }` and the like. */
+const AgentError = Schema.Struct({
+    error: Schema.optionalKey(Schema.String),
+    detail: Schema.optionalKey(Schema.String),
+});
+const rejected = (message) => new ActionRejected({ message });
+const UNREACHABLE = "The agent could not be reached, so the message was not delivered. Try again.";
+/**
+ * A delivery that got no answer (DNS, TLS, a timeout, a dropped body): the caught error is logged
+ * for the operator, with the token redacted, and the caller is told only that the agent was
+ * unreachable.
+ */
+function deliveryFailed(error, token) {
+    const diagnostic = error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unreachable";
+    const redact = (text) => text.split(token).join("[redacted]");
+    return Effect.logWarning("ontology.agent.delivery_failed").pipe(Effect.annotateLogs({ diagnostic, error: describeError(error, redact) }), Effect.andThen(Effect.fail(rejected(UNREACHABLE))));
+}
+/**
+ * What the caller is told when the agent does not accept the message, by its status and body. The
+ * status and the agent's error code are logged; the body is not.
+ */
+function refusal(status, text) {
+    const body = Option.getOrElse(Schema.decodeUnknownOption(Schema.fromJsonString(AgentError))(text), () => ({}));
+    return Effect.logWarning("ontology.agent.delivery_refused").pipe(Effect.annotateLogs({ status, diagnostic: body.error ?? "refused" }), Effect.andThen(Effect.fail(refusalMessage(status, body))));
+}
+/** The caller's message for a refusal, by the agent's status and decoded error body. */
+function refusalMessage(status, body) {
+    switch (status) {
+        case 400:
+            return rejected(`The agent refused the message as invalid${body.detail ? `: ${body.detail}` : "."}`);
+        case 401:
+        case 403:
+            return rejected("The agent refused the deployment's token, so the message was not delivered.");
+        case 404:
+            return rejected("The deployed agent does not take messages from the ontology. Redeploy the agent with an " +
+                "SDK that does.");
+        case 503:
+            return body.error === "channels_disabled"
+                ? rejected("The agent's channels run only in the production deployment, so it cannot deliver " +
+                    "the message from here.")
+                : rejected("The agent is temporarily unavailable, so the message was not delivered. Try again.");
+        default:
+            return rejected(UNREACHABLE);
+    }
+}
+/**
+ * The agent of a deployment that has one, at `https://<VERCEL_PROJECT_PRODUCTION_URL>`. Each message
+ * goes to {@link AGENT_MESSAGES_PATH} with the deployment's Vercel OIDC token, which the agent
+ * verifies as its own project's. A member's private chat is their live Telegram identity.
+ */
+export function deployedAgentChannel(agentUrl, fetchImpl = fetch) {
+    const url = `${agentUrl}${AGENT_MESSAGES_PATH}`;
+    return ({ identityToken, store }) => ({
+        privateChat: (userId) => store === undefined
+            ? Effect.succeed(undefined)
+            : store
+                .listIdentities(userId)
+                .pipe(Effect.map((identities) => identities.find((identity) => identity.provider === TELEGRAM)?.externalId)),
+        send: (message) => identityToken === undefined || identityToken === ""
+            ? Effect.fail(rejected("The request carries no Vercel OIDC token, which the agent requires. Messages are " +
+                "sent from the production deployment."))
+            : Effect.tryPromise({
+                try: async (signal) => {
+                    const response = await fetchImpl(url, {
+                        method: "POST",
+                        headers: {
+                            authorization: `Bearer ${identityToken}`,
+                            "content-type": "application/json",
+                            accept: "application/json",
+                        },
+                        body: JSON.stringify(message),
+                        redirect: "error",
+                        signal: AbortSignal.any([signal, AbortSignal.timeout(DELIVERY_TIMEOUT_MS)]),
+                    });
+                    return { ok: response.ok, status: response.status, text: await response.text() };
+                },
+                catch: (error) => error,
+            }).pipe(Effect.catch((error) => deliveryFailed(error, identityToken)), Effect.flatMap((answer) => answer.ok ? Effect.void : refusal(answer.status, answer.text))),
+    });
+}

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

@@ -26,6 +26,20 @@ export declare const PairingRequest: Schema.Struct<{
     readonly display: Schema.optionalKey<Schema.NullOr<Schema.String>>;
 }>;
 export type PairingRequest = typeof PairingRequest.Type;
+/**
+ * `POST /api/ontology/agent/chats/seen`: a group chat the agent saw a message in, and who wrote, or
+ * the paired member who left it, or the agent itself leaving it, or the group it was before it
+ * became a supergroup.
+ */
+export declare const ChatSeenRequest: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly externalId: Schema.String;
+    readonly title: Schema.String;
+    readonly memberId: Schema.optionalKey<Schema.String>;
+    readonly leftMemberId: Schema.optionalKey<Schema.String>;
+    readonly agentLeft: Schema.optionalKey<Schema.Literal<true>>;
+    readonly migratedFrom: Schema.optionalKey<Schema.String>;
+}>;
 /** An identity on the wire, as the member's connect page and settings show it. */
 export declare function identityForWire(identity: AgentIdentity): {
     id: string;

package/dist/service/agent/protocol.js

@@ -40,6 +40,32 @@ export const PairingRequest = Schema.Struct({
         description: "How the channel names the account, shown to the member who approves.",
     })),
 });
+/** A chat's id on the channel. */
+const ChatId = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_EXTERNAL_ID_LENGTH));
+/**
+ * `POST /api/ontology/agent/chats/seen`: a group chat the agent saw a message in, and who wrote, or
+ * the paired member who left it, or the agent itself leaving it, or the group it was before it
+ * became a supergroup.
+ */
+export const ChatSeenRequest = Schema.Struct({
+    provider: Provider,
+    externalId: ChatId.annotate({ description: "The chat's id on the channel." }),
+    title: Schema.String.check(Schema.isMaxLength(MAX_DISPLAY_LENGTH)).annotate({
+        description: "The chat's name on the channel.",
+    }),
+    memberId: Schema.optionalKey(Schema.String.annotate({
+        description: "The user id of the member who wrote, when the sender is paired.",
+    })),
+    leftMemberId: Schema.optionalKey(Schema.String.annotate({
+        description: "The user id of a paired member who left the chat, to unlink from its members.",
+    })),
+    agentLeft: Schema.optionalKey(Schema.Literal(true).annotate({
+        description: "The agent itself left the chat or was removed: every member is unlinked.",
+    })),
+    migratedFrom: Schema.optionalKey(ChatId.annotate({
+        description: "The chat's id before it became a supergroup: its record moves to externalId.",
+    })),
+});
 /** An identity on the wire, as the member's connect page and settings show it. */
 export function identityForWire(identity) {
     return {

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

@@ -19,7 +19,8 @@ export interface AgentServerOptions {
     readonly exchangeSession: SessionExchange | undefined;
 }
 /**
- * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * The routes that pair channel accounts with members for the app's own agent, and record the group
+ * chats it sees. 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.

package/dist/service/agent/server.js

@@ -10,11 +10,12 @@ import { secretHash } from "../oauth/protocol.js";
 import { clientAddress, fixedWindowLimiter, } from "../rate-limit.js";
 import { OntologyBackend } from "../runtime-contract.js";
 import { logRuntimeRejection } from "../runtime-identity.js";
-import { PAIRING_TTL_MS, PairingRequest, canonicalPairingCode, identityForWire, memberForWire, newPairingCode, } from "./protocol.js";
+import { ChatSeenRequest, PAIRING_TTL_MS, PairingRequest, canonicalPairingCode, identityForWire, memberForWire, newPairingCode, } from "./protocol.js";
 /** The agent's endpoints, under the ontology service's path. */
 export const AGENT_PATH = `${BASE_PATH}/agent`;
 const PAIRINGS_PATH = `${AGENT_PATH}/pairings`;
 const IDENTITIES_PATH = `${AGENT_PATH}/identities`;
+const CHATS_SEEN_PATH = `${AGENT_PATH}/chats/seen`;
 /**
  * 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.
@@ -153,6 +154,25 @@ function resolveIdentity(store) {
         return json(memberForWire(member));
     });
 }
+/**
+ * `POST /api/ontology/agent/chats/seen` (runtime): the agent saw a message in a group chat. The chat
+ * is recorded, or its title kept current, a paired writer joins its members and a paired member who
+ * left is unlinked from them, or all of them when the agent itself left; the answer says what the
+ * chat is for, so that the agent knows it.
+ */
+function seeChat(store) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const decoded = Schema.decodeUnknownResult(ChatSeenRequest)(yield* jsonBody(request), {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        return json(yield* store.seeChat(decoded.success));
+    });
+}
 /** `GET /api/ontology/agent/identities` (member): the member's own live identities. */
 function listIdentities(store, member) {
     return Effect.gen(function* () {
@@ -174,7 +194,8 @@ function revokeIdentity(store, member) {
     });
 }
 /**
- * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * The routes that pair channel accounts with members for the app's own agent, and record the group
+ * chats it sees. 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.
@@ -230,6 +251,7 @@ export function agentLayer(options) {
         yield* router.add("POST", `${PAIRINGS_PATH}/:code/approve`, asMember((_, member) => approvePairing(store, member)));
         yield* router.add("GET", IDENTITIES_PATH, asMember((_, member) => listIdentities(store, member)));
         yield* router.add("GET", `${IDENTITIES_PATH}/:provider/:external_id`, asRuntime(() => resolveIdentity(store)));
+        yield* router.add("POST", CHATS_SEEN_PATH, asRuntime(seeChat(store)));
         yield* router.add("DELETE", `${IDENTITIES_PATH}/:id`, asMember((_, member) => revokeIdentity(store, member)));
     }));
 }

package/dist/service/aggregate-platform.d.ts

@@ -47,6 +47,11 @@ export interface AggregateEnvironment {
     readonly appCredential?: Redacted.Redacted<string>;
     readonly manifestHash: string;
 }
+/**
+ * A failed call for the operator: name, message and stack, then each cause, with every occurrence
+ * of the credential replaced.
+ */
+export declare function describeError(error: unknown, redact: (text: string) => string, depth?: number): string;
 /**
  * SegmentStream's `POST /api/v1/workspaces/{id}/aggregate`, and its per-entity
  * `…/entities/{entity}/aggregate`, called with the workspace app credential. `undefined` when the deployment has none, or when SegmentStream's origin is plain

package/dist/service/aggregate-platform.js

@@ -58,7 +58,7 @@ function securePlatform(origin) {
  * A failed call for the operator: name, message and stack, then each cause, with every occurrence
  * of the credential replaced.
  */
-function describeError(error, redact, depth = 0) {
+export function describeError(error, redact, depth = 0) {
     if (!(error instanceof Error)) {
         return redact(String(error));
     }

package/dist/service/config.d.ts

@@ -37,6 +37,11 @@ export declare const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES: {
     readonly audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE";
     readonly projectId: "VERCEL_PROJECT_ID";
 };
+/**
+ * The project's production domain, which Vercel sets: the agent of a deployment with runtime identity
+ * takes the messages of `agent_chat.send_message` there.
+ */
+export declare const AGENT_HOST_VARIABLE = "VERCEL_PROJECT_PRODUCTION_URL";
 /** Where the workspace's Neon Auth issues and publishes the keys of its users' tokens. */
 export interface NeonAuthEnvironment {
     /** The Auth URL, such as `https://ep-….neon.tech/ontology/auth`. Its origin is the issuer. */
@@ -68,6 +73,11 @@ export interface OntologyEnvironment {
      * authenticate, acting as the member `X-SegmentStream-Act-As` names.
      */
     readonly runtimeIdentity?: RuntimeIdentityConfig;
+    /**
+     * The agent's origin, `https://<VERCEL_PROJECT_PRODUCTION_URL>`, set with `runtimeIdentity`:
+     * `agent_chat.send_message` hands messages to the agent there.
+     */
+    readonly agentUrl?: string;
     /**
      * The local grant `segmentstream exec --connection …` passed, in development. Without it, actions
      * call connections through SegmentStream with the deployment's Vercel OIDC token.