@maxceem/agw 0.1.8 → 0.1.9

package/README.md

@@ -27,18 +27,26 @@ Add a provider. Paste its API key into the hidden prompt.
 agw provider add --type openai
 ```
 
-Add an app. It uses every provider you have added.
+Add an app. It uses every provider you have added. A server app is created with
+an application key, written to a private file; an iOS app authenticates with
+App Attest instead and ships no key.
 
 ```sh
+agw app add --type server --name "My backend"
 agw app add --type ios --team-id ABCDE12345 --bundle-id com.example.app
 ```
 
-Print the Swift code that calls the gateway from that app.
+Creating an app prints the request it can send. To print it again — as curl for
+a server app, as Swift for an iOS one:
 
 ```sh
-agw app snippet <app-id> --provider openai
+agw app snippet <app-id>
+agw app snippet <app-id> --provider openai   # when several could serve it
 ```
 
+The example is written from the app's own providers and models, and uses named
+placeholders such as `PROVIDER_SLUG` for anything not configured yet.
+
 ## Self-host on Cloudflare
 
 The package drives Wrangler and installs the gateway release of its own version.
@@ -118,14 +126,42 @@ overwritten. `app validate --file` checks a file without touching the account.
 Windows), mode 0700. Do not delete it to fix an authentication error; run
 `agw account login` instead. Output files are never overwritten.
 
-## Contributing
+## Local development
+
+The source lives in `cli/` of the
+[main repository](https://github.com/maxceem/app-ai-gateway). Clone it and run
+`pnpm install`.
+
+From the repository root, `pnpm cli:dev` is `agw` built from your own source
+instead of an installed copy. It rebuilds before every run, so your latest edit
+is always the one that runs.
+
+```sh
+pnpm cli:dev account login
+pnpm cli:dev provider add --type openai
+pnpm cli:dev app list
+```
+
+It keeps its state in `.agw-dev/`, separate from the state an installed `agw`
+uses. To start again from nothing:
+
+```sh
+pnpm cli:dev:reset
+```
+
+Deploying needs the gateway itself built too, once per change to the Worker,
+console or migrations:
+
+```sh
+pnpm --filter @maxceem/agw release:build
+pnpm cli:dev deployment setup --name my-gateway --no-domain
+```
 
-The CLI lives in `cli/` of the
-[main repository](https://github.com/maxceem/app-ai-gateway). From the repo root:
+Type-check and test:
 
 ```sh
-pnpm run cli:check   # type-check and bundle
-pnpm run cli:test    # run the CLI tests
+pnpm run cli:check
+pnpm run cli:test
 ```
 
 ## License

package/dist/agw.mjs

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 };
 
 // <define:__AGW_MANIFEST__>
-var define_AGW_MANIFEST_default = { version: "0.1.8", wrangler: "4.96.0", upgradeFrom: ["0.1.8", "0.1.7", "0.1.6", "0.1.5", "0.1.4", "0.1.3", "0.1.2", "0.1.1", "0.1.0"], release: { url: "https://github.com/maxceem/app-ai-gateway/releases/download/v0.1.8/gateway-0.1.8.tar.gz", sha256: "a4123a9186809038e7613f80d299637075eee47016b7aa309fd82f3a6a978ee9", manifest: "f6b6451ba84b7409c5f1e239e57319aa2e92bb54739bb07f27171d652c68b326" } };
+var define_AGW_MANIFEST_default = { version: "0.1.9", wrangler: "4.96.0", upgradeFrom: ["0.1.9", "0.1.8", "0.1.7", "0.1.6", "0.1.5", "0.1.4", "0.1.3", "0.1.2", "0.1.1", "0.1.0"], release: { url: "https://github.com/maxceem/app-ai-gateway/releases/download/v0.1.9/gateway-0.1.9.tar.gz", sha256: "a3722d70b8345b41d9e57662985141006214a1b02628af6016b4763e0d177287", manifest: "40ef2a1c2a44d1530a45a3a20eb4df4eb2a840af71ee53762432430f8262c142" } };
 
 // src/main.ts
 import { Writable } from "node:stream";
@@ -15018,7 +15018,7 @@ var ErrorResponseSchema = external_exports.object({
     code: external_exports.string(),
     message: external_exports.string(),
     data: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()])).optional().meta({
-      description: "Machine-readable facts about this rejection, present only where the code alone is not actionable. A billing_request_quota_exceeded rejection carries periodId, periodStart, periodEnd, limit, used, and resetAt; an app_rate_limited or app_budget_exhausted rejection carries scope, either user or app."
+      description: "Machine-readable facts about this rejection, present only where the code alone is not actionable. A billing_request_quota_exceeded rejection carries periodId, periodStart, periodEnd, limit, used, and resetAt; a billing_plan_limit_reached rejection carries limit and used; an app_rate_limited or app_budget_exhausted rejection carries scope, either user or app; a rate_limited rejection carries scope naming the endpoint policy that refused, plus limit, windowSeconds, retryAfterSeconds and resetAt."
     })
   })
 }).meta({ id: "ErrorResponse" });
@@ -15751,12 +15751,27 @@ var CliErrorDetailsSchema = external_exports.object({
   providerGatewayId: external_exports.string().optional(),
   revoked: external_exports.boolean().optional(),
   storagePath: external_exports.string().optional(),
+  /** Which ceiling refused the request, for the codes that name one. */
+  scope: external_exports.string().optional(),
+  limit: external_exports.number().optional(),
+  used: external_exports.number().optional(),
+  windowSeconds: external_exports.number().optional(),
+  retryAfterSeconds: external_exports.number().optional(),
+  resetAt: external_exports.string().optional(),
   id: external_exports.string().optional(),
   state: external_exports.string().optional(),
   expiresAt: external_exports.string().optional(),
   url: external_exports.string().optional(),
   /** The tail of a failed subprocess's own output, for failures it explains. */
-  output: external_exports.string().optional()
+  output: external_exports.string().optional(),
+  /**
+   * What Cloudflare itself said about a refused API call: each error's message
+   * and its code. Carried because the things that refuse a deployment — an
+   * account ceiling, a permission a token lacks — are named only there, and
+   * wrangler reports an API refusal it aggregates as the bare sentence that a
+   * request failed.
+   */
+  apiErrors: external_exports.string().optional()
 });
 
 // src/apps.ts
@@ -16223,7 +16238,10 @@ function parse3(argv) {
     if (!match || !types[match[1]])
       fail(
         "unknown_flag",
-        `Unknown flag ${token.split("=")[0]} for ${command}.`
+        `Unknown flag ${token.split("=")[0]} for ${command}.`,
+        // Resources are addressed positionally throughout, so the one mistake
+        // worth answering with more than the help text is naming one as a flag.
+        spec.args && ["id", "app", "app-id"].includes(match?.[1] ?? "") ? `Pass the identifier as an argument: agw ${command}${" <id>".repeat(spec.args)}.` : void 0
       );
     const name = match[1];
     const inline = match[2];
@@ -16935,6 +16953,129 @@ var StateStore = class {
   }
 };
 
+// ../src/shared/first-request.ts
+var PROVIDER_PLACEHOLDER = "PROVIDER_SLUG";
+var MODEL_PLACEHOLDER = "MODEL";
+var BODY_PLACEHOLDER = "REQUEST_BODY";
+var EXAMPLE_GAP_NOTES = {
+  provider: `No provider is configured yet, so ${PROVIDER_PLACEHOLDER} stands in for one. Add a provider key, then use its slug.`,
+  model: `No priced model was found for this provider, so ${MODEL_PLACEHOLDER} stands in for one. Use a model the provider serves.`,
+  body: `This app allows no path whose request shape is known here, so ${BODY_PLACEHOLDER} stands in for the body the provider documents.`
+};
+function examplePath(type, { gatewayRouted = false, model } = {}) {
+  if (type === "openai") return "v1/responses";
+  if (type === "anthropic") return "v1/messages";
+  if (type === "gemini")
+    return model ? `v1beta/models/${model}:generateContent` : void 0;
+  if (gatewayRouted) return "v1/chat/completions";
+  if (type === "groq") return "openai/v1/chat/completions";
+  if (type === "fireworks") return "inference/v1/chat/completions";
+  if (["deepseek", "perplexity", "bytedance"].includes(type)) return "chat/completions";
+  return "v1/chat/completions";
+}
+function bodyFor(path, model) {
+  const messages = [{ role: "user", content: "Say hello." }];
+  if (path.endsWith("responses")) return { model, input: "Say hello." };
+  if (path.endsWith("chat/completions")) return { model, messages };
+  if (path.endsWith("messages")) return { model, max_tokens: 128, messages };
+  if (path.endsWith(":generateContent"))
+    return { contents: [{ parts: [{ text: "Say hello." }] }] };
+  return null;
+}
+function modelsFor(provider, policy2, prices) {
+  if (policy2?.allowed_models?.length) return policy2.allowed_models;
+  return [
+    ...Object.keys(provider.pricing ?? {}),
+    ...Object.entries(prices[provider.type] ?? {}).filter(([, price]) => price.output !== void 0).map(([model]) => model)
+  ];
+}
+function firstRequest(routing, providers, prices) {
+  let fallback;
+  for (const provider of providers) {
+    if (provider.status !== "active") continue;
+    const policy2 = routing?.providers?.[provider.slug];
+    if (routing?.providerMode === "selected" && !policy2) continue;
+    const models = modelsFor(provider, policy2, prices);
+    const model = models[0] ?? MODEL_PLACEHOLDER;
+    const gaps = models.length ? [] : ["model"];
+    const fallbackPath = examplePath(provider.type, {
+      gatewayRouted: Boolean(provider.providerGatewayId),
+      model
+    });
+    const paths = policy2?.allowed_paths?.length ? policy2.allowed_paths : fallbackPath ? [fallbackPath] : [];
+    for (const entry of paths) {
+      const path = typeof entry === "string" ? entry : entry.path;
+      if (path.includes("*")) continue;
+      const fixed = typeof entry !== "string" ? entry.fixed_model : void 0;
+      const body = bodyFor(path, fixed ?? model);
+      const example = {
+        target: { provider: provider.slug, path },
+        body,
+        anthropic: path.endsWith("messages"),
+        // A fixed model is the app's own, so a catalog that has none of its
+        // own to offer is not a gap on a path that never carries one.
+        gaps: body && fixed ? [] : gaps
+      };
+      if (body) return example;
+      fallback ??= { ...example, gaps: [...example.gaps, "body"] };
+    }
+  }
+  return fallback ?? {
+    target: { provider: PROVIDER_PLACEHOLDER, path: "v1/chat/completions" },
+    body: bodyFor("v1/chat/completions", MODEL_PLACEHOLDER),
+    anthropic: false,
+    gaps: ["provider", "model"]
+  };
+}
+function exampleNotes(example) {
+  return example.gaps.map((gap) => EXAMPLE_GAP_NOTES[gap]);
+}
+function exampleUrl(baseUrl, appId, target) {
+  const origin2 = baseUrl.replace(/\/+$/, "");
+  const app = `${origin2}/v1/apps/${encodeURIComponent(appId)}`;
+  return "endpoint" in target ? `${app}/endpoints/${encodeURIComponent(target.endpoint)}` : `${app}/proxy/${encodeURIComponent(target.provider)}/${target.path}`;
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function commented(notes, marker) {
+  return (notes ?? []).map((note) => `${marker} ${note}
+`).join("");
+}
+function curlSnippet(options) {
+  const { baseUrl, appId, example, notes, keyExpression = "$APP_AI_GATEWAY_KEY" } = options;
+  const body = example.body ? JSON.stringify(example.body) : BODY_PLACEHOLDER;
+  return commented(notes, "#") + `curl --fail-with-body ${shellQuote(exampleUrl(baseUrl, appId, example.target))} \\
+  -H "Authorization: Bearer ${keyExpression}" \\
+  -H 'Content-Type: application/json' \\
+` + (example.anthropic ? "  -H 'anthropic-version: 2023-06-01' \\\n" : "") + `  -d ${shellQuote(body)}
+`;
+}
+function swiftSnippet(options) {
+  const { baseUrl, appId, example, notes, authMode = ".appAttestInstall" } = options;
+  const target = "endpoint" in example.target ? `endpointSlug: ${JSON.stringify(example.target.endpoint)}` : `provider: ${JSON.stringify(example.target.provider)},
+    providerPath: ${JSON.stringify(example.target.path)}`;
+  const body = example.body ? `request.httpBody = Data(${JSON.stringify(JSON.stringify(example.body))}.utf8)` : `// Supply the provider-native JSON body.
+request.httpBody = Data(${JSON.stringify(BODY_PLACEHOLDER)}.utf8)`;
+  return commented(notes, "//") + `import Foundation
+import AppAIGateway
+
+let gateway = AppAIGatewayClient(
+    appID: ${JSON.stringify(appId)},
+    baseURL: URL(string: ${JSON.stringify(baseUrl.replace(/\/+$/, ""))})!,
+    authMode: ${authMode}
+)
+
+var request = try await gateway.authorizedRequest(
+    ${target}
+)
+request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+${example.anthropic ? 'request.setValue("2023-06-01", forHTTPHeaderField: "anthropic-version")\n' : ""}${body}
+let (data, _) = try await URLSession.shared.data(for: request)
+print(String(decoding: data, as: UTF8.self))
+`;
+}
+
 // src/apps.ts
 var unlimited = () => ({
   requests: { per_minute: null, per_day: null },
@@ -17174,20 +17315,22 @@ async function appCommand(ctx, command, args, flags) {
         ({ app, resolved, config_error: configError } = updated.data);
       }
       let snippet;
-      if (doc2.config.authentication.type === "apple_app_attest") {
-        try {
-          const example = await appCommand(ctx, "app snippet", [app.id], {});
-          if ("snippet" in example) snippet = example.snippet;
-        } catch {
-        }
+      try {
+        const example = await appCommand(ctx, "app snippet", [app.id], {});
+        if ("snippet" in example) snippet = example.snippet;
+      } catch {
       }
+      if (snippet && key)
+        snippet = `export APP_AI_GATEWAY_KEY="$(cat ${shellQuote(key.storagePath)})"
+
+${snippet}`;
       return {
         ...snippet ? { snippet } : {},
         app,
         resolved,
         config_error: configError,
         ...key ? { applicationKey: key } : {},
-        guidance: doc2.config.authentication.type === "apple_app_attest" ? `Add https://github.com/maxceem/app-ai-gateway-swift from 1.0.0, enable App Attest, and test on a supported physical device. Run agw app snippet ${app.id} --provider <slug> for integration code. Production releases should use production-only App Attest.` : "Store the generated key on your server; never embed it in a mobile application."
+        guidance: doc2.config.authentication.type === "apple_app_attest" ? `Add https://github.com/maxceem/app-ai-gateway-swift from 1.0.0, enable App Attest, and test on a supported physical device. Run agw app snippet ${app.id} --provider <slug> for integration code. Production releases should use production-only App Attest.` : `Store the generated key on your server; never embed it in a mobile application. Run agw app snippet ${app.id} for this request again.`
       };
     } finally {
       await output?.cancel();
@@ -17274,62 +17417,75 @@ async function appCommand(ctx, command, args, flags) {
     };
   }
   if (action === "snippet") {
-    if (flags.language && flags.language !== "swift")
-      fail("invalid_input", "Only --language swift is supported.");
-    if (doc.config.authentication.type !== "apple_app_attest")
+    const ios = doc.config.authentication.type === "apple_app_attest";
+    const language = flags.language ?? (ios ? "swift" : "curl");
+    if (!["swift", "curl"].includes(language))
+      fail("invalid_input", "--language must be swift or curl.");
+    if (language === "swift" !== ios)
       fail(
         "unsupported_snippet",
-        "Swift snippets are for iOS applications.",
-        "Use your server HTTP client with the stored application key."
+        ios ? "iOS applications authenticate with App Attest, which curl cannot perform." : "Swift snippets are for iOS applications.",
+        `Run agw app snippet ${appId} --language ${ios ? "swift" : "curl"}.`
       );
-    let target;
+    const notes = [];
+    let example;
     if (flags.endpoint) {
-      if (!doc.config.endpoints?.[flags.endpoint])
+      const endpoint = doc.config.endpoints?.[flags.endpoint];
+      if (!endpoint)
         fail("endpoint_not_found", "Choose an existing named endpoint.");
-      target = `endpointSlug: ${JSON.stringify(flags.endpoint)}`;
+      const responses = endpoint.api_style === "responses";
+      example = {
+        target: { endpoint: flags.endpoint },
+        body: responses ? { input: "Say hello." } : null,
+        anthropic: false,
+        gaps: responses ? [] : ["body"]
+      };
     } else {
+      const routing = {
+        providerMode: doc.config.routing.providers.mode,
+        providers: doc.config.routing.providers.selected
+      };
       const { data: all } = await ctx.call("listProviders", []);
-      let providers = all.providers.filter(
-        (p2) => p2.status === "active" && (doc.config.routing.providers.mode === "all" || Object.hasOwn(doc.config.routing.providers.selected ?? {}, p2.slug))
+      const reachable = all.providers.filter(
+        (p) => p.status === "active" && (routing.providerMode === "all" || Object.hasOwn(routing.providers ?? {}, p.slug))
       );
       const requested = typeof flags.provider === "string" ? flags.provider : void 0;
-      if (requested) providers = providers.filter((p2) => p2.slug === requested);
-      const p = providers[0];
-      if (providers.length !== 1 || !p)
+      if (requested && !reachable.some((p) => p.slug === requested))
         fail(
-          "provider_required",
-          "Choose one available provider slug using --provider, or use --endpoint."
+          all.providers.some((p) => p.slug === requested) ? "provider_unavailable" : "provider_not_found",
+          all.providers.some((p) => p.slug === requested) ? "That provider is disabled or outside this app's proxy policy." : "No provider has that slug.",
+          "Run agw provider list for the slugs, and agw app show <id> for the policy."
         );
-      const { data: capabilities } = await ctx.publicCall("getCliCapabilities", []);
-      const cap = capabilities.providers.find((c) => c.type === p.type);
-      const path = cap?.defaultPath;
-      if (!path)
-        fail(
-          "provider_path_required",
-          "This provider has no default snippet path in deployment capabilities.",
-          "Configure and select a named endpoint."
+      const { data: catalog } = await ctx.call("listModelPrices", []);
+      const providers = requested ? reachable.filter((p) => p.slug === requested) : reachable;
+      example = firstRequest(routing, providers, catalog.prices);
+      if (!requested && reachable.length > 1)
+        notes.push(`This app can reach ${reachable.length} providers. Add --provider <slug> for a different one.`);
+    }
+    notes.push(...exampleNotes(example));
+    const clientUrl = ctx.active?.deployment?.apiUrl ?? ctx.url;
+    let snippet;
+    if (ios) {
+      const endUser = doc.config.authentication.type === "apple_app_attest" ? doc.config.authentication.end_user : void 0;
+      const issuer = endUser?.source === "issuer";
+      if (issuer)
+        notes.push(
+          "Replace yourIdentitySDK.currentIDToken(forceRefresh: forceRefresh) with your configured issuer integration."
         );
-      target = `provider: ${JSON.stringify(p.slug)},
-    providerPath: ${JSON.stringify(path)}`;
-    }
-    const issuer = doc.config.authentication.end_user.source === "issuer";
-    const authMode = issuer ? ".appAttest(issuerTokenProvider: { forceRefresh in\n        // Return a fresh signed token from your configured identity SDK.\n        try await yourIdentitySDK.currentIDToken(forceRefresh: forceRefresh)\n    })" : ".appAttestInstall";
-    const snippet = `// Swift package: https://github.com/maxceem/app-ai-gateway-swift (from: 1.0.0)
-// Enable App Attest and test on a supported physical device.
-import Foundation
-import AppAIGateway
-
-let gateway = AppAIGatewayClient(
-    appID: ${JSON.stringify(appId)},
-    baseURL: URL(string: ${JSON.stringify(ctx.url)})!,
-    authMode: ${authMode}
-)
-
-var request = try await gateway.authorizedRequest(
-    ${target}
-)
-// Supply the provider-native JSON body, then send request with URLSession.
-`;
+      snippet = swiftSnippet({
+        baseUrl: clientUrl,
+        appId,
+        example,
+        authMode: issuer ? ".appAttest(issuerTokenProvider: { forceRefresh in\n        // Return a fresh signed token from your configured identity SDK.\n        try await yourIdentitySDK.currentIDToken(forceRefresh: forceRefresh)\n    })" : ".appAttestInstall",
+        notes: [
+          "Swift package: https://github.com/maxceem/app-ai-gateway-swift (from: 1.0.0)",
+          "Enable App Attest and test on a supported physical device.",
+          ...notes
+        ]
+      });
+    } else {
+      snippet = curlSnippet({ baseUrl: clientUrl, appId, example, notes });
+    }
     if (flags.output) {
       const output = await reserveOutput(flags.output);
       try {
@@ -17339,13 +17495,7 @@ var request = try await gateway.authorizedRequest(
         await output.cancel();
       }
     }
-    return {
-      language: "swift",
-      snippet,
-      ...issuer ? {
-        requires: "Replace yourIdentitySDK.currentIDToken(forceRefresh: forceRefresh) with your configured issuer integration."
-      } : {}
-    };
+    return { language: ios ? "swift" : "shell", snippet, notes };
   }
   fail("unknown_command", "Unknown command.");
 }
@@ -17885,9 +18035,11 @@ async function openBrowser(url2) {
 
 // src/deployment.ts
 import { spawn as spawn2 } from "node:child_process";
+import { stripVTControlCharacters } from "node:util";
 import { createRequire as createRequire2 } from "node:module";
 import { randomUUID } from "node:crypto";
 import { cp, writeFile as writeFile2, unlink as unlink2 } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join as join3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 
@@ -18133,9 +18285,11 @@ async function release(requested = VERSION, base = dirname(fileURLToPath(import.
 
 // src/deployment.ts
 var require2 = createRequire2(import.meta.url);
-var OUTPUT_TAIL = 2e3;
+var OUTPUT_TAIL = 5e3;
 function wranglerFailure(args, code, output, redact = []) {
-  const tail = redact.filter((value) => value.length >= 8).reduce((text2, value) => text2.split(value).join("[redacted]"), output).trim().slice(-OUTPUT_TAIL);
+  const tail = stripVTControlCharacters(
+    redact.filter((value) => value.length >= 8).reduce((text2, value) => text2.split(value).join("[redacted]"), output)
+  ).trim().slice(-OUTPUT_TAIL);
   return new CliError(
     "wrangler_failed",
     `wrangler ${args[0] ?? ""} failed${code === null ? "" : ` (exit ${code})`}.`,
@@ -18144,16 +18298,21 @@ function wranglerFailure(args, code, output, redact = []) {
     tail ? { output: tail } : void 0
   );
 }
+function wranglerEnvironment({
+  interactive = false
+} = {}) {
+  return {
+    ...process.env,
+    WRANGLER_SEND_METRICS: "false",
+    WRANGLER_LOG: "log",
+    CI: interactive ? "" : "true"
+  };
+}
 async function runWrangler(args, { cwd, input, interactive = false, redact } = {}) {
   return new Promise((resolve3, reject2) => {
     const child = spawn2(process.execPath, [require2.resolve("wrangler/bin/wrangler.js"), ...args], {
       ...cwd === void 0 ? {} : { cwd },
-      env: {
-        ...process.env,
-        WRANGLER_SEND_METRICS: "false",
-        WRANGLER_LOG: "error",
-        CI: interactive ? "" : "true"
-      },
+      env: wranglerEnvironment({ interactive }),
       stdio: [input ? "pipe" : interactive ? "inherit" : "ignore", "pipe", "pipe"]
     });
     let output = "";
@@ -18184,6 +18343,24 @@ async function runWrangler(args, { cwd, input, interactive = false, redact } = {
     });
   });
 }
+function usable(auth) {
+  return auth.type === "api_key" ? Boolean(auth.key && auth.email) : Boolean(auth.token);
+}
+function environmentCredentials() {
+  const env = process.env;
+  const token = env.CLOUDFLARE_API_TOKEN ?? env.CF_API_TOKEN;
+  const key = env.CLOUDFLARE_API_KEY ?? env.CF_API_KEY;
+  const email3 = env.CLOUDFLARE_EMAIL ?? env.CF_EMAIL;
+  return [token, key && email3 ? key : void 0].filter(
+    (value) => Boolean(value)
+  );
+}
+var API_ERROR_TAIL = 500;
+function apiErrors(data) {
+  return (data.errors ?? []).map(
+    (error51) => [error51.message, error51.code === void 0 ? "" : `[code: ${error51.code}]`].filter(Boolean).join(" ")
+  ).filter(Boolean).join("; ").slice(0, API_ERROR_TAIL);
+}
 var Cloudflare = class {
   run;
   fetch;
@@ -18192,22 +18369,62 @@ var Cloudflare = class {
     this.run = run;
     this.fetch = fetchImpl;
   }
-  async authenticate(flags) {
+  /**
+   * The authorization wrangler holds, or undefined when it holds none.
+   *
+   * Only one outcome may be read as "logged out": wrangler exiting non-zero
+   * with nothing in the environment for it to have used. A run that failed
+   * while credentials were set failed at something else, a run that could not
+   * start failed at nothing to do with authorization, and output that will not
+   * parse means this CLI and the wrangler it drives disagree about the
+   * command. Answering any of those with a login would hide the cause behind a
+   * message about something the caller had already done.
+   */
+  async readAuth() {
+    const credentials = environmentCredentials();
+    let reported2;
     try {
-      this.auth = JSON.parse(await this.run(["auth", "token", "--json"]));
+      reported2 = await this.run(["auth", "token", "--json"], {
+        cwd: tmpdir(),
+        redact: credentials
+      });
+    } catch (error51) {
+      if (credentials.length > 0 || !(error51 instanceof CliError) || error51.code !== "wrangler_failed")
+        throw error51;
+      return void 0;
+    }
+    let auth;
+    try {
+      auth = JSON.parse(reported2);
     } catch {
-      if (flags["no-input"] || flags["dry-run"])
-        fail(
-          "cloudflare_auth_required",
-          "Cloudflare authentication is required.",
-          "Set CLOUDFLARE_API_TOKEN securely, or run setup interactively to authorize Cloudflare.",
-          4
-        );
-      await this.run(["login"], { interactive: true });
-      this.auth = JSON.parse(await this.run(["auth", "token", "--json"]));
+      fail(
+        "cloudflare_auth_unreadable",
+        "Wrangler did not report the Cloudflare authorization it holds.",
+        "Reinstall the CLI so the wrangler it bundles is the one it expects, then retry.",
+        3
+      );
     }
-    if (!this.auth?.token && this.auth?.type !== "api_key")
-      fail("cloudflare_auth_required", "No Cloudflare authorization is available.");
+    return usable(auth) ? auth : void 0;
+  }
+  async authenticate(flags) {
+    this.auth = await this.readAuth();
+    if (this.auth) return;
+    if (flags["no-input"] || flags["dry-run"])
+      fail(
+        "cloudflare_auth_required",
+        "Cloudflare authentication is required.",
+        "Set CLOUDFLARE_API_TOKEN securely, or run setup interactively to authorize Cloudflare.",
+        4
+      );
+    await this.run(["login"], { interactive: true, cwd: tmpdir() });
+    this.auth = await this.readAuth();
+    if (!this.auth)
+      fail(
+        "cloudflare_auth_required",
+        "Cloudflare authorization was not completed.",
+        "Read the wrangler output above, complete the browser login, then retry the same command.",
+        4
+      );
   }
   authHeaders() {
     const auth = this.auth;
@@ -18243,13 +18460,16 @@ var Cloudflare = class {
     } catch {
       fail("cloudflare_error", "Cloudflare returned an invalid response.");
     }
-    if (!response.ok || !data.success)
+    if (!response.ok || !data.success) {
+      const reported2 = apiErrors(data);
       fail(
         "cloudflare_error",
-        `Cloudflare rejected the request (HTTP ${response.status}).`,
+        `Cloudflare rejected the request (HTTP ${response.status})${reported2 ? `: ${reported2}` : ""}`,
         "Check Cloudflare permissions and the deployment resource IDs; retry the same command.",
-        3
+        3,
+        reported2 ? { apiErrors: reported2 } : void 0
       );
+    }
     return data;
   }
   async all(path) {
@@ -18833,6 +19053,27 @@ function reported(value, sent) {
 }
 var RECOVERABLE_RESOURCE_CODES = ["resource_receipt_expired", "resource_key_unavailable"];
 var RECOVERABLE_RESOURCE_FIELDS = ["appId", "keyId", "providerId", "providerGatewayId"];
+var LIMIT_CODES = [
+  "rate_limited",
+  "app_rate_limited",
+  "app_budget_exhausted",
+  "billing_request_quota_exceeded",
+  "billing_plan_limit_reached"
+];
+var LIMIT_TEXT_FIELDS = ["scope", "resetAt"];
+var LIMIT_NUMBER_FIELDS = ["limit", "used", "windowSeconds", "retryAfterSeconds"];
+function nextActionFor(status, code, details) {
+  if (status === 401) return "Run agw account login.";
+  if (code === "billing_plan_limit_reached")
+    return "Delete one you no longer need, or move to a plan whose limits are higher.";
+  if (status === 429) {
+    const seconds = details.retryAfterSeconds;
+    if (seconds === void 0)
+      return "Wait for the limit named in the message to reset, then run the same command again.";
+    return seconds >= 3600 && details.resetAt !== void 0 ? `Wait until ${details.resetAt}, then run the same command again.` : `Wait ${seconds} seconds, then run the same command again.`;
+  }
+  return "Review command configuration and account status.";
+}
 var Transport = class {
   fetch;
   constructor(fetchImpl = fetch) {
@@ -18887,18 +19128,27 @@ var Transport = class {
       const wire = data ?? {};
       const code = typeof wire.error?.code === "string" ? wire.error.code : typeof wire.code === "string" ? wire.code : `http_${response.status}`;
       const details = { status: response.status };
-      if (RECOVERABLE_RESOURCE_CODES.includes(code)) {
-        const reported2 = wire.error?.data ?? {};
+      const facts = wire.error?.data ?? {};
+      if (RECOVERABLE_RESOURCE_CODES.includes(code))
         for (const field of RECOVERABLE_RESOURCE_FIELDS) {
-          const value = reported2[field];
+          const value = facts[field];
           if (typeof value === "string") details[field] = value;
         }
+      if (LIMIT_CODES.includes(code)) {
+        for (const field of LIMIT_TEXT_FIELDS) {
+          const value = facts[field];
+          if (typeof value === "string") details[field] = value;
+        }
+        for (const field of LIMIT_NUMBER_FIELDS) {
+          const value = facts[field];
+          if (typeof value === "number") details[field] = value;
+        }
       }
       const explanation = reported(wire.error?.message ?? wire.message, body);
       fail(
         code,
         `Deployment rejected the request (HTTP ${response.status})` + (explanation ? `: ${explanation}` : "."),
-        response.status === 401 ? "Run agw account login." : "Review command configuration and account status.",
+        nextActionFor(response.status, code, details),
         3,
         details
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxceem/agw",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
   "description": "Manage App AI Gateway from a terminal or coding agent: providers, iOS and server apps, usage, and self-hosted deployment on Cloudflare",
   "keywords": [
@@ -25,7 +25,7 @@
     "directory": "cli"
   },
   "bugs": "https://github.com/maxceem/app-ai-gateway/issues",
-  "upgradeFrom": ["0.1.7", "0.1.6", "0.1.5", "0.1.4", "0.1.3", "0.1.2", "0.1.1", "0.1.0"],
+  "upgradeFrom": ["0.1.8", "0.1.7", "0.1.6", "0.1.5", "0.1.4", "0.1.3", "0.1.2", "0.1.1", "0.1.0"],
   "license": "Apache-2.0",
   "bin": {
     "agw": "dist/agw.mjs"