@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/handlers.js

@@ -0,0 +1,287 @@
+import { effectivePermissions } from "../permissions.js";
+import { HttpServerResponse } from "effect/unstable/http";
+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 { EARLIER_QUERY_METRICS_ROUTE } from "../legacy.js";
+import { QUERY_METRICS_ENDPOINT, SERVICE_GROUP, hasMetrics, } from "./api.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { currentCaller } from "./caller-context.js";
+import { invokesAgent, runtimeManifest } from "./mcp/runtime-policy.js";
+import { catalogFor, graphOf } from "./catalog.js";
+import { describeCatalog } from "../render.js";
+import { InvalidRequestBody, SignInCheckLimited, schemaIssues } from "./errors.js";
+import { identityToken, makeOperations, toQuery } from "./operations.js";
+import { clientAddress, fixedWindowLimiter, } from "./rate-limit.js";
+import { OntologyBackend } from "./runtime-contract.js";
+import { ActionEnvelope } from "./schemas.js";
+/** Prune excluded invocation routes and the schemas reachable only from those routes. */
+function runtimeOpenApi(document) {
+    const paths = Object.fromEntries(Object.entries(document.paths).filter(([path]) => {
+        const match = /^\/api\/ontology\/([^/]+)\/actions\/([^/]+)$/.exec(path);
+        return match === null || !invokesAgent({ entity: match[1], action: match[2] });
+    }));
+    const { schemas = {}, ...components } = document.components;
+    const retained = new Set();
+    const visit = (value) => {
+        if (value === null || typeof value !== "object") {
+            return;
+        }
+        const reference = value.$ref;
+        if (typeof reference === "string" && reference.startsWith("#/components/schemas/")) {
+            const name = reference.slice("#/components/schemas/".length);
+            if (!retained.has(name)) {
+                retained.add(name);
+                visit(schemas[name]);
+            }
+        }
+        Object.values(value).forEach(visit);
+    };
+    visit({ ...document, paths, components });
+    return {
+        ...document,
+        paths,
+        components: {
+            ...components,
+            schemas: Object.fromEntries(Object.entries(schemas).filter(([name]) => retained.has(name))),
+        },
+    };
+}
+function dynamicGroup(api, identifier, build) {
+    const group = HttpApiBuilder.group;
+    return group(api, identifier, build);
+}
+function isJsonMediaType(contentType) {
+    if (contentType === undefined || contentType.trim() === "") {
+        return true;
+    }
+    const mediaType = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    return mediaType === "application/json" || mediaType.endsWith("+json");
+}
+/** 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);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return yield* new InvalidRequestBody({ reason: "invalid_json", issues: [] });
+        }
+    });
+}
+/** 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, metricQueries) {
+    // Registered beside the record routes; `query_metrics` and its earlier path are static segments,
+    // record ids are UUIDs.
+    const withMetricQuery = (handlers) => {
+        if (!hasMetrics(planned)) {
+            return handlers;
+        }
+        const handler = queryMetricsHandler(metricQueries.entity(planned.name));
+        return handlers
+            .handleRaw(QUERY_METRICS_ENDPOINT, handler)
+            .handleRaw(EARLIER_QUERY_METRICS_ROUTE, handler);
+    };
+    return dynamicGroup(built.api, planned.name, (handlers) => Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        const operations = operationsOf(backend);
+        let registered = withMetricQuery(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));
+        if (planned.resolved.entity.definition.source === undefined) {
+            registered = registered.handle("history", (request) => operations.history(planned, request.params.id, request.query));
+        }
+        for (const property of planned.resolved.properties.filter((property) => property.definition.type === "blob")) {
+            registered = registered.handle(`blobs.${property.name}`, (request) => Effect.gen(function* () {
+                const principal = yield* CurrentPrincipal;
+                if (!backend.blobs) {
+                    return yield* new Conflict({
+                        entity: planned.name,
+                        message: "File storage is not configured.",
+                    });
+                }
+                return yield* backend.blobs.download(planned.name, request.params.id, property.name, request.payload, principal);
+            }));
+        }
+        for (const traversal of planned.traversals) {
+            registered = registered.handle(`related.${traversal.name}`, (request) => operations.traverse(planned, traversal, request.params.id, toQuery(request.query)));
+        }
+        for (const action of planned.actions) {
+            registered = registered.handleRaw(`actions.${action.name}`, ({ request }) => readEnvelope(request).pipe(Effect.flatMap((envelope) => operations.runAction(planned, action, {
+                input: envelope.input,
+                validateOnly: envelope.options?.validateOnly === true,
+                ...(envelope.options === undefined ? {} : { options: envelope.options }),
+                identityToken: identityToken(request),
+            }))));
+        }
+        return registered;
+    }));
+}
+/**
+ * Sign-in checks one client may make per minute. A person checks once per sign-in, a few times at
+ * most; the limit slows down anyone testing addresses to learn who the app's members are.
+ */
+export const SIGN_IN_CHECK_LIMIT = { limit: 10, windowMs: 60_000, maxKeys: 10_000 };
+/**
+ * `POST /api/ontology/sign-in/check`, before any authentication: rate limited per client address,
+ * then answered by the backend. A malformed address is a 400, so the app can ask for a valid one
+ * instead of reporting that nobody invited it.
+ */
+function checkSignIn(backend, limiter) {
+    return (request) => Effect.gen(function* () {
+        const retryAfterSeconds = limiter.take(clientAddress(request.request));
+        if (retryAfterSeconds !== undefined) {
+            return yield* new SignInCheckLimited({ retryAfterSeconds });
+        }
+        const email = request.payload.email.trim();
+        if (!EMAIL_PATTERN.test(email.toLowerCase())) {
+            return yield* new InvalidRequestBody({
+                reason: "invalid_request",
+                issues: [{ path: ["email"], message: "Expected an email address." }],
+            });
+        }
+        return yield* backend.checkSignIn(email);
+    });
+}
+/**
+ * `POST /api/ontology/query_metrics` and `POST /api/ontology/<entity>/query_metrics`, and their
+ * earlier paths: 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 queryMetricsHandler(queryMetrics) {
+    return ({ request }) => readJson(request).pipe(Effect.flatMap(queryMetrics), 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, queryMetrics, deployment) {
+    const { manifest } = built.plan.ontology;
+    const graph = graphOf(manifest);
+    const signInLimiter = fixedWindowLimiter(SIGN_IN_CHECK_LIMIT);
+    let openApi;
+    return dynamicGroup(built.api, SERVICE_GROUP, (handlers) => Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        // `as=me` reads the catalog with the caller's permissions; otherwise it is the whole catalog.
+        const permissionsFor = (as) => Effect.gen(function* () {
+            if (as !== "me") {
+                return undefined;
+            }
+            const principal = yield* CurrentPrincipal;
+            return effectivePermissions(principal);
+        });
+        return handlers
+            .handle("catalog", (request) => Effect.gen(function* () {
+            return catalogFor(runtimeManifest(manifest, yield* currentCaller), yield* permissionsFor(request.query.as));
+        }))
+            .handle("graph", () => Effect.succeed(graph))
+            .handle("me", () => operationsOf(backend).caller)
+            .handle("openapi", () => Effect.gen(function* () {
+            const caller = yield* currentCaller;
+            if (openApi === undefined) {
+                openApi = OpenApi.fromApi(built.api);
+                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-metrics": entity.metrics,
+                            "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,
+                        };
+                    }
+                }
+            }
+            if (caller.kind !== "runtime") {
+                return openApi;
+            }
+            return runtimeOpenApi(openApi);
+        }))
+            .handle("describe", (request) => Effect.gen(function* () {
+            return describeCatalog(runtimeManifest(manifest, yield* currentCaller), yield* permissionsFor(request.query.as));
+        }))
+            .handle("status", () => Effect.map(backend.appliedHash, (appliedHash) => ({
+            hash: manifest.hash,
+            appliedHash: appliedHash ?? null,
+            upToDate: appliedHash === manifest.hash,
+            ...(deployment ? { deployment } : {}),
+        })))
+            .handle("signInCheck", checkSignIn(backend, signInLimiter))
+            .handleRaw(QUERY_METRICS_ENDPOINT, queryMetricsHandler(queryMetrics))
+            .handleRaw(EARLIER_QUERY_METRICS_ROUTE, queryMetricsHandler(queryMetrics));
+    }));
+}
+function storageHandlers(built) {
+    return dynamicGroup(built.api, STORAGE_GROUP, (handlers) => Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        const configured = () => backend.blobs
+            ? Effect.succeed(backend.blobs)
+            : Effect.fail(new Conflict({ entity: "upload", message: "File storage is not configured." }));
+        let registered = handlers.handle("begin", (request) => Effect.gen(function* () {
+            const principal = yield* CurrentPrincipal;
+            const blobs = yield* configured();
+            return yield* blobs.begin(request.payload, principal);
+        }));
+        registered = registered.handle("list", () => Effect.gen(function* () {
+            const principal = yield* CurrentPrincipal;
+            const blobs = yield* configured();
+            if (!blobs.list) {
+                return yield* new Conflict({ entity: "upload", message: "file_listing_unavailable" });
+            }
+            return yield* blobs.list(principal);
+        }));
+        for (const method of ["status", "part", "complete", "cancel"]) {
+            registered = registered.handle(method, (request) => Effect.gen(function* () {
+                const principal = yield* CurrentPrincipal;
+                const blobs = yield* configured();
+                return yield* blobs[method](request.params.id, principal);
+            }));
+        }
+        return registered.handle("maintain", () => backend.maintainBlobs ??
+            Effect.fail(new Conflict({ entity: "upload", message: "File storage is not configured." })));
+    }));
+}
+/** The handlers of every group of the API; they require {@link OntologyBackend}. */
+export function handlersLayer(built, hooks, connections, replicate, metricQueries, chatDelivery, deployment) {
+    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate, chatDelivery);
+    const layers = [
+        serviceHandlers(built, operationsOf, metricQueries.model, deployment),
+        ...(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, metricQueries)),
+    ];
+    const [first, ...rest] = layers;
+    return Layer.mergeAll(first, ...rest);
+}

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

@@ -0,0 +1,68 @@
+import type { JsonSchemaObject } from "../../analyze.js";
+import type { OntologyManifest } from "../../manifest.js";
+import type { McpToolAnnotations } from "./tools.js";
+/** Presentation travels with the call, but is never business input or an idempotency key. */
+export declare const CONFIRMATION_ARGUMENT = "_confirmation";
+export declare function needsConfirmation(hints: McpToolAnnotations): boolean;
+export declare function withConfirmation(schema: JsonSchemaObject, hints: McpToolAnnotations): JsonSchemaObject;
+export declare function withoutConfirmation(input: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * The annotation of a confirmable action's listed tool that carries its {@link ConfirmationFacts}.
+ * Eve's approval policy receives a tool's annotations from the listing Eve already holds, but not
+ * its input schema: these facts let the agent present the card without reading the ontology's
+ * metadata again.
+ */
+export declare const CONFIRMATION_FACTS = "segmentstream/confirmation";
+/**
+ * The JSON-RPC method that asks a confirmable action what its person confirms, instead of running
+ * it: `{ name, arguments, locale }`, `locale` being the chat's language. It answers as `tools/call`
+ * does, with `{ confirmation }` as the action's `confirm` describes it, or fails as the action would
+ * refuse the input. Only a tool whose {@link ConfirmationFacts} carry `preview` accepts it; any
+ * other tool, and a service without the method, answers with a JSON-RPC error and runs nothing.
+ */
+export declare const CONFIRMATION_PREVIEW_METHOD = "segmentstream/confirmation/preview";
+/** A preview request's chat language, as a lower-case BCP 47 tag; English when it is not one. */
+export declare function previewLocale(locale: unknown): string;
+/** One input field as a confirmation card shows it. */
+export interface ConfirmationField {
+    readonly label: string;
+    /** The value is a list. */
+    readonly list?: true;
+    /** The value is the id of a record: the card shows the record's `title` property instead. */
+    readonly ref?: {
+        readonly entity: string;
+        readonly title?: string;
+    };
+    /** The value is one of these: the card shows its label, and no value without one. */
+    readonly options?: Readonly<Record<string, string>>;
+}
+/**
+ * The facts of a confirmation card, in the ontology's own labels. Fields that are not listed, such
+ * as files, structured values and ids that name no record, are not shown.
+ */
+export interface ConfirmationFacts {
+    readonly action: string;
+    readonly entity?: string;
+    readonly description?: string;
+    readonly fields: Readonly<Record<string, ConfirmationField>>;
+    /**
+     * The action describes its own confirmation: {@link CONFIRMATION_PREVIEW_METHOD} answers what to
+     * show, or why the action would refuse.
+     */
+    readonly preview?: true;
+}
+/**
+ * The card facts of a confirmable action's tool, from its input schema and the ontology's labels:
+ * every top-level field except its options, files, structured values and ids that name no record.
+ */
+export declare function confirmationFacts(input: {
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    readonly manifest: OntologyManifest;
+    readonly entity: string;
+    /** Arguments the runtime handles itself, never shown as facts. */
+    readonly omit: ReadonlyArray<string>;
+    /** The action has `confirm`. */
+    readonly preview?: boolean;
+}): ConfirmationFacts;

package/dist/service/mcp/confirmation.js

@@ -0,0 +1,178 @@
+import { nameToWire } from "../../authoring-names.js";
+import { BLOB_UPLOAD_ANNOTATION } from "../../blob.js";
+import { humanize } from "../../names.js";
+import { REFERENCE_ANNOTATION } from "../../property.js";
+/** Presentation travels with the call, but is never business input or an idempotency key. */
+export const CONFIRMATION_ARGUMENT = "_confirmation";
+export function needsConfirmation(hints) {
+    return (hints.readOnlyHint !== true &&
+        (hints.destructiveHint === true ||
+            hints.irreversibleHint === true ||
+            hints.openWorldHint === true ||
+            (hints.destructiveHint === undefined && hints.irreversibleHint === undefined)));
+}
+export function withConfirmation(schema, hints) {
+    if (!needsConfirmation(hints)) {
+        return schema;
+    }
+    return {
+        ...schema,
+        properties: {
+            ...schema.properties,
+            [CONFIRMATION_ARGUMENT]: {
+                description: "Confirmation presentation in the chat's language. Plain single-line text only; " +
+                    "no IDs, tool names, snake_case, URLs, credentials or markup. The question describes " +
+                    "this action and its key parameters. The runtime adds trusted facts and fixed markers.",
+                // Eve validates the wire schema before execution. Presentation mistakes must reach
+                // the SDK's validator so they use the neutral fallback rather than block the action.
+                anyOf: [
+                    {
+                        type: "object",
+                        properties: Object.fromEntries([
+                            "question",
+                            "confirm",
+                            "cancel",
+                            "done",
+                            "cancelled",
+                            "failed",
+                            "expired",
+                            "interrupted",
+                            "edit",
+                        ].map((key) => [
+                            key,
+                            { type: "string", minLength: 1, maxLength: key === "question" ? 300 : 24 },
+                        ])),
+                        required: ["question", "confirm", "cancel", "done", "cancelled", "failed"],
+                        additionalProperties: false,
+                    },
+                    {},
+                ],
+            },
+        },
+    };
+}
+export function withoutConfirmation(input) {
+    return Object.fromEntries(Object.entries(input).filter(([key]) => key !== CONFIRMATION_ARGUMENT));
+}
+/**
+ * The annotation of a confirmable action's listed tool that carries its {@link ConfirmationFacts}.
+ * Eve's approval policy receives a tool's annotations from the listing Eve already holds, but not
+ * its input schema: these facts let the agent present the card without reading the ontology's
+ * metadata again.
+ */
+export const CONFIRMATION_FACTS = "segmentstream/confirmation";
+/**
+ * The JSON-RPC method that asks a confirmable action what its person confirms, instead of running
+ * it: `{ name, arguments, locale }`, `locale` being the chat's language. It answers as `tools/call`
+ * does, with `{ confirmation }` as the action's `confirm` describes it, or fails as the action would
+ * refuse the input. Only a tool whose {@link ConfirmationFacts} carry `preview` accepts it; any
+ * other tool, and a service without the method, answers with a JSON-RPC error and runs nothing.
+ */
+export const CONFIRMATION_PREVIEW_METHOD = "segmentstream/confirmation/preview";
+/** A preview request's chat language, as a lower-case BCP 47 tag; English when it is not one. */
+export function previewLocale(locale) {
+    return typeof locale === "string" && /^[a-z]{2,3}(?:-[a-z0-9]{1,8}){0,3}$/i.test(locale)
+        ? locale.toLowerCase()
+        : "en";
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function resolve(value, root, depth = 0) {
+    const schema = record(value);
+    if (depth > 12) {
+        return { schema: {}, choices: [] };
+    }
+    const reference = typeof schema.$ref === "string" && schema.$ref.startsWith("#/")
+        ? resolve(schema.$ref
+            .slice(2)
+            .split("/")
+            .reduce((at, key) => record(at)[key.replace(/~1/g, "/").replace(/~0/g, "~")], root), root, depth + 1)
+        : undefined;
+    const branches = [schema.allOf, schema.anyOf, schema.oneOf]
+        .flatMap((items) => (Array.isArray(items) ? items : []))
+        .filter((item) => record(item).type !== "null")
+        .map((item) => resolve(item, root, depth + 1));
+    const values = Array.isArray(schema.enum)
+        ? schema.enum.filter((item) => typeof item === "string")
+        : [];
+    // A schema that allows exactly one value is an option, and its title is that option's label.
+    const option = typeof schema.const === "string" || values.length === 1;
+    const own = typeof schema.const === "string"
+        ? [{ value: schema.const, title: text(schema.title) }]
+        : values.map((item) => ({ value: item, ...(option ? { title: text(schema.title) } : {}) }));
+    return {
+        schema: Object.assign({}, reference?.schema, ...branches.map(({ schema }) => schema), schema),
+        choices: [...(reference?.choices ?? []), ...branches.flatMap(({ choices }) => choices), ...own],
+        title: (option ? undefined : text(schema.title)) ??
+            reference?.title ??
+            (branches.length === 1 ? branches[0].title : undefined),
+    };
+}
+/**
+ * The card facts of a confirmable action's tool, from its input schema and the ontology's labels:
+ * every top-level field except its options, files, structured values and ids that name no record.
+ */
+export function confirmationFacts(input) {
+    const root = input.inputSchema;
+    const owner = input.manifest.entities.find((entity) => entity.name === input.entity);
+    const fields = {};
+    for (const [name, declared] of Object.entries(record(root.properties))) {
+        if (name === CONFIRMATION_ARGUMENT || input.omit.includes(name)) {
+            continue;
+        }
+        const field = resolve(declared, root);
+        const list = field.schema.type === "array";
+        const item = list ? resolve(field.schema.items, root) : field;
+        const target = item.schema[REFERENCE_ANNOTATION];
+        if (field.schema.writeOnly === true ||
+            item.schema.writeOnly === true ||
+            item.schema.format === "password" ||
+            item.schema.type === "object" ||
+            item.schema[BLOB_UPLOAD_ANNOTATION] !== undefined ||
+            (typeof target !== "string" && item.schema.format === "uuid")) {
+            continue;
+        }
+        const property = owner?.properties.find((candidate) => candidate.name === name);
+        const referenced = typeof target === "string"
+            ? input.manifest.entities.find((entity) => entity.name === target || nameToWire(entity.name) === target)
+            : undefined;
+        const labels = new Map([
+            ...(property?.options ?? []).map(({ value, label }) => [value, label]),
+            ...item.choices.flatMap(({ value, title }) => title === undefined ? [] : [[value, title]]),
+        ]);
+        fields[name] = {
+            label: field.title ?? (list ? item.title : undefined) ?? property?.label ?? humanize(name),
+            ...(list ? { list: true } : {}),
+            ...(typeof target === "string"
+                ? {
+                    ref: {
+                        entity: target,
+                        ...(referenced === undefined ? {} : { title: referenced.title }),
+                    },
+                }
+                : {}),
+            ...(item.choices.length === 0 && property?.options === undefined
+                ? {}
+                : {
+                    options: Object.fromEntries([...new Set([...item.choices.map(({ value }) => value), ...labels.keys()])].flatMap((value) => {
+                        const label = labels.get(value);
+                        return label === undefined ? [] : [[value, label]];
+                    })),
+                }),
+        };
+    }
+    const description = text(input.description.split("\n\n")[0]);
+    return {
+        action: input.title,
+        ...(owner === undefined ? {} : { entity: owner.label }),
+        ...(description === undefined ? {} : { description }),
+        fields,
+        ...(input.preview === true ? { preview: true } : {}),
+    };
+}

package/dist/service/mcp/find-input.d.ts

@@ -0,0 +1,12 @@
+import type { JsonSchemaObject } from "../../analyze.js";
+import type { OntologyManifest } from "../../manifest.js";
+/** The query language of `<entity>_find`, in the tool's description, which clients show whole. */
+export declare const FIND_CONDITIONS: string;
+/**
+ * The input an MCP client sees for `<entity>_find`. It is the same query as `POST
+ * /<entity>/query`, published compactly: each field names its type once, a relationship names
+ * its target's fields instead of repeating their filters, and paging, sorting and includes come
+ * before the conditions. The server still decodes every call with the closed query schema, so an
+ * unknown field or operator is refused with its reason.
+ */
+export declare function findToolInput(manifest: OntologyManifest, entityName: string): JsonSchemaObject;

package/dist/service/mcp/find-input.js

@@ -0,0 +1,122 @@
+import { findEntityManifest, queryFields, queryJsonSchema, queryLinks, } from "../../query.js";
+/** The JSON types of a bare value of the field, as `eq` takes it. */
+function bareType(field) {
+    switch (field.storage) {
+        case "integer":
+            return "integer";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "json":
+            return "unknown";
+        default:
+            return "string";
+    }
+}
+/** What a field's operators and values are, in a few words. */
+function fieldNote(field) {
+    if (field.storage === "list") {
+        return "A list: has takes a value, has_any a list of values.";
+    }
+    if (field.storage === "date") {
+        return "YYYY-MM-DD.";
+    }
+    if (field.storage === "timestamp") {
+        return "ISO 8601 with a time zone.";
+    }
+    if (field.storage === "json") {
+        return "JSON; eq compares values.";
+    }
+    return undefined;
+}
+/**
+ * One field's condition: a bare value, null, or an object of operators. The operators are named
+ * once, in the `where` description, instead of being spelled out for every field.
+ */
+function fieldCondition(field) {
+    const note = fieldNote(field);
+    const bare = field.options !== undefined
+        ? { enum: [...field.options] }
+        : bareType(field) === "unknown"
+            ? {}
+            : { type: bareType(field) };
+    return {
+        anyOf: [bare, { type: "null" }, { type: "object" }],
+        ...(note === undefined ? {} : { description: note }),
+    };
+}
+/** The query language of `<entity>_find`, in the tool's description, which clients show whole. */
+export const FIND_CONDITIONS = "where: a field takes a bare value (eq), null (is_null: true) or an object of operators: eq, " +
+    "ne, in and is_null; text fields also contains and starts_with, which ignore case; numbers, " +
+    "dates and timestamps also gt, gte, lt, lte and between [from, to], which includes both ends. " +
+    "ne also matches empty values. Dates are YYYY-MM-DD. A relationship takes conditions on its " +
+    "target's fields, one level deep; a to-many one wraps them in some, none or every. and and or " +
+    "take lists of conditions; not takes one. Unknown fields and operators are refused.";
+// Clients that shorten schema descriptions keep this first sentence.
+const WHERE_DESCRIPTION = "Operators: eq, ne, in, is_null; text contains, starts_with; ordered gt, gte, lt, lte, " +
+    "between. All conditions must hold; the tool description has the rules.";
+/** A target's fields for a relationship's hint: its title and properties first, then its id. */
+function targetFields(manifest, name) {
+    const target = findEntityManifest(manifest, name);
+    if (target === undefined) {
+        return [];
+    }
+    const system = new Set(["id", "created_at", "updated_at", "created_by", "updated_by"]);
+    const fields = queryFields(target)
+        .map((field) => field.name)
+        .filter((field) => !system.has(field));
+    const title = typeof target.title === "string" ? target.title : undefined;
+    return [
+        ...(title !== undefined && fields.includes(title) ? [title] : []),
+        ...fields.filter((field) => field !== title),
+        "id",
+    ];
+}
+/**
+ * The input an MCP client sees for `<entity>_find`. It is the same query as `POST
+ * /<entity>/query`, published compactly: each field names its type once, a relationship names
+ * its target's fields instead of repeating their filters, and paging, sorting and includes come
+ * before the conditions. The server still decodes every call with the closed query schema, so an
+ * unknown field or operator is refused with its reason.
+ */
+export function findToolInput(manifest, entityName) {
+    const precise = queryJsonSchema(manifest, entityName, true);
+    const properties = precise.properties;
+    const entity = findEntityManifest(manifest, entityName);
+    const conditions = {};
+    for (const field of queryFields(entity)) {
+        conditions[field.name] = fieldCondition(field);
+    }
+    for (const link of queryLinks(manifest, entityName, true)) {
+        conditions[link.name] = {
+            type: "object",
+            description: `${link.cardinality === "many" ? "some, none or every: " : ""}${link.target} ` +
+                `fields ${targetFields(manifest, link.target).join(", ")}.`,
+        };
+    }
+    conditions.and = { type: "array", items: { type: "object" } };
+    conditions.or = { type: "array", items: { type: "object" } };
+    conditions.not = { type: "object" };
+    const ordered = {};
+    for (const key of ["limit", "after", "include", "order_by", "select"]) {
+        if (properties[key] !== undefined) {
+            ordered[key] = properties[key];
+        }
+    }
+    ordered.where = {
+        type: "object",
+        description: WHERE_DESCRIPTION,
+        properties: conditions,
+        additionalProperties: false,
+    };
+    if (JSON.stringify(ordered).includes('"$ref"')) {
+        throw new Error(`The compact find input of ${entityName} still refers to definitions.`);
+    }
+    return {
+        type: "object",
+        ...(typeof precise.description === "string" ? { description: precise.description } : {}),
+        properties: ordered,
+        additionalProperties: false,
+    };
+}