@segmentstream-cloud/ontology 0.13.0 → 0.15.0

package/dist/service/authentication.d.ts

@@ -6,6 +6,7 @@ import type { Principal } from "../runtime.js";
 import type { NeonAuthEnvironment } from "./config.js";
 import { RequestId } from "./errors.js";
 import { OntologyBackend, type SignInIdentity } from "./runtime-contract.js";
+import { type RuntimeCredential, type RuntimeTokenVerifier } from "./runtime-identity.js";
 declare const CurrentPrincipal_base: Context.ServiceClass<CurrentPrincipal, "@segmentstream-cloud/ontology/CurrentPrincipal", Principal>;
 /** The principal the request runs as, provided by {@link Authentication}. */
 export declare class CurrentPrincipal extends CurrentPrincipal_base {
@@ -23,9 +24,10 @@ declare const Authentication_base: HttpApiMiddleware.ServiceClass<Authentication
     readonly bearer: HttpApiSecurity.Http;
 }, CurrentPrincipal, readonly [import("effect/Schema").Top, import("effect/Schema").Top, import("effect/Schema").Top], RequestId>>;
 /**
- * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * or an API key, all as `Authorization: Bearer …`; without one, the app's Neon Auth session cookie.
- * Failures answer the request directly, before its input is decoded.
+ * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token,
+ * an API key or the deployment's runtime token acting as a member, all as `Authorization: Bearer …`;
+ * without one, the app's Neon Auth session cookie. Failures answer the request directly, before its
+ * input is decoded.
  */
 export declare class Authentication extends Authentication_base {
 }
@@ -115,6 +117,9 @@ type Authenticated = {
     readonly status: "rejected";
 } | {
     readonly status: "not_invited";
+} | {
+    readonly status: "forbidden";
+    readonly detail: string;
 } | {
     readonly status: "unavailable";
 };
@@ -125,6 +130,11 @@ export interface CredentialOptions {
      * an access token is rejected, as it was issued for the MCP server only.
      */
     readonly oauthResource?: string;
+    /**
+     * The deployment's own runtime token may authenticate here, acting as the member it names. Without
+     * it a runtime token is just an invalid token.
+     */
+    readonly runtime?: RuntimeCredential;
 }
 /** Resolves a bearer credential to a principal. */
 export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, options?: CredentialOptions): Effect.Effect<Authenticated, never, OntologyBackend>;
@@ -147,7 +157,8 @@ export declare function withPrincipal<E, R>(credential: Redacted.Redacted<string
 }): Effect.Effect<HttpServerResponse.HttpServerResponse, E, Exclude<R, CurrentPrincipal> | RequestId>;
 /**
  * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
- * a request without a bearer token may authenticate with the app's Neon Auth session cookie.
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie; with
+ * `verifyRuntime`, the deployment's own runtime token may act as the member it names.
  */
-export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange): Layer.Layer<Authentication, never, OntologyBackend>;
+export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange, verifyRuntime?: RuntimeTokenVerifier): Layer.Layer<Authentication, never, OntologyBackend>;
 export {};

package/dist/service/authentication.js

@@ -3,9 +3,10 @@ import { HttpServerRequest } from "effect/unstable/http";
 import { HttpApiMiddleware, HttpApiSecurity, OpenApi } from "effect/unstable/httpapi";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify, } from "jose";
 import { API_KEY_PREFIX } from "../runtime/principals.js";
-import { RequestId, crossOriginSession, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { RequestId, crossOriginSession, forbidden, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
 import { ACCESS_TOKEN_PREFIX, principalOfAccessToken } from "./oauth/protocol.js";
 import { OntologyBackend } from "./runtime-contract.js";
+import { ACT_AS_HEADER, logRuntimeRejection, runtimeCredential, } from "./runtime-identity.js";
 import { ErrorSchemas } from "./schemas.js";
 const CLOCK_TOLERANCE_SECONDS = 5;
 const JWKS_TIMEOUT_MS = 5_000;
@@ -13,9 +14,10 @@ const JWKS_TIMEOUT_MS = 5_000;
 export class CurrentPrincipal extends Context.Service()("@segmentstream-cloud/ontology/CurrentPrincipal") {
 }
 /**
- * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * or an API key, all as `Authorization: Bearer …`; without one, the app's Neon Auth session cookie.
- * Failures answer the request directly, before its input is decoded.
+ * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token,
+ * an API key or the deployment's runtime token acting as a member, all as `Authorization: Bearer …`;
+ * without one, the app's Neon Auth session cookie. Failures answer the request directly, before its
+ * input is decoded.
  */
 export class Authentication extends HttpApiMiddleware.Service()("@segmentstream-cloud/ontology/Authentication", {
     security: {
@@ -274,6 +276,29 @@ function sessionMayAuthenticate(request) {
     const origin = request.headers.origin;
     return origin !== undefined && origin === requestOrigin(request);
 }
+/**
+ * The member a verified runtime caller acts for: the member `X-SegmentStream-Act-As` names, with the
+ * roles they hold now, while they are active and paired with the agent. Without the header, the
+ * runtime may call only the agent's own routes, which authenticate it themselves.
+ */
+function actingMember(actAs) {
+    return Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        if (actAs === undefined) {
+            return {
+                status: "forbidden",
+                detail: `The app's agent names the member it acts for in ${ACT_AS_HEADER}.`,
+            };
+        }
+        const member = backend.agents === undefined ? undefined : yield* backend.agents.actingMember(actAs);
+        return member === undefined
+            ? {
+                status: "forbidden",
+                detail: "The member is inactive or has not paired with the app's agent.",
+            }
+            : { status: "authenticated", principal: member };
+    });
+}
 /** Resolves a bearer credential to a principal. */
 export function authenticate(credential, verifyToken, options = {}) {
     return Effect.gen(function* () {
@@ -296,6 +321,21 @@ export function authenticate(credential, verifyToken, options = {}) {
                 ? { status: "rejected" }
                 : { status: "authenticated", principal: service };
         }
+        if (options.runtime !== undefined) {
+            const { verify, actAs } = options.runtime;
+            const runtime = yield* Effect.promise(() => verify(token));
+            switch (runtime.status) {
+                case "valid":
+                    return yield* actingMember(actAs);
+                case "invalid":
+                    yield* logRuntimeRejection(runtime.reason);
+                    return { status: "rejected" };
+                case "unavailable":
+                    return { status: "unavailable" };
+                case "other":
+                    break;
+            }
+        }
         const verification = yield* Effect.promise(() => verifyToken(token));
         if (verification.status !== "valid") {
             return verification.status === "invalid"
@@ -358,6 +398,8 @@ export function withPrincipal(credential, verifyToken, backend, effect, options
                 return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked.", options.challenge?.(false)));
             case "not_invited":
                 return toServerResponse(notInvited(requestId));
+            case "forbidden":
+                return toServerResponse(forbidden(requestId, outcome.detail));
             case "cross_origin":
                 return toServerResponse(crossOriginSession(requestId));
             case "unavailable":
@@ -369,16 +411,19 @@ export function withPrincipal(credential, verifyToken, backend, effect, options
 }
 /**
  * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
- * a request without a bearer token may authenticate with the app's Neon Auth session cookie.
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie; with
+ * `verifyRuntime`, the deployment's own runtime token may act as the member it names.
  */
-export function authenticationLayer(verifyToken, exchangeSession) {
+export function authenticationLayer(verifyToken, exchangeSession, verifyRuntime) {
     return Layer.effect(Authentication, Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         return Authentication.of({
             bearer: (httpEffect, { credential }) => Effect.gen(function* () {
                 const request = yield* HttpServerRequest.HttpServerRequest;
+                const runtime = runtimeCredential(verifyRuntime, request);
                 return yield* withPrincipal(credential, verifyToken, backend, httpEffect, {
                     session: { request, exchange: exchangeSession },
+                    ...(runtime === undefined ? {} : { runtime }),
                 });
             }),
         });

package/dist/service/config.d.ts

@@ -3,6 +3,7 @@ import { BlobStorageBinding } from "../storage/provider.js";
 import type { Principal } from "../runtime.js";
 import { type ConnectionTransportFactory, type LocalConnectionContext } from "./connections.js";
 import type { OntologyServiceRuntime } from "./runtime-contract.js";
+import type { RuntimeIdentityConfig } from "./runtime-identity.js";
 /** The environment of the workspace deployment's ontology service. */
 export declare const ENVIRONMENT_VARIABLES: {
     readonly databaseUrl: "SEGMENTSTREAM_ONTOLOGY_DATABASE_URL";
@@ -25,6 +26,22 @@ export declare const NEON_AUTH_ENVIRONMENT_VARIABLES: {
     readonly baseUrl: "NEON_AUTH_BASE_URL";
     readonly jwksUrl: "NEON_AUTH_JWKS_URL";
 };
+/**
+ * The deployment's own runtime callers, such as the app's agent: the issuer and the audience of the
+ * team's Vercel OIDC tokens, set together by the platform on deployments that have an agent. Without
+ * them a runtime token is an invalid token. Tokens must also name the project in Vercel's
+ * `VERCEL_PROJECT_ID`, as the agent runs in the same Vercel project as the ontology service.
+ */
+export declare const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES: {
+    readonly issuer: "SEGMENTSTREAM_RUNTIME_OIDC_ISSUER";
+    readonly audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE";
+    readonly projectId: "VERCEL_PROJECT_ID";
+};
+/**
+ * The project's production domain, which Vercel sets: the agent of a deployment with runtime identity
+ * takes the messages of `agent_chat.send_message` there.
+ */
+export declare const AGENT_HOST_VARIABLE = "VERCEL_PROJECT_PRODUCTION_URL";
 /** Where the workspace's Neon Auth issues and publishes the keys of its users' tokens. */
 export interface NeonAuthEnvironment {
     /** The Auth URL, such as `https://ep-….neon.tech/ontology/auth`. Its origin is the issuer. */
@@ -51,6 +68,16 @@ export interface OntologyEnvironment {
     readonly appCredential?: Redacted.Redacted<string>;
     /** Present once the workspace has Neon Auth: members then sign in with its tokens. */
     readonly neonAuth?: NeonAuthEnvironment;
+    /**
+     * Present on deployments with a runtime caller: the deployment's own Vercel OIDC tokens then
+     * authenticate, acting as the member `X-SegmentStream-Act-As` names.
+     */
+    readonly runtimeIdentity?: RuntimeIdentityConfig;
+    /**
+     * The agent's origin, `https://<VERCEL_PROJECT_PRODUCTION_URL>`, set with `runtimeIdentity`:
+     * `agent_chat.send_message` hands messages to the agent there.
+     */
+    readonly agentUrl?: string;
     /**
      * The local grant `segmentstream exec --connection …` passed, in development. Without it, actions
      * call connections through SegmentStream with the deployment's Vercel OIDC token.
@@ -99,8 +126,8 @@ export declare class OntologyServiceConfigError extends OntologyServiceConfigErr
 /**
  * Reads the service's configuration from the environment. It fails closed: a missing or invalid
  * variable throws {@link OntologyServiceConfigError} naming every missing variable, and never the
- * value of the database URL. The Neon Auth variables are optional, but only as a pair. The app
- * credential is optional and kept redacted.
+ * value of the database URL. The Neon Auth and runtime identity variables are optional, but only as
+ * pairs. The app credential is optional and kept redacted.
  */
 export declare function configFromEnv(environment?: Readonly<Record<string, string | undefined>>): OntologyEnvironment;
 export {};

package/dist/service/config.js

@@ -23,6 +23,22 @@ export const NEON_AUTH_ENVIRONMENT_VARIABLES = {
     baseUrl: "NEON_AUTH_BASE_URL",
     jwksUrl: "NEON_AUTH_JWKS_URL",
 };
+/**
+ * The deployment's own runtime callers, such as the app's agent: the issuer and the audience of the
+ * team's Vercel OIDC tokens, set together by the platform on deployments that have an agent. Without
+ * them a runtime token is an invalid token. Tokens must also name the project in Vercel's
+ * `VERCEL_PROJECT_ID`, as the agent runs in the same Vercel project as the ontology service.
+ */
+export const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES = {
+    issuer: "SEGMENTSTREAM_RUNTIME_OIDC_ISSUER",
+    audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE",
+    projectId: "VERCEL_PROJECT_ID",
+};
+/**
+ * The project's production domain, which Vercel sets: the agent of a deployment with runtime identity
+ * takes the messages of `agent_chat.send_message` there.
+ */
+export const AGENT_HOST_VARIABLE = "VERCEL_PROJECT_PRODUCTION_URL";
 /** The service cannot start: its configuration is incomplete or invalid. */
 export class OntologyServiceConfigError extends Schema.TaggedError()("OntologyServiceConfigError", { message: Schema.String }) {
 }
@@ -60,6 +76,35 @@ function neonAuthFromEnv(read) {
         jwksUrl: httpUrl(NEON_AUTH_ENVIRONMENT_VARIABLES.jwksUrl, read(NEON_AUTH_ENVIRONMENT_VARIABLES.jwksUrl)).href,
     };
 }
+/**
+ * The runtime issuer and audience, both or neither, and the project the tokens must name. A partial
+ * configuration is a broken deployment, so the service refuses to start rather than run without the
+ * agent's identity, or trust tokens of every project of the team.
+ */
+function runtimeIdentityFromEnv(read) {
+    const { issuer, audience, projectId } = RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES;
+    const pair = [issuer, audience];
+    const missingPair = pair.filter((name) => read(name) === "");
+    if (missingPair.length === pair.length) {
+        return undefined;
+    }
+    if (missingPair.length > 0) {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${pair.join(" and ")} are set together; ` +
+                `${missingPair.join(", ")} is not set.`,
+        });
+    }
+    if (read(projectId) === "") {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${projectId} is not set, which runtime tokens must name.`,
+        });
+    }
+    return {
+        issuer: httpUrl(issuer, read(issuer)).href.replace(/\/+$/, ""),
+        audience: read(audience),
+        projectId: read(projectId),
+    };
+}
 function checkDatabaseUrl(name, value) {
     // The value is a credential: errors name the variable, never the value.
     if (!URL.canParse(value)) {
@@ -76,8 +121,8 @@ function checkDatabaseUrl(name, value) {
 /**
  * Reads the service's configuration from the environment. It fails closed: a missing or invalid
  * variable throws {@link OntologyServiceConfigError} naming every missing variable, and never the
- * value of the database URL. The Neon Auth variables are optional, but only as a pair. The app
- * credential is optional and kept redacted.
+ * value of the database URL. The Neon Auth and runtime identity variables are optional, but only as
+ * pairs. The app credential is optional and kept redacted.
  */
 export function configFromEnv(environment = process.env) {
     const read = (name) => environment[name]?.trim() ?? "";
@@ -90,6 +135,7 @@ export function configFromEnv(environment = process.env) {
         });
     }
     const neonAuth = neonAuthFromEnv(read);
+    const runtimeIdentity = runtimeIdentityFromEnv(read);
     const localConnections = localConnectionsFromEnv(environment);
     let blobStorage;
     if (read("SEGMENTSTREAM_ONTOLOGY_STORAGE")) {
@@ -118,6 +164,10 @@ export function configFromEnv(environment = process.env) {
             ? { appCredential: Redacted.make(read(APP_CREDENTIAL_VARIABLE)) }
             : {}),
         ...(neonAuth === undefined ? {} : { neonAuth }),
+        ...(runtimeIdentity === undefined ? {} : { runtimeIdentity }),
+        ...(runtimeIdentity === undefined || read(AGENT_HOST_VARIABLE) === ""
+            ? {}
+            : { agentUrl: normalizeUrl(AGENT_HOST_VARIABLE, `https://${read(AGENT_HOST_VARIABLE)}`) }),
         ...(localConnections === undefined ? {} : { localConnections }),
     };
 }

package/dist/service/errors.d.ts

@@ -92,6 +92,12 @@ export declare function notInvited(requestId: string): ErrorResponse;
  * The cookie rides along with any request to the app's domain, so only its origin can vouch for it.
  */
 export declare function crossOriginSession(requestId: string): ErrorResponse;
+/** The caller is authenticated but may not do this; the detail says why. */
+export declare function forbidden(requestId: string, detail: string): ErrorResponse;
+/** A client asked too often; it may ask again after `retryAfterSeconds`. */
+export declare function rateLimited(requestId: string, detail: string, retryAfterSeconds: number): ErrorResponse;
+/** The resource does not exist, or not for this caller; the detail says what to do. */
+export declare function notFound(requestId: string, detail: string): ErrorResponse;
 export declare function unavailable(requestId: string): ErrorResponse;
 export declare function internalError(requestId: string): ErrorResponse;
 export declare function routeNotFound(requestId: string): ErrorResponse;

package/dist/service/errors.js

@@ -129,6 +129,22 @@ export function crossOriginSession(requestId) {
         },
     };
 }
+/** The caller is authenticated but may not do this; the detail says why. */
+export function forbidden(requestId, detail) {
+    return { status: 403, body: { error: "forbidden", detail, requestId } };
+}
+/** A client asked too often; it may ask again after `retryAfterSeconds`. */
+export function rateLimited(requestId, detail, retryAfterSeconds) {
+    return {
+        status: 429,
+        body: { error: "rate_limited", detail, requestId },
+        headers: { "retry-after": String(retryAfterSeconds) },
+    };
+}
+/** The resource does not exist, or not for this caller; the detail says what to do. */
+export function notFound(requestId, detail) {
+    return { status: 404, body: { error: "not_found", detail, requestId } };
+}
 export function unavailable(requestId) {
     return {
         status: 503,

package/dist/service/handlers.d.ts

@@ -4,6 +4,7 @@ import type { Aggregates } from "./aggregate.js";
 import { type BuiltApi } from "./api.js";
 import type { AfterCommitHook } from "./config.js";
 import type { ReplicationKick } from "./replication.js";
+import type { AgentChannelFactory } from "./agent/channel.js";
 import type { ConnectionTransportFactory } from "./connections.js";
 import { type RateLimit } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
@@ -13,4 +14,4 @@ import { OntologyBackend } from "./runtime-contract.js";
  */
 export declare const SIGN_IN_CHECK_LIMIT: RateLimit;
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, aggregates: Aggregates): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;
+export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, aggregates: Aggregates, agentChannel: AgentChannelFactory | undefined): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;

package/dist/service/handlers.js

@@ -216,8 +216,8 @@ function storageHandlers(built) {
     }));
 }
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export function handlersLayer(built, hooks, connections, replicate, aggregates) {
-    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate);
+export function handlersLayer(built, hooks, connections, replicate, aggregates, agentChannel) {
+    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate, agentChannel);
     const layers = [
         serviceHandlers(built, operationsOf, aggregates.model),
         ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))

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

@@ -4,10 +4,12 @@ import type { Aggregates } from "../aggregate.js";
 import type { BuiltApi } from "../api.js";
 import { type TokenVerifier } from "../authentication.js";
 import type { AfterCommitHook } from "../config.js";
+import type { AgentChannelFactory } from "../agent/channel.js";
 import type { ConnectionTransportFactory } from "../connections.js";
 import { RequestId } from "../errors.js";
 import type { ReplicationKick } from "../replication.js";
 import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
 export declare const MCP_PATH = "/mcp";
 /** The MCP revisions the server speaks, newest first. */
@@ -18,8 +20,12 @@ export interface McpServerOptions {
     readonly connections: ConnectionTransportFactory;
     readonly replicate: ReplicationKick;
     readonly verifyToken: TokenVerifier;
+    /** The deployment's runtime tokens, acting as a member; `undefined` while that is disabled. */
+    readonly verifyRuntime?: RuntimeTokenVerifier | undefined;
     /** The facade the aggregate routes run; the aggregate tool runs its model-level aggregate. */
     readonly aggregates: Aggregates;
+    /** The workspace's agent, for `agent_chat.send_message`; `undefined` without one. */
+    readonly agentChannel?: AgentChannelFactory | undefined;
 }
 /**
  * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can

package/dist/service/mcp/server.js

@@ -12,6 +12,7 @@ import { publicOrigin } from "../oauth/protocol.js";
 import { mcpChallenge, mcpResource } from "../oauth/server.js";
 import { identityToken, makeOperations, toQuery } from "../operations.js";
 import { OntologyBackend } from "../runtime-contract.js";
+import { runtimeCredential } from "../runtime-identity.js";
 import { ActionResponse, HistoryPage, HistoryParams, IdParam, Me, } from "../schemas.js";
 import { mcpTools, visibleTools } from "./tools.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
@@ -346,7 +347,7 @@ function crossOrigin(request) {
     return !URL.canParse(origin) || new URL(origin).host !== new URL(publicOrigin(request)).host;
 }
 /** `POST /mcp`: one JSON-RPC message in, one JSON response out, nothing kept between requests. */
-function handlePost(server, verifyToken, backend) {
+function handlePost(server, verifyToken, verifyRuntime, backend) {
     const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
     return (request) => Effect.gen(function* () {
         const requestId = yield* RequestId;
@@ -389,14 +390,18 @@ function handlePost(server, verifyToken, backend) {
             }
         });
         const origin = publicOrigin(request);
+        const runtime = runtimeCredential(verifyRuntime, request);
         // With the OAuth tables, members' access tokens work here, and a 401 tells the client where
-        // the member authorizes it.
-        return yield* withPrincipal(yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request), verifyToken, backend, answer, backend.oauth === undefined
-            ? {}
-            : {
-                oauthResource: mcpResource(origin),
-                challenge: (missing) => mcpChallenge(origin, missing),
-            });
+        // the member authorizes it. The app's agent calls as the member it names.
+        return yield* withPrincipal(yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request), verifyToken, backend, answer, {
+            ...(runtime === undefined ? {} : { runtime }),
+            ...(backend.oauth === undefined
+                ? {}
+                : {
+                    oauthResource: mcpResource(origin),
+                    challenge: (missing) => mcpChallenge(origin, missing),
+                }),
+        });
     });
 }
 /**
@@ -412,10 +417,10 @@ export function mcpLayer(options) {
         const server = {
             built: options.built,
             tools,
-            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate),
+            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate, options.agentChannel),
             aggregate: options.aggregates.model,
         };
-        yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, backend));
+        yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, options.verifyRuntime, backend));
         yield* router.add("GET", MCP_PATH, METHOD_NOT_ALLOWED);
         yield* router.add("DELETE", MCP_PATH, METHOD_NOT_ALLOWED);
     }));

package/dist/service/operations.d.ts

@@ -5,6 +5,7 @@ import type { Query, QueryResult } from "../query.js";
 import { CurrentPrincipal } from "./authentication.js";
 import type { AfterCommitHook } from "./config.js";
 import type { ReplicationKick } from "./replication.js";
+import type { AgentChannelFactory } from "./agent/channel.js";
 import { type ConnectionTransportFactory } from "./connections.js";
 import { InvalidActionInput, RequestId } from "./errors.js";
 import type { ApiPlan, PlannedAction, PlannedEntity, Traversal } from "./plan.js";
@@ -59,8 +60,11 @@ export interface Caller {
     readonly permissions: ReadonlyArray<string>;
 }
 type Backend = OntologyBackend["Service"];
-/** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick): {
+/**
+ * The operations of a planned ontology, bound to its backend, after-commit hooks, connections and,
+ * on deployments with one, the workspace's agent.
+ */
+export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, agentChannel?: AgentChannelFactory): {
     /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
     find: (planned: PlannedEntity, query: Query) => Effect.Effect<QueryResult<Readonly<Record<string, unknown>>>, PermissionDenied | import("../index.js").InvalidQuery, CurrentPrincipal>;
     /** One record. Requires `read` on the entity. */

package/dist/service/operations.js

@@ -6,6 +6,7 @@ import { PermissionDenied } from "../errors.js";
 import { toCamelCase } from "../names.js";
 import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
 import { CurrentPrincipal } from "./authentication.js";
+import { AgentChannel } from "../agent-chat.js";
 import { OIDC_TOKEN_HEADER } from "./connections.js";
 import { InvalidActionInput, RequestId } from "./errors.js";
 /**
@@ -145,12 +146,12 @@ function traverseOf(backend, targets, planned, traversal, id, query) {
         return page(yield* backend.find({ entity: traversal.target, query: { ...query, where } }));
     });
 }
-function runActionOf(backend, ontology, hooks, connections, replicate) {
+function runActionOf(backend, ontology, hooks, connections, replicate, agentChannel) {
     return (planned, { name, generated }, call) => Effect.gen(function* () {
         const principal = yield* CurrentPrincipal;
         const requestId = yield* RequestId;
         const hook = hooks.get(`${planned.name}.${name}`);
-        const outcome = yield* backend.runAction({
+        const run = backend.runAction({
             entity: planned.name,
             action: name,
             input: call.input,
@@ -175,6 +176,10 @@ function runActionOf(backend, ontology, hooks, connections, replicate) {
                 }
                 : {}),
         });
+        // Built-in actions reach the workspace's agent through it, when the deployment has one.
+        const outcome = yield* agentChannel === undefined
+            ? run
+            : run.pipe(Effect.provideService(AgentChannel, agentChannel({ identityToken: call.identityToken, store: backend.agents })));
         const { issues } = outcome.validation;
         if (!outcome.validation.ok && !call.validateOnly) {
             return yield* new InvalidActionInput({ issues });
@@ -208,8 +213,11 @@ function callerOf(backend) {
         };
     });
 }
-/** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export function makeOperations(backend, plan, hooks, connections, replicate) {
+/**
+ * The operations of a planned ontology, bound to its backend, after-commit hooks, connections and,
+ * on deployments with one, the workspace's agent.
+ */
+export function makeOperations(backend, plan, hooks, connections, replicate, agentChannel) {
     const targets = relationshipTargets(plan);
     return {
         /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
@@ -221,7 +229,7 @@ export function makeOperations(backend, plan, hooks, connections, replicate) {
         /** The records a relationship reaches from one record, as a page of the target entity. */
         traverse: (planned, traversal, id, query) => traverseOf(backend, targets, planned, traversal, id, query),
         /** Runs an action as the caller, with the action's after-commit hook and connections. */
-        runAction: runActionOf(backend, plan.ontology, hooks, connections, replicate),
+        runAction: runActionOf(backend, plan.ontology, hooks, connections, replicate, agentChannel),
         /** The caller's user, roles and permissions. It needs no permission. */
         caller: callerOf(backend),
     };

package/dist/service/runtime-contract.d.ts

@@ -153,6 +153,98 @@ export interface OAuthStore {
     /** The member a grant acts for, with the roles they hold now; undefined once they may not sign in. */
     readonly memberPrincipal: (userId: string) => Effect.Effect<Principal | undefined>;
 }
+/** A channel account waiting, for ten minutes, for a member to claim it with its pairing code. */
+export interface AgentPairing {
+    readonly id: string;
+    /** The channel, such as `telegram`. */
+    readonly provider: string;
+    /** The account's id on the channel. */
+    readonly externalId: string;
+    /** How the channel names the account, shown on the connect page. */
+    readonly display: string | null;
+    readonly expiresAt: Date;
+}
+/** A channel account paired with a member: the app's agent acts as the member for its messages. */
+export interface AgentIdentity {
+    readonly id: string;
+    readonly provider: string;
+    readonly externalId: string;
+    readonly userId: string;
+    readonly display: string | null;
+    readonly createdAt: Date;
+    /** When the identity stopped working; null while it is live. */
+    readonly revokedAt: Date | null;
+}
+/** A member as the agent names them: their user's name and the roles they hold now. */
+export interface AgentMember {
+    readonly name: string;
+    readonly principal: Principal;
+}
+/** A group chat the agent saw, as `POST /api/ontology/agent/chats/seen` answers. */
+export interface SeenChat {
+    readonly id: string;
+    readonly title: string;
+    readonly purpose: string | null;
+    readonly whenToUse: string | null;
+}
+/**
+ * Where the app's agent keeps pairing codes and the identities they create: the runtime's agent
+ * tables in the workspace database. Codes are stored only as SHA-256 hashes. Expiry is checked
+ * against the database's clock; failures are defects.
+ */
+export interface AgentStore {
+    /** Stores a pairing under its code's hash and forgets expired ones; false when the hash is taken. */
+    readonly savePairing: (pairing: AgentPairing & {
+        readonly codeHash: string;
+    }) => Effect.Effect<boolean>;
+    /** A pairing that has neither expired nor been approved. */
+    readonly findPairing: (codeHash: string) => Effect.Effect<AgentPairing | undefined>;
+    /**
+     * Consumes a live pairing, once, and pairs its account with the member. The account's previous
+     * identity and the member's previous identity on the same provider are revoked: each has one live
+     * identity per provider. `undefined` when the pairing expired or was already approved.
+     */
+    readonly approvePairing: (input: {
+        readonly codeHash: string;
+        readonly userId: string;
+        readonly identityId: string;
+    }) => Effect.Effect<AgentIdentity | undefined>;
+    /** The account's live identity, else its latest revoked one, else `undefined`. */
+    readonly findIdentity: (input: {
+        readonly provider: string;
+        readonly externalId: string;
+    }) => Effect.Effect<AgentIdentity | undefined>;
+    /** The member's live identities, oldest first. */
+    readonly listIdentities: (userId: string) => Effect.Effect<ReadonlyArray<AgentIdentity>>;
+    /** Revokes one of the member's live identities; false when they have no such identity. */
+    readonly revokeIdentity: (input: {
+        readonly id: string;
+        readonly userId: string;
+    }) => Effect.Effect<boolean>;
+    /** An active member by user id; `undefined` for an unknown user, a service or an inactive member. */
+    readonly member: (userId: string) => Effect.Effect<AgentMember | undefined>;
+    /** The member a runtime caller acts for: active, and with a live identity. */
+    readonly actingMember: (userId: string) => Effect.Effect<Principal | undefined>;
+    /**
+     * Records a message the agent saw in a group chat: creates the `agent_chat` or keeps its title
+     * current, records when the chat last had a message (at most every 15 minutes, so that history
+     * keeps it without a row per message), links the writer to its members when they are an active
+     * member, and unlinks `leftMemberId`, a member who left, when linked. With `agentLeft`, the agent
+     * itself left the chat: every member is unlinked, and the chat stays. With `migratedFrom`, the
+     * chat had that id before it became a supergroup: its record moves to `externalId`, or, when both
+     * ids have one, the new record takes the old one's members, and its purpose and when to use where
+     * it has none. Concurrent calls for one chat leave one record.
+     */
+    readonly seeChat: (input: {
+        readonly provider: string;
+        readonly externalId: string;
+        readonly title: string;
+        readonly memberId?: string;
+        readonly leftMemberId?: string;
+        readonly agentLeft?: true;
+        readonly migratedFrom?: string;
+    }) => Effect.Effect<SeenChat>;
+}
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
     readonly blobs?: BlobRuntime;
     readonly maintainBlobs?: Effect.Effect<{
@@ -192,6 +284,8 @@ declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segm
     readonly replicationEnabled?: Effect.Effect<boolean>;
     /** The OAuth tables, for members who connect agents; without it, agents use API keys. */
     readonly oauth?: OAuthStore;
+    /** The agent tables, which pair channel accounts with members for the app's own agent. */
+    readonly agents?: AgentStore;
 }>;
 /**
  * The runtime as the HTTP service sees it, with its database and ontology already bound. Failures