@segmentstream-cloud/ontology 0.11.0 → 0.13.0

package/dist/service/errors.d.ts

@@ -30,6 +30,38 @@ declare const SignInCheckLimited_base: Schema.Class<SignInCheckLimited, Schema.T
 /** A client asked `POST /api/ontology/sign-in/check` too often; it may ask again after this. */
 export declare class SignInCheckLimited extends SignInCheckLimited_base {
 }
+declare const InvalidAggregateQuery_base: Schema.Class<InvalidAggregateQuery, Schema.TaggedStruct<"InvalidAggregateQuery", {
+    readonly reason: Schema.String;
+}>, Cause.YieldableError>;
+/** An aggregate request the ontology cannot answer; the reason is written for the caller. */
+export declare class InvalidAggregateQuery extends InvalidAggregateQuery_base {
+}
+declare const ReadDenied_base: Schema.Class<ReadDenied, Schema.TaggedStruct<"ReadDenied", {
+    readonly permissions: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+/** The caller lacks `<entity>:read` on entities an aggregate reads: every such permission. */
+export declare class ReadDenied extends ReadDenied_base {
+}
+declare const AggregateUnavailable_base: Schema.Class<AggregateUnavailable, Schema.TaggedStruct<"AggregateUnavailable", {}>, Cause.YieldableError>;
+/** The deployment has no workspace app credential: previews and local development. */
+export declare class AggregateUnavailable extends AggregateUnavailable_base {
+}
+declare const AggregateLimited_base: Schema.Class<AggregateLimited, Schema.TaggedStruct<"AggregateLimited", {
+    readonly retryAfterSeconds: Schema.Number;
+}>, Cause.YieldableError>;
+/** A principal ran more aggregates than its window allows; it may run more after this. */
+export declare class AggregateLimited extends AggregateLimited_base {
+}
+declare const AggregateUpstreamUnavailable_base: Schema.Class<AggregateUpstreamUnavailable, Schema.TaggedStruct<"AggregateUpstreamUnavailable", {
+    readonly reason: Schema.Literals<readonly ["unreachable", "timeout", "invalid_response", "credential_rejected", "upstream_misconfigured"]>;
+    readonly status: Schema.optionalKey<Schema.Number>;
+}>, Cause.YieldableError>;
+/**
+ * SegmentStream did not answer an aggregate usably, or its answer faults the deployment rather than
+ * the caller. The operator log keeps the details; the caller learns only the reason.
+ */
+export declare class AggregateUpstreamUnavailable extends AggregateUpstreamUnavailable_base {
+}
 export interface ErrorBody {
     readonly error: string;
     readonly detail: string;

package/dist/service/errors.js

@@ -20,6 +20,50 @@ export class InvalidRequestBody extends Schema.TaggedError()("InvalidRequestBody
 /** A client asked `POST /api/ontology/sign-in/check` too often; it may ask again after this. */
 export class SignInCheckLimited extends Schema.TaggedError()("SignInCheckLimited", { retryAfterSeconds: Schema.Number }) {
 }
+/** An aggregate request the ontology cannot answer; the reason is written for the caller. */
+export class InvalidAggregateQuery extends Schema.TaggedError()("InvalidAggregateQuery", { reason: Schema.String }) {
+}
+/** The caller lacks `<entity>:read` on entities an aggregate reads: every such permission. */
+export class ReadDenied extends Schema.TaggedError()("ReadDenied", {
+    permissions: Schema.Array(Schema.String),
+}) {
+}
+/** The deployment has no workspace app credential: previews and local development. */
+export class AggregateUnavailable extends Schema.TaggedError()("AggregateUnavailable", {}) {
+}
+/** A principal ran more aggregates than its window allows; it may run more after this. */
+export class AggregateLimited extends Schema.TaggedError()("AggregateLimited", {
+    retryAfterSeconds: Schema.Number,
+}) {
+}
+/**
+ * SegmentStream did not answer an aggregate usably, or its answer faults the deployment rather than
+ * the caller. The operator log keeps the details; the caller learns only the reason.
+ */
+export class AggregateUpstreamUnavailable extends Schema.TaggedError()("AggregateUpstreamUnavailable", {
+    reason: Schema.Literals([
+        "unreachable",
+        "timeout",
+        "invalid_response",
+        "credential_rejected",
+        "upstream_misconfigured",
+    ]),
+    status: Schema.optionalKey(Schema.Number),
+}) {
+}
+const UPSTREAM_DETAILS = {
+    unreachable: "SegmentStream could not be reached. Try again shortly.",
+    timeout: "SegmentStream did not answer in time. Try again shortly.",
+    invalid_response: "SegmentStream answered with an unexpected response.",
+    credential_rejected: "SegmentStream refused the deployment's credential.",
+    upstream_misconfigured: "SegmentStream does not serve aggregates for this deployment.",
+};
+/** `a`, `a and b`, `a, b and c`. */
+function listed(values) {
+    return values.length <= 1
+        ? values.join("")
+        : `${values.slice(0, -1).join(", ")} and ${values.at(-1)}`;
+}
 export function toServerResponse(response) {
     return HttpServerResponse.jsonUnsafe(errorBodyForWire(response.body), {
         status: response.status,
@@ -279,6 +323,64 @@ export function expectedFailure(error, requestId) {
             },
         };
     }
+    if (Predicate.isTagged(error, "ReadDenied")) {
+        const { permissions } = error;
+        return {
+            status: 403,
+            body: {
+                error: "forbidden",
+                detail: `${listed(permissions)} ${permissions.length === 1 ? "is" : "are"} required.`,
+                requestId,
+                permissions,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "AggregateLimited")) {
+        const { retryAfterSeconds } = error;
+        return {
+            status: 429,
+            body: {
+                error: "rate_limited",
+                detail: `Too many aggregates. Wait ${retryAfterSeconds} seconds, then try again.`,
+                requestId,
+                retryable: true,
+            },
+            headers: { "retry-after": String(retryAfterSeconds) },
+        };
+    }
+    if (Predicate.isTagged(error, "InvalidAggregateQuery")) {
+        return {
+            status: 400,
+            body: {
+                error: "invalid_aggregate_query",
+                detail: error.reason,
+                requestId,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "AggregateUnavailable")) {
+        return {
+            status: 503,
+            body: {
+                error: "aggregate_unavailable",
+                detail: "Aggregates are available in production deployments.",
+                requestId,
+                retryable: false,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "AggregateUpstreamUnavailable")) {
+        const { reason } = error;
+        return {
+            status: 502,
+            body: {
+                error: "aggregate_upstream_unavailable",
+                detail: UPSTREAM_DETAILS[reason],
+                requestId,
+                retryable: reason === "unreachable" || reason === "timeout",
+            },
+        };
+    }
     if (Predicate.isTagged(error, "ConnectionError")) {
         return connectionFailure(error, requestId);
     }

package/dist/service/handlers.d.ts

@@ -1,7 +1,9 @@
 import { Layer } from "effect";
 import { type HttpApiGroup } from "effect/unstable/httpapi";
+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 { ConnectionTransportFactory } from "./connections.js";
 import { type RateLimit } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
@@ -11,4 +13,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): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, 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>;

package/dist/service/handlers.js

@@ -3,11 +3,12 @@ import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
 import { STORAGE_GROUP } from "../storage/api.js";
 import { Conflict } from "../errors.js";
+import { isValueMatched } from "../manifest.js";
 import { EMAIL_PATTERN } from "../property.js";
-import { renderCatalog } from "../render.js";
-import { SERVICE_GROUP } from "./api.js";
+import { SERVICE_GROUP, hasMeasures } from "./api.js";
 import { CurrentPrincipal } from "./authentication.js";
 import { catalogFor, graphOf } from "./catalog.js";
+import { describeCatalog } from "../render.js";
 import { InvalidRequestBody, SignInCheckLimited, schemaIssues } from "./errors.js";
 import { identityToken, makeOperations, requireRead, toQuery, } from "./operations.js";
 import { clientAddress, fixedWindowLimiter, } from "./rate-limit.js";
@@ -24,34 +25,43 @@ function isJsonMediaType(contentType) {
     const mediaType = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
     return mediaType === "application/json" || mediaType.endsWith("+json");
 }
-/** Reads `{ input, options? }`. The input itself is validated by `runAction`. */
-function readEnvelope(request) {
+/** Reads a JSON body: `application/json` or a `+json` type, or no content type at all. */
+function readJson(request) {
     return Effect.gen(function* () {
         if (!isJsonMediaType(request.headers["content-type"])) {
             return yield* new InvalidRequestBody({ reason: "unsupported_media_type", issues: [] });
         }
         const text = yield* Effect.orDie(request.text);
-        let body;
         try {
-            body = JSON.parse(text);
+            return JSON.parse(text);
         }
         catch {
             return yield* new InvalidRequestBody({ reason: "invalid_json", issues: [] });
         }
-        return yield* Schema.decodeUnknownEffect(ActionEnvelope)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error.issue) })));
     });
 }
-function entityHandlers(built, planned, operationsOf) {
+/** Reads `{ input, options? }`. The input itself is validated by `runAction`. */
+function readEnvelope(request) {
+    return readJson(request).pipe(Effect.flatMap((body) => Schema.decodeUnknownEffect(ActionEnvelope)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({
+        reason: "invalid_request",
+        issues: schemaIssues(error.issue),
+    })))));
+}
+function entityHandlers(built, planned, operationsOf, aggregates) {
+    // Registered beside the record routes; `aggregate` is a static segment, record ids are UUIDs.
+    const withAggregate = (handlers) => hasMeasures(planned)
+        ? handlers.handleRaw("aggregate", aggregateHandler(aggregates.entity(planned.name)))
+        : handlers;
     return dynamicGroup(built.api, planned.name, (handlers) => Effect.gen(function* () {
         if (planned.resolved.entity.definition.source !== undefined) {
-            return handlers.handleRaw("sourceCollection", () => requireRead([planned.name]).pipe(Effect.andThen(() => HttpServerResponse.json({
+            return withAggregate(handlers).handleRaw("sourceCollection", () => requireRead([planned.name]).pipe(Effect.andThen(() => HttpServerResponse.json({
                 error: "not_found",
                 detail: `${planned.name} uses a warehouse source; query it through the workspace API.`,
             }, { status: 404 }))));
         }
         const backend = yield* OntologyBackend;
         const operations = operationsOf(backend);
-        let registered = handlers
+        let registered = withAggregate(handlers)
             .handle("find", (request) => operations.find(planned, toQuery(request.query)))
             .handle("query", (request) => operations.find(planned, toQuery(request.payload)))
             .handle("get", (request) => operations.get(planned, request.params.id))
@@ -108,7 +118,21 @@ function checkSignIn(backend, limiter) {
         return yield* backend.checkSignIn(email);
     });
 }
-function serviceHandlers(built, operationsOf) {
+/**
+ * `POST /api/ontology/aggregate` and `POST /api/ontology/<entity>/aggregate`: the facade's answer is
+ * SegmentStream's, so its status and JSON body pass through as they came, with its `Retry-After` on
+ * a 429 or a 503.
+ */
+function aggregateHandler(aggregate) {
+    return ({ request }) => readJson(request).pipe(Effect.flatMap(aggregate), Effect.map((answer) => HttpServerResponse.text(answer.text, {
+        status: answer.status,
+        contentType: "application/json",
+        ...(answer.retryAfter === undefined
+            ? {}
+            : { headers: { "retry-after": answer.retryAfter } }),
+    })));
+}
+function serviceHandlers(built, operationsOf, aggregate) {
     const { manifest } = built.plan.ontology;
     const graph = graphOf(manifest);
     const signInLimiter = fixedWindowLimiter(SIGN_IN_CHECK_LIMIT);
@@ -130,29 +154,43 @@ function serviceHandlers(built, operationsOf) {
             .handle("openapi", () => Effect.sync(() => {
             if (openApi === undefined) {
                 openApi = OpenApi.fromApi(built.api);
-                for (const entity of manifest.entities.filter((entity) => entity.source !== undefined)) {
-                    const document = Schema.toJsonSchemaDocument(built.schemas.get(entity.name).record);
-                    openApi.components.schemas ??= {};
-                    openApi.components.schemas[entity.name] = {
-                        ...(document.definitions[`${entity.name
-                            .split("_")
-                            .map((part) => part[0].toUpperCase() + part.slice(1))
-                            .join("")}Record`] ?? document.schema),
-                        "x-ontology-source": entity.source,
-                        "x-ontology-measures": entity.measures,
-                        "x-ontology-relationships": entity.relationships,
-                    };
+                openApi.components.schemas ??= {};
+                for (const entity of manifest.entities) {
+                    const recordName = `${entity.name
+                        .split("_")
+                        .map((part) => part[0].toUpperCase() + part.slice(1))
+                        .join("")}Record`;
+                    if (entity.source !== undefined) {
+                        const document = Schema.toJsonSchemaDocument(built.schemas.get(entity.name).record);
+                        openApi.components.schemas[entity.name] = {
+                            ...(document.definitions[recordName] ?? document.schema),
+                            "x-ontology-source": entity.source,
+                            "x-ontology-measures": entity.measures,
+                            "x-ontology-relationships": entity.relationships,
+                        };
+                        continue;
+                    }
+                    // A value-matched relationship has no key field or route; only this names it.
+                    const matched = entity.relationships.filter(isValueMatched);
+                    const record = openApi.components.schemas[recordName];
+                    if (matched.length > 0 && record !== undefined) {
+                        openApi.components.schemas[recordName] = {
+                            ...record,
+                            "x-ontology-relationships": matched,
+                        };
+                    }
                 }
             }
             return openApi;
         }))
-            .handle("describe", (request) => Effect.map(permissionsFor(request.query.as), (permissions) => renderCatalog(manifest, permissions === undefined ? {} : { as: permissions })))
+            .handle("describe", (request) => Effect.map(permissionsFor(request.query.as), (permissions) => describeCatalog(manifest, permissions)))
             .handle("status", () => Effect.map(backend.appliedHash, (appliedHash) => ({
             hash: manifest.hash,
             appliedHash: appliedHash ?? null,
             upToDate: appliedHash === manifest.hash,
         })))
-            .handle("signInCheck", checkSignIn(backend, signInLimiter));
+            .handle("signInCheck", checkSignIn(backend, signInLimiter))
+            .handleRaw("aggregate", aggregateHandler(aggregate));
     }));
 }
 function storageHandlers(built) {
@@ -178,14 +216,14 @@ function storageHandlers(built) {
     }));
 }
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export function handlersLayer(built, hooks, connections) {
-    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections);
+export function handlersLayer(built, hooks, connections, replicate, aggregates) {
+    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate);
     const layers = [
-        serviceHandlers(built, operationsOf),
+        serviceHandlers(built, operationsOf, aggregates.model),
         ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
             ? [storageHandlers(built)]
             : []),
-        ...built.plan.entities.map((planned) => entityHandlers(built, planned, operationsOf)),
+        ...built.plan.entities.map((planned) => entityHandlers(built, planned, operationsOf, aggregates)),
     ];
     const [first, ...rest] = layers;
     return Layer.mergeAll(first, ...rest);

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

@@ -1,10 +1,12 @@
 import { Layer } from "effect";
 import { HttpRouter } from "effect/unstable/http";
+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 { ConnectionTransportFactory } from "../connections.js";
 import { RequestId } from "../errors.js";
+import type { ReplicationKick } from "../replication.js";
 import { OntologyBackend } from "../runtime-contract.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
 export declare const MCP_PATH = "/mcp";
@@ -14,7 +16,10 @@ export interface McpServerOptions {
     readonly built: BuiltApi;
     readonly hooks: ReadonlyMap<string, AfterCommitHook>;
     readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
     readonly verifyToken: TokenVerifier;
+    /** The facade the aggregate routes run; the aggregate tool runs its model-level aggregate. */
+    readonly aggregates: Aggregates;
 }
 /**
  * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can

package/dist/service/mcp/server.js

@@ -3,9 +3,10 @@ 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";
@@ -79,6 +80,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 +144,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 +198,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 +243,7 @@ function readResource({ built }, uri) {
                     {
                         uri,
                         mimeType: "text/plain",
-                        text: renderCatalog(manifest, { as: principal.permissions }),
+                        text: describeCatalog(manifest, principal.permissions),
                     },
                 ];
             default:
@@ -210,16 +252,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 +271,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) {
@@ -361,7 +412,8 @@ export function mcpLayer(options) {
         const server = {
             built: options.built,
             tools,
-            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections),
+            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("GET", 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>;