@every-app/sdk 0.3.0-rc.1 → 0.3.0-rc.11

package/dist/server/everyApp.js

@@ -13,11 +13,24 @@
  * `everyapp.config.ts` (the Cloudflare Vite plugin hides every file
  * `cloudflare.config.ts` imports from the Worker in dev).
  * It also answers the gateway's internal tools contract
- * (`/__everyapp/tools/*`) for the app's `defineTools()` catalog.
+ * (`/__everyapp/tools/*`) for the app's `defineTools()` catalog, and the
+ * event sink's deliveries (`/__everyapp/events`) for `events: { on }`.
+ *
+ * Around the handler and around each tool call it opens the request
+ * context (context.ts): `currentUser()` reads the user anywhere below, and
+ * every call back to the Gateway is attributed to the request without a
+ * `for`. A deployed Worker is pinned to its organization
+ * (`EVERY_APP_ORG_ID`), and an identity for any other is refused on both
+ * paths. The response leaves without `Set-Cookie`: the perimeter strips
+ * every `Cookie` before a request reaches the app, so a cookie the app's
+ * framework sets could never come back, and one named like the Gateway's
+ * session cookie would lock the person out of the app host.
  */
-import { APP_ID_ENV, AUDIENCE_ENV, ConfigurationError, DEV_ENV, IdentityError, ISSUER_ENV, PUBLIC_KEYS_ENV, getIdentityFromRequest, } from "../internal/index.js";
+import { APP_ID_ENV, AUDIENCE_ENV, ConfigurationError, DEV_ENV, IdentityError, IDENTITY_HEADER, ISSUER_ENV, ORG_ID_ENV, PUBLIC_KEYS_ENV, getIdentityFromRequest, isAdmin, isAgentCall, } from "../internal/index.js";
+import { currentUser, serveRequest } from "./context.js";
 import { handleToolsRequest } from "./toolsEndpoint.js";
-export { ConfigurationError, IdentityError };
+import { handleEventsRequest, } from "./eventsEndpoint.js";
+export { ConfigurationError, IdentityError, isAdmin, isAgentCall };
 const requestIdentities = new WeakMap();
 function envValue(env, key) {
     if (!env || typeof env !== "object")
@@ -68,6 +81,17 @@ function audienceFor(env, config) {
         return appId;
     throw new ConfigurationError(`${AUDIENCE_ENV} is not set — the app's cloudflare.config.ts must declare it (everyAppWorker() does at deploy).`);
 }
+/**
+ * The organization a deployed Worker serves ({@link ORG_ID_ENV}), which an
+ * identity must name. Under the dev opt-in there is none to enforce: the
+ * stub gateway's one organization is the only one, and `everyapp dev
+ * --mode mirror` signs real organizations in.
+ */
+function pinnedOrganization(env, config) {
+    if (devIdentitiesAllowed(env, config))
+        return undefined;
+    return envValue(env, ORG_ID_ENV);
+}
 function unauthorized(message) {
     return Response.json({ error: "unauthenticated", message }, { status: 401 });
 }
@@ -77,6 +101,7 @@ function misconfigured(message) {
 function identityOptions(env, config, audience) {
     return {
         audience,
+        organizationId: pinnedOrganization(env, config),
         issuer: config.issuer ?? envValue(env, ISSUER_ENV),
         publicKeys: config.publicKeys,
         env: env,
@@ -91,15 +116,54 @@ async function resolveIdentity(request, env, config) {
 function rememberIdentity(request, identity) {
     requestIdentities.set(request, identity);
 }
+/**
+ * The user the request context already verified, when `request` carries
+ * the same identity token: a framework that rebuilds the request (TanStack
+ * Start's `getRequest()`, a Hono context) still gets the one verification.
+ */
+function contextUserFor(request) {
+    const headers = "headers" in request ? request.headers : request;
+    const token = headers.get(IDENTITY_HEADER);
+    if (!token)
+        return null;
+    const scoped = servedRequestToken();
+    return scoped && scoped.token === token ? scoped.user : null;
+}
+/**
+ * The served request's token and user, or null outside a request. Reads
+ * the context without throwing (currentUser() throws outside one).
+ */
+function servedRequestToken() {
+    let user;
+    try {
+        user = currentUser();
+    }
+    catch {
+        return null;
+    }
+    if (!user)
+        return null;
+    const served = servedRequests.get(user);
+    return served ? { token: served, user } : null;
+}
+// The identity token of each request everyApp() serves, by its user, so a
+// second read of the same token answers from the context.
+const servedRequests = new WeakMap();
 /**
  * Return the verified Every App user for this request, or null for a declared
- * public request. Uses the request cache first, then verifies the identity
- * headers from the app id and public keys configured in env.
+ * public request. `request` is the inbound `Request` or just its `Headers`
+ * (a framework that hands out headers alone needs no made-up Request).
+ * Answers from the request context or the per-request cache first, then
+ * verifies the identity headers from the audience and public keys in env.
+ * Inside a handler `everyApp()` serves, `currentUser()` is the shorter way.
  */
 export async function getEveryAppUser(request, env) {
     const cached = requestIdentities.get(request);
     if (cached)
         return cached.user;
+    const fromContext = contextUserFor(request);
+    if (fromContext)
+        return fromContext;
     const identity = await resolveIdentity(request, env, {
         keysEnvVar: PUBLIC_KEYS_ENV,
     });
@@ -125,6 +189,40 @@ export async function requireEveryAppUser(request, env) {
         throw error;
     }
 }
+/**
+ * The user of the request being served (`currentUser()`), or throw the
+ * same 401 JSON Response as `requireEveryAppUser()` on a public route.
+ * Outside a request (`withOrganization()` work, a handler not under
+ * `everyApp()`) it throws `RequestContextError`, as `currentUser()` does.
+ */
+export function requireCurrentUser() {
+    const user = currentUser();
+    if (!user) {
+        throw unauthorized("this request does not have an authenticated user");
+    }
+    return user;
+}
+/**
+ * `response` without `Set-Cookie`: the perimeter strips every `Cookie`
+ * before a request reaches the app, so no cookie the app sets ever comes
+ * back, and one named like the Gateway's session cookie locks the person
+ * out of the app host (the perimeter refuses a session cookie sent twice).
+ * A WebSocket handshake (101) passes as it is: it can't be rebuilt from
+ * its body, and the perimeter drops its cookies' `Domain`.
+ */
+function withoutCookies(response) {
+    if (response.status === 101 || !response.headers.has("set-cookie")) {
+        return response;
+    }
+    console.warn("[everyapp] Dropped a Set-Cookie header: the Gateway never sends an app's cookies back to it.");
+    const headers = new Headers(response.headers);
+    headers.delete("set-cookie");
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
 export function hasScope(user, scope) {
     return user.scopes.includes("*") || user.scopes.includes(scope);
 }
@@ -165,6 +263,13 @@ export function everyApp(handler, manifestOrOptions, legacyOptions = {}) {
             });
             if (toolsResponse)
                 return toolsResponse;
+            // So does the event sink's delivery path (`/__everyapp/events`).
+            const eventsResponse = await handleEventsRequest(request, env, ctx, {
+                events: options.events,
+                identity: identityOptions(env, config, audience),
+            });
+            if (eventsResponse)
+                return eventsResponse;
             let identity;
             try {
                 identity = await getIdentityFromRequest(request, identityOptions(env, config, audience));
@@ -179,7 +284,12 @@ export function everyApp(handler, manifestOrOptions, legacyOptions = {}) {
                     return unauthorized(err.message);
                 throw err;
             }
-            return handler(request, env, ctx, identity.user);
+            const { user, expiresAt } = identity;
+            if (user) {
+                servedRequests.set(user, request.headers.get(IDENTITY_HEADER) ?? "");
+            }
+            const response = await serveRequest({ request, user, expiresAt }, () => handler(request, env, ctx, user));
+            return withoutCookies(response);
         },
     };
 }

package/dist/server/fromMcpTools.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `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 { type ToolRisk } from "../internal/index.js";
+import { type StandardSchemaWithJSON, type ToolContext, type ToolDefinition, type ToolSchema } from "./tools.js";
+/** MCP tool annotations (all hints); only these are read. */
+export interface McpToolAnnotationsLike {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** An MCP `CallToolResult`, structurally. */
+export interface McpToolResultLike {
+    content?: ReadonlyArray<{
+        readonly type: string;
+    }>;
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+/**
+ * A tool schema as MCP servers write one: a {@link ToolSchema} (a full zod
+ * object, `{ jsonSchema, validate }`), a raw shape of Standard Schemas
+ * (`{ query: z.string() }`, what `McpServer.registerTool` takes), or a plain
+ * JSON Schema object (a low-level server's `tools/list`), which is described
+ * but not validated: the handler checks its own arguments, as it did before.
+ */
+export type McpToolSchemaLike = ToolSchema | Readonly<Record<string, StandardSchemaWithJSON>> | Readonly<Record<string, unknown>>;
+/** One MCP tool: `registerTool`'s name, config and handler, flattened. */
+export interface McpToolLike<TExtra = ToolContext> {
+    name: string;
+    title?: string;
+    description?: string;
+    /** Omitted: the tool takes no arguments. */
+    inputSchema?: McpToolSchemaLike;
+    outputSchema?: McpToolSchemaLike;
+    annotations?: McpToolAnnotationsLike;
+    /**
+     * Called with the validated arguments and the value of
+     * {@link FromMcpToolsOptions.context} (the call's {@link ToolContext} by
+     * default). Return a `CallToolResult`; throw {@link ToolError} for a message
+     * the model may read.
+     */
+    handler: (args: never, extra: TExtra) => McpToolResultLike | Promise<McpToolResultLike>;
+}
+export interface FromMcpToolsOptions<TExtra = ToolContext> {
+    /**
+     * What each handler gets as its second argument, built per call from the
+     * verified caller (`user`, `env`, `request`, `callId`). Default: the
+     * {@link ToolContext} itself.
+     */
+    context?: (context: ToolContext) => TExtra | Promise<TExtra>;
+    /**
+     * A tool's risk, overriding the default for the tools it returns a risk
+     * for. Default: `readOnlyHint: true` is `read`, `destructiveHint: true`
+     * is `destructive`, anything else `write`.
+     */
+    risk?: (tool: McpToolLike<TExtra>) => ToolRisk | undefined;
+}
+/**
+ * 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 declare function fromMcpTools<TExtra = ToolContext>(tools: Iterable<McpToolLike<TExtra>>, options?: FromMcpToolsOptions<TExtra>): Record<string, ToolDefinition>;
+//# sourceMappingURL=fromMcpTools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fromMcpTools.d.ts","sourceRoot":"","sources":["../../src/server/fromMcpTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAqB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAIpB,6DAA6D;AAC7D,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,GAChD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtC,0EAA0E;AAC1E,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC;;;;;OAKG;IACH,OAAO,EAAE,CACP,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,MAAM,KACV,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,mBAAmB,CAAC,MAAM,GAAG,WAAW;IACvD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,QAAQ,GAAG,SAAS,CAAC;CAC5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAG,WAAW,EAC/C,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EACpC,OAAO,GAAE,mBAAmB,CAAC,MAAM,CAAM,GACxC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA+ChC"}

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

@@ -3,27 +3,48 @@ 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;
-    /** `1` on a shared app's Workers (`everyAppWorker()` sets it). */
-    EVERYAPP_SHARED?: string;
-    OPENAI_API_KEY?: string;
-    OPENROUTER_API_KEY?: string;
-    /** Workers AI: an API token (Workers AI Read and Edit) and the account it bills. */
-    WORKERS_AI_API_TOKEN?: string;
-    CLOUDFLARE_ACCOUNT_ID?: 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;
     /**
-     * Whom the call is for: the inbound request (its user), or
-     * `{ background: true, organizationId }` for work no person started
-     * (crons, Workflows, queues). An organization's own app may omit it for
-     * background work, which is then the app's; a shared app's Worker must
-     * pass one or the other ({@link AttributionError}).
+     * 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 a fetch for the gateway's AI providers (`/api/ai/<provider>/…`),
@@ -31,7 +52,10 @@ export interface CreateGatewayFetchOptions {
  * developer's own provider key from `.dev.vars` is a direct-provider
  * fallback when no binding exists.
  */
-export declare function createGatewayFetch({ env, for: target, }: CreateGatewayFetchOptions): typeof fetch;
+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":"AASA,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,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,eAAe,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,GAAG,EACH,GAAG,EAAE,MAAM,GACZ,EAAE,yBAAyB,GAAG,OAAO,KAAK,CA8D1C;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,GACf,OAAO,CAUT"}
+{"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"}