@segmentstream-cloud/ontology 0.13.0 → 0.15.0

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/runtime/service-binding.js

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

package/dist/service/agent/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

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

package/dist/service/agent/protocol.js

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

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

@@ -0,0 +1,28 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type SessionExchange, type TokenVerifier } from "../authentication.js";
+import { RequestId } from "../errors.js";
+import { type RateLimit } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+/** The agent's endpoints, under the ontology service's path. */
+export declare const AGENT_PATH = "/api/ontology/agent";
+/**
+ * Pairings one client address may start per minute; each one is a row in the database. The agent's
+ * functions share a few egress addresses, so the limit leaves room for a busy channel.
+ */
+export declare const PAIRING_LIMIT: RateLimit;
+export interface AgentServerOptions {
+    readonly verifyToken: TokenVerifier;
+    /** The deployment's runtime tokens; `undefined` while runtime authentication is disabled. */
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+    readonly exchangeSession: SessionExchange | undefined;
+}
+/**
+ * The routes that pair channel accounts with members for the app's own agent, 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.
+ */
+export declare function agentLayer(options: AgentServerOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

package/dist/service/agent/server.js

@@ -0,0 +1,257 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Layer, Redacted, Result, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { schemaIssues } from "../../runtime/validation.js";
+import { BASE_PATH } from "../api.js";
+import { CurrentPrincipal, withPrincipal, } from "../authentication.js";
+import { RequestId, errorBodyForWire, forbidden, notFound, rateLimited, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+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 { 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.
+ */
+export const PAIRING_LIMIT = { limit: 60, windowMs: 60_000, maxKeys: 10_000 };
+/** A fresh code collides with a live one about never; a few attempts make it never in practice. */
+const CODE_ATTEMPTS = 3;
+const NO_STORE = { "cache-control": "no-store" };
+function json(body, status = 200) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: NO_STORE });
+}
+function jsonBody(request) {
+    return Effect.map(Effect.orDie(request.text), (text) => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+function invalidBody(requestId, issues) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "invalid_request",
+        detail: "The request body is invalid.",
+        requestId,
+        issues,
+    }), { status: 400 });
+}
+function pairingNotFound(requestId) {
+    return toServerResponse(notFound(requestId, "The pairing code expired or was already used. Send the agent a message for a new link."));
+}
+function routeParam(name) {
+    return Effect.map(HttpRouter.params, (params) => params[name] ?? "");
+}
+/**
+ * `POST /api/ontology/agent/pairings` (runtime): a sender the agent does not know gets a short code
+ * that a signed-in member approves on the app's connect page. Only the code's hash is stored.
+ */
+function createPairing(store, limiter) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const retryAfter = limiter.take(clientAddress(request));
+        if (retryAfter !== undefined) {
+            return toServerResponse(rateLimited(requestId, "Too many pairings; try again in a minute.", retryAfter));
+        }
+        const body = yield* jsonBody(request);
+        const decoded = Schema.decodeUnknownResult(PairingRequest)(body, {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        const { provider, external_id: externalId, display } = decoded.success;
+        const trimmedDisplay = display?.trim() || null;
+        for (let attempt = 0; attempt < CODE_ATTEMPTS; attempt++) {
+            const code = newPairingCode();
+            const expiresAt = new Date(Date.now() + PAIRING_TTL_MS);
+            const saved = yield* store.savePairing({
+                id: randomUUID(),
+                codeHash: secretHash(code),
+                provider,
+                externalId,
+                display: trimmedDisplay,
+                expiresAt,
+            });
+            if (saved) {
+                return json({ code, expires_at: expiresAt.toISOString() }, 201);
+            }
+        }
+        return yield* Effect.die(new Error("No free pairing code after several attempts."));
+    });
+}
+/** `GET /api/ontology/agent/pairings/:code` (member): what the connect page shows. */
+function describePairing(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const pairing = code === undefined ? undefined : yield* store.findPairing(secretHash(code));
+        if (pairing === undefined) {
+            return pairingNotFound(requestId);
+        }
+        return json({
+            provider: pairing.provider,
+            display: pairing.display,
+            expires_at: pairing.expiresAt.toISOString(),
+        });
+    });
+}
+/**
+ * `POST /api/ontology/agent/pairings/:code/approve` (member): pairs the account with the signed-in
+ * member, once. The account's previous identity and the member's previous identity on the same
+ * channel stop working: each has one live identity per channel, so an approval tricked out of a
+ * member displaces their own account, which they notice.
+ */
+function approvePairing(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const identity = code === undefined
+            ? undefined
+            : yield* store.approvePairing({
+                codeHash: secretHash(code),
+                userId: member.id,
+                identityId: randomUUID(),
+            });
+        if (identity === undefined) {
+            return pairingNotFound(requestId);
+        }
+        yield* Effect.logInfo("ontology.agent.paired").pipe(Effect.annotateLogs({ identityId: identity.id, provider: identity.provider, requestId }));
+        return json({ identity: identityForWire(identity) });
+    });
+}
+/**
+ * `GET /api/ontology/agent/identities/:provider/:external_id` (runtime): the member an account acts
+ * as, with the roles they hold now. 404 for an account nobody paired; 403 once its identity was
+ * revoked or its member deactivated.
+ */
+function resolveIdentity(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const provider = yield* routeParam("provider");
+        const externalId = yield* routeParam("external_id");
+        const identity = yield* store.findIdentity({ provider, externalId });
+        if (identity === undefined) {
+            return toServerResponse(notFound(requestId, "No member paired this account."));
+        }
+        if (identity.revokedAt !== null) {
+            return toServerResponse(forbidden(requestId, "The account's pairing was revoked."));
+        }
+        const member = yield* store.member(identity.userId);
+        if (member === undefined) {
+            return toServerResponse(forbidden(requestId, "The member is inactive."));
+        }
+        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* () {
+        const identities = yield* store.listIdentities(member.id);
+        return json({ identities: identities.map(identityForWire) });
+    });
+}
+/** `DELETE /api/ontology/agent/identities/:id` (member): revokes one of the member's identities. */
+function revokeIdentity(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const id = yield* routeParam("id");
+        const revoked = yield* store.revokeIdentity({ id, userId: member.id });
+        if (!revoked) {
+            return toServerResponse(notFound(requestId, "You have no such identity."));
+        }
+        yield* Effect.logInfo("ontology.agent.unpaired").pipe(Effect.annotateLogs({ identityId: id, requestId }));
+        return HttpServerResponse.empty({ status: 204, headers: NO_STORE });
+    });
+}
+/**
+ * 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.
+ */
+export function agentLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const store = backend.agents;
+        if (store === undefined) {
+            return;
+        }
+        const limiter = fixedWindowLimiter(PAIRING_LIMIT);
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        const bearerOf = (request) => Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+        const asRuntime = (answer) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* bearerOf(request);
+            const token = Redacted.value(bearer);
+            const verified = options.verifyRuntime === undefined || token === ""
+                ? undefined
+                : yield* Effect.promise(() => options.verifyRuntime(token));
+            switch (verified?.status) {
+                case "valid":
+                    return yield* answer(request);
+                case "invalid":
+                    yield* logRuntimeRejection(verified.reason);
+                    return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
+                case "unavailable":
+                    return toServerResponse(unavailable(requestId));
+                default:
+                    // Any other credential is authenticated as usual, so that it gets the usual 401, and
+                    // then refused: these routes are the agent's.
+                    return yield* withPrincipal(bearer, options.verifyToken, backend, Effect.succeed(toServerResponse(forbidden(requestId, "Only the app's agent calls this route."))));
+            }
+        });
+        const asMember = (answer) => (request) => Effect.gen(function* () {
+            const bearer = yield* bearerOf(request);
+            const decided = Effect.gen(function* () {
+                const requestId = yield* RequestId;
+                const principal = yield* CurrentPrincipal;
+                if (principal.kind !== "member") {
+                    return toServerResponse(forbidden(requestId, "Only a signed-in member can pair the app's agent."));
+                }
+                return yield* answer(request, principal);
+            });
+            return yield* withPrincipal(bearer, options.verifyToken, backend, decided, {
+                session: { request, exchange: options.exchangeSession },
+            });
+        });
+        yield* router.add("POST", PAIRINGS_PATH, asRuntime(createPairing(store, limiter)));
+        yield* router.add("GET", `${PAIRINGS_PATH}/:code`, asMember(() => describePairing(store)));
+        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));
     }