@segmentstream-cloud/ontology 0.13.0 → 0.15.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
@@ -140,7 +143,8 @@ export default defineOntology({
 - `rel.one` and `rel.many` declare relationships. Between stored entities, `rel.one` adds a
   key and `rel.many` a join table. With a warehouse-backed end, `rel.one` declares one `on`
   pair and is matched by value. `User` is the built-in entity for app users and service
-  principals.
+  principals; `AgentChat` (`agent_chat`) is the built-in entity for the group chats of the
+  app's agent (see [Agents](#agents)). Every ontology includes both.
 - `role(name, { description, permissions })` declares a role: a named set of permissions.
   `member` is built in: every active app user holds it, with the permissions of
   `defineOntology({ member })`.
@@ -159,7 +163,9 @@ export default defineOntology({
 
 A permission is `<entity>:<verb>`. The verbs are `read`, the generated `create`, `update`,
 `delete`, `link` and `unlink`, and the names of authored actions. A role may use `*` for the
-entity, the verb or both: `lead:*`, `*:read`, `*:*`.
+entity, the verb or both: `lead:*`, `*:read`, `*:*`. An entity wildcard never covers the
+built-in `agent_chat`: reading or changing it needs a permission that names it, such as
+`agent_chat:read`.
 
 - Reads require `<entity>:read`: lists, queries, records, history, both entities of a
   relationship traversal, and every entity an aggregate touches. `include` and a filter through a relationship require `read` on
@@ -211,9 +217,13 @@ 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.                            |
+| `VERCEL_PROJECT_PRODUCTION_URL`       | Set by Vercel. With the runtime pair, where `agent_chat.send_message` reaches the agent.     |
 
 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 +259,58 @@ 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                                                                                                     |
+| `POST /api/ontology/agent/chats/seen`                         | agent  | `{ provider, externalId, title, memberId?, leftMemberId?, agentLeft?, migratedFrom? }` → `{ id, title, purpose, whenToUse }` |
+
+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 built-in entity `agent_chat` keeps the group chats the agent is in. The agent reports each
+message it sees there to `chats/seen`, which creates the chat or keeps its title current,
+records `lastMessageAt` at most every 15 minutes, links a paired, active writer to
+`members` and unlinks `leftMemberId`, a paired member who left, when linked, or every member
+with `agentLeft: true`, when the agent itself left (the chat stays). With `migratedFrom`, the
+old id of a group that became a supergroup, it moves the old record to `externalId`, or, when
+both are recorded, moves the members and a missing `purpose` and `whenToUse` to the new one and
+deletes the old one. `provider`, `externalId`, `title` and `lastMessageAt` are
+managed. Members set `purpose` and `whenToUse` with the generated
+`agent_chat.update`, the chat's only generated action. The built-in action
+`agent_chat.send_message` (`{ message, chat?, person? }`, `message` at most 4000 characters) asks the agent to write to the chat
+given, else to the person's one chat, else to their paired private chat; a person in several
+chats is refused with the candidates, or only their number without `agent_chat:read`. The service posts the message to the agent at
+`https://<VERCEL_PROJECT_PRODUCTION_URL>/eve/v1/telegram/messages` with the deployment's OIDC
+token, naming the requester with their `id`, `name`, `kind`, `roles` and `actAs`, true for a
+member with a live pairing, whom the agent's turn can act as; without the runtime
+pair, or when the agent refuses, the action is rejected with the reason. Both actions need their own permission (`agent_chat:update`,
+`agent_chat:send_message`), which no role holds until the workspace grants it, and reading
+chats needs `agent_chat:read` by name: `*:read` and `*:*` do not cover `agent_chat`.
+
 ## The `segmentstream-ontology` binary
 
 Run the binary in the `ontology/` folder. The entry defaults to `./index.ts`. The binary

package/dist/agent-chat.d.ts

@@ -0,0 +1,75 @@
+import { Context, Effect, Schema } from "effect";
+import { ActionRejected } from "./errors.js";
+/** The only channel the agent delivers to so far, and the provider of its chats. */
+export declare const TELEGRAM = "telegram";
+/**
+ * What `agent_chat.send_message` asks the agent to deliver: the body of the agent's
+ * `POST /eve/v1/telegram/messages`. A Telegram private chat's id is the person's Telegram user id.
+ */
+export interface AgentMessage {
+    readonly target: {
+        readonly kind: "group" | "private";
+        readonly provider: typeof TELEGRAM;
+        readonly chatId: string;
+    };
+    /** The request for the agent, written as an instruction to it. */
+    readonly message: string;
+    /** Whom the agent should address, when the caller named someone. */
+    readonly person: {
+        readonly id: string;
+        readonly name: string;
+    } | null;
+    /** Who asked: the principal that ran the action. */
+    readonly requester: {
+        readonly id: string;
+        readonly name: string;
+        readonly kind: "member" | "service";
+        /** The role names the principal holds, which pick the model of a session the request starts. */
+        readonly roles: ReadonlyArray<string>;
+        /**
+         * Whether the agent can act as the requester in the turn: a member with a live paired identity.
+         * Otherwise the turn runs without a member and has no ontology.
+         */
+        readonly actAs: boolean;
+    };
+}
+declare const AgentChannel_base: Context.ServiceClass<AgentChannel, "@segmentstream-cloud/ontology/AgentChannel", {
+    /** The Telegram user id of the member's live paired identity: their private chat's id. */
+    readonly privateChat: (userId: string) => Effect.Effect<string | undefined>;
+    /** Hands the message to the agent; a refusal or failure explains itself to the caller. */
+    readonly send: (message: AgentMessage) => Effect.Effect<void, ActionRejected>;
+}>;
+/**
+ * The workspace's agent, as `agent_chat.send_message` reaches it. The ontology service provides it to
+ * actions only on deployments with an agent; without it, the action is refused.
+ */
+export declare class AgentChannel extends AgentChannel_base {
+}
+/**
+ * The built-in agent chat: a group chat the workspace's agent is in. Every ontology includes it,
+ * after `User`. The agent records each chat it sees and the members it sees writing there, through
+ * `POST /api/ontology/agent/chats/seen`; members say what a chat is for with the generated `update`,
+ * which changes only `purpose` and `whenToUse`. `send_message` asks the agent to write to a chat.
+ */
+export declare const AgentChat: import("./entity.js").Entity<"agent_chat", {
+    readonly provider: import("./property.js").Property<string, false, false>;
+    readonly externalId: import("./property.js").Property<string, false, false>;
+    readonly title: import("./property.js").Property<string, false, false>;
+    readonly lastMessageAt: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly purpose: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly whenToUse: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+}, {
+    readonly members: import("./relationship.js").ManyRelationship;
+}, {
+    readonly sendMessage: import("./action.js").Action<Schema.Struct<{
+        readonly message: import("./property.js").Property<string, false, false>;
+        readonly chat: Schema.optionalKey<Schema.Codec<string, string, never, never>>;
+        readonly person: Schema.optionalKey<Schema.Codec<string, string, never, never>>;
+    }>, {
+        chat: string;
+        target: "group" | "private";
+        delivered: true;
+    }>;
+}, Readonly<Record<never, never>>>;
+export type AgentChat = typeof AgentChat.Type;
+export {};

package/dist/agent-chat.js

@@ -0,0 +1,176 @@
+import { Context, Effect, Option, Schema } from "effect";
+import { action } from "./action.js";
+import { entity } from "./entity.js";
+import { ActionRejected } from "./errors.js";
+import { isAllowed, permissionOf, READ_VERB } from "./permissions.js";
+import { p } from "./property.js";
+import { rel } from "./relationship.js";
+import { User } from "./user.js";
+/** The only channel the agent delivers to so far, and the provider of its chats. */
+export const TELEGRAM = "telegram";
+/**
+ * The workspace's agent, as `agent_chat.send_message` reaches it. The ontology service provides it to
+ * actions only on deployments with an agent; without it, the action is refused.
+ */
+export class AgentChannel extends Context.Service()("@segmentstream-cloud/ontology/AgentChannel") {
+}
+/** A group chat as the agent's target; the agent delivers only to Telegram so far. */
+function groupTarget(chat) {
+    return chat.provider === TELEGRAM
+        ? Effect.succeed({ kind: "group", provider: TELEGRAM, chatId: chat.externalId })
+        : Effect.fail(new ActionRejected({
+            message: `The agent delivers only to Telegram chats; ${chat.title} is on ${chat.provider}.`,
+        }));
+}
+const NO_AGENT = "The workspace has no agent deployed, so nobody can deliver the message. " +
+    "Deploy the workspace's agent first.";
+/**
+ * The built-in agent chat: a group chat the workspace's agent is in. Every ontology includes it,
+ * after `User`. The agent records each chat it sees and the members it sees writing there, through
+ * `POST /api/ontology/agent/chats/seen`; members say what a chat is for with the generated `update`,
+ * which changes only `purpose` and `whenToUse`. `send_message` asks the agent to write to a chat.
+ */
+export const AgentChat = entity("agent_chat", {
+    id: "ent_agent_chat",
+    label: "Agent chat",
+    plural: "Agent chats",
+    title: "title",
+    description: "A group chat the workspace's agent is in. The agent records each chat it sees; " +
+        "members say what the chat is for, so that agents know where to write.",
+    properties: {
+        provider: p.text({ managed: true, description: "The channel, for example telegram." }),
+        externalId: p.text({ managed: true, description: "The chat's id at the provider." }),
+        title: p.text({
+            managed: true,
+            description: "The chat's name at the provider, kept current by the agent.",
+        }),
+        lastMessageAt: p.timestamp({
+            optional: true,
+            managed: true,
+            label: "Last message",
+            description: "When the agent last saw a message in the chat, recorded at most every 15 minutes.",
+        }),
+        purpose: p.text({
+            optional: true,
+            maxLength: 64,
+            description: "A short key that code and agents look the chat up by, such as accounting.",
+        }),
+        whenToUse: p.text({
+            optional: true,
+            maxLength: 1000,
+            display: "multiline",
+            label: "When to use",
+            description: "For agents: what the chat is for and when to write there, such as " +
+                '"Invoices and payments; Yulia answers on weekdays."',
+        }),
+    },
+    relationships: {
+        // By name, so that an ontology rebuilt with the deployed `user` still resolves it.
+        members: rel.many("user", {
+            inverse: "agentChats",
+            phrase: ["includes", "is in"],
+            description: "Workspace members the agent has seen writing in the chat.",
+        }),
+    },
+    indexes: [{ properties: ["provider", "externalId"], unique: true }],
+}).actions((self) => ({
+    sendMessage: action({
+        description: "Ask the workspace's agent to write to a group chat or a person, for example " +
+            '"ask Yulia for the amount on invoice 118". message is the request for the agent, written ' +
+            "as an instruction to it, not necessarily the text to post. The target is chosen without " +
+            "guessing: with chat, that chat (person, if given, is whom the agent addresses there); with " +
+            "only person, the one agent chat whose members include them, or, when they are in none, " +
+            "their private chat with the agent if they paired a Telegram account. A person in several " +
+            "chats is refused with the candidates (id, title, purpose, when to use; only their number " +
+            "without agent_chat:read): call again with chat. The agent then writes in that chat and " +
+            "handles the replies there, in that chat's own session; this action only delivers the " +
+            "request and does not wait for an answer. Requires an agent deployed in the workspace.",
+        input: Schema.Struct({
+            message: p.text({
+                maxLength: 4000,
+                description: "The request for the agent, as an instruction: what to ask or tell, of whom.",
+            }),
+            chat: p.ref("agent_chat", { optional: true, description: "The agent chat to write in." }),
+            person: p.ref("user", {
+                optional: true,
+                description: "The member to address; alone, it picks their chat with the agent.",
+            }),
+        }),
+        hints: { destructive: false },
+        connections: [],
+        prepare: ({ input, principal }) => Effect.gen(function* () {
+            const channel = yield* Effect.serviceOption(AgentChannel);
+            if (Option.isNone(channel)) {
+                return yield* new ActionRejected({ message: NO_AGENT });
+            }
+            const person = input.person === undefined ? undefined : yield* User.get(input.person);
+            if (person !== undefined && (person.kind !== "member" || !person.active)) {
+                return yield* new ActionRejected({
+                    message: `${person.name} is not an active member, so the agent does not contact them.`,
+                });
+            }
+            let chat;
+            let target;
+            if (input.chat !== undefined) {
+                chat = yield* self.get(input.chat);
+                target = yield* groupTarget(chat);
+            }
+            else if (person !== undefined) {
+                const chats = yield* self.find({
+                    where: { members: { some: { id: { eq: person.id } } } },
+                });
+                if (chats.length > 1) {
+                    // The action reads chats whatever the caller holds; only a reader sees which they are.
+                    if (!isAllowed(permissionOf(self.name, READ_VERB), principal)) {
+                        return yield* new ActionRejected({
+                            message: `${person.name} is in ${chats.length} chats with the agent; call again with ` +
+                                "the chat's id as chat. Listing them requires agent_chat:read.",
+                        });
+                    }
+                    const candidates = chats.map((candidate) => `- ${candidate.id}: ${candidate.title}; purpose: ${candidate.purpose ?? "none"}; ` +
+                        `when to use: ${candidate.whenToUse ?? "not set"}`);
+                    return yield* new ActionRejected({
+                        message: `${person.name} is in ${chats.length} chats with the agent; ` +
+                            `call again with one of them as chat:\n${candidates.join("\n")}`,
+                    });
+                }
+                chat = chats[0];
+                if (chat !== undefined) {
+                    target = yield* groupTarget(chat);
+                }
+                else {
+                    const chatId = yield* channel.value.privateChat(person.id);
+                    if (chatId === undefined) {
+                        return yield* new ActionRejected({
+                            message: `${person.name} is in no chat with the agent and has not paired a Telegram ` +
+                                "account with it, so the agent cannot reach them.",
+                        });
+                    }
+                    target = { kind: "private", provider: TELEGRAM, chatId };
+                }
+            }
+            else {
+                return yield* new ActionRejected({
+                    message: "Name the chat to write in, the person to write to, or both.",
+                });
+            }
+            const requester = yield* User.get(principal.id);
+            // The agent acts as a member only through their pairing.
+            const actAs = principal.kind === "member" &&
+                (yield* channel.value.privateChat(principal.id)) !== undefined;
+            yield* channel.value.send({
+                target,
+                message: input.message,
+                person: person === undefined ? null : { id: person.id, name: person.name },
+                requester: {
+                    id: requester.id,
+                    name: requester.name,
+                    kind: principal.kind,
+                    roles: principal.roles,
+                    actAs,
+                },
+            });
+            return { chat: chat?.id ?? null, target: target.kind, delivered: true };
+        }),
+    }),
+}));

package/dist/analyze.d.ts

@@ -9,7 +9,10 @@ import { type Role } from "./role.js";
 import { type SignInOptions } from "./sign-in.js";
 /** The input of `defineOntology` and `check`. */
 export interface OntologyConfig<Entities extends ReadonlyArray<AnyEntity> = ReadonlyArray<AnyEntity>> {
-    /** The app's entities. The built-in `User` is always included; listing it is optional. */
+    /**
+     * The app's entities. The built-in `User` and `AgentChat` are always included; listing them is
+     * optional.
+     */
     readonly entities: Entities;
     /** Business roles. The built-in `member` role is always included. */
     readonly roles?: ReadonlyArray<Role>;
@@ -82,7 +85,8 @@ export interface ResolvedIndex {
 }
 /**
  * The permissions of an entity's reads and generated actions. The built-in User has no generated
- * actions; `link` and `unlink` exist when the entity declares a `rel.many`.
+ * actions and the built-in agent chat only `update`; `link` and `unlink` exist when the entity
+ * declares a `rel.many`.
  */
 export interface EntityPermissions {
     readonly read: string;

package/dist/analyze.js

@@ -7,10 +7,11 @@ import { CONNECTION_KEY, isConnection } from "./connection.js";
 import { isEntity } from "./entity.js";
 import { AGGREGATE_ROUTE, LEGACY_MEMBER_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MCP_READ_TOOLS, MCP_TOOL_NAME_MAX_LENGTH, MEMBER_ROLE, mcpToolName, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, } from "./names.js";
 import { REFERENCE_ANNOTATION, propertyDefinition, referenceTarget, } from "./property.js";
-import { generatedActionPermissions, parsePermission, permissionOf, READ_VERB, rolesGranting, WILDCARD, } from "./permissions.js";
+import { EXPLICIT_GRANT_ENTITIES, generatedActionPermissions, parsePermission, permissionOf, READ_VERB, rolesGranting, WILDCARD, } from "./permissions.js";
 import { ON_DELETE, isRelationship } from "./relationship.js";
 import { isRole, member, role } from "./role.js";
 import { DEFAULT_SIGN_IN_POLICY, isSignInPolicy } from "./sign-in.js";
+import { AgentChat } from "./agent-chat.js";
 import { User } from "./user.js";
 import { authoringToWire } from "./authoring.js";
 import { nameToWire } from "./authoring-names.js";
@@ -34,10 +35,9 @@ export function analyze(config, options = {}) {
         diagnostics.push({ severity, code, path, message });
     };
     const original = config;
-    const normalized = authoringToWire(config, options.user ?? User, report);
+    const normalized = authoringToWire(config, [options.user ?? User, AgentChat], report);
     config = normalized.config;
-    const user = normalized.user;
-    const entities = collectEntities(config, user, report);
+    const entities = collectEntities(config, normalized.builtIns, report);
     const roles = collectRoles(config, report);
     const signIn = signInOptions(config, report);
     const connections = collectConnections(config, report);
@@ -49,7 +49,7 @@ export function analyze(config, options = {}) {
     }
     const scope = {
         report,
-        user,
+        builtIns: new Set(normalized.builtIns.map((candidate) => candidate.definition)),
         entitiesByName,
         definitions: new Set(entities.map((candidate) => candidate.definition)),
         entityProperties: new Set([...entities, ...(original.entities ?? []).filter(isEntity)].flatMap((candidate) => Object.values(candidate.definition.properties ?? {}))),
@@ -74,7 +74,7 @@ export function analyze(config, options = {}) {
 function toolOperations(candidate) {
     const { permissions } = candidate;
     const generated = [
-        ...(permissions.create !== undefined ? ["create", "update", "delete"] : []),
+        ...["create", "update", "delete"].filter((verb) => permissions[verb] !== undefined),
         ...(permissions.create !== undefined
             ? candidate.properties
                 .filter(({ definition }) => definition.unique)
@@ -169,9 +169,10 @@ function checkConnectionsUsed(entities, connections, declared, report) {
 }
 /**
  * The keys of an action's connections, each listed in `defineOntology({ connections })`, and the
- * phases they require: `prepare` with connections, and `prepare` or `handler` always.
+ * phases they require: `prepare` with connections and only with them, except for built-in actions,
+ * and `prepare` or `handler` always.
  */
-function resolveActionConnections(path, action, scope) {
+function resolveActionConnections(path, action, scope, builtIn) {
     const { report } = scope;
     const declared = action.connections;
     const keys = [];
@@ -200,7 +201,8 @@ function resolveActionConnections(path, action, scope) {
     if (Array.isArray(declared) && declared.length > 0 && !hasPrepare) {
         report("invalid-prepare", `${path}.prepare`, "an action with connections calls them in prepare, which runs before the transaction.");
     }
-    if (hasPrepare && Array.isArray(declared) && declared.length === 0) {
+    // A built-in action's prepare reaches the platform, such as the workspace's agent, instead.
+    if (hasPrepare && !builtIn && Array.isArray(declared) && declared.length === 0) {
         report("invalid-prepare", `${path}.prepare`, "prepare is for calling connections; an action without connections does its work in handler.");
     }
     if (!hasPrepare && !hasHandler) {
@@ -208,8 +210,8 @@ function resolveActionConnections(path, action, scope) {
     }
     return keys;
 }
-function collectEntities(config, user, report) {
-    const entities = [user];
+function collectEntities(config, builtIns, report) {
+    const entities = [...builtIns];
     (config.entities ?? []).forEach((candidate, index) => {
         if (!isEntity(candidate)) {
             report("invalid-entity", `entities[${index}]`, "is not an entity; declare entities with entity(name, { … }).");
@@ -330,7 +332,7 @@ function resolveEntity(candidate, scope) {
     else if (!properties.some((property) => property.name === definition.title)) {
         report("invalid-title", `${name}.title`, `"${definition.title}" is not a declared property of ${name}.`);
     }
-    const builtIn = candidate.definition === scope.user.definition;
+    const builtIn = scope.builtIns.has(candidate.definition);
     return {
         entity: candidate,
         name,
@@ -342,11 +344,15 @@ function resolveEntity(candidate, scope) {
         permissions: entityPermissions(name, builtIn || definition.source !== undefined, relationships),
     };
 }
-/** Reads need `<entity>:read`; each generated action needs the permission named after it. */
+/**
+ * Reads need `<entity>:read`; each generated action needs the permission named after it. Built-in
+ * entities hold the platform's records: only `agent_chat` has a generated action, `update`, for the
+ * properties members edit.
+ */
 function entityPermissions(name, builtIn, relationships) {
     const read = permissionOf(name, READ_VERB);
     if (builtIn) {
-        return { read };
+        return name === AgentChat.name ? { read, update: permissionOf(name, "update") } : { read };
     }
     const many = relationships.some(({ relationship }) => relationship.cardinality === "many");
     return {
@@ -628,7 +634,7 @@ function resolveActions(candidate, scope) {
             action,
             permission: resolvePermission(path, permissionOf(candidate.name, name), action, scope),
             input: resolveInput(path, action.input, scope),
-            connections: resolveActionConnections(path, action, scope),
+            connections: resolveActionConnections(path, action, scope, scope.builtIns.has(candidate.definition)),
             hints: resolveHints(path, action, report),
         });
     }
@@ -762,7 +768,9 @@ function checkEntityIdentities(entities, report) {
         const existingName = names.get(candidate.name);
         const existingId = ids.get(definition.id);
         if (existingName !== undefined) {
-            const builtIn = existingName.builtIn ? " (the built-in User)" : "";
+            const builtIn = existingName.builtIn
+                ? ` (the built-in ${existingName.entity.definition.label})`
+                : "";
             report("duplicate-name", candidate.name, `another entity is named ${candidate.name}${builtIn}.`);
         }
         else {
@@ -869,7 +877,9 @@ function knownVerbs(entities) {
 /** Why a role's permission matches nothing in the ontology, or `undefined` when it matches. */
 function unknownPermission(value, { entity, verb }, verbs) {
     if (entity === WILDCARD) {
-        const matched = verb === WILDCARD || [...verbs.values()].some((own) => own.has(verb));
+        // A wildcard entity does not reach the entities only a named permission covers.
+        const matched = verb === WILDCARD ||
+            [...verbs].some(([name, own]) => !EXPLICIT_GRANT_ENTITIES.has(name) && own.has(verb));
         return matched ? undefined : `${value} matches nothing: no entity has ${verb}.`;
     }
     const own = verbs.get(entity);
@@ -961,7 +971,8 @@ function checkPermissions(entities, roles, report) {
         name: candidate.name,
         permissions: Array.isArray(candidate.permissions) ? candidate.permissions : [],
     }));
-    for (const candidate of entities) {
+    // Built-in actions are granted by the workspace's roles when it wants them.
+    for (const candidate of entities.filter((entity) => !entity.builtIn)) {
         for (const { name, permission } of candidate.actions) {
             const parsed = parsePermission(permission);
             // An invalid name or permission is already an error; it needs no warning on top.

package/dist/authoring.d.ts

@@ -4,9 +4,12 @@ import { type AnyEntity } from "./entity.js";
 import type { Principal } from "./runtime.js";
 type Report = (code: DiagnosticCode, path: string, message: string) => void;
 export declare function principalFromWire(principal: Principal): Principal;
-/** Canonical definitions feed REST, storage and future transports; the public config stays camelCase. */
-export declare function authoringToWire(config: OntologyConfig, user: AnyEntity, report: Report): {
+/**
+ * Canonical definitions feed REST, storage and future transports; the public config stays camelCase.
+ * The built-in entities, which every ontology includes, are normalized with the declared ones.
+ */
+export declare function authoringToWire(config: OntologyConfig, builtIns: ReadonlyArray<AnyEntity>, report: Report): {
     readonly config: OntologyConfig;
-    readonly user: AnyEntity;
+    readonly builtIns: ReadonlyArray<AnyEntity>;
 };
 export {};

package/dist/authoring.js

@@ -217,8 +217,11 @@ class AuthoringEncoder {
         return normalized;
     }
 }
-/** Canonical definitions feed REST, storage and future transports; the public config stays camelCase. */
-export function authoringToWire(config, user, report) {
+/**
+ * Canonical definitions feed REST, storage and future transports; the public config stays camelCase.
+ * The built-in entities, which every ontology includes, are normalized with the declared ones.
+ */
+export function authoringToWire(config, builtIns, report) {
     const encoder = new AuthoringEncoder(report);
     const normalized = {
         ...config,
@@ -233,5 +236,5 @@ export function authoringToWire(config, user, report) {
             permissions: config.member.permissions.map(permissionToWire),
         };
     }
-    return { config: normalized, user: encoder.entity(user) };
+    return { config: normalized, builtIns: builtIns.map((entity) => encoder.entity(entity)) };
 }

package/dist/index.d.ts

@@ -34,6 +34,8 @@ export type { SignInCheck, SignInMethod, SignInOptions, SignInPolicy } from "./s
 export { OntologyReads, OntologyRuntime, OntologyWrites } from "./runtime.js";
 export type { FieldCondition, OntologyRuntimeService, FindOptions, GetOptions, Principal, RecordWhere, StoredRecord, StoredValues, UpsertResult, } from "./runtime.js";
 export { User } from "./user.js";
+export { AgentChannel, AgentChat } from "./agent-chat.js";
+export type { AgentMessage } from "./agent-chat.js";
 export { DEFAULT_QUERY_LIMIT, entityQueryResultSchema, entityQuerySchema, entityQuerySchemas, entityRecordSchema, FILTER_OPERATORS, MANY_QUANTIFIERS, MAX_IN_VALUES, MAX_QUERY_LIMIT, OrderBy, Query, queryFields, queryJsonSchema, queryLinks, QueryResult, queryResultJsonSchema, queryResultSchema, SortDirection, WHERE_COMBINATORS, } from "./query.js";
 export type { EntityQuerySchemas, FieldFilter, FilterOperator, JsonRecord, ManyFilter, QueryField, QueryLink, StorageType, Where, } from "./query.js";
 export { InvalidQuery, InvalidValues, MemberNotFound, PrincipalRejected, StoredRecordMismatch, UnknownAction, UnknownRole, ValidationIssue, WriteOutsideAction, } from "./runtime/errors.js";
@@ -52,11 +54,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, AGENT_HOST_VARIABLE, 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, SeenChat, 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

@@ -17,6 +17,7 @@ export { member, role } from "./role.js";
 export { DEFAULT_SIGN_IN_POLICY, SIGN_IN_METHODS, SIGN_IN_POLICIES } from "./sign-in.js";
 export { OntologyReads, OntologyRuntime, OntologyWrites } from "./runtime.js";
 export { User } from "./user.js";
+export { AgentChannel, AgentChat } from "./agent-chat.js";
 // The query language of `find` and of the service's list, query and traversal routes.
 export { DEFAULT_QUERY_LIMIT, entityQueryResultSchema, entityQuerySchema, entityQuerySchemas, entityRecordSchema, FILTER_OPERATORS, MANY_QUANTIFIERS, MAX_IN_VALUES, MAX_QUERY_LIMIT, OrderBy, Query, queryFields, queryJsonSchema, queryLinks, QueryResult, queryResultJsonSchema, queryResultSchema, SortDirection, WHERE_COMBINATORS, } from "./query.js";
 // The SQL runtime: data access, the action pipeline, generated actions, history and principals.
@@ -31,9 +32,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, AGENT_HOST_VARIABLE, 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