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

package/dist/internal/tools.js

@@ -0,0 +1,80 @@
+/**
+ * The internal tools contract (v1) between the gateway's ToolBus and an app's
+ * `everyApp()` wrapper. Two reserved endpoints, reached only over the
+ * gateway's service binding and never public:
+ *
+ *   POST /__everyapp/tools/list  x-everyapp-system JWT (purpose "tools.list")
+ *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp" + tc claim
+ *
+ * MCP itself (protocol eras, headers, envelopes) stays in the gateway; apps
+ * only ever speak this small versioned JSON shape. Both sides import the
+ * shapes, paths and the catalog hash from here so they cannot drift.
+ */
+export const TOOLS_PROTOCOL_VERSION = 1;
+export const TOOLS_PATH_PREFIX = "/__everyapp/tools";
+export const TOOLS_LIST_PATH = `${TOOLS_PATH_PREFIX}/list`;
+export const TOOLS_CALL_PATH = `${TOOLS_PATH_PREFIX}/call`;
+export const TOOL_RISKS = ["read", "write", "destructive"];
+/** Scopes the gateway mints on `chan: "mcp"` identities, one per risk. */
+export const MCP_READ_SCOPE = "mcp:read";
+export const MCP_WRITE_SCOPE = "mcp:write";
+/** Never minted in v1: destructive tools are hidden until approvals exist. */
+export const MCP_DESTRUCTIVE_SCOPE = "mcp:destructive";
+/** Local tool names: lowercase snake_case, at most 48 characters. */
+export const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{0,47}$/;
+export function isToolRisk(value) {
+    return (typeof value === "string" &&
+        TOOL_RISKS.includes(value));
+}
+/** The exact scope a `chan: "mcp"` identity must carry to call a tool. */
+export function requiredScopeForRisk(risk) {
+    switch (risk) {
+        case "read":
+            return MCP_READ_SCOPE;
+        case "write":
+            return MCP_WRITE_SCOPE;
+        case "destructive":
+            return MCP_DESTRUCTIVE_SCOPE;
+    }
+}
+/**
+ * JSON with object keys sorted at every depth, so equal values always
+ * serialize identically. `undefined` members are dropped, as JSON.stringify
+ * does.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (!value || typeof value !== "object")
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        const member = value[key];
+        if (member !== undefined)
+            sorted[key] = sortKeys(member);
+    }
+    return sorted;
+}
+/**
+ * `sha256:<hex>` over the canonical JSON of a catalog. The SDK reports it with
+ * every list and call; the gateway stores it at sync and re-syncs when a call
+ * reports a different one.
+ */
+export async function catalogHash(catalog) {
+    const canonical = canonicalJson({
+        instructions: catalog.instructions ?? null,
+        tools: catalog.tools,
+    });
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+    return `sha256:${toHex(digest)}`;
+}
+function toHex(buffer) {
+    let out = "";
+    for (const byte of new Uint8Array(buffer)) {
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}

package/dist/server/attribution.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Whom a call through the gateway is for, which decides the organization
+ * it counts against:
+ *
+ *  - the inbound `Request`: its person, by the identity the gateway put on
+ *    it (forwarded as is);
+ *  - `{ background: true, organizationId }`: work no request started (a
+ *    cron, a Workflow step, a queue). A shared app's Worker serves every
+ *    organization, so it names the one the work is for, which the gateway
+ *    checks is active and has a live member. An organization's own app may
+ *    leave it out (the gateway knows its organization) and may only name
+ *    its own.
+ */
+export type GatewayCallFor = Request | {
+    background: true;
+    organizationId?: string;
+};
+/**
+ * A gateway call that doesn't say whom it is for where it must: from a
+ * shared app's Worker, with neither the request nor an organization.
+ */
+export declare class AttributionError extends Error {
+    readonly code = "attribution_required";
+    constructor(message: string);
+}
+/**
+ * Check `target` before any call is made: a shared app's Worker must pass
+ * the request or name the organization, and anything else passed must be
+ * one of the two shapes.
+ */
+export declare function checkAttribution(env: object, target: GatewayCallFor | undefined, what: string): void;
+/**
+ * Put the call's attribution on its headers: the request's identity, or the
+ * background work's organization, and never one the app set itself.
+ */
+export declare function applyAttribution(headers: Headers, target: GatewayCallFor | undefined): void;
+/** Whether `for` is the inbound request (rather than background work). */
+export declare function isRequest(value: unknown): value is Request;
+//# sourceMappingURL=attribution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,GACP;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,0BAA0B;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,IAAI,CAsBN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,IAAI,CAUN;AASD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO1D"}

package/dist/server/attribution.js

@@ -0,0 +1,67 @@
+import { IDENTITY_HEADER, ORG_HEADER, SHARED_ENV } from "../internal/index.js";
+/**
+ * A gateway call that doesn't say whom it is for where it must: from a
+ * shared app's Worker, with neither the request nor an organization.
+ */
+export class AttributionError extends Error {
+    code = "attribution_required";
+    constructor(message) {
+        super(message);
+        this.name = "AttributionError";
+    }
+}
+/**
+ * Check `target` before any call is made: a shared app's Worker must pass
+ * the request or name the organization, and anything else passed must be
+ * one of the two shapes.
+ */
+export function checkAttribution(env, target, what) {
+    if (target !== undefined && !isRequest(target)) {
+        if (target === null || typeof target !== "object" || !target.background) {
+            throw new AttributionError(`${what}: \`for\` is the inbound Request or { background: true, organizationId }.`);
+        }
+        if (target.organizationId !== undefined &&
+            !nonEmpty(target.organizationId)) {
+            throw new AttributionError(`${what}: { background: true, organizationId } needs a non-empty organization id.`);
+        }
+    }
+    if (!isSharedWorker(env))
+        return;
+    if (target === undefined || (!isRequest(target) && !target.organizationId)) {
+        throw new AttributionError(`${what} in a shared app's Worker serves every organization, so it must say whom the call is for: for: request, or for: { background: true, organizationId } for work no request started.`);
+    }
+}
+/**
+ * Put the call's attribution on its headers: the request's identity, or the
+ * background work's organization, and never one the app set itself.
+ */
+export function applyAttribution(headers, target) {
+    headers.delete(IDENTITY_HEADER);
+    headers.delete(ORG_HEADER);
+    if (target === undefined)
+        return;
+    if (isRequest(target)) {
+        const identity = target.headers.get(IDENTITY_HEADER);
+        if (identity)
+            headers.set(IDENTITY_HEADER, identity);
+        return;
+    }
+    if (target.organizationId)
+        headers.set(ORG_HEADER, target.organizationId);
+}
+function isSharedWorker(env) {
+    const value = env[SHARED_ENV];
+    return value === "1" || value === "true" || value === true;
+}
+// Duck-typed: a Request from another realm (a test runner, a polyfill) is
+// still the request.
+/** Whether `for` is the inbound request (rather than background work). */
+export function isRequest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "headers" in value &&
+        typeof value.headers?.get === "function");
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist/server/authorizeUrl.d.ts

@@ -0,0 +1,43 @@
+import { type OAuthClientCapabilityId } from "../internal/index.js";
+import type { OAuthClientIntegrationStatus } from "./integrationFetch.js";
+export interface AuthorizeUrlOptions {
+    /** The OAuth client, as listed in the manifest's `capabilities`. */
+    provider: OAuthClientCapabilityId;
+    /** What `integrationStatus()` answered for it, ready and with its `clientId`. */
+    status: OAuthClientIntegrationStatus;
+    /** One of the redirect URIs the operator registered on the client. */
+    redirectUri: string;
+    /** The app's own anti-forgery value, checked when the person comes back. */
+    state: string;
+    /** PKCE: the S256 challenge of the verifier the app keeps for the exchange. */
+    codeChallenge?: string;
+    /**
+     * The provider's extras (`prompt`, `login_hint`, Google's `hd`). Never
+     * one of the parameters this helper sets (PKCE's and the provider's own
+     * included), nor Google's `include_granted_scopes`.
+     */
+    params?: Record<string, string>;
+}
+/**
+ * The provider's authorize URL to send a person to, for a client with
+ * scope sets (`google-workspace`, `microsoft-365`, `slack`), built from the
+ * capability's status: the registry's authorize endpoint (or the instance
+ * the status names), `client_id`, `response_type=code`, `redirect_uri`,
+ * `state`, and the scopes the status allows this app, which are exactly
+ * what the gateway will let the token carry. Each provider's own needs
+ * are added: Google's `access_type=offline` (a refresh token), Microsoft's
+ * `response_mode=query`, Slack's comma-joined `scope` and its `user_scope`
+ * (the status's `userScopes`, when the app's sets include a user set). With
+ * `codeChallenge`, PKCE as S256. The app keeps its `state` and verifier
+ * for the callback.
+ *
+ * A client without scope sets (LinkedIn, Mastodon, ...) is refused: the
+ * registry's checklist for one isn't what the gateway holds a token to,
+ * so an app builds that URL itself from the status's `clientId`.
+ *
+ * Throws a `TypeError` naming the fix when the client has no scope sets,
+ * when the status isn't ready or has no `clientId`, when the status lacks
+ * `scopes`, or when `params` names a parameter the helper sets.
+ */
+export declare function authorizeUrl({ provider, status, redirectUri, state, codeChallenge, params, }: AuthorizeUrlOptions): URL;
+//# sourceMappingURL=authorizeUrl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authorizeUrl.d.ts","sourceRoot":"","sources":["../../src/server/authorizeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,QAAQ,EAAE,uBAAuB,CAAC;IAClC,iFAAiF;IACjF,MAAM,EAAE,4BAA4B,CAAC;IACrC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAgCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,MAAM,EACN,WAAW,EACX,KAAK,EACL,aAAa,EACb,MAAM,GACP,EAAE,mBAAmB,GAAG,GAAG,CA2D3B"}

package/dist/server/authorizeUrl.js

@@ -0,0 +1,110 @@
+import { CAPABILITIES, ConfigurationError, } from "../internal/index.js";
+/**
+ * Parameters the helper owns: the status decides the scopes, the caller's
+ * other arguments decide the rest (PKCE from `codeChallenge`, always as
+ * S256), each provider's own are fixed (Google's `access_type=offline` is
+ * what gets a refresh token, Microsoft's `response_mode=query` is what
+ * the callback reads), and Google's `include_granted_scopes` would widen
+ * the token to every scope the person ever granted this client, which the
+ * gateway refuses (`integration_scope_exceeded`).
+ */
+const RESERVED_PARAMS = [
+    "scope",
+    "user_scope",
+    "client_id",
+    "redirect_uri",
+    "state",
+    "response_type",
+    "code_challenge",
+    "code_challenge_method",
+    "access_type",
+    "response_mode",
+    "include_granted_scopes",
+];
+/** The OAuth clients with scope sets: the ones this helper builds for. */
+function scopedClientIds() {
+    return Object.entries(CAPABILITIES)
+        .filter(([, found]) => found.mode === "oauth_client" && found.scopePolicy)
+        .map(([id]) => id);
+}
+/**
+ * The provider's authorize URL to send a person to, for a client with
+ * scope sets (`google-workspace`, `microsoft-365`, `slack`), built from the
+ * capability's status: the registry's authorize endpoint (or the instance
+ * the status names), `client_id`, `response_type=code`, `redirect_uri`,
+ * `state`, and the scopes the status allows this app, which are exactly
+ * what the gateway will let the token carry. Each provider's own needs
+ * are added: Google's `access_type=offline` (a refresh token), Microsoft's
+ * `response_mode=query`, Slack's comma-joined `scope` and its `user_scope`
+ * (the status's `userScopes`, when the app's sets include a user set). With
+ * `codeChallenge`, PKCE as S256. The app keeps its `state` and verifier
+ * for the callback.
+ *
+ * A client without scope sets (LinkedIn, Mastodon, ...) is refused: the
+ * registry's checklist for one isn't what the gateway holds a token to,
+ * so an app builds that URL itself from the status's `clientId`.
+ *
+ * Throws a `TypeError` naming the fix when the client has no scope sets,
+ * when the status isn't ready or has no `clientId`, when the status lacks
+ * `scopes`, or when `params` names a parameter the helper sets.
+ */
+export function authorizeUrl({ provider, status, redirectUri, state, codeChallenge, params, }) {
+    const capability = oauthClientCapability(provider);
+    if (!capability.scopePolicy) {
+        throw new TypeError(`authorizeUrl() builds URLs for clients with scope sets (${scopedClientIds().join(", ")}); build ${capability.label}'s authorize URL yourself from the status's clientId.`);
+    }
+    if (!status.ready || !status.clientId) {
+        throw new TypeError(`authorizeUrl(${JSON.stringify(provider)}) needs a ready status with a clientId, and integrationStatus() answered ready: ${String(status.ready)}. Show ${capability.label} as not available instead: its operator sets the client up on the gateway, and an app lists the scope sets it uses in everyapp.config.ts.`);
+    }
+    if (!status.scopes) {
+        throw new TypeError(`authorizeUrl(${JSON.stringify(provider)}) takes ${capability.label}'s scopes from integrationStatus().scopes, which this status lacks: pass the status as the gateway (or everyapp dev) answered it.`);
+    }
+    for (const name of Object.keys(params ?? {})) {
+        if (!RESERVED_PARAMS.includes(name))
+            continue;
+        throw new TypeError(name === "include_granted_scopes"
+            ? `authorizeUrl(${JSON.stringify(provider)}): include_granted_scopes would widen the token to every scope the person granted this client, which the gateway refuses (integration_scope_exceeded); leave it out of params.`
+            : `authorizeUrl(${JSON.stringify(provider)}) sets ${name} itself; leave it out of params.`);
+    }
+    const base = status.origin ?? capability.defaultOrigin;
+    if (!/^https:/.test(capability.authorize.url) && !base) {
+        throw new TypeError(`authorizeUrl(${JSON.stringify(provider)}) needs the instance ${capability.label} is on: the status carries it as origin once ${capability.hostSetting} is set.`);
+    }
+    const url = new URL(capability.authorize.url, base);
+    // The status speaks for the gateway: its scopes are the token's ceiling.
+    const scopes = status.scopes;
+    const slack = url.host === "slack.com";
+    url.searchParams.set("client_id", status.clientId);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("state", state);
+    url.searchParams.set("scope", scopes.join(slack ? "," : " "));
+    if (status.userScopes && status.userScopes.length > 0) {
+        url.searchParams.set("user_scope", status.userScopes.join(","));
+    }
+    if (codeChallenge) {
+        url.searchParams.set("code_challenge", codeChallenge);
+        url.searchParams.set("code_challenge_method", "S256");
+    }
+    if (url.host === "accounts.google.com") {
+        // Without it Google issues no refresh token.
+        url.searchParams.set("access_type", "offline");
+    }
+    else if (url.host === "login.microsoftonline.com") {
+        url.searchParams.set("response_mode", "query");
+    }
+    for (const [name, value] of Object.entries(params ?? {})) {
+        url.searchParams.set(name, value);
+    }
+    return url;
+}
+/** The OAuth client `provider` names, from plain JavaScript or a stale type too. */
+function oauthClientCapability(provider) {
+    const found = Object.hasOwn(CAPABILITIES, provider)
+        ? CAPABILITIES[provider]
+        : undefined;
+    if (found?.mode !== "oauth_client") {
+        throw new ConfigurationError(`${JSON.stringify(String(provider))} isn't an OAuth client the gateway holds.`);
+    }
+    return found;
+}

package/dist/server/emit.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `emit()`: an app's own event onto the gateway's event bus
+ * (docs/design/2026-10-events-out.md, section 7). It is shaped like
+ * `sendEmail()` on purpose: the same `{ env, for }` attribution, the same
+ * route over the EVERY_APP_GATEWAY binding, the same refusals thrown as
+ * `GatewayRefusalError`, and the same local-dev twin that checks what the
+ * gateway would check and prints instead of sending. The name and data
+ * rules live in `internal/events.ts`, which the gateway reads too, so the
+ * two can't drift.
+ */
+import { type EmitEventResult } from "../internal/index.js";
+import { type GatewayCallFor } from "./attribution.js";
+export interface EmitOptions {
+    /** The Worker env: the EVERY_APP_GATEWAY binding when deployed; EVERYAPP_DEV in local dev. */
+    env: object;
+    /**
+     * Whom the event is about: the inbound request (its user becomes the
+     * event's actor), or `{ background: true, organizationId }` for work no
+     * person started (a cron, a queue, a provider's webhook). An
+     * organization's own app may omit it for background work; a shared app's
+     * Worker must pass one or the other ({@link AttributionError}).
+     */
+    for?: GatewayCallFor;
+    /**
+     * The app's own name for what happened: lowercase letters, digits and
+     * underscores in dotted segments (`invoice.paid`, `todo.completed`), at
+     * most 64 characters. The gateway delivers it as `app.<app id>.<event>`.
+     */
+    event: string;
+    /**
+     * What a subscriber needs to act on it: a JSON object, at most 8 KiB
+     * serialized, nested at most 8 levels. Ids, names, amounts and states;
+     * never a credential. A key named like one at any depth (`token`,
+     * `secret`, `password`, `apiKey`, `session`, `cookie`, ...) is refused.
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * Put an event on the gateway's event bus, for the organization's webhook
+ * and email subscribers. The gateway names it `app.<app id>.<event>`, so an
+ * app can never emit one of the gateway's own types (`member.joined`);
+ * owners and admins choose `app.<app id>.*` (or one name) in Manage
+ * workspace, Events, or with `everyapp events add`. Nothing is declared in
+ * the manifest. Delivery happens after the call returns: a subscriber that
+ * is down doesn't slow or fail the app.
+ *
+ * `data` goes, as written, to every URL a subscriber chose (Slack, Zapier,
+ * an agent): put in it what a person or a workflow reads, never a
+ * credential, a session or a person's private content they didn't expect
+ * to leave the app. The gateway refuses a key named like a credential.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't take it
+ * (`event_name_invalid`, `event_data_invalid`, `event_data_refused`,
+ * `event_data_too_large`, `event_rate_limited` past 600 an hour, ...), with
+ * the code and a message to show. An emit that must never fail the work
+ * around it goes under `ctx.waitUntil()` or a `.catch()`.
+ *
+ * In local dev (`everyapp dev`, no binding) the event is checked the way
+ * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
+ * nothing is delivered.
+ */
+export declare function emit({ env, for: target, event, data, }: EmitOptions): Promise<EmitEventResult>;
+//# sourceMappingURL=emit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/server/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EASL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,IAAI,CAAC,EACzB,GAAG,EACH,GAAG,EAAE,MAAM,EACX,KAAK,EACL,IAAI,GACL,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAoBxC"}

package/dist/server/emit.js

@@ -0,0 +1,101 @@
+/**
+ * `emit()`: an app's own event onto the gateway's event bus
+ * (docs/design/2026-10-events-out.md, section 7). It is shaped like
+ * `sendEmail()` on purpose: the same `{ env, for }` attribution, the same
+ * route over the EVERY_APP_GATEWAY binding, the same refusals thrown as
+ * `GatewayRefusalError`, and the same local-dev twin that checks what the
+ * gateway would check and prints instead of sending. The name and data
+ * rules live in `internal/events.ts`, which the gateway reads too, so the
+ * two can't drift.
+ */
+import { APP_EVENT_DATA_MAX_BYTES, APP_ID_ENV, ConfigurationError, EVENTS_EMIT_PATH, appEventNameProblem, appEventType, checkEventData, } from "../internal/index.js";
+import { applyAttribution, checkAttribution, } from "./attribution.js";
+import { BINDING_ORIGIN } from "./gatewayFetch.js";
+import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
+/**
+ * Put an event on the gateway's event bus, for the organization's webhook
+ * and email subscribers. The gateway names it `app.<app id>.<event>`, so an
+ * app can never emit one of the gateway's own types (`member.joined`);
+ * owners and admins choose `app.<app id>.*` (or one name) in Manage
+ * workspace, Events, or with `everyapp events add`. Nothing is declared in
+ * the manifest. Delivery happens after the call returns: a subscriber that
+ * is down doesn't slow or fail the app.
+ *
+ * `data` goes, as written, to every URL a subscriber chose (Slack, Zapier,
+ * an agent): put in it what a person or a workflow reads, never a
+ * credential, a session or a person's private content they didn't expect
+ * to leave the app. The gateway refuses a key named like a credential.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't take it
+ * (`event_name_invalid`, `event_data_invalid`, `event_data_refused`,
+ * `event_data_too_large`, `event_rate_limited` past 600 an hour, ...), with
+ * the code and a message to show. An emit that must never fail the work
+ * around it goes under `ctx.waitUntil()` or a `.catch()`.
+ *
+ * In local dev (`everyapp dev`, no binding) the event is checked the way
+ * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
+ * nothing is delivered.
+ */
+export async function emit({ env, for: target, event, data, }) {
+    checkAttribution(env, target, "emit");
+    const values = env;
+    const binding = values["EVERY_APP_GATEWAY"];
+    if (binding) {
+        if (typeof binding.fetch !== "function") {
+            throw new ConfigurationError("EVERY_APP_GATEWAY is configured but is not a valid service binding.");
+        }
+        return emitThroughGateway(binding, target, { event, data });
+    }
+    if (!values["EVERYAPP_DEV"]) {
+        throw new ConfigurationError("Events are unavailable: deploy with the EVERY_APP_GATEWAY binding (everyapp deploy), or run under everyapp dev.");
+    }
+    return emitInDev(values, { event, data });
+}
+async function emitThroughGateway(binding, target, body) {
+    const headers = new Headers({ "content-type": "application/json" });
+    applyAttribution(headers, target);
+    const response = await binding.fetch(new Request(`${BINDING_ORIGIN}${EVENTS_EMIT_PATH}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    }));
+    const refusal = await gatewayRefusal(response);
+    if (refusal)
+        throw new GatewayRefusalError(refusal);
+    if (!response.ok) {
+        throw new GatewayRefusalError({
+            status: response.status,
+            code: "event_emit_failed",
+            message: `The Every App gateway answered ${response.status} to the event.`,
+        });
+    }
+    return (await response.json());
+}
+/**
+ * What the gateway would do, with no gateway: the same name and data
+ * rules, then one line on the console. The data isn't printed: it may hold
+ * a person's content, and the line is for "it fired", not for its payload.
+ */
+function emitInDev(values, { event, data }) {
+    const nameProblem = appEventNameProblem(event);
+    if (nameProblem) {
+        throw new GatewayRefusalError({
+            status: 400,
+            code: "event_name_invalid",
+            message: nameProblem,
+        });
+    }
+    const checked = checkEventData(data, APP_EVENT_DATA_MAX_BYTES);
+    if (!checked.ok) {
+        throw new GatewayRefusalError({
+            status: checked.code === "event_data_too_large" ? 413 : 400,
+            code: checked.code,
+            message: checked.message,
+        });
+    }
+    const appId = values[APP_ID_ENV];
+    // The gateway prefixes the manifest id; a dev env without it still shows the shape.
+    const type = appEventType(typeof appId === "string" && appId.trim() ? appId.trim() : "app", event);
+    console.info(`[everyapp dev] event ${type} (not delivered: no Gateway)`);
+    return { id: `dev-${crypto.randomUUID()}`, type };
+}

package/dist/server/everyApp.d.ts

@@ -1,20 +1,31 @@
 /**
  * `everyApp()` — the app-side identity boundary.
  *
- *   import manifest from "../everyapp.config.js";
- *   export default everyApp(handler, manifest);
+ *   export default everyApp(handler, { tools });
  *
  * The wrapper verifies the gateway-injected identity before app code runs,
  * stores the result on the original Request, and then delegates to the
- * worker-style handler.
+ * worker-style handler. The expected audience is the Worker's own name in
+ * `env.EVERYAPP_AUDIENCE`, which `everyAppWorker()` sets at deploy (the
+ * gateway stamps every token it mints for the app with it); only in
+ * development, where `everyapp dev` mints for the app id, does the app id in
+ * `env.EVERYAPP_APP_ID` stand in. The Worker never imports
+ * `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.
  */
 import { ConfigurationError, IdentityError, type EveryAppUser, type IdentityResult } from "../internal/index.js";
+import type { ToolSet } from "./tools.js";
 export { ConfigurationError, IdentityError };
 export type { EveryAppUser, IdentityResult };
-export interface ExecutionContextLike {
-    waitUntil(promise: Promise<unknown>): void;
-    passThroughOnException?(): void;
-}
+/**
+ * The runtime's `ExecutionContext`, which `everyApp()` passes to the handler
+ * as the Worker received it, so it goes on to Hono's `app.fetch(request,
+ * env, ctx)` or React Router's request handler as is. Tests that call
+ * `fetch` themselves pass a stub cast to it.
+ */
+export type ExecutionContextLike = ExecutionContext;
 export interface EveryAppManifestLike {
     id: string;
     [key: string]: unknown;
@@ -31,13 +42,21 @@ export interface EveryAppOptions {
      * Never enable this in production.
      */
     allowDevIdentities?: boolean;
+    /**
+     * Agent tools from `defineTools()`. The gateway snapshots them at deploy
+     * and serves them to MCP clients; see `defineTools`.
+     */
+    tools?: ToolSet;
     /** Override for tests. */
     now?: number;
 }
-/** The handler accepted by everyApp, with the verified user as a 4th argument. */
-export type EveryAppHandler<TEnv = Record<string, unknown>> = (request: Request, env: TEnv, ctx: ExecutionContextLike, user: EveryAppUser | null) => Response | Promise<Response>;
-interface EveryAppExport<TEnv> {
-    fetch(request: Request, env: TEnv, ctx: ExecutionContextLike): Promise<Response>;
+/**
+ * The handler accepted by everyApp, with the verified user as a 4th argument.
+ * `TCtx` narrows the context, e.g. to `ExecutionContext<Props>`.
+ */
+export type EveryAppHandler<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext> = (request: Request, env: TEnv, ctx: TCtx, user: EveryAppUser | null) => Response | Promise<Response>;
+interface EveryAppExport<TEnv, TCtx extends ExecutionContextLike> {
+    fetch(request: Request, env: TEnv, ctx: TCtx): Promise<Response>;
 }
 /**
  * Return the verified Every App user for this request, or null for a declared
@@ -51,5 +70,12 @@ export declare function getEveryAppUser(request: Request, env: object): Promise<
  */
 export declare function requireEveryAppUser(request: Request, env: object): Promise<EveryAppUser>;
 export declare function hasScope(user: EveryAppUser, scope: string): boolean;
-export declare function everyApp<TEnv = Record<string, unknown>>(handler: EveryAppHandler<TEnv>, manifest: EveryAppManifestLike, options?: EveryAppOptions): EveryAppExport<TEnv>;
+/** Wrap a Worker fetch handler with Every App identity verification. */
+export declare function everyApp<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext>(handler: EveryAppHandler<TEnv, TCtx>, options?: EveryAppOptions): EveryAppExport<TEnv, TCtx>;
+/**
+ * @deprecated Drop the manifest: the app id now comes from
+ *   `env.EVERYAPP_APP_ID` and the audience from `env.EVERYAPP_AUDIENCE`.
+ *   When passed, it must match the app id.
+ */
+export declare function everyApp<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext>(handler: EveryAppHandler<TEnv, TCtx>, manifest: EveryAppManifestLike | undefined, options?: EveryAppOptions): EveryAppExport<TEnv, TCtx>;
 //# sourceMappingURL=everyApp.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"everyApp.d.ts","sourceRoot":"","sources":["../../src/server/everyApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAEL,kBAAkB,EAElB,aAAa,EAIb,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3C,sBAAsB,CAAC,IAAI,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,kFAAkF;AAClF,MAAM,MAAM,eAAe,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAC5D,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,oBAAoB,EACzB,IAAI,EAAE,YAAY,GAAG,IAAI,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,UAAU,cAAc,CAAC,IAAI;IAC3B,KAAK,CACH,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtB;AAiFD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAW9B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,CAAC,CAevB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,QAAQ,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,EAC9B,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAAC,IAAI,CAAC,CAqBtB"}
+{"version":3,"file":"everyApp.d.ts","sourceRoot":"","sources":["../../src/server/everyApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGL,kBAAkB,EAElB,aAAa,EAIb,KAAK,YAAY,EACjB,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CACzB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,IAClD,CACF,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,YAAY,GAAG,IAAI,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,UAAU,cAAc,CAAC,IAAI,EAAE,IAAI,SAAS,oBAAoB;IAC9D,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAClE;AAoHD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,CAAC,CAevB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAUD,wEAAwE;AACxE,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9B;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC"}