@ggui-ai/protocol 0.13.0 → 0.15.0

package/dist/types/refusal-codes.d.ts

@@ -0,0 +1,340 @@
+/**
+ * `PRE_GENERATION_REFUSAL_CODES` — the closed registry of refusal codes
+ * (ggui#786).
+ *
+ * A **pre-generation refusal** is a deployment declining a call BEFORE
+ * it does any work: no state read, nothing committed, no model spend.
+ * (The call has already passed the SDK's check against the declared
+ * `inputSchema`; the claim is nothing READ, not nothing validated.)
+ * It is a third outcome, not a failure — a failure describes work
+ * that ran and did not produce a result. The wire shape
+ * of a refused render lives in `../schemas/mcp.ts`
+ * (`renderRefusalSchema`); this file owns the NAMES.
+ *
+ * ## Why one file
+ *
+ * The registry is the anti-drift mechanism: one `code` namespace across
+ * every surface a deployment can refuse on, so two names can never mean
+ * the same state and one name can never mean two. Emitters read a row
+ * from here; they never mint a code literal of their own. A code that
+ * is not in this file fails the wire enum at the transport, loudly — a
+ * bug, never a wire state.
+ *
+ * ## The rules every row obeys
+ *
+ * - **Name the STATE, not the verb.** `subscription_exists`, not
+ *   `cannot_create_subscription`: the same state may refuse more than
+ *   one action later, and the code must not encode which.
+ * - **One state, one code.** Two codes never share a name; one code MAY
+ *   list several `surfaces` when a single state surfaces in more than
+ *   one place (`billing_mode_anomaly`).
+ * - **`retry` is defined from the CALLER's side.** `after-fix` — a
+ *   named party can act and the SAME call then succeeds; `next-period`
+ *   — time restores it at the next period boundary; `later` —
+ *   unbounded time (transient unavailability); `never` — no action by
+ *   the caller restores the call under this identity.
+ * - **`fixBy` names WHO acts.** REQUIRED on every `after-fix` row;
+ *   PERMITTED on a `later` row (naming the operator who restores a
+ *   surface that is transiently unavailable); FORBIDDEN on
+ *   `next-period` and `never` — time restores the first and nothing
+ *   restores the second, so naming a party would be a lie about who
+ *   can act. **An agent MUST NOT auto-retry an `after-fix` refusal
+ *   whose `fixBy` is not `caller`** — otherwise "retry after fix"
+ *   would mean "perform someone else's billing or policy decision on
+ *   their behalf". `caller` is the only value an agent may act on
+ *   itself.
+ * - **`emitter` is named.** A row whose emitter is unrecorded is the
+ *   drift the registry exists to prevent.
+ *
+ * ## Reading this file as a self-hoster
+ *
+ * Every `description` here ships to npm, and the render-gate subset
+ * reaches an agent as JSON-Schema metadata through `tools/list`. The
+ * wording is therefore written from the DEPLOYMENT-POLICY perspective
+ * ("the allowance this deployment configured for the app is
+ * exhausted"), never from an operator's internal vocabulary. A
+ * deployment that configures none of these policies emits none of these
+ * codes; the registry is the vocabulary, not a mandate.
+ */
+/**
+ * The surfaces a refusal code may be emitted on.
+ *
+ *   - `render-gate` — the pre-generation gate on the render/mutation
+ *     tools. These are the only codes that can appear in a refused
+ *     tool result's `refusal.code`.
+ *   - `owner-api` — an app owner's own billing mutations.
+ *   - `provisioning-api` — a tenant provisioning an app on behalf of
+ *     its own users.
+ *   - `mcp-endpoint` — the per-app MCP endpoint's authorization, on
+ *     any JSON-RPC request (`initialize` included). The refusal rides
+ *     the JSON-RPC error object's `data.refusal` (HTTP 403, error code
+ *     `-32003` `APP_NOT_FOUND`, message `App not found` — ggui#836); only the codes listed
+ *     here are ever typed there, and an authorization failure that is
+ *     NOT one of them stays a bare 403 by contract, so a client can
+ *     never learn which of the untyped arms it hit.
+ */
+export declare const REFUSAL_SURFACES: readonly ["render-gate", "owner-api", "provisioning-api", "mcp-endpoint"];
+/** One member of {@link REFUSAL_SURFACES}. */
+export type RefusalSurface = (typeof REFUSAL_SURFACES)[number];
+/** The closed `retry` vocabulary — see the file header for semantics. */
+export declare const REFUSAL_RETRIES: readonly ["after-fix", "next-period", "later", "never"];
+/** One member of {@link REFUSAL_RETRIES}. */
+export type RefusalRetry = (typeof REFUSAL_RETRIES)[number];
+/**
+ * Who can act on an `after-fix` refusal. Only `caller` is the agent
+ * itself — see the no-auto-retry rule in the file header.
+ */
+export declare const REFUSAL_FIX_BY: readonly ["caller", "owner", "tenant", "operator"];
+/** One member of {@link REFUSAL_FIX_BY}. */
+export type RefusalFixBy = (typeof REFUSAL_FIX_BY)[number];
+declare const REFUSAL_ROWS: {
+    readonly unsupported_provider: {
+        readonly code: "unsupported_provider";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's generation gate, provider arm";
+        readonly description: "The provider behind the requested model is not one this deployment can fund for the app. The app owner picks a funded provider or configures the app with its own credentials.";
+    };
+    readonly insufficient_credit: {
+        readonly code: "insufficient_credit";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's generation gate, balance arm";
+        readonly description: "The balance this deployment funds the app from is exhausted. The app owner adds funds, after which the same call succeeds.";
+    };
+    readonly hard_cap_exceeded: {
+        readonly code: "hard_cap_exceeded";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "next-period";
+        readonly emitter: "a deployment's generation gate, cap arm";
+        readonly description: "The app reached the hard ceiling this deployment set for the current period. Nothing the caller or the owner does lifts it before the period rolls over.";
+    };
+    readonly model_not_in_tier: {
+        readonly code: "model_not_in_tier";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "caller";
+        readonly emitter: "a deployment's generation gate, model arm";
+        readonly description: "The requested model is not among those the app is allowed to use. The caller picks an allowed model and retries — the one render-gate state an agent may act on itself.";
+    };
+    readonly managed_default_cap_exceeded: {
+        readonly code: "managed_default_cap_exceeded";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "tenant";
+        readonly emitter: "a deployment's generation gate, delegated-policy arm";
+        readonly description: "The app is running on the default ceiling because the tenant that provisioned it has declared no policy of its own, and that ceiling is reached. The tenant declares an explicit policy for the app.";
+    };
+    readonly app_policy_missing: {
+        readonly code: "app_policy_missing";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "tenant";
+        readonly emitter: "a deployment's generation gate, delegated-policy arm";
+        readonly description: "The app exists but carries no policy yet — the window between provisioning it and declaring what it may spend. The tenant declares the policy.";
+    };
+    readonly billing_mode_anomaly: {
+        readonly code: "billing_mode_anomaly";
+        readonly surfaces: readonly ["provisioning-api", "render-gate"];
+        readonly retry: "never";
+        readonly emitter: "a deployment's provisioning guard and its generation gate, reading the same record";
+        readonly description: "The app record declares a funding mode this deployment does not recognise, or declares none at all. The value is reported as read and never coerced — an unreadable record is not a policy.";
+    };
+    readonly app_canceled: {
+        readonly code: "app_canceled";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's generation gate, plan-state arm";
+        readonly description: "The app's plan has ended, so it renders nothing while the stored work is kept. The owner starts a new plan to restore rendering.";
+    };
+    readonly trial_exhausted: {
+        readonly code: "trial_exhausted";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's generation gate, trial arm";
+        readonly description: "The trial this deployment grants the app has used up its allotment. The owner starts a paid plan.";
+    };
+    readonly trial_expired: {
+        readonly code: "trial_expired";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's generation gate, trial arm";
+        readonly description: "The app's trial window has closed. The owner starts a paid plan.";
+    };
+    readonly issuer_rate_limited: {
+        readonly code: "issuer_rate_limited";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "later";
+        readonly emitter: "the per-issuer render-rate cap's denial";
+        readonly description: "Calls arriving under this issuing identity are over the rate this deployment allows. Time restores it; retry shortly.";
+    };
+    readonly app_rate_limited: {
+        readonly code: "app_rate_limited";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "later";
+        readonly emitter: "the per-app render-rate cap's denial";
+        readonly description: "This app is rendering faster than the rate this deployment allows it. The cap is the app’s own, not the issuing identity’s — the two are separate states with separate codes. Time restores it; retry shortly.";
+    };
+    readonly app_deprovisioned: {
+        readonly code: "app_deprovisioned";
+        readonly surfaces: readonly ["render-gate", "mcp-endpoint"];
+        readonly retry: "never";
+        readonly emitter: "the generation gate's owner-claim check, before any reservation or metering";
+        readonly description: "The app record has no owner claim any more — either the claim was removed, or the record names no issuing tenant at all. A record with no owner cannot be funded, so nothing renders under it and no caller action restores it.";
+    };
+    readonly billing_path_missing: {
+        readonly code: "billing_path_missing";
+        readonly surfaces: readonly ["render-gate"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "the generation gate's fall-through arm: a non-playground identity that resolves to no billing path (not a trial account, not a managed app, not a credit holder)";
+        readonly description: "The caller has no billing subject on this deployment, so nothing renders under it. The owner provisions one — a trial account, a managed policy, or credit. Unlike `billing_mode_anomaly` — an app record that exists and declares a funding mode this deployment cannot read — no record arm applies here: there is simply no subject to bill. A deployment MAY suppress this refusal by operator override; that switch is deployment policy, not a wire state.";
+    };
+    readonly subscription_exists: {
+        readonly code: "subscription_exists";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "An active (non-canceled) plan exists on this app. It refuses starting another one AND deleting the app — the refusal's own `fix` names the next step for the action that was called.";
+    };
+    readonly checkout_unavailable: {
+        readonly code: "checkout_unavailable";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "later";
+        readonly fixBy: "operator";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "The surface that starts a plan is unavailable on this deployment right now — unconfigured, or its provider is down. Only the operator can restore it.";
+    };
+    readonly card_update_unavailable: {
+        readonly code: "card_update_unavailable";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "later";
+        readonly fixBy: "operator";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "The surface that updates a payment method is unavailable on this deployment right now. Only the operator can restore it.";
+    };
+    readonly portal_unavailable: {
+        readonly code: "portal_unavailable";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "later";
+        readonly fixBy: "operator";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "The self-service billing surface is unavailable on this deployment right now. Only the operator can restore it.";
+    };
+    readonly no_subscription: {
+        readonly code: "no_subscription";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "A plan-management action was called on an app that has no plan. The owner starts a plan first.";
+    };
+    readonly already_on_tier: {
+        readonly code: "already_on_tier";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "after-fix";
+        readonly fixBy: "owner";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "The plan requested is the one the app is already on. The owner picks a different plan.";
+    };
+    readonly managed_app_no_checkout: {
+        readonly code: "managed_app_no_checkout";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "never";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "This app is funded by the tenant that provisioned it, so it has no owner-facing plan surface at all. No owner action creates one.";
+    };
+    readonly managed_app_no_card_update: {
+        readonly code: "managed_app_no_card_update";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "never";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "This app is funded by the tenant that provisioned it, so it carries no owner payment method to update.";
+    };
+    readonly managed_app_no_portal: {
+        readonly code: "managed_app_no_portal";
+        readonly surfaces: readonly ["owner-api"];
+        readonly retry: "never";
+        readonly emitter: "a deployment's owner billing mutations";
+        readonly description: "This app is funded by the tenant that provisioned it, so it has no owner self-service billing surface.";
+    };
+    readonly owner_ref_mismatch: {
+        readonly code: "owner_ref_mismatch";
+        readonly surfaces: readonly ["provisioning-api"];
+        readonly retry: "after-fix";
+        readonly fixBy: "tenant";
+        readonly emitter: "a deployment's provisioning guard";
+        readonly description: "The owner reference the caller supplied is not the one recorded on this app. The refusal names the route and the app, never the recorded reference. The tenant re-derives the reference and retries.";
+    };
+    readonly policy_version_stale: {
+        readonly code: "policy_version_stale";
+        readonly surfaces: readonly ["provisioning-api"];
+        readonly retry: "after-fix";
+        readonly fixBy: "tenant";
+        readonly emitter: "a deployment's provisioning guard, policy-write arm";
+        readonly description: "The policy write carries a version older than the one stored, so it would overwrite a newer decision. The refusal reports the stored version; the tenant re-derives from it and writes again.";
+    };
+};
+/** A refusal code = a registry key. Derived; never a second list. */
+export type RefusalCode = keyof typeof REFUSAL_ROWS;
+/**
+ * A registry row, as consumers read it. Normalized (not the literal
+ * row union) so `PRE_GENERATION_REFUSAL_CODES[code]` for any
+ * {@link RefusalCode} exposes `fixBy` as `RefusalFixBy | undefined`
+ * rather than a union in which some rows lack the property. The
+ * literal rows above still derive {@link RefusalCode}, enforce
+ * `code === key`, and enforce the retry/fixBy pairing.
+ */
+export interface RefusalRow {
+    readonly code: RefusalCode;
+    readonly surfaces: readonly RefusalSurface[];
+    readonly retry: RefusalRetry;
+    readonly fixBy?: RefusalFixBy;
+    readonly emitter: string;
+    readonly description: string;
+}
+/** The registry consumers read. */
+export declare const PRE_GENERATION_REFUSAL_CODES: Readonly<Record<RefusalCode, RefusalRow>>;
+/**
+ * The codes on one surface, derived type-level from the literal rows'
+ * `surfaces` tuples. A runtime `.filter()` cannot narrow a type, so the
+ * union is computed here and the tuple below is proved complete
+ * against it.
+ */
+type CodesOnSurface<S extends RefusalSurface> = {
+    [K in RefusalCode]: S extends (typeof REFUSAL_ROWS)[K]['surfaces'][number] ? K : never;
+}[RefusalCode];
+/**
+ * A code that can appear in a refused tool result's `refusal.code` —
+ * i.e. one whose `surfaces` include `render-gate`. Derived, so an
+ * owner-api or provisioning-api code is not even expressible on the
+ * render wire.
+ */
+export type PreGenerationRefusalCode = CodesOnSurface<'render-gate'>;
+/**
+ * A code that can appear in a per-app MCP endpoint refusal's
+ * `error.data.refusal.code` — i.e. one whose `surfaces` include
+ * `mcp-endpoint` (ggui#825). Derived, so a render-gate-only code is not
+ * expressible on the transport wire.
+ */
+export type McpEndpointRefusalCode = CodesOnSurface<'mcp-endpoint'>;
+/**
+ * Every render-gate code, as the literal tuple the wire enum
+ * (`renderRefusalSchema.code`) is built from. Order is the registry's.
+ */
+export declare const RENDER_GATE_REFUSAL_CODES: readonly ["unsupported_provider", "insufficient_credit", "hard_cap_exceeded", "model_not_in_tier", "managed_default_cap_exceeded", "app_policy_missing", "billing_mode_anomaly", "billing_path_missing", "app_canceled", "trial_exhausted", "trial_expired", "issuer_rate_limited", "app_rate_limited", "app_deprovisioned"];
+/**
+ * Every mcp-endpoint code, as the literal tuple the transport wire enum
+ * (`transportRefusalSchema.code`) is built from — the refusals a per-app
+ * MCP endpoint's authorization types on `error.data.refusal`
+ * (ggui#825). Order is the registry's.
+ */
+export declare const MCP_ENDPOINT_REFUSAL_CODES: readonly ["app_deprovisioned"];
+export {};
+//# sourceMappingURL=refusal-codes.d.ts.map

package/dist/types/refusal-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal-codes.d.ts","sourceRoot":"","sources":["../../src/types/refusal-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,2EAKnB,CAAC;AAEX,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,yEAAyE;AACzE,eAAO,MAAM,eAAe,yDAKlB,CAAC;AAEX,6CAA6C;AAC7C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,cAAc,oDAAqD,CAAC;AAEjF,4CAA4C;AAC5C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAiD3D,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqOhB,CAAC;AAEH,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,mCAAmC;AACnC,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CACjD,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CACjB,CAAC;AAEjB;;;;;GAKG;AACH,KAAK,cAAc,CAAC,CAAC,SAAS,cAAc,IAAI;KAC7C,CAAC,IAAI,WAAW,GAAG,CAAC,SAAS,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,GACtE,CAAC,GACD,KAAK;CACV,CAAC,WAAW,CAAC,CAAC;AAEf;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;AAkBpE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,8TAepC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,gCAErC,CAAC"}