@segmentstream-cloud/ontology 0.14.0 → 0.15.0

package/README.md

@@ -143,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 })`.
@@ -162,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
@@ -216,6 +219,7 @@ one is missing or invalid, and never repeats the database URL.
 | `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 and the runtime pair on deployments with an agent. With the runtime
@@ -268,14 +272,15 @@ The agent acts for a member by adding `X-SegmentStream-Act-As: <user id>` on any
 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                                             |
+| 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
@@ -286,6 +291,26 @@ agent, even acting as a member, so only members pair. Pairings and identities li
 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,10 +54,10 @@ 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, RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES, } 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 { AgentIdentity, AgentMember, AgentPairing, AgentStore, 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";

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,7 +32,7 @@ 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, RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES, } 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.

package/dist/permissions.d.ts

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