@every-app/sdk 0.2.0 → 0.3.0-rc.10

package/dist/server/fromMcpTools.js

@@ -0,0 +1,192 @@
+/**
+ * `fromMcpTools()` — an app's existing MCP tools as `defineTools()` entries.
+ *
+ *   const tools: McpToolLike[] = [];
+ *   registerMyTools((name, config, handler) =>
+ *     tools.push({ name, ...config, handler }),
+ *   );
+ *   export default everyApp(handler, {
+ *     tools: defineTools(fromMcpTools(tools), { instructions }),
+ *   });
+ *
+ * Takes the shape `McpServer.registerTool(name, config, handler)` is called
+ * with (or what a low-level server's `tools/list` returns, plus a handler),
+ * structurally: the SDK takes no dependency on `@modelcontextprotocol/sdk`,
+ * and a live `McpServer` keeps its registry private, so the app hands over
+ * the list it registers from.
+ */
+import { TOOL_NAME_PATTERN } from "../internal/index.js";
+import { ToolError, toolResult, } from "./tools.js";
+const JSON_SCHEMA_TARGET = "draft-2020-12";
+/**
+ * Adapt MCP tools into `defineTools()` entries, keyed by tool name, to spread
+ * beside the app's own: `defineTools({ ...fromMcpTools(list), my_tool })`.
+ *
+ * - `title`, `description` (the name when absent), `idempotentHint` and
+ *   `openWorldHint` carry over; risk as {@link FromMcpToolsOptions.risk}.
+ * - A result's text blocks, joined by a blank line, are what the model
+ *   reads; `structuredContent` is sent as structured content (checked
+ *   against `outputSchema` when there is one). Other blocks are dropped.
+ * - `isError: true` becomes a {@link ToolError} with the result's text.
+ *
+ * Names must already be lowercase snake_case; `defineTools()` checks them.
+ */
+export function fromMcpTools(tools, options = {}) {
+    const out = {};
+    for (const tool of tools) {
+        const problem = (message) => new TypeError(`fromMcpTools: tool "${tool?.name}" ${message}`);
+        if (!tool || typeof tool.name !== "string") {
+            throw new TypeError("fromMcpTools: every tool needs a name");
+        }
+        if (!TOOL_NAME_PATTERN.test(tool.name)) {
+            throw problem("must be named in lowercase snake_case: a letter, then letters, digits or _ (at most 48 characters); rename it in the list");
+        }
+        if (Object.prototype.hasOwnProperty.call(out, tool.name)) {
+            throw problem("is listed twice");
+        }
+        if (typeof tool.handler !== "function") {
+            throw problem("needs a handler function");
+        }
+        const output = tool.outputSchema === undefined
+            ? undefined
+            : toToolSchema(tool.outputSchema, problem);
+        const annotations = tool.annotations ?? {};
+        const title = tool.title ?? annotations.title;
+        out[tool.name] = {
+            ...(title !== undefined ? { title } : {}),
+            description: tool.description?.trim() ? tool.description : tool.name,
+            risk: options.risk?.(tool) ?? defaultRisk(annotations),
+            input: toToolSchema(tool.inputSchema ?? {}, problem),
+            ...(output ? { output } : {}),
+            ...(annotations.idempotentHint !== undefined
+                ? { idempotent: annotations.idempotentHint }
+                : {}),
+            ...(annotations.openWorldHint !== undefined
+                ? { openWorld: annotations.openWorldHint }
+                : {}),
+            handler: async (args, context) => {
+                const extra = options.context
+                    ? await options.context(context)
+                    : context;
+                const result = await tool.handler(args, extra);
+                return fromCallToolResult(result);
+            },
+        };
+    }
+    return out;
+}
+function defaultRisk(annotations) {
+    if (annotations.readOnlyHint === true)
+        return "read";
+    return annotations.destructiveHint === true ? "destructive" : "write";
+}
+function fromCallToolResult(result) {
+    if (!isRecord(result)) {
+        throw new Error("the MCP tool did not return a CallToolResult");
+    }
+    const text = (Array.isArray(result.content) ? result.content : [])
+        .flatMap((part) => isRecord(part) && part.type === "text" && typeof part.text === "string"
+        ? [part.text]
+        : [])
+        .join("\n\n");
+    if (result.isError === true)
+        throw new ToolError(text || "The tool failed.");
+    const structured = result.structuredContent;
+    if (isRecord(structured) && !Array.isArray(structured)) {
+        return toolResult({ text, structured });
+    }
+    return text;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isStandardWithJson(value) {
+    if (!isRecord(value))
+        return false;
+    const standard = value["~standard"];
+    return (isRecord(standard) &&
+        typeof standard.validate === "function" &&
+        isRecord(standard.jsonSchema));
+}
+function isPlainToolSchema(value) {
+    return isRecord(value.jsonSchema) && typeof value.validate === "function";
+}
+function toToolSchema(schema, problem) {
+    if (!isRecord(schema) || Array.isArray(schema)) {
+        throw problem("has a schema that is not an object");
+    }
+    if (isStandardWithJson(schema) || isPlainToolSchema(schema)) {
+        return schema;
+    }
+    if ("~standard" in schema) {
+        throw problem("has a schema that doesn't convert to JSON Schema (zod >= 4.2 does)");
+    }
+    const values = Object.values(schema);
+    if (values.every((value) => isRecord(value) && "~standard" in value)) {
+        if (!values.every(isStandardWithJson)) {
+            throw problem("has a raw shape whose fields don't convert to JSON Schema (zod >= 4.2 does)");
+        }
+        return rawShapeSchema(schema);
+    }
+    return jsonSchemaOnly(schema);
+}
+/** A plain JSON Schema: described as is; any object passes. */
+function jsonSchemaOnly(jsonSchema) {
+    return {
+        jsonSchema,
+        validate: (value) => isRecord(value) && !Array.isArray(value)
+            ? { value }
+            : { issues: [{ message: "Expected an object" }] },
+    };
+}
+/**
+ * `{ key: schema }` as an object schema, the way `McpServer` wraps one in
+ * `z.object()`: unknown keys are dropped, and a field is optional when its
+ * schema accepts `undefined`.
+ */
+function rawShapeSchema(shape) {
+    const properties = {};
+    const required = [];
+    for (const [key, field] of Object.entries(shape)) {
+        const { $schema: _, ...property } = field["~standard"].jsonSchema.input({
+            target: JSON_SCHEMA_TARGET,
+        });
+        properties[key] = property;
+        const absent = field["~standard"].validate(undefined);
+        // An async validator can't be asked here; call the field required.
+        if (absent instanceof Promise || absent.issues)
+            required.push(key);
+    }
+    return {
+        jsonSchema: {
+            type: "object",
+            properties,
+            ...(required.length > 0 ? { required } : {}),
+        },
+        validate: async (value) => {
+            if (!isRecord(value) || Array.isArray(value)) {
+                return { issues: [{ message: "Expected an object" }] };
+            }
+            const parsed = {};
+            const issues = [];
+            for (const [key, field] of Object.entries(shape)) {
+                const result = await field["~standard"].validate(value[key]);
+                if (result.issues) {
+                    for (const issue of result.issues) {
+                        issues.push({
+                            message: issue.message,
+                            path: [
+                                key,
+                                ...(issue.path ?? []).map((segment) => typeof segment === "object" ? segment.key : segment),
+                            ],
+                        });
+                    }
+                }
+                else if (key in value || result.value !== undefined) {
+                    parsed[key] = result.value;
+                }
+            }
+            return issues.length > 0 ? { issues } : { value: parsed };
+        },
+    };
+}

package/dist/server/gatewayFetch.d.ts

@@ -1,21 +1,61 @@
-interface GatewayServiceBinding {
+import { type GatewayCallFor } from "./attribution.js";
+export declare const BINDING_ORIGIN = "http://every-app-gateway.internal";
+export interface GatewayServiceBinding {
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 }
-export interface GatewayFetchEnv {
-    EVERY_APP_GATEWAY?: GatewayServiceBinding;
-    EVERYAPP_DEV?: string | boolean;
-    OPENAI_API_KEY?: string;
-}
+/**
+ * The Gateway the SDK's services call: the `EVERY_APP_GATEWAY` service
+ * binding when deployed; under `everyapp dev --gateway` (linked dev,
+ * docs/design/linked-dev.md) a `{ fetch }` that sends the same requests to
+ * the gateway-lite's loopback forwarder, which adds the person's token and
+ * forwards them to the real Gateway's `/linked-dev/<app>` route. Undefined
+ * with neither (stub and mirror modes: the `.dev.vars` fallbacks). A value
+ * under the binding's name that isn't one is answered as before by each
+ * caller (`ConfigurationError`).
+ */
+export declare function gatewayBinding(env: object): GatewayServiceBinding | undefined;
+/**
+ * The linked dev shim: a request to the binding's origin goes to the
+ * forwarder's URL with the same path and query, the run's nonce on it. The
+ * forwarder answers as the Gateway did, refusals included; nothing here
+ * falls back to a local key.
+ */
+export declare function linkedDevBinding(forwarderUrl: string, nonce: string): GatewayServiceBinding;
 export interface CreateGatewayFetchOptions {
-    env: GatewayFetchEnv;
-    /** The inbound app request whose verified identity may be forwarded. */
-    request: Request;
+    /**
+     * The Worker env, as it is: the EVERY_APP_GATEWAY binding when deployed,
+     * or in local dev EVERYAPP_DEV and the provider's settings in
+     * `.dev.vars` (`OPENROUTER_API_KEY`, …). No cast needed.
+     */
+    env: object;
+    /**
+     * Whom the call is for. Left out, the request `everyApp()` is serving
+     * (its user, while the identity is good) or the organization
+     * `withOrganization()` named; outside both, `RequestContextError`.
+     * Explicitly: the inbound request, or `{ background: true,
+     * organizationId }` for work no person started (crons, Workflows,
+     * queues). A shared app's Worker must end up with one or the other
+     * ({@link AttributionError}).
+     */
+    for?: GatewayCallFor;
+    /**
+     * `true`: answer null instead of throwing `ConfigurationError` when AI
+     * is unavailable (no binding, and in local dev no provider key), so a
+     * feature that can do without a model checks for null. A binding that
+     * isn't one, and an attribution mistake, still throw.
+     */
+    optional?: boolean;
 }
 /**
- * Create an OpenAI-compatible fetch function backed by the private gateway
- * service binding. In local dev only, the developer's own OPENAI_API_KEY is a
- * direct-provider fallback when no binding exists.
+ * Create a fetch for the gateway's AI providers (`/api/ai/<provider>/…`),
+ * backed by the private gateway service binding. In local dev only, the
+ * developer's own provider key from `.dev.vars` is a direct-provider
+ * fallback when no binding exists.
  */
-export declare function createGatewayFetch({ env, request: inboundRequest, }: CreateGatewayFetchOptions): typeof fetch;
-export {};
+export declare function createGatewayFetch(options: CreateGatewayFetchOptions & {
+    optional: true;
+}): typeof fetch | null;
+export declare function createGatewayFetch(options: CreateGatewayFetchOptions): typeof fetch;
+/** A copy of `source` aimed at `url`, streaming its body rather than buffering it. */
+export declare function streamingRequest(url: string, source: Request, headers: Headers): Request;
 //# sourceMappingURL=gatewayFetch.d.ts.map

package/dist/server/gatewayFetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gatewayFetch.d.ts","sourceRoot":"","sources":["../../src/server/gatewayFetch.ts"],"names":[],"mappings":"AAMA,UAAU,qBAAqB;IAC7B,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,eAAe,CAAC;IACrB,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,GAAG,EACH,OAAO,EAAE,cAAc,GACxB,EAAE,yBAAyB,GAAG,OAAO,KAAK,CAyC1C"}
+{"version":3,"file":"gatewayFetch.d.ts","sourceRoot":"","sources":["../../src/server/gatewayFetch.ts"],"names":[],"mappings":"AAiBA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,cAAc,sCAAsC,CAAC;AAGlE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAW7E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GACZ,qBAAqB,CAiBvB;AAeD,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GACtD,OAAO,KAAK,GAAG,IAAI,CAAC;AACvB,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,OAAO,KAAK,CAAC;AA2HhB,sFAAsF;AACtF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,GACf,OAAO,CAUT"}

package/dist/server/gatewayFetch.js

@@ -1,44 +1,142 @@
-import { ConfigurationError, IDENTITY_HEADER } from "../internal/index.js";
-const BINDING_ORIGIN = "http://every-app-gateway.internal";
-const OPENAI_UPSTREAM_ORIGIN = "https://api.openai.com";
-const OPENAI_PROXY_PREFIX = "/api/ai/openai";
+import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER, AI_DEFAULT_ROUTES, aiProviderSettings, authorizationOf, ConfigurationError, DEV_AI_PROVIDERS, DEV_ENV, devAiProvider, joinProviderUrl, LINKED_DEV_HEADER, LINKED_DEV_NONCE_ENV, LINKED_DEV_URL_ENV, resolveAiDefault, } from "../internal/index.js";
+import { applyAttribution, attributionFor, } from "./attribution.js";
+export const BINDING_ORIGIN = "http://every-app-gateway.internal";
+const AI_PROXY_PREFIX = "/api/ai/";
 /**
- * Create an OpenAI-compatible fetch function backed by the private gateway
- * service binding. In local dev only, the developer's own OPENAI_API_KEY is a
- * direct-provider fallback when no binding exists.
+ * The Gateway the SDK's services call: the `EVERY_APP_GATEWAY` service
+ * binding when deployed; under `everyapp dev --gateway` (linked dev,
+ * docs/design/linked-dev.md) a `{ fetch }` that sends the same requests to
+ * the gateway-lite's loopback forwarder, which adds the person's token and
+ * forwards them to the real Gateway's `/linked-dev/<app>` route. Undefined
+ * with neither (stub and mirror modes: the `.dev.vars` fallbacks). A value
+ * under the binding's name that isn't one is answered as before by each
+ * caller (`ConfigurationError`).
  */
-export function createGatewayFetch({ env, request: inboundRequest, }) {
-    const binding = env.EVERY_APP_GATEWAY;
-    const devProviderKey = env.EVERYAPP_DEV
-        ? env.OPENAI_API_KEY?.trim()
-        : undefined;
+export function gatewayBinding(env) {
+    const values = env;
+    const binding = values["EVERY_APP_GATEWAY"];
+    if (binding)
+        return binding;
+    if (!values[DEV_ENV])
+        return undefined;
+    const url = values[LINKED_DEV_URL_ENV];
+    const nonce = values[LINKED_DEV_NONCE_ENV];
+    if (typeof url !== "string" || !url.trim() || typeof nonce !== "string") {
+        return undefined;
+    }
+    return linkedDevBinding(url.trim(), nonce);
+}
+/**
+ * The linked dev shim: a request to the binding's origin goes to the
+ * forwarder's URL with the same path and query, the run's nonce on it. The
+ * forwarder answers as the Gateway did, refusals included; nothing here
+ * falls back to a local key.
+ */
+export function linkedDevBinding(forwarderUrl, nonce) {
+    const base = forwarderUrl.replace(/\/+$/, "");
+    return {
+        fetch(input, init) {
+            const outbound = new Request(input, init);
+            const url = new URL(outbound.url);
+            const headers = new Headers(outbound.headers);
+            headers.set(LINKED_DEV_HEADER, nonce);
+            return fetch(streamingRequest(`${base}${url.pathname}${url.search}`, outbound, headers));
+        },
+    };
+}
+export function createGatewayFetch({ env: workerEnv, for: explicitTarget, optional = false, }) {
+    const env = workerEnv;
+    // Checked now, so a call nobody's fails where the fetch is made; and
+    // again per call, where an identity may since have neared its expiry.
+    attributionFor(env, explicitTarget, "createGatewayFetch");
+    const binding = gatewayBinding(env);
+    const devProviders = env.EVERYAPP_DEV ? localProviders(env) : {};
     if (binding && typeof binding.fetch !== "function") {
         throw new ConfigurationError("EVERY_APP_GATEWAY is configured but is not a valid service binding.");
     }
-    if (!binding && !devProviderKey) {
-        throw new ConfigurationError("AI gateway unavailable: deploy with the EVERY_APP_GATEWAY binding, or set OPENAI_API_KEY in .dev.vars for direct local development.");
+    if (!binding && Object.keys(devProviders).length === 0) {
+        if (optional)
+            return null;
+        throw new ConfigurationError(`AI gateway unavailable: deploy with the EVERY_APP_GATEWAY binding, or set the provider's key (${listOf(Object.values(DEV_AI_PROVIDERS).map((spec) => settingsNames(spec, "with")), "or")}) in .dev.vars for direct local development.`, { code: "ai_provider_not_configured" });
     }
     return async (input, init) => {
+        const target = attributionFor(env, explicitTarget, "createGatewayFetch");
         const outbound = new Request(input, init);
         const headers = new Headers(outbound.headers);
         headers.delete("authorization");
-        const identity = inboundRequest.headers.get(IDENTITY_HEADER);
-        if (identity)
-            headers.set(IDENTITY_HEADER, identity);
-        else
-            headers.delete(IDENTITY_HEADER);
         if (binding) {
-            const target = new URL(outbound.url);
-            const bindingRequest = streamingRequest(`${BINDING_ORIGIN}${target.pathname}${target.search}`, outbound, headers);
+            applyAttribution(headers, target);
+            const url = new URL(outbound.url);
+            const bindingRequest = streamingRequest(`${BINDING_ORIGIN}${url.pathname}${url.search}`, outbound, headers);
             return binding.fetch(bindingRequest);
         }
-        const providerUrl = directOpenAiUrl(outbound.url);
-        headers.delete(IDENTITY_HEADER);
-        headers.set("authorization", `Bearer ${devProviderKey}`);
-        return fetch(streamingRequest(providerUrl, outbound, headers));
+        const direct = directProviderPath(outbound.url, env);
+        const { provider, spec, path, search } = direct;
+        const dev = devProviders[provider];
+        if (!dev) {
+            throw new ConfigurationError(`Set ${settingsNames(spec)} in .dev.vars to call ${provider} in local development.`, {
+                code: "ai_provider_not_configured",
+                settings: aiProviderSettings(spec),
+            });
+        }
+        const url = joinProviderUrl(`${spec.origin}${dev.basePath}`, path, search);
+        if (!url)
+            throw new ConfigurationError("Invalid provider proxy path.");
+        applyAttribution(headers, undefined);
+        // The default route in dev: the model filled in as the gateway would.
+        let body = outbound;
+        if (direct.fillModel !== null) {
+            body = await withModel(outbound, direct.fillModel, headers);
+        }
+        // The developer's key, put where the provider's entry says (a bearer
+        // token for the three today), as the gateway would put its own.
+        const auth = authorizationOf(spec.auth, { [spec.keyEnv]: dev.key });
+        for (const [name, value] of Object.entries(auth?.headers ?? {})) {
+            headers.set(name, value);
+        }
+        for (const [name, value] of Object.entries(auth?.query ?? {})) {
+            url.searchParams.set(name, value);
+        }
+        const response = await fetch(streamingRequest(url.toString(), body, headers));
+        // What the gateway does to the provider's answer, so dev behaves alike.
+        return spec.normalizeResponse?.(path, response) ?? response;
     };
 }
-function streamingRequest(url, source, headers) {
+/**
+ * `source` with `model` put into its JSON body where the app named none
+ * or named `default`, as the gateway's default route does. A body that
+ * isn't a JSON object goes through as it is.
+ */
+async function withModel(source, model, headers) {
+    if (!canIncludeBody(source.method) || !source.body)
+        return source;
+    const text = await source.clone().text();
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        return source;
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return source;
+    }
+    const record = payload;
+    if (record["model"] === undefined ||
+        record["model"] === null ||
+        record["model"] === AI_DEFAULT_MODEL) {
+        record["model"] = model;
+    }
+    headers.delete("content-length");
+    return new Request(source.url, {
+        method: source.method,
+        headers,
+        body: JSON.stringify(record),
+        signal: source.signal,
+    });
+}
+/** A copy of `source` aimed at `url`, streaming its body rather than buffering it. */
+export function streamingRequest(url, source, headers) {
     const body = canIncludeBody(source.method) ? source.body : undefined;
     const init = {
         method: source.method,
@@ -49,20 +147,86 @@ function streamingRequest(url, source, headers) {
     };
     return new Request(url, init);
 }
-function directOpenAiUrl(input) {
+/** The providers `.dev.vars` sets every setting of, with their key and base path. */
+function localProviders(env) {
+    const providers = {};
+    for (const [provider, spec] of Object.entries(DEV_AI_PROVIDERS)) {
+        const settings = {};
+        for (const name of aiProviderSettings(spec)) {
+            const value = env[name];
+            if (typeof value === "string" && value.trim()) {
+                settings[name] = value.trim();
+            }
+        }
+        const key = settings[spec.keyEnv];
+        // A provider is reachable only with every setting it needs.
+        if (!key || Object.keys(settings).length < aiProviderSettings(spec).length)
+            continue;
+        providers[provider] = { key, basePath: spec.basePath?.(settings) ?? "" };
+    }
+    return providers;
+}
+function directProviderPath(input, env) {
     const incoming = new URL(input);
-    if (incoming.pathname !== OPENAI_PROXY_PREFIX &&
-        !incoming.pathname.startsWith(`${OPENAI_PROXY_PREFIX}/`)) {
-        throw new ConfigurationError(`Direct local provider fallback only supports ${OPENAI_PROXY_PREFIX} paths.`);
+    const match = incoming.pathname.match(/^\/api\/ai\/([a-z][a-z0-9-]*)(\/.*)?$/);
+    let provider = match?.[1];
+    let path = match?.[2] || "/";
+    let fillModel = null;
+    if (provider === AI_DEFAULT_PROVIDER) {
+        // The default in dev, by the gateway's rule on the developer's own
+        // `.dev.vars`: the first provider of the order with every setting set,
+        // with its seed models (dev has no operator settings; a request that
+        // names a model sends it as it is).
+        const values = env;
+        const resolution = resolveAiDefault({
+            provider: null,
+            isSet: (name) => typeof values[name] === "string" &&
+                values[name].trim().length > 0,
+        });
+        if (!resolution.configured) {
+            throw new ConfigurationError(`Set ${resolution.settings.join(" and ")} (or another model provider's key) in .dev.vars to call the default model in local development.`, {
+                code: "ai_default_not_configured",
+                settings: resolution.settings,
+            });
+        }
+        const route = path === AI_DEFAULT_ROUTES.chat
+            ? resolution.chat
+            : path === AI_DEFAULT_ROUTES.embeddings
+                ? resolution.embeddings
+                : undefined;
+        if (!route) {
+            throw new ConfigurationError(`The default model serves ${AI_DEFAULT_ROUTES.chat} and ${AI_DEFAULT_ROUTES.embeddings} only; call /api/ai/<provider>/… for anything else.`);
+        }
+        provider = resolution.provider;
+        path = route.path;
+        fillModel =
+            route === resolution.chat
+                ? resolution.model
+                : (resolution.embeddingsModel ?? null);
     }
-    const upstreamPath = incoming.pathname.slice(OPENAI_PROXY_PREFIX.length) || "/";
-    if (!upstreamPath.startsWith("/") || upstreamPath.startsWith("//")) {
-        throw new ConfigurationError("Invalid OpenAI proxy path.");
+    const spec = provider
+        ? devAiProvider(provider, env)
+        : undefined;
+    if (!provider || !spec) {
+        throw new ConfigurationError(`Direct local provider fallback only supports ${listOf([AI_DEFAULT_PROVIDER, ...Object.keys(DEV_AI_PROVIDERS)].map((name) => `${AI_PROXY_PREFIX}${name}`), "and")} paths.`);
     }
-    const upstream = new URL(OPENAI_UPSTREAM_ORIGIN);
-    upstream.pathname = upstreamPath;
-    upstream.search = incoming.search;
-    return upstream.toString();
+    if (path.startsWith("//") || path.includes("\\")) {
+        throw new ConfigurationError("Invalid provider proxy path.");
+    }
+    return { provider, spec, path, search: incoming.search, fillModel };
+}
+/** A provider's settings as a person reads them: `KEY`, or `KEY and SETTING`. */
+function settingsNames(spec, conjunction = "and") {
+    const [key, ...others] = aiProviderSettings(spec);
+    return others.length
+        ? `${key} ${conjunction} ${listOf(others, "and")}`
+        : key;
+}
+/** `a`, `a and b`, `a, b and c`. */
+function listOf(items, conjunction) {
+    return items.length < 2
+        ? (items[0] ?? "")
+        : `${items.slice(0, -1).join(", ")} ${conjunction} ${items.at(-1)}`;
 }
 function canIncludeBody(method) {
     const normalized = method.toUpperCase();

package/dist/server/gatewayUrl.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The Gateway's URL, with `path` on it: `gatewayUrl(env)` for the launcher,
+ * `gatewayUrl(env, "/admin/users")` for the page where owners and admins
+ * invite people.
+ *
+ * Read from `env.GATEWAY_URL`, which the deploy sets on every Worker of the
+ * app and `everyapp dev` sets to its local launcher, so the same link works
+ * in both. `env` is the Worker's env (any object; only `GATEWAY_URL` is
+ * read). Throws {@link ConfigurationError} when it is unset or not an http(s)
+ * URL: a Worker no deploy or `everyapp dev` built.
+ */
+export declare function gatewayUrl(env: object, path?: string): string;
+//# sourceMappingURL=gatewayUrl.d.ts.map

package/dist/server/gatewayUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatewayUrl.d.ts","sourceRoot":"","sources":["../../src/server/gatewayUrl.ts"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,MAAM,CAgB1D"}

package/dist/server/gatewayUrl.js

@@ -0,0 +1,34 @@
+/**
+ * `gatewayUrl()`: the one rule for a link from an app back to its Gateway
+ * ("‹ Every App", "Invite people", "Sign out").
+ */
+import { ConfigurationError } from "../internal/index.js";
+/** Where the Gateway is: the deploy sets it, and so does `everyapp dev`. */
+const GATEWAY_URL_ENV = "GATEWAY_URL";
+/**
+ * The Gateway's URL, with `path` on it: `gatewayUrl(env)` for the launcher,
+ * `gatewayUrl(env, "/admin/users")` for the page where owners and admins
+ * invite people.
+ *
+ * Read from `env.GATEWAY_URL`, which the deploy sets on every Worker of the
+ * app and `everyapp dev` sets to its local launcher, so the same link works
+ * in both. `env` is the Worker's env (any object; only `GATEWAY_URL` is
+ * read). Throws {@link ConfigurationError} when it is unset or not an http(s)
+ * URL: a Worker no deploy or `everyapp dev` built.
+ */
+export function gatewayUrl(env, path = "/") {
+    const value = env[GATEWAY_URL_ENV];
+    let base;
+    if (typeof value === "string" && value) {
+        try {
+            base = new URL(value);
+        }
+        catch {
+            base = undefined;
+        }
+    }
+    if (!base || (base.protocol !== "https:" && base.protocol !== "http:")) {
+        throw new ConfigurationError(`${GATEWAY_URL_ENV} is ${value ? "not an http(s) URL" : "unset"}: everyapp deploy and everyapp dev set it on the app's Worker.`);
+    }
+    return new URL(path, base.origin).toString();
+}

package/dist/server/index.d.ts

@@ -3,7 +3,27 @@
  *
  * There is intentionally no client-side export.
  */
-export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, requireEveryAppUser, type EveryAppOptions, type EveryAppManifestLike, type EveryAppHandler, type EveryAppUser, type IdentityResult, } from "./everyApp.js";
-export { createGatewayFetch, type CreateGatewayFetchOptions, type GatewayFetchEnv, } from "./gatewayFetch.js";
-export { createMcpHandler, type CreateMcpHandlerOptions, type McpToolContext, type McpToolDefinition, type McpRequestHandler, } from "./mcp.js";
+export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, isAdmin, requireCurrentUser, requireEveryAppUser, type EveryAppOptions, type EveryAppManifestLike, type EveryAppHandler, type EveryAppUser, type IdentityResult, type OrgRole, } from "./everyApp.js";
+export { OrganizationMismatchError, RequestContextError, currentUser, withOrganization, } from "./context.js";
+export { AttributionError, type GatewayCallFor } from "./attribution.js";
+export { gatewayUrl } from "./gatewayUrl.js";
+export type { EveryAppEnv } from "./env.js";
+/** The header a Gateway refusal carries its code in; `gatewayRefusal()` reads the rest. */
+export { GATEWAY_ERROR_HEADER } from "../internal/protocol.js";
+export { authorizeUrl, type AuthorizeUrlOptions } from "./authorizeUrl.js";
+export { connectPath, connectUrl, type ConnectUrlOptions, } from "./connectUrl.js";
+export { createGatewayFetch, type CreateGatewayFetchOptions, } from "./gatewayFetch.js";
+export { ai, aiBaseUrl, aiStatus, providerBaseUrl, AI_DEFAULT_BASE_URL, type AiClient, type AiStatus, } from "./ai.js";
+export { AI_NOT_CONFIGURED_CODES, GatewayRefusalError, gatewayRefusal, isAiNotConfigured, refusalFromError, type GatewayRefusal, type SetupInfo, } from "./refusal.js";
+export { devAccessTokenName, integrationFetch, integrationStatus, type EmailIntegrationStatus, type IntegrationFetchOptions, type IntegrationStatus, type IntegrationStatusOf, type OAuthClientIntegrationStatus, } from "./integrationFetch.js";
+export { nodeServerHandler, type NodeServer, type NodeServerHandlerOptions, } from "./nodeServer.js";
+export { sendEmail, type SendEmailOptions } from "./sendEmail.js";
+export { gatewayAiBinding, type GatewayAiBindingOptions } from "./aiBinding.js";
+export { gatewayEmailBinding, type GatewayEmailBindingMessage, type GatewayEmailBindingOptions, } from "./emailBinding.js";
+export { listMembers, type ListMembersOptions } from "./listMembers.js";
+export { emit, type EmitOptions } from "./emit.js";
+export type { ApiKeyCapabilityId, CapabilityId, OAuthClientCapabilityId, ConnectionAccount, EmailAddressInput, EmailAttachmentInput, SendEmailMessage, SendEmailResult, ListMembersResult, OrganizationMember, OrganizationMemberRole, EmitEventResult, } from "../internal/index.js";
+export { ToolError, defineTools, toolResult, type DefineToolsOptions, type PlainToolSchema, type StandardSchemaWithJSON, type ToolContext, type ToolDefinition, type ToolResult, type ToolSchema, type ToolSet, } from "./tools.js";
+export type { ToolRisk } from "../internal/index.js";
+export { fromMcpTools, type FromMcpToolsOptions, type McpToolAnnotationsLike, type McpToolLike, type McpToolResultLike, type McpToolSchemaLike, } from "./fromMcpTools.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}