@segmentstream-cloud/ontology 0.12.0 → 0.14.0

package/dist/service/mcp/server.js

@@ -3,14 +3,16 @@ import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstab
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
 import { encodeManifest } from "../../manifest.js";
 import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
-import { renderCatalog } from "../../render.js";
+import { SCOPE_MISMATCH } from "../aggregate-platform.js";
 import { CurrentPrincipal, withPrincipal } from "../authentication.js";
 import { catalogFor } from "../catalog.js";
+import { describeCatalog, measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
 import { RequestId, errorBodyForWire, expectedFailure, internalError, schemaIssues, } from "../errors.js";
 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. */
@@ -79,6 +81,41 @@ function errorText(body) {
         : [];
     return `${body.detail} (${body.error}, request ${body.requestId})${issues.join("")}`;
 }
+/** SegmentStream's refusal when its deployed manifest is not the one the service checked against. */
+const VERSION_MISMATCH = "ontology_version_mismatch";
+/** What the agent reads instead of SegmentStream's detail, for refusals it must act on itself. */
+const AGENT_DETAILS = {
+    [VERSION_MISMATCH]: "The ontology changed; reload and try again: call describe for the current measures and " +
+        "names, then call aggregate with them.",
+    [SCOPE_MISMATCH]: "SegmentStream would read entities this app's ontology service did not check, so it refused. " +
+        "Retrying will not help: ask the app's operator to update @segmentstream-cloud/ontology and " +
+        "redeploy.",
+};
+/**
+ * SegmentStream's answer to an aggregate as the model reads it: the body as structured content, its
+ * warnings first in the text so they are not missed, and an error status as a tool error.
+ */
+function aggregateOutput(answer) {
+    const { body } = answer;
+    if (answer.status >= 400) {
+        const code = typeof body.error === "string" ? body.error : `HTTP ${answer.status}`;
+        const reference = typeof body.requestId === "string" ? `, request ${body.requestId}` : "";
+        const detail = AGENT_DETAILS[code] ??
+            (typeof body.detail === "string" ? body.detail : "The aggregate failed.");
+        return { text: `${detail} (${code}${reference})`, structured: body, isError: true };
+    }
+    const execution = body.execution;
+    const warnings = Array.isArray(execution?.warnings)
+        ? execution.warnings.filter((warning) => typeof warning === "string")
+        : [];
+    const json = JSON.stringify(body);
+    return {
+        text: warnings.length === 0
+            ? json
+            : `Warnings:\n${warnings.map((warning) => `- ${warning}`).join("\n")}\n\n${json}`,
+        structured: body,
+    };
+}
 /**
  * A failed tool call as the model reads it: `isError`, the REST route's error body as structured
  * content, and the same in a sentence. Unexpected failures are logged with their cause and answered
@@ -108,16 +145,21 @@ function toolFailure(cause, requestId) {
         isError: true,
     }));
 }
-function runTool({ built, operations }, tool, args, request) {
+function runTool({ built, operations, aggregate }, tool, args, request) {
     return Effect.gen(function* () {
         const { target } = tool;
         switch (target.kind) {
             case "describe": {
                 const principal = yield* CurrentPrincipal;
                 return {
-                    text: renderCatalog(built.plan.ontology.manifest, { as: principal.permissions }),
+                    text: describeCatalog(built.plan.ontology.manifest, principal.permissions),
                 };
             }
+            case "aggregate": {
+                // The route's facade, as the caller: the arguments are the request body.
+                const answer = yield* aggregate(args).pipe(Effect.catchTag("InvalidRequestBody", (error) => Effect.fail(new InvalidArguments({ issues: error.issues }))));
+                return aggregateOutput(answer);
+            }
             case "me":
                 return structured(yield* encoded(Me, yield* operations.caller));
             case "find": {
@@ -157,9 +199,10 @@ function callTool(server, params, request) {
         if (!isObject(args)) {
             return { kind: "invalid", message: "The tool's arguments must be an object." };
         }
-        const result = yield* runTool(server, tool, args, request).pipe(Effect.map(({ text, structured: content }) => ({
+        const result = yield* runTool(server, tool, args, request).pipe(Effect.map(({ text, structured: content, isError }) => ({
             content: [{ type: "text", text }],
             ...(content === undefined ? {} : { structuredContent: content }),
+            ...(isError === true ? { isError } : {}),
         })), Effect.catchCause((cause) => toolFailure(cause, requestId)));
         return { kind: "called", result };
     });
@@ -201,7 +244,7 @@ function readResource({ built }, uri) {
                     {
                         uri,
                         mimeType: "text/plain",
-                        text: renderCatalog(manifest, { as: principal.permissions }),
+                        text: describeCatalog(manifest, principal.permissions),
                     },
                 ];
             default:
@@ -210,16 +253,18 @@ function readResource({ built }, uri) {
     });
 }
 /**
- * What an agent learns when it connects: what the server is, the entities the caller may read and
- * where to find the rest.
+ * What an agent learns when it connects: what the server is, the entities the caller may read, the
+ * measures of every entity they may read, stored or warehouse-backed, and where to find the rest.
  */
 function instructions({ built }, permissions) {
+    const { manifest } = built.plan.ontology;
     const readable = built.plan.entities
         .filter(({ name, resolved }) => {
         const definition = resolved.entity.definition;
         return (definition.source === undefined && isAllowed(permissionOf(name, READ_VERB), { permissions }));
     })
         .map(({ name, resolved }) => `- ${name}: ${resolved.entity.definition.description}`);
+    const measures = measuresFor(manifest, permissions).map(({ name, measure }) => `- ${name}: ${measure.description}`);
     return [
         "This server is the app's ontology: the records the company works with and the actions " +
             "that change them. Every change goes through an action, is checked against your " +
@@ -227,7 +272,14 @@ function instructions({ built }, permissions) {
         readable.length > 0
             ? `Entities you may read, each with <entity>_find, <entity>_get and <entity>_history:\n${readable.join("\n")}`
             : "You may read no entities.",
-        "Call describe for the full catalog: properties, relationships and the actions you may run.",
+        ...(measures.length > 0
+            ? [
+                `Measures you may aggregate with the aggregate tool; ${RECORDS_OR_AGGREGATES}:\n` +
+                    measures.join("\n"),
+            ]
+            : []),
+        "Call describe for the full catalog: properties, relationships, measures and the actions " +
+            "you may run.",
     ].join("\n\n");
 }
 function negotiate(requested) {
@@ -295,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;
@@ -338,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),
+                }),
+        });
     });
 }
 /**
@@ -362,8 +418,9 @@ export function mcpLayer(options) {
             built: options.built,
             tools,
             operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate),
+            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/mcp/tools.d.ts

@@ -22,6 +22,8 @@ export type McpToolTarget = {
     readonly kind: "describe";
 } | {
     readonly kind: "me";
+} | {
+    readonly kind: "aggregate";
 };
 /** A tool of the ontology's MCP server, derived from the same plan as the HTTP routes. */
 export interface McpTool {
@@ -34,14 +36,23 @@ export interface McpTool {
     readonly annotations: McpToolAnnotations;
     /** Every permission a caller needs to see and run the tool; none for the global tools. */
     readonly permissions: ReadonlyArray<string>;
+    /**
+     * For a tool whose input depends on what the caller may read: the caller's input schema, or
+     * `undefined` when the tool can do nothing for them and is not listed. Calls are checked anyway.
+     */
+    readonly inputSchemaFor?: (caller: PermissionHolder) => JsonSchemaObject | undefined;
     readonly target: McpToolTarget;
 }
 /**
- * The MCP tools of an ontology: `describe` and `me`, then for every stored entity `find`, `get`,
+ * The MCP tools of an ontology: `describe` and `me`, `aggregate` when the ontology has measures,
+ * then for every stored entity `find`, `get`,
  * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
  * `check` already refuses.
  */
 export declare function mcpTools(built: BuiltApi): ReadonlyArray<McpTool>;
-/** The tools a caller may see: those whose every permission the caller's roles grant. */
+/**
+ * The tools a caller may see: those whose every permission the caller's roles grant, each with the
+ * caller's input schema.
+ */
 export declare function visibleTools(tools: ReadonlyArray<McpTool>, caller: PermissionHolder): ReadonlyArray<McpTool>;

package/dist/service/mcp/tools.js

@@ -1,11 +1,14 @@
 import { Schema } from "effect";
+import { AGGREGATE_NAME_PATTERN } from "../../aggregate-routes.js";
 import { InvalidOntology } from "../../diagnostics.js";
+import { isValueMatched } from "../../manifest.js";
 import { GENERATED_UPSERT_PREFIX, humanize, mcpToolName } from "../../names.js";
 import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { queryJsonSchema } from "../../query.js";
+import { measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
 import { actionDescription, requires } from "../descriptions.js";
-import { HistoryPage, Me } from "../schemas.js";
+import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, HistoryPage, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
 /**
  * A JSON Schema whose root is an object schema, as MCP requires of tool inputs and outputs: a root
@@ -94,12 +97,30 @@ function relatedHint(planned, traversal) {
                 `{"${traversal.opposite}": {"some": {"id": {"eq": "${id}"}}}}.`);
     }
 }
+/**
+ * How an agent reads the target of a value-matched relationship, which the service cannot traverse:
+ * the reference is an ordinary property, and the target lives in the warehouse.
+ */
+function matchedHints(planned) {
+    return planned.resolved.relationships.flatMap(({ name, relationship, target }) => {
+        if (relationship.cardinality !== "one" || !isValueMatched(relationship)) {
+            return [];
+        }
+        const property = Object.keys(relationship.on ?? {})[0] ?? "";
+        return [
+            `${name} is matched on ${property}; read ${target ?? "it"} through the workspace aggregates.`,
+        ];
+    });
+}
 function readTools(planned, schemas, built) {
     const { manifest } = built.plan.ontology;
     const { definition } = planned.resolved.entity;
     const label = definition.label.toLowerCase();
     const read = permissionOf(planned.name, READ_VERB);
-    const related = planned.traversals.map((traversal) => `- ${relatedHint(planned, traversal)}`);
+    const related = [
+        ...planned.traversals.map((traversal) => relatedHint(planned, traversal)),
+        ...matchedHints(planned),
+    ].map((hint) => `- ${hint}`);
     return [
         {
             name: mcpToolName(planned.name, "find"),
@@ -181,14 +202,140 @@ const GLOBAL_TOOLS = [
         target: { kind: "me" },
     },
 ];
+const AGGREGATE_NAME = {
+    type: "string",
+    pattern: AGGREGATE_NAME_PATTERN,
+    description: "<entity>.<property>, or a route from a measure's entity when it reaches the property's " +
+        "entity in several ways: <entity>.<relationship>.<property>, at most two relationships.",
+};
+const AGGREGATE_VALUE = {
+    anyOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }],
+};
+/** One `anyOf` branch per measure: a JSON Schema `enum` cannot describe its values. */
+function measureChoice({ name, entity, measure }) {
+    return {
+        const: name,
+        description: `${entity.label} · ${measure.label} (${measure.unit}): ${measure.description}`,
+    };
+}
+/** The aggregate tool's input for a caller: the request of `POST /api/ontology/aggregate`. */
+function aggregateInput(measures) {
+    return {
+        type: "object",
+        properties: {
+            measures: {
+                type: "array",
+                minItems: 1,
+                maxItems: AGGREGATE_LIMITS.measures,
+                uniqueItems: true,
+                items: { anyOf: measures.map(measureChoice) },
+                description: "What to compute, as <entity>.<measure>. Measures of several entities are each " +
+                    "computed over their own entity's rows, then combined on the dimensions.",
+            },
+            dimensions: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.dimensions,
+                uniqueItems: true,
+                items: AGGREGATE_NAME,
+                description: "What to group by. Every dimension must be reachable from every measure's entity.",
+            },
+            filters: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.filters,
+                description: "All must hold. A filter applies to each measure's entity that reaches it; the answer " +
+                    "warns about the others.",
+                items: {
+                    type: "object",
+                    properties: {
+                        dimension: AGGREGATE_NAME,
+                        operator: { enum: [...AGGREGATE_FILTER_OPERATORS] },
+                        value: { ...AGGREGATE_VALUE, description: "The value of equals." },
+                        values: {
+                            type: "array",
+                            minItems: 1,
+                            maxItems: AGGREGATE_LIMITS.values,
+                            items: AGGREGATE_VALUE,
+                            description: "The values of in, or the two inclusive bounds of between, for example " +
+                                '["2026-09-01", "2026-09-30"].',
+                        },
+                    },
+                    required: ["dimension", "operator"],
+                    additionalProperties: false,
+                },
+            },
+            granularity: {
+                enum: [...AGGREGATE_GRANULARITIES],
+                description: "Buckets the date or timestamp dimension granularityOf names.",
+            },
+            granularityOf: { ...AGGREGATE_NAME, description: "A requested date or timestamp dimension." },
+            orderBy: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.orderBy,
+                items: {
+                    type: "object",
+                    properties: {
+                        measure: { type: "string", description: "A requested measure." },
+                        dimension: { type: "string", description: "A requested dimension." },
+                        direction: { enum: ["asc", "desc"] },
+                    },
+                    required: ["direction"],
+                    additionalProperties: false,
+                },
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: AGGREGATE_LIMITS.rows,
+                description: "At most 1000 rows; 100 by default.",
+            },
+        },
+        required: ["measures"],
+        additionalProperties: false,
+    };
+}
+const AGGREGATE_DESCRIPTION = "Numbers about the model: measures from one or several entities, grouped and filtered by " +
+    `properties of related entities. The rule: ${RECORDS_OR_AGGREGATES}.\n\n` +
+    "Examples, with entities sales, stock and product:\n" +
+    '- September revenue by brand: {"measures": ["sales.revenue"], "dimensions": ["product.brand"], ' +
+    '"filters": [{"dimension": "sales.order_date", "operator": "between", ' +
+    '"values": ["2026-09-01", "2026-09-30"]}]}\n' +
+    '- September units sold beside units in stock, by status: {"measures": ["sales.units", ' +
+    '"stock.on_hand"], "dimensions": ["product.status"], "filters": [{"dimension": ' +
+    '"sales.order_date", "operator": "between", "values": ["2026-09-01", "2026-09-30"]}]}\n\n' +
+    "Partitioned warehouse entities require a between filter on their date property; the error " +
+    "names it. Currency measures need a single-currency filter. " +
+    "Answers come from the warehouse, and stored records from its replica: execution.sources says " +
+    "how fresh each is, and execution.warnings says when a filter did not apply to a measure. " +
+    "Requires reading every entity the request reads, path intermediates included. Call describe " +
+    "for the model's measures and relationships.";
+function aggregateTool(manifest) {
+    return {
+        name: "aggregate",
+        title: "Aggregate measures",
+        description: AGGREGATE_DESCRIPTION,
+        inputSchema: aggregateInput(measuresFor(manifest)),
+        inputSchemaFor: (caller) => {
+            const measures = measuresFor(manifest, caller.permissions);
+            return measures.length === 0 ? undefined : aggregateInput(measures);
+        },
+        annotations: READ,
+        permissions: [],
+        target: { kind: "aggregate" },
+    };
+}
 /**
- * The MCP tools of an ontology: `describe` and `me`, then for every stored entity `find`, `get`,
+ * The MCP tools of an ontology: `describe` and `me`, `aggregate` when the ontology has measures,
+ * then for every stored entity `find`, `get`,
  * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
  * `check` already refuses.
  */
 export function mcpTools(built) {
-    const tools = [...GLOBAL_TOOLS];
+    const { manifest } = built.plan.ontology;
+    const tools = [
+        ...GLOBAL_TOOLS,
+        ...(measuresFor(manifest).length > 0 ? [aggregateTool(manifest)] : []),
+    ];
     for (const planned of built.plan.entities) {
         if (planned.resolved.entity.definition.source !== undefined) {
             continue;
@@ -212,7 +359,19 @@ export function mcpTools(built) {
     }
     return tools;
 }
-/** The tools a caller may see: those whose every permission the caller's roles grant. */
+/**
+ * The tools a caller may see: those whose every permission the caller's roles grant, each with the
+ * caller's input schema.
+ */
 export function visibleTools(tools, caller) {
-    return tools.filter((tool) => tool.permissions.every((required) => isAllowed(required, caller)));
+    return tools.flatMap((tool) => {
+        if (!tool.permissions.every((required) => isAllowed(required, caller))) {
+            return [];
+        }
+        if (tool.inputSchemaFor === undefined) {
+            return [tool];
+        }
+        const inputSchema = tool.inputSchemaFor(caller);
+        return inputSchema === undefined ? [] : [{ ...tool, inputSchema }];
+    });
 }

package/dist/service/plan.js

@@ -63,13 +63,19 @@ export function planApi(ontology, generatedActions) {
     const report = (path, message) => {
         diagnostics.push({ severity: "error", code: "reserved-name", path, message });
     };
+    // The service cannot read warehouse records, so a relationship to one has no route.
+    const warehouseBacked = new Set(ontology.entities
+        .filter((candidate) => candidate.entity.definition.source !== undefined)
+        .map((candidate) => candidate.name));
     const entities = ontology.entities.map((resolved) => ({
         name: resolved.name,
         resolved,
         traversals: resolved.entity.definition.source !== undefined
             ? []
             : [
-                ...resolved.relationships.map(declaredTraversal),
+                ...resolved.relationships
+                    .filter(({ target }) => target === undefined || !warehouseBacked.has(target))
+                    .map(declaredTraversal),
                 ...inverseTraversals(resolved.name, ontology.entities),
             ],
         actions: plannedActions(resolved, (entity) => generatedActions(entity, ontology), report),

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

@@ -153,6 +153,72 @@ 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;
+}
+/**
+ * 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>;
+}
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
     readonly blobs?: BlobRuntime;
     readonly maintainBlobs?: Effect.Effect<{
@@ -192,6 +258,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

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

@@ -0,0 +1,59 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { type JWTVerifyGetKey } from "jose";
+/**
+ * The header in which a runtime caller names the member it acts for: the member's user id. The
+ * service honours it only with a verified runtime token, so nobody else can claim a member with it.
+ */
+export declare const ACT_AS_HEADER = "x-segmentstream-act-as";
+/**
+ * Whom the service trusts as its runtime caller: Vercel OIDC tokens of the functions of this
+ * deployment's own project. The app's agent is a service of the same Vercel project as the ontology
+ * service, so `VERCEL_PROJECT_ID` pins exactly the deployment's own functions.
+ */
+export interface RuntimeIdentityConfig {
+    /** The team's issuer: `https://oidc.vercel.com/<team slug>` in team issuer mode. */
+    readonly issuer: string;
+    /** The audience Vercel issues function tokens for: `https://vercel.com/<team slug>`. */
+    readonly audience: string;
+    /** The project the token must name, from `VERCEL_PROJECT_ID`. */
+    readonly projectId: string;
+}
+export type RuntimeVerification = {
+    readonly status: "valid";
+}
+/** The token claims the runtime issuer but fails verification; `reason` names what failed. */
+ | {
+    readonly status: "invalid";
+    readonly reason: string;
+} | {
+    readonly status: "unavailable";
+}
+/** The token does not claim the runtime issuer: it is some other credential. */
+ | {
+    readonly status: "other";
+};
+/** Verifies a bearer token as the deployment's own runtime token. */
+export type RuntimeTokenVerifier = (token: string) => Promise<RuntimeVerification>;
+/** The issuer's key set, at `<issuer>/.well-known/jwks` as Vercel publishes it. */
+export declare function runtimeKeySet(issuer: string): JWTVerifyGetKey;
+/**
+ * Verifies the Vercel OIDC token of a function of this deployment's project, as backend-next
+ * verifies the ontology service's own: RS256 from the team's issuer, for the team's audience,
+ * unexpired, with `project_id` equal to the configured project and `environment` `production`.
+ * The issuer and the audience name the team, so no further owner check is needed. A token that
+ * claims another issuer is `other`, without a key-set fetch.
+ */
+export declare function makeRuntimeTokenVerifier(config: RuntimeIdentityConfig, keySet: JWTVerifyGetKey): RuntimeTokenVerifier;
+/** The runtime verifier on the issuer's remote key set, which jose caches between requests. */
+export declare function runtimeTokenVerifier(config: RuntimeIdentityConfig): RuntimeTokenVerifier;
+/** A runtime token that failed verification: the reason is logged, the token never. */
+export declare function logRuntimeRejection(reason: string): Effect.Effect<void>;
+/** How a request may authenticate as the runtime: the verifier and the member it names, if any. */
+export interface RuntimeCredential {
+    readonly verify: RuntimeTokenVerifier;
+    /** The user id in `X-SegmentStream-Act-As`; `undefined` without the header. */
+    readonly actAs: string | undefined;
+}
+/** The request's runtime credential, or `undefined` while runtime authentication is disabled. */
+export declare function runtimeCredential(verify: RuntimeTokenVerifier | undefined, request: HttpServerRequest.HttpServerRequest): RuntimeCredential | undefined;