@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/connection-stream.js

@@ -0,0 +1,191 @@
+import { Effect, Stream } from "effect";
+import { bufferedStream, ConnectionError, } from "../connection.js";
+export const CONNECTION_STREAM_MEDIA_TYPE = "application/vnd.segmentstream.proxy-stream.v1+ndjson";
+const MAX_FRAME_BYTES = 128 * 1024;
+const MAX_CHUNK_BYTES = 65_536;
+const MAX_LEGACY_BYTES = 4 * 1024 * 1024;
+const CALL_TIMEOUT_MS = 40_000;
+function invalid(connection, cause) {
+    return new ConnectionError({
+        connection,
+        reason: "invalid_response",
+        message: "invalid_response",
+        retryable: false,
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function metadata(connection, value) {
+    if (!object(value) ||
+        Object.keys(value).length !== 2 ||
+        !Number.isInteger(value.statusCode) ||
+        Number(value.statusCode) < 100 ||
+        Number(value.statusCode) > 599 ||
+        !Array.isArray(value.headers) ||
+        value.headers.length > 100 ||
+        !value.headers.every((pair) => Array.isArray(pair) &&
+            pair.length === 2 &&
+            pair.every((item) => typeof item === "string"))) {
+        throw invalid(connection);
+    }
+    const headers = value.headers;
+    if (headers.reduce((size, [name, item]) => size + name.length + item.length, 0) > 16_384) {
+        throw invalid(connection);
+    }
+    return { status: Number(value.statusCode), headers };
+}
+async function* frames(reader, connection) {
+    let pending = Buffer.alloc(0);
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    for (;;) {
+        const next = await reader.read();
+        if (next.done) {
+            if (pending.length > 0) {
+                throw invalid(connection);
+            }
+            return;
+        }
+        let offset = 0;
+        while (offset < next.value.length) {
+            const newline = next.value.indexOf(10, offset);
+            const end = newline < 0 ? next.value.length : newline + 1;
+            const part = next.value.subarray(offset, end);
+            if (pending.length + part.length > MAX_FRAME_BYTES) {
+                throw invalid(connection);
+            }
+            pending = Buffer.concat([pending, part]);
+            offset = end;
+            if (newline >= 0) {
+                const value = JSON.parse(decoder.decode(pending));
+                pending = Buffer.alloc(0);
+                yield value;
+            }
+        }
+    }
+}
+/** Negotiates once; never retries a provider operation to change response formats. */
+export function openConnectionStream(input) {
+    return Effect.gen(function* () {
+        const controller = yield* Effect.acquireRelease(Effect.sync(() => new AbortController()), (controller) => Effect.sync(() => controller.abort()));
+        const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(CALL_TIMEOUT_MS)]);
+        const failure = (cause) => {
+            if (cause instanceof ConnectionError) {
+                return cause;
+            }
+            const timeout = signal.aborted &&
+                signal.reason instanceof DOMException &&
+                signal.reason.name === "TimeoutError";
+            return new ConnectionError({
+                connection: input.connection,
+                reason: timeout ? "timeout" : "unavailable",
+                message: timeout ? "timeout" : "unavailable",
+                retryable: true,
+                cause,
+            });
+        };
+        const response = yield* Effect.tryPromise({
+            try: (interrupted) => input.request(AbortSignal.any([signal, interrupted])),
+            catch: failure,
+        });
+        if (response.body === null) {
+            return yield* invalid(input.connection);
+        }
+        let closed = false;
+        const closeReader = (reader) => Effect.suspend(() => {
+            if (closed) {
+                return Effect.void;
+            }
+            closed = true;
+            controller.abort();
+            return Effect.tryPromise({ try: () => reader.cancel(), catch: (cause) => cause }).pipe(Effect.timeout("1 second"), Effect.catch((cause) => Effect.logError("ontology.connection.stream_cleanup_failed", cause)));
+        });
+        const reader = yield* Effect.acquireRelease(Effect.sync(() => response.body.getReader()), closeReader);
+        const streamed = response.headers.get("content-type")?.split(";")[0]?.trim() === CONNECTION_STREAM_MEDIA_TYPE;
+        if (!response.ok || !streamed) {
+            return yield* Effect.tryPromise({
+                try: async () => {
+                    const chunks = [];
+                    let size = 0;
+                    for (;;) {
+                        const next = await reader.read();
+                        if (next.done) {
+                            break;
+                        }
+                        size += next.value.length;
+                        if (size > MAX_LEGACY_BYTES) {
+                            throw invalid(input.connection);
+                        }
+                        chunks.push(next.value);
+                    }
+                    let value;
+                    try {
+                        value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                    }
+                    catch (cause) {
+                        throw response.ok
+                            ? invalid(input.connection, cause)
+                            : input.refusal(response.status, undefined, cause);
+                    }
+                    if (!response.ok) {
+                        throw input.refusal(response.status, value);
+                    }
+                    return bufferedStream(input.legacy(value));
+                },
+                catch: failure,
+            });
+        }
+        const iterator = frames(reader, input.connection);
+        const first = yield* Effect.tryPromise({
+            try: () => iterator.next(),
+            catch: (cause) => cause instanceof SyntaxError || cause instanceof TypeError
+                ? invalid(input.connection, cause)
+                : failure(cause),
+        });
+        const head = yield* Effect.try({
+            try: () => metadata(input.connection, first.value),
+            catch: (cause) => invalid(input.connection, cause),
+        });
+        // Pull with interruptible Effects: an async iterable's return() can wait forever
+        // behind a pending next(), preventing the reader's cancellation finalizer.
+        const body = Stream.unfold(false, (completed) => Effect.gen(function* () {
+            let ended = completed;
+            for (;;) {
+                if (signal.aborted) {
+                    return yield* failure(signal.reason);
+                }
+                const next = yield* Effect.tryPromise({
+                    try: () => iterator.next(),
+                    catch: (cause) => cause instanceof SyntaxError || cause instanceof TypeError
+                        ? invalid(input.connection, cause)
+                        : failure(cause),
+                });
+                if (next.done) {
+                    return ended ? undefined : yield* failure({ error: "incomplete_stream" });
+                }
+                const value = next.value;
+                if (ended || !object(value) || Object.keys(value).length !== 1) {
+                    return yield* invalid(input.connection);
+                }
+                if (value.end === true) {
+                    ended = true;
+                }
+                else if (typeof value.error === "string") {
+                    return yield* failure({ error: value.error });
+                }
+                else if (typeof value.data === "string") {
+                    const bytes = Buffer.from(value.data, "base64");
+                    if (bytes.length > MAX_CHUNK_BYTES || bytes.toString("base64") !== value.data) {
+                        return yield* invalid(input.connection);
+                    }
+                    return [new Uint8Array(bytes), ended];
+                }
+                else {
+                    return yield* invalid(input.connection);
+                }
+            }
+        })).pipe(Stream.ensuring(closeReader(reader)));
+        return { ...head, body };
+    });
+}

package/dist/service/connections.d.ts

@@ -0,0 +1,60 @@
+import { type ConnectionTransport } from "../connection.js";
+/** The header Vercel sets on each function request: the deployment's OIDC token. */
+export declare const OIDC_TOKEN_HEADER = "x-vercel-oidc-token";
+/** Where `segmentstream exec` passes the local runtime context: a pipe's file descriptor. */
+export declare const RUNTIME_CONTEXT_FD = "SEGMENTSTREAM_RUNTIME_CONTEXT_FD";
+/** Who a connection call is made for. SegmentStream logs these; it never trusts them. */
+export interface ConnectionAudit {
+    /** `<entity>.<action>`. */
+    readonly action: string;
+    readonly principalId: string;
+    readonly requestId: string;
+}
+/** Builds the transport of one action request. */
+export type ConnectionTransportFactory = (input: {
+    /** The deployment's OIDC token, from the request or the environment. */
+    readonly identityToken: string | undefined;
+    readonly audit: ConnectionAudit;
+}) => ConnectionTransport["Service"];
+/** A connection the local grant covers, as the CLI describes it. */
+export interface LocalConnection {
+    readonly key: string;
+    readonly apis: Readonly<Record<string, string>>;
+    readonly defaultApi: string | null;
+}
+/** The local runtime context `segmentstream exec --connection …` passes through a pipe. */
+export interface LocalConnectionContext {
+    readonly apiUrl: string;
+    readonly workspaceId: string;
+    readonly proxyGrant: string;
+    readonly connections: ReadonlyArray<LocalConnection>;
+}
+/** The local runtime context is present but cannot be used. */
+export declare class LocalConnectionContextError extends Error {
+    readonly name = "LocalConnectionContextError";
+}
+type Fetch = typeof fetch;
+/**
+ * The transport of a deployed ontology service: each call goes to backend-next with the
+ * deployment's Vercel OIDC token, which proves the workspace application. The organization id only
+ * selects the tenant; backend-next admits the call only if the token's project is that tenant's
+ * application for the workspace, and only for a connection the deployed ontology declares.
+ */
+export declare function deployedConnections(environment: {
+    readonly segmentstreamUrl: string;
+    readonly workspaceId: string;
+    readonly organizationId: string;
+}, fetchImpl?: Fetch): ConnectionTransportFactory;
+/**
+ * The transport of `segmentstream exec --connection … -- npm run dev`: each call goes to the local
+ * proxy route with the CLI's one-hour grant, for the connections the grant covers.
+ */
+export declare function localConnections(context: LocalConnectionContext, fetchImpl?: Fetch): ConnectionTransportFactory;
+/** Parses the context the CLI wrote, as the pipeline SDK does. */
+export declare function parseLocalConnectionContext(text: string): LocalConnectionContext;
+/**
+ * Reads the local runtime context from the pipe `segmentstream exec` opened, once, and removes the
+ * variable so that child processes cannot read it again. `undefined` when the CLI passed none.
+ */
+export declare function readLocalConnectionContext(environment: Record<string, string | undefined>): LocalConnectionContext | undefined;
+export {};

package/dist/service/connections.js

@@ -0,0 +1,271 @@
+import { closeSync, readFileSync } from "node:fs";
+import { Effect, Stream } from "effect";
+import { CONNECTION_KEY, ConnectionError, MAXIMUM_CONNECTION_BODY_BYTES, MAXIMUM_CONNECTION_RESPONSE_BYTES, } from "../connection.js";
+import { CONNECTION_STREAM_MEDIA_TYPE, openConnectionStream } from "./connection-stream.js";
+/** The header Vercel sets on each function request: the deployment's OIDC token. */
+export const OIDC_TOKEN_HEADER = "x-vercel-oidc-token";
+/** Where `segmentstream exec` passes the local runtime context: a pipe's file descriptor. */
+export const RUNTIME_CONTEXT_FD = "SEGMENTSTREAM_RUNTIME_CONTEXT_FD";
+const MAXIMUM_CONTEXT_BYTES = 4 * 1_048_576;
+/** The local runtime context is present but cannot be used. */
+export class LocalConnectionContextError extends Error {
+    name = "LocalConnectionContextError";
+}
+const decoder = new TextDecoder();
+function failure(connection, reason, message, requestId, cause) {
+    return new ConnectionError({
+        connection,
+        reason,
+        message,
+        retryable: reason === "unavailable" || reason === "timeout",
+        ...(requestId === undefined ? {} : { requestId }),
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+const REASONS = {
+    connection_authorization_required: "authorization_required",
+    connections_not_deployed: "not_deployed",
+    connections_redeployment_required: "not_deployed",
+    connection_not_found: "not_deployed",
+    connection_not_granted: "not_granted",
+    runtime_unauthorized: "not_granted",
+    runtime_value_not_granted: "not_granted",
+    unauthorized: "not_granted",
+    connection_provider_unavailable: "unavailable",
+    service_unavailable: "unavailable",
+    connection_proxy_unavailable: "timeout",
+    connection_provider_refused: "refused",
+    connection_response_too_large: "invalid_response",
+    invalid_connection: "invalid_request",
+    invalid_request: "invalid_request",
+};
+const MESSAGES = {
+    authorization_required: "Configure or authorize this connection in SegmentStream.",
+    not_deployed: "Deploy the workspace's connections/connections.py with this connection.",
+    not_granted: "SegmentStream did not grant this connection to the ontology service.",
+    unavailable: "The connection is temporarily unavailable.",
+    refused: "The provider refused the request.",
+    timeout: "The connection call exceeded its deadline.",
+    invalid_request: "The connection proxy refused the request.",
+    invalid_response: "The connection proxy answered with an invalid response.",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHeaderPairs(value) {
+    return (Array.isArray(value) &&
+        value.every((pair) => Array.isArray(pair) &&
+            pair.length === 2 &&
+            typeof pair[0] === "string" &&
+            typeof pair[1] === "string"));
+}
+/** The proxy's JSON answer, `{ statusCode, headers, body }` with a base64 body. */
+function reply(connection, value) {
+    if (!isRecord(value) ||
+        typeof value.statusCode !== "number" ||
+        !isHeaderPairs(value.headers) ||
+        typeof value.body !== "string") {
+        throw failure(connection, "invalid_response", MESSAGES.invalid_response);
+    }
+    const body = Buffer.from(value.body, "base64");
+    if (body.byteLength > MAXIMUM_CONNECTION_BODY_BYTES) {
+        throw failure(connection, "invalid_response", "The provider's response exceeds 2 MiB.");
+    }
+    return { status: value.statusCode, headers: value.headers, body: new Uint8Array(body) };
+}
+/** A refusal from SegmentStream, by its error code. */
+function refusal(connection, status, value, cause) {
+    const code = isRecord(value) && typeof value.error === "string" ? value.error : "";
+    const requestId = isRecord(value) && typeof value.requestId === "string" ? value.requestId : undefined;
+    const reason = REASONS[code] ?? (status >= 500 ? "unavailable" : "not_granted");
+    const detail = isRecord(value) && typeof value.detail === "string" ? value.detail : undefined;
+    return failure(connection, reason, detail ?? MESSAGES[reason], requestId, cause);
+}
+/**
+ * A buffered call's reply, collected from a streamed one: streaming lifts the proxy's 2 MiB cap on
+ * buffered responses, and the collected body stays bounded so one response cannot exhaust the
+ * memory the service's concurrent requests share.
+ */
+function collected(connection, reply) {
+    const chunks = [];
+    let size = 0;
+    return Stream.runForEach(reply.body, (chunk) => {
+        size += chunk.byteLength;
+        if (size > MAXIMUM_CONNECTION_RESPONSE_BYTES) {
+            return Effect.fail(failure(connection, "invalid_response", "The provider's response exceeds 64 MiB. Read it with the connection's stream."));
+        }
+        chunks.push(chunk);
+        return Effect.void;
+    }).pipe(Effect.map(() => ({
+        status: reply.status,
+        headers: reply.headers,
+        body: new Uint8Array(Buffer.concat(chunks)),
+    })));
+}
+/** Shared admission and wire requests for buffered and streamed responses. */
+function transport(fetchImpl, resolve) {
+    const open = (call) => resolve(call).pipe(Effect.flatMap((selected) => openConnectionStream({
+        connection: call.connection,
+        request: (signal) => fetchImpl(selected.url, {
+            method: "POST",
+            headers: {
+                ...selected.headers,
+                "content-type": "application/json",
+                accept: CONNECTION_STREAM_MEDIA_TYPE,
+            },
+            body: JSON.stringify({
+                ...(selected.call.api === undefined ? {} : { api: selected.call.api }),
+                method: selected.call.method,
+                path: selected.call.path,
+                headers: selected.call.headers,
+                body: Buffer.from(selected.call.body).toString("base64"),
+            }),
+            redirect: "error",
+            signal,
+        }),
+        legacy: (value) => reply(call.connection, value),
+        refusal: (status, value, cause) => refusal(call.connection, status, value, cause),
+    })));
+    return {
+        request: (call) => open(call).pipe(Effect.flatMap((reply) => collected(call.connection, reply)), Effect.scoped),
+        stream: (call) => open(call),
+    };
+}
+/**
+ * The transport of a deployed ontology service: each call goes to backend-next with the
+ * deployment's Vercel OIDC token, which proves the workspace application. The organization id only
+ * selects the tenant; backend-next admits the call only if the token's project is that tenant's
+ * application for the workspace, and only for a connection the deployed ontology declares.
+ */
+export function deployedConnections(environment, fetchImpl = fetch) {
+    const workspace = `${environment.segmentstreamUrl}/api/internal/v1/workspaces/${environment.workspaceId}`;
+    const base = `${workspace}/ontology/connections`;
+    return ({ identityToken, audit }) => transport(fetchImpl, (call) => {
+        if (identityToken === undefined || identityToken === "") {
+            return Effect.fail(failure(call.connection, "not_granted", "The request carries no Vercel OIDC token. Connections are available to production " +
+                "deployments, and locally through segmentstream exec --connection."));
+        }
+        return Effect.succeed({
+            url: `${base}/${encodeURIComponent(call.connection)}/request`,
+            headers: {
+                "x-segmentstream-runtime-identity": identityToken,
+                "x-segmentstream-organization-id": environment.organizationId,
+                "x-segmentstream-ontology-action": audit.action,
+                "x-segmentstream-ontology-principal": audit.principalId,
+                "x-segmentstream-request-id": audit.requestId,
+            },
+            call: { ...call, api: call.api },
+        });
+    });
+}
+/**
+ * The transport of `segmentstream exec --connection … -- npm run dev`: each call goes to the local
+ * proxy route with the CLI's one-hour grant, for the connections the grant covers.
+ */
+export function localConnections(context, fetchImpl = fetch) {
+    const connections = new Map(context.connections.map((candidate) => [candidate.key, candidate]));
+    const workspace = `${context.apiUrl}/api/v1/workspaces/${context.workspaceId}`;
+    return () => transport(fetchImpl, (call) => {
+        const granted = connections.get(call.connection);
+        if (granted === undefined) {
+            return Effect.fail(failure(call.connection, "not_granted", `Run the service with segmentstream exec --connection ${call.connection}.`));
+        }
+        const api = call.api ?? granted.defaultApi ?? undefined;
+        if (api === undefined || !(api in granted.apis)) {
+            return Effect.fail(failure(call.connection, "invalid_request", api === undefined
+                ? `The connection ${call.connection} has no default API; set api.`
+                : `The connection ${call.connection} declares no API named ${api}.`));
+        }
+        return Effect.succeed({
+            url: `${workspace}/connections/${encodeURIComponent(call.connection)}/request`,
+            headers: { "x-segmentstream-connection-grant": context.proxyGrant },
+            call: { ...call, api },
+        });
+    });
+}
+function localConnection(value) {
+    if (!isRecord(value) ||
+        typeof value.key !== "string" ||
+        !CONNECTION_KEY.test(value.key) ||
+        !isRecord(value.apis) ||
+        Object.values(value.apis).some((url) => typeof url !== "string") ||
+        (value.defaultApi !== null && typeof value.defaultApi !== "string")) {
+        throw new LocalConnectionContextError("The SegmentStream runtime context is invalid.");
+    }
+    return {
+        key: value.key,
+        apis: value.apis,
+        defaultApi: value.defaultApi ?? null,
+    };
+}
+/** The URL without trailing slashes, in linear time: a regex would backtrack on many slashes. */
+function withoutTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url[end - 1] === "/") {
+        end -= 1;
+    }
+    return url.slice(0, end);
+}
+/** Parses the context the CLI wrote, as the pipeline SDK does. */
+export function parseLocalConnectionContext(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new LocalConnectionContextError("The SegmentStream runtime context is invalid.");
+    }
+    if (!isRecord(value) ||
+        value.schemaVersion !== 3 ||
+        typeof value.apiUrl !== "string" ||
+        typeof value.workspaceId !== "string" ||
+        typeof value.proxyGrant !== "string" ||
+        value.proxyGrant === "" ||
+        !Array.isArray(value.connections)) {
+        throw new LocalConnectionContextError("The SegmentStream runtime context is invalid.");
+    }
+    const apiUrl = URL.canParse(value.apiUrl) ? new URL(value.apiUrl) : undefined;
+    if (apiUrl === undefined || apiUrl.protocol !== "https:" || apiUrl.username || apiUrl.search) {
+        throw new LocalConnectionContextError("The SegmentStream API URL is invalid.");
+    }
+    return {
+        apiUrl: withoutTrailingSlashes(`${apiUrl.origin}${apiUrl.pathname}`),
+        workspaceId: value.workspaceId,
+        proxyGrant: value.proxyGrant,
+        connections: value.connections.map(localConnection),
+    };
+}
+/**
+ * Reads the local runtime context from the pipe `segmentstream exec` opened, once, and removes the
+ * variable so that child processes cannot read it again. `undefined` when the CLI passed none.
+ */
+export function readLocalConnectionContext(environment) {
+    const raw = environment[RUNTIME_CONTEXT_FD];
+    if (raw === undefined) {
+        return undefined;
+    }
+    delete environment[RUNTIME_CONTEXT_FD];
+    if (!/^[0-9]+$/.test(raw) || Number(raw) < 3) {
+        throw new LocalConnectionContextError("The SegmentStream runtime context is unavailable. Run the service with segmentstream exec.");
+    }
+    const descriptor = Number(raw);
+    let bytes;
+    try {
+        bytes = readFileSync(descriptor);
+    }
+    catch {
+        throw new LocalConnectionContextError("The SegmentStream runtime context is unavailable. Run the service with segmentstream exec.");
+    }
+    finally {
+        try {
+            closeSync(descriptor);
+        }
+        catch {
+            // Already closed: the context was read, or there was nothing to read.
+        }
+    }
+    if (bytes.byteLength === 0 || bytes.byteLength > MAXIMUM_CONTEXT_BYTES) {
+        throw new LocalConnectionContextError("The SegmentStream runtime context is invalid.");
+    }
+    return parseLocalConnectionContext(decoder.decode(bytes));
+}

package/dist/service/decisions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Yes-or-no questions about one shared state, answered by a decision model on AI Gateway, such as
+ * TypeSafe's Jev: each answer is the probability of "yes". The SDK asks them to rank `discover`'s
+ * entities by meaning, when the ontology opts in with `discovery: { model }`.
+ */
+export interface DecisionRequest {
+    readonly model: string;
+    /** What the questions are about: text, such as the caller's request. */
+    readonly state: string;
+    /** Each question's instructions by its id. */
+    readonly questions: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+}
+/** The probability of "yes" by question id, for every question asked. */
+export type Decide = (request: DecisionRequest) => Promise<Readonly<Record<string, number>>>;
+/** A credential for AI Gateway: an API key, or the deployment's Vercel OIDC token. */
+export interface GatewayCredential {
+    readonly token: string;
+    readonly method: "api-key" | "oidc";
+}
+/** AI Gateway refused or failed a decision, or answered something other than probabilities. */
+export declare class DecisionFailed extends Error {
+    readonly name = "DecisionFailed";
+}
+/**
+ * Asks AI Gateway's decision endpoint, as the AI SDK's `experimental_decide` does, without its
+ * dependencies: one POST with the state as a text part and one boolean question per id.
+ */
+export declare function gatewayDecisions(options: {
+    /** The credential for this call, or none: the call then fails without a request. */
+    readonly credential: () => GatewayCredential | undefined;
+    readonly fetch?: typeof fetch;
+}): Decide;
+/** AI Gateway's credential in this environment: `AI_GATEWAY_API_KEY`, else the OIDC token given. */
+export declare function gatewayCredential(identityToken: string | undefined, environment?: Readonly<Record<string, string | undefined>>): GatewayCredential | undefined;

package/dist/service/decisions.js

@@ -0,0 +1,63 @@
+/** The decision endpoint of AI Gateway, as the AI SDK's gateway provider calls it. */
+const GATEWAY_DECISIONS = "https://ai-gateway.vercel.sh/v4/ai/decision-model";
+/** AI Gateway refused or failed a decision, or answered something other than probabilities. */
+export class DecisionFailed extends Error {
+    name = "DecisionFailed";
+}
+/**
+ * Asks AI Gateway's decision endpoint, as the AI SDK's `experimental_decide` does, without its
+ * dependencies: one POST with the state as a text part and one boolean question per id.
+ */
+export function gatewayDecisions(options) {
+    return async ({ model, state, questions, signal }) => {
+        const credential = options.credential();
+        if (credential === undefined) {
+            throw new DecisionFailed("No AI Gateway credential: set AI_GATEWAY_API_KEY, or run on Vercel with OIDC.");
+        }
+        const response = await (options.fetch ?? fetch)(GATEWAY_DECISIONS, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${credential.token}`,
+                "ai-gateway-auth-method": credential.method,
+                "ai-gateway-protocol-version": "0.0.1",
+                "ai-decision-model-specification-version": "4",
+                "ai-model-id": model,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                stateParts: [{ type: "text", text: state }],
+                questions: Object.fromEntries(Object.entries(questions).map(([id, instructions]) => [
+                    id,
+                    { type: "boolean", instructions },
+                ])),
+            }),
+            redirect: "error",
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (!response.ok) {
+            throw new DecisionFailed(`AI Gateway answered HTTP ${response.status} for ${model}: ${(await response.text()).slice(0, 500)}`);
+        }
+        const body = (await response.json());
+        const answers = typeof body.answers === "object" && body.answers !== null
+            ? body.answers
+            : {};
+        return Object.fromEntries(Object.keys(questions).map((id) => {
+            const answer = answers[id];
+            const probability = answer?.type === "boolean" ? answer.probability : undefined;
+            if (typeof probability !== "number" || !(probability >= 0 && probability <= 1)) {
+                throw new DecisionFailed(`${model} gave no probability for question ${id}.`);
+            }
+            return [id, probability];
+        }));
+    };
+}
+/** AI Gateway's credential in this environment: `AI_GATEWAY_API_KEY`, else the OIDC token given. */
+export function gatewayCredential(identityToken, environment = process.env) {
+    const key = environment.AI_GATEWAY_API_KEY;
+    if (key !== undefined && key !== "") {
+        return { token: key, method: "api-key" };
+    }
+    return identityToken === undefined || identityToken === ""
+        ? undefined
+        : { token: identityToken, method: "oidc" };
+}

package/dist/service/descriptions.d.ts

@@ -0,0 +1,8 @@
+import type { PlannedAction } from "./plan.js";
+/** `Requires lead:read.`, `Requires lead:create and lead:update.` */
+export declare function requires(permissions: ReadonlyArray<string>): string;
+/**
+ * What an action's route and its MCP tool say about it: its description, whether it is generated,
+ * the permissions it requires, the entities it declares it writes and the connections it calls.
+ */
+export declare function actionDescription({ action, generated, permissions, writes, }: PlannedAction): string;

package/dist/service/descriptions.js

@@ -0,0 +1,20 @@
+/** `Requires lead:read.`, `Requires lead:create and lead:update.` */
+export function requires(permissions) {
+    return `Requires ${permissions.join(" and ")}.`;
+}
+/**
+ * What an action's route and its MCP tool say about it: its description, whether it is generated,
+ * the permissions it requires, the entities it declares it writes and the connections it calls.
+ */
+export function actionDescription({ action, generated, permissions, writes, }) {
+    const origin = generated ? "Generated action." : "Action.";
+    const changes = writes === undefined
+        ? ""
+        : writes.length > 0
+            ? ` Writes ${writes.join(", ")}.`
+            : " Writes no records.";
+    const calls = action.connections.length > 0
+        ? ` Calls ${action.connections.map((handle) => handle.key).join(", ")} before its transaction.`
+        : "";
+    return `${action.description}\n\n${origin} ${requires(permissions)}${changes}${calls}`;
+}