@weirgate/cli 0.3.1 → 0.4.1

package/README.md

@@ -32,10 +32,23 @@ in output. Exit codes are listed in the guide.
 
 `weirgate models list` shows model prices and provider policy (`--upstream`,
 `--modality`), and `weirgate audit list --all` reads the whole audit log (up to 10,000
-events; `--limit` and `--cursor` page by hand).
+events; `--limit` and `--cursor` page by hand). `weirgate usage events` and `weirgate
+usage users` page the usage export and the per-user, per-rail rollup.
+
+`weirgate config export --output json > config.json` (or `--output yaml`), edit the file,
+then `weirgate config propose --file config.json`: propose reads the exported file as is.
 
 ## Changes
 
+- **0.4.1**: on macOS, `weirgate auth login` stores the key in the Keychain through
+  `security -i` on stdin, so the key no longer appears on the `security` command line,
+  where other local users and process listings could read it.
+- **0.4.0**: `weirgate auth login` and the local secret-entry page exit as soon as the
+  browser is done (they used to wait on the browser's open connections). `config propose`
+  and `config validate` accept a `config export` file as is. `weirgate audit list
+  --include-platform-access` shows Weirgate's own access rows, which are hidden by default. New `weirgate usage
+  events` and `weirgate usage users`, and MCP tools `weirgate_export_usage_events` and
+  `weirgate_list_user_usage`.
 - **0.3.1**: the CLI and `weirgate-mcp` refuse the platform super-admin key on every
   command (exit code 4, `platform_key_rejected`) and ask for a tenant-scoped key, instead
   of acting on the first tenant the platform key can see.

package/dist/cli/browser-secret-entry.js

@@ -0,0 +1,50 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { API_VERSION, WeirgateApiError } from "../shared/api-client.js";
+import { closeLoopbackServer, LOOPBACK_HEADERS } from "./loopback-server.js";
+/**
+ * One-time localhost page where a human enters a scoped key or provider key, so the value
+ * never appears as an argument, in shell history, or in the model's context. The server
+ * shuts down, connections included, once the value is posted (#268).
+ */
+export function browserSecretEntry(dependencies = {}) {
+    const openExternal = dependencies.openExternal ?? openInBrowser;
+    const notify = dependencies.notify ?? ((message) => process.stderr.write(message));
+    return new Promise((resolveSecret, reject) => {
+        const server = createServer((request, response) => {
+            if (request.method === "GET") {
+                response.writeHead(200, { ...LOOPBACK_HEADERS, "content-type": "text/html; charset=utf-8" });
+                response.end("<!doctype html><title>Weirgate local secret entry</title><form method=post><label>Scoped key or provider key <input name=key type=password autofocus required></label><button>Continue</button></form><p>The value is sent only to this localhost process.</p>");
+                return;
+            }
+            let body = "";
+            request.on("data", (chunk) => { body += String(chunk); });
+            request.on("end", () => {
+                const key = new URLSearchParams(body).get("key") ?? "";
+                response.writeHead(key ? 200 : 400, { ...LOOPBACK_HEADERS, "content-type": "text/plain" });
+                response.end(key ? "Captured locally. You may close this tab." : "Missing value.");
+                closeLoopbackServer(server, response);
+                key ? resolveSecret(key) : reject(invalidInvocation("No secret entered."));
+            });
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                closeLoopbackServer(server);
+                reject(invalidInvocation("Could not start local secret entry."));
+                return;
+            }
+            const url = `http://127.0.0.1:${address.port}`;
+            openExternal(url);
+            notify(`Opened one-time localhost secret entry: ${url}\n`);
+        });
+    });
+}
+function openInBrowser(url) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", url] : [url];
+    spawn(opener, args, { detached: true, stdio: "ignore" }).unref();
+}
+function invalidInvocation(message) {
+    return new WeirgateApiError({ message, errorType: "invalid_invocation", status: 400, requestId: "local", apiVersion: API_VERSION });
+}

package/dist/cli/browser-session-grant.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { API_VERSION, WeirgateApiError } from "../shared/api-client.js";
+import { closeLoopbackServer, LOOPBACK_HEADERS } from "./loopback-server.js";
 const SUCCESS_PATH = "/cli/access-granted";
 const FAILURE_PATH = "/cli/access-failed";
 export async function browserSessionGrant(input, dependencies = {}) {
@@ -28,17 +29,17 @@ export async function browserSessionGrant(input, dependencies = {}) {
             callbackInProgress = true;
             void exchangeSessionGrantCode(apiUrl, code, fetchImpl).then((grant) => {
                 redirect(response, new URL(SUCCESS_PATH, dashboardUrl));
-                finish(() => resolveGrant(grant));
+                finish(() => resolveGrant(grant), response);
             }).catch((error) => {
                 redirect(response, new URL(FAILURE_PATH, dashboardUrl));
-                finish(() => rejectGrant(error));
+                finish(() => rejectGrant(error), response);
             });
         });
-        const finish = (settle) => {
+        const finish = (settle, last) => {
             if (settled)
                 return;
             settled = true;
-            server.close();
+            closeLoopbackServer(server, last);
             settle();
         };
         server.once("error", (error) => finish(() => rejectGrant(error)));
@@ -95,7 +96,7 @@ function requireHttpsUrls(input) {
 }
 function redirect(response, destination) {
     response.writeHead(303, {
-        "cache-control": "no-store",
+        ...LOOPBACK_HEADERS,
         location: destination.toString(),
         "referrer-policy": "no-referrer",
     });
@@ -103,7 +104,7 @@ function redirect(response, destination) {
 }
 function respondText(response, status, message) {
     response.writeHead(status, {
-        "cache-control": "no-store",
+        ...LOOPBACK_HEADERS,
         "content-type": "text/plain; charset=utf-8",
         "referrer-policy": "no-referrer",
     });

package/dist/cli/config-file.js

@@ -0,0 +1,21 @@
+import { API_VERSION, record, WeirgateApiError } from "../shared/api-client.js";
+/**
+ * The tenant config inside a `--file`/`--data` document for `config propose` and `config
+ * validate`. `weirgate config export --output json|yaml` prints the CLI's usual success
+ * envelope, `{ok, data, request_id, api_version}`; a document of that shape is unwrapped to
+ * its `data`, so an export round-trips to propose unchanged (#268). A bare config passes
+ * through. A config has no `ok` or `api_version` field, so the two shapes can't be confused.
+ */
+export function configDocument(value) {
+    if (!("ok" in value && "api_version" in value))
+        return value;
+    if (value.ok !== true)
+        throw invalid("The file is a failed CLI result ({\"ok\": false, …}), not a config.");
+    const data = record(value.data);
+    if (Object.keys(data).length === 0)
+        throw invalid("The CLI result in the file has no config in data.");
+    return data;
+}
+function invalid(message) {
+    return new WeirgateApiError({ message, errorType: "invalid_invocation", status: 400, requestId: "local", apiVersion: API_VERSION });
+}

package/dist/cli/index.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { createServer } from "node:http";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { stdin, stdout } from "node:process";
 import YAML from "yaml";
 import { AgentApiClient, API_VERSION, DEFAULT_API_URL, pathPart, WeirgateApiError } from "../shared/api-client.js";
 import { invokeTool } from "../shared/tools.js";
+import { browserSecretEntry } from "./browser-secret-entry.js";
 import { browserSessionGrant } from "./browser-session-grant.js";
+import { configDocument } from "./config-file.js";
 import { exitCodeFor } from "./exit-codes.js";
 import { AUDIT_ALL_CAP, listAllAuditEvents, modelsTable } from "./listing.js";
 let deferringRequiredFlags = false;
@@ -81,7 +82,7 @@ async function clientFromEnvironment(flags) {
     const key = process.env.WEIRGATE_API_KEY ?? keychainRead();
     if (!key)
         throw invocation("No key reference resolved. Set WEIRGATE_API_KEY or run `weirgate auth login`.");
-    return new AgentApiClient({ apiKey: key, baseUrl: stringFlag(flags, "api-url") ?? process.env.WEIRGATE_API_URL ?? DEFAULT_API_URL });
+    return new AgentApiClient({ apiKey: key, baseUrl: stringFlag(flags, "api-url") ?? process.env.WEIRGATE_API_URL ?? DEFAULT_API_URL, requireTenantKey: true });
 }
 async function authCommand(verb, flags) {
     if (verb === "logout") {
@@ -99,18 +100,29 @@ async function authCommand(verb, flags) {
                 dashboardUrl: stringFlag(flags, "dashboard-url") ?? "https://dashboard.weirgate.com",
                 scope: stringFlag(flags, "scope") ?? "propose",
             }));
-        const client = new AgentApiClient({ apiKey: key, baseUrl: apiUrl });
+        const client = new AgentApiClient({ apiKey: key, baseUrl: apiUrl, requireTenantKey: true });
         const identity = await client.whoami();
-        if (identity.data.actor.type === "platform_super_admin")
-            throw invocation("Platform super-admin credentials are rejected.");
-        const stored = spawnSync("security", ["add-generic-password", "-U", "-s", "weirgate-cli", "-a", "default", "-w", key], { stdio: "ignore" });
-        if (stored.status !== 0)
-            throw invocation("Unable to store key in macOS Keychain; use WEIRGATE_API_KEY instead.");
+        keychainStore(key);
         return identity;
     }
     const client = await clientFromEnvironment(flags);
     return client.whoami();
 }
+/**
+ * Stores the key without putting it in argv (visible to `ps` and exec telemetry):
+ * `security -i` reads the command from stdin. The key must be a plain `wgk_` key
+ * (AgentApiClient already enforces this), so it cannot break out of the one command line.
+ */
+function keychainStore(key) {
+    if (!/^wgk_[a-f0-9]{64}$/.test(key))
+        throw invocation("Unable to store key in macOS Keychain; use WEIRGATE_API_KEY instead.");
+    const stored = spawnSync("/usr/bin/security", ["-i"], {
+        input: `add-generic-password -U -s weirgate-cli -a default -w ${key}\n`,
+        stdio: ["pipe", "ignore", "ignore"],
+    });
+    if (stored.status !== 0)
+        throw invocation("Unable to store key in macOS Keychain; use WEIRGATE_API_KEY instead.");
+}
 function keychainRead() {
     const result = spawnSync("security", ["find-generic-password", "-s", "weirgate-cli", "-a", "default", "-w"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
     return result.status === 0 ? result.stdout.trim() : undefined;
@@ -144,11 +156,13 @@ async function commandToTool(client, noun, verb, flags) {
         "proposals:cancel": ["weirgate_cancel_proposal", { proposal_id: requiredFlag(flags, "proposal") }],
         "proposals:apply": ["weirgate_apply_proposal", { proposal_id: requiredFlag(flags, "proposal"), expected_base_revision: numberFlag(flags, "expected-base-revision"), idempotency_key: requiredFlag(flags, "idempotency-key") }],
         "usage:query": ["weirgate_query_usage", { ...common, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until"), group_by: stringFlag(flags, "group-by"), bucket: stringFlag(flags, "bucket"), limit: numberFlag(flags, "limit") }],
+        "usage:events": ["weirgate_export_usage_events", { ...common, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until"), cursor: stringFlag(flags, "cursor"), limit: numberFlag(flags, "limit") }],
+        "usage:users": ["weirgate_list_user_usage", { ...common, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until"), cursor: stringFlag(flags, "cursor"), limit: numberFlag(flags, "limit") }],
         "usage:failures": ["weirgate_list_failures", { ...common, since: stringFlag(flags, "since"), until: stringFlag(flags, "until"), cursor: stringFlag(flags, "cursor"), limit: numberFlag(flags, "limit") }],
         "pricing-insights:get": ["weirgate_get_pricing_insights", { ...common, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until") }],
         "users:timeline": ["weirgate_get_user_timeline", { ...common, external_id: requiredFlag(flags, "user") }],
         "events:list": ["weirgate_list_events", common],
-        "audit:list": ["weirgate_list_audit_events", { ...common, since: stringFlag(flags, "since"), until: stringFlag(flags, "until"), action: stringFlag(flags, "action"), limit: numberFlag(flags, "limit"), cursor: stringFlag(flags, "cursor") }],
+        "audit:list": ["weirgate_list_audit_events", { ...common, since: stringFlag(flags, "since"), until: stringFlag(flags, "until"), action: stringFlag(flags, "action"), limit: numberFlag(flags, "limit"), cursor: stringFlag(flags, "cursor"), include_platform_access: flags["include-platform-access"] === true ? true : undefined }],
         "models:list": ["weirgate_list_models", { upstream: stringFlag(flags, "upstream"), modality: stringFlag(flags, "modality") }],
         "provider-keys:list": ["weirgate_list_provider_key_slots", common],
         "provider-keys:test": ["weirgate_test_provider_key", { ...common, provider: requiredFlag(flags, "provider") }],
@@ -179,12 +193,12 @@ async function commandToTool(client, noun, verb, flags) {
         tableView = modelsTable;
     if (noun === "audit" && flags.all) {
         const input = entry[1];
-        return listAllAuditEvents(client, { app_id: input.app_id, action: input.action, since: input.since, until: input.until }, { cursor: input.cursor, pageSize: input.limit });
+        return listAllAuditEvents(client, { app_id: input.app_id, action: input.action, since: input.since, until: input.until, include_platform_access: input.include_platform_access === true ? "true" : undefined }, { cursor: input.cursor, pageSize: input.limit });
     }
     if (entry[0] === "__auth_presets")
         return client.request("/v1/admin/auth-presets");
     if (entry[0] === "__config_propose")
-        return client.request("/v1/admin/config/proposals", { method: "POST", body: entry[1] });
+        return client.request("/v1/admin/config/proposals", { method: "POST", body: configDocument(entry[1]) });
     if (entry[0].startsWith("__tiers")) {
         const result = await invokeTool(client, "weirgate_get_app", common);
         const appData = result.data.app;
@@ -217,37 +231,7 @@ async function readSecret(flags) {
     }
     if (flags.browser === false)
         throw invocation("Choose --browser or --stdin. Secret values are never positional arguments.");
-    return browserSecretCeremony();
-}
-async function browserSecretCeremony() {
-    return new Promise((resolveSecret, reject) => {
-        const server = createServer((request, response) => {
-            if (request.method === "GET") {
-                response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
-                response.end("<!doctype html><title>Weirgate local secret entry</title><form method=post><label>Scoped key or provider key <input name=key type=password autofocus required></label><button>Continue</button></form><p>The value is sent only to this localhost process.</p>");
-                return;
-            }
-            let body = "";
-            request.on("data", (chunk) => { body += String(chunk); });
-            request.on("end", () => {
-                const key = new URLSearchParams(body).get("key") ?? "";
-                response.writeHead(key ? 200 : 400, { "content-type": "text/plain", "cache-control": "no-store" });
-                response.end(key ? "Captured locally. You may close this tab." : "Missing value.");
-                server.close();
-                key ? resolveSecret(key) : reject(invocation("No secret entered."));
-            });
-        });
-        server.listen(0, "127.0.0.1", () => {
-            const address = server.address();
-            if (!address || typeof address === "string")
-                return reject(invocation("Could not start local secret entry."));
-            const url = `http://127.0.0.1:${address.port}`;
-            const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
-            const args = process.platform === "win32" ? ["/c", "start", url] : [url];
-            spawn(opener, args, { detached: true, stdio: "ignore" }).unref();
-            process.stderr.write(`Opened one-time localhost secret entry: ${url}\n`);
-        });
-    });
+    return browserSecretEntry();
 }
 async function installMcp(flags) {
     const target = stringFlag(flags, "client") ?? "codex";
@@ -287,7 +271,7 @@ async function init(client, flags) {
     }
 }
 async function validateConfig(flags) {
-    const data = await dataFlag(flags);
+    const data = configDocument(await dataFlag(flags));
     const valid = typeof data.tenant_id === "string" && Array.isArray(data.apps);
     if (!valid)
         throw new WeirgateApiError({ message: "Config must contain tenant_id and apps[]", errorType: "validation_error", status: 400, requestId: "local", apiVersion: API_VERSION });
@@ -354,7 +338,7 @@ function redact(value) { if (Array.isArray(value))
     return value.map(redact); if (!value || typeof value !== "object")
     return value; return Object.fromEntries(Object.entries(value).map(([key, item]) => [/^(key|secret|token|password|credential|authorization)$/i.test(key) ? key : key, /^(key|secret|token|password|credential|authorization)$/i.test(key) ? "[redacted]" : redact(item)])); }
 function help() {
-    return `weirgate <noun> <verb> [flags]\n\nAuth: auth login|status|logout, mcp install, init\nApps: apps list|get|propose, config export|validate|propose|apply, auth-presets list\nConfig: features/tiers/rules/overrides/proposals, doctor, sandbox\nOps: usage, pricing-insights, users, user-tiers, events, audit, provider-keys, grants, docs\nModels: models list [--upstream openrouter|openai|anthropic|google|xai] [--modality chat|embedding|image|audio]\nAudit: audit list [--limit n] [--cursor c] [--all] (--all follows next_cursor, up to ${AUDIT_ALL_CAP} events)\nOutput: --output json|table|yaml; --json; mutations use --idempotency-key\nAuth login: browser consent by default; --stdin accepts a pre-minted key\nSecrets: provider-keys put|rotate defaults to --browser; --stdin rejects pipes without --allow-pipe\n`;
+    return `weirgate <noun> <verb> [flags]\n\nAuth: auth login|status|logout, mcp install, init\nApps: apps list|get|propose, config export|validate|propose|apply, auth-presets list\nConfig: features/tiers/rules/overrides/proposals, doctor, sandbox\nOps: usage, pricing-insights, users, user-tiers, events, audit, provider-keys, grants, docs\nModels: models list [--upstream openrouter|openai|anthropic|google|xai] [--modality chat|embedding|image|audio]\nUsage: usage query|failures|events|users (events: one row per settled request; users: per user and rail; --since/--until, --cursor, --limit)\nAudit: audit list [--limit n] [--cursor c] [--all] [--include-platform-access] (--all follows next_cursor, up to ${AUDIT_ALL_CAP} events)\nOutput: --output json|table|yaml; --json; mutations use --idempotency-key\nAuth login: browser consent by default; --stdin accepts a pre-minted key\nSecrets: provider-keys put|rotate defaults to --browser; --stdin rejects pipes without --allow-pipe\n`;
 }
 function completion(shell) {
     const commands = "auth mcp init apps config auth-presets models features tiers rules overrides proposals usage pricing-insights users user-tiers events audit provider-keys grants doctor sandbox docs completion";

package/dist/cli/loopback-server.js

@@ -0,0 +1,21 @@
+/**
+ * Response headers for the CLI's one-shot loopback pages. `Connection: close` makes Node end
+ * each socket after its response, so the browser can't keep the connection alive (#268).
+ */
+export const LOOPBACK_HEADERS = { "cache-control": "no-store", connection: "close" };
+/**
+ * Stops a one-shot loopback server so the CLI process can exit (#268). `server.close()` alone
+ * waits for every open socket, and a browser keeps its connection (and any spare connection it
+ * opened ahead of time) alive. After `last` (the final response) is sent, this also destroys
+ * every remaining connection; waiting for it first keeps the final response from being cut off.
+ */
+export function closeLoopbackServer(server, last) {
+    server.close();
+    const destroyRemaining = () => server.closeAllConnections();
+    if (!last || last.writableFinished)
+        destroyRemaining();
+    else {
+        last.once("finish", destroyRemaining);
+        last.once("close", destroyRemaining);
+    }
+}

package/dist/mcp/server.js

@@ -1,23 +1,25 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { AgentApiClient, API_VERSION, WeirgateApiError } from "../shared/api-client.js";
+import { AgentApiClient, API_VERSION, PLATFORM_KEY_REFUSAL, refusePlatformIdentity, WeirgateApiError } from "../shared/api-client.js";
 import { allowedTools, invokeTool, toolGroupAllowed, TOOL_DEFINITIONS } from "../shared/tools.js";
 export async function authenticateAgent(apiKey, baseUrl) {
-    const client = new AgentApiClient({ apiKey, baseUrl });
+    const client = new AgentApiClient({ apiKey, baseUrl, requireTenantKey: true });
     const result = await client.whoami();
-    if (result.data.actor.type === "platform_super_admin") {
+    refusePlatformIdentity(result);
+    return { client, identity: result.data, identityRequestId: result.request_id };
+}
+const rank = { read: 0, propose: 1, apply: 2 };
+export function createMcpServer(auth) {
+    // Agent tools act on one tenant; never serve them to the platform key (#232).
+    if (auth.identity.actor.type === "platform_super_admin") {
         throw new WeirgateApiError({
-            message: "The platform super-admin credential is never accepted by agent surfaces",
+            message: PLATFORM_KEY_REFUSAL,
             errorType: "platform_key_rejected",
             status: 403,
-            requestId: result.request_id,
-            apiVersion: result.api_version,
+            requestId: auth.identityRequestId,
+            apiVersion: API_VERSION,
         });
     }
-    return { client, identity: result.data, identityRequestId: result.request_id };
-}
-const rank = { read: 0, propose: 1, apply: 2 };
-export function createMcpServer(auth) {
     const server = new Server({ name: "weirgate", version: API_VERSION }, {
         capabilities: { tools: { listChanged: false } },
         instructions: "Operate Weirgate only through the 2026-07-18 public API. Propose before apply. Provider keys are entered outside the model-facing MCP surface.",

package/dist/mcp/stdio.js

@@ -1,9 +1,19 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WeirgateApiError } from "../shared/api-client.js";
 import { authenticateAgent, createMcpServer } from "./server.js";
 const apiKey = process.env.WEIRGATE_API_KEY;
 if (!apiKey)
     throw new Error("WEIRGATE_API_KEY must reference a minted scoped wgk_ key");
-const auth = await authenticateAgent(apiKey, process.env.WEIRGATE_API_URL);
-const server = createMcpServer(auth);
-await server.connect(new StdioServerTransport());
+try {
+    const auth = await authenticateAgent(apiKey, process.env.WEIRGATE_API_URL);
+    const server = createMcpServer(auth);
+    await server.connect(new StdioServerTransport());
+}
+catch (error) {
+    if (!(error instanceof WeirgateApiError))
+        throw error;
+    // A refused key (platform key, bad shape, 401) is an expected stop, not a crash.
+    process.stderr.write(`weirgate-mcp: ${error.errorType}: ${error.message}\n`);
+    process.exit(1);
+}

package/dist/shared/api-client.js

@@ -17,13 +17,34 @@ export class WeirgateApiError extends Error {
         this.detail = input.detail;
     }
 }
+/**
+ * The refusal every agent surface (CLI, local stdio MCP, hosted MCP) gives a platform
+ * super-admin key. Agent tools act on one tenant; with the platform key they used to act on
+ * whichever tenant `/config` listed first (#232).
+ */
+export const PLATFORM_KEY_REFUSAL = "The platform super-admin key is not accepted by Weirgate agent tools. Use a tenant-scoped key: mint a wgk_ key for one tenant (dashboard or POST /v1/admin/keys) and use that instead.";
+/** Throws `platform_key_rejected` (403) when `whoami` identifies the platform super-admin key. */
+export function refusePlatformIdentity(result) {
+    if (result.data.actor.type !== "platform_super_admin")
+        return;
+    throw new WeirgateApiError({
+        message: PLATFORM_KEY_REFUSAL,
+        errorType: "platform_key_rejected",
+        status: 403,
+        requestId: result.request_id,
+        apiVersion: result.api_version,
+    });
+}
 export class AgentApiClient {
     baseUrl;
     apiKey;
+    /** When set, the first call checks `whoami` and refuses a platform key before any other request. */
+    requireTenantKey;
+    tenantKeyCheck;
     constructor(input) {
         if (!/^wgk_[a-f0-9]{64}$/.test(input.apiKey)) {
             throw new WeirgateApiError({
-                message: "A minted wgk_ management key is required",
+                message: "A minted wgk_ management key is required. The platform super-admin key is not accepted by Weirgate agent tools; use a tenant-scoped key.",
                 errorType: "invalid_api_key",
                 status: 401,
                 requestId: "local",
@@ -31,6 +52,7 @@ export class AgentApiClient {
             });
         }
         this.apiKey = input.apiKey;
+        this.requireTenantKey = input.requireTenantKey ?? false;
         this.baseUrl = (input.baseUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
         if (new URL(this.baseUrl).protocol !== "https:") {
             throw new WeirgateApiError({
@@ -43,6 +65,11 @@ export class AgentApiClient {
         }
     }
     async request(path, options = {}) {
+        if (this.requireTenantKey)
+            await this.whoami();
+        return this.send(path, options);
+    }
+    async send(path, options = {}) {
         const url = new URL(path, `${this.baseUrl}/`);
         for (const [key, value] of Object.entries(options.query ?? {})) {
             if (value !== undefined)
@@ -90,8 +117,17 @@ export class AgentApiClient {
         }
         return { data: payload, request_id: requestId, api_version: API_VERSION };
     }
+    /** With `requireTenantKey`, the identity is fetched once and a platform key is refused. */
     whoami() {
-        return this.request("/v1/admin/whoami");
+        if (!this.requireTenantKey)
+            return this.send("/v1/admin/whoami");
+        this.tenantKeyCheck ??= this.send("/v1/admin/whoami").then((result) => {
+            refusePlatformIdentity(result);
+            return result;
+        });
+        // A failed check (network, 401) is retried on the next call rather than cached.
+        this.tenantKeyCheck.catch(() => { this.tenantKeyCheck = undefined; });
+        return this.tenantKeyCheck;
     }
 }
 export function pathPart(value) {

package/dist/shared/tools.js

@@ -26,12 +26,14 @@ export const TOOL_DEFINITIONS = [
     { name: "weirgate_get_integration_snippet", title: "Get integration snippet", description: "Generate an HTTP/curl integration snippet.", scope: "read", group: "setup", inputSchema: objectSchema({ ...app, mode: { enum: ["http", "curl"] }, feature_id: str() }, appRequired) },
     { name: "weirgate_run_mock_call", title: "Run mock call", description: "Run a deterministic sandbox fixture; never invokes live inference.", scope: "apply", group: "sandbox", inputSchema: objectSchema({ ...app, fixture: str(), session_name: str(), idempotency_key: str() }, ["app_id", "fixture"]) },
     { name: "weirgate_query_usage", title: "Query usage", description: "Query windowed usage totals, groups, latency, refusals, and an optional day/hour series.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, since: str(), until: str(), group_by: { enum: ["feature", "user", "model", "funding_rail", "refusal_code"] }, bucket: { enum: ["day", "hour"] }, limit: integer() }, ["app_id", "since", "until"]) },
+    { name: "weirgate_export_usage_events", title: "Export usage events", description: "Export settled requests in [since, until), one row each, oldest first, for billing and reconciliation: request_id, upstream_generation_id (OpenRouter gen-… matches its Logs export), feature, user, funding_rail, upstream_provider, model, tokens, units_debited, provider_cost_usd (developer rail), user_cost_usd (user_key, best effort), latency. At most 1,000 rows per page; pass pagination.next_cursor back as cursor with the same since and until. End the window at least five minutes in the past for a complete export. Never add provider_cost_usd, user_cost_usd, and units together: they are different parties' money.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, since: str("Window start (inclusive), ISO 8601"), until: str("Window end (exclusive), ISO 8601"), cursor: str("next_cursor of the previous page"), limit: { type: "integer", minimum: 1, maximum: 1000 } }, ["app_id", "since", "until"]) },
+    { name: "weirgate_list_user_usage", title: "List usage by user and rail", description: "Sum settled usage per end user and funding rail over whole UTC days [since, until) (both UTC midnights): requests, prompt and completion tokens, units, provider_cost_usd, user_cost_usd, and cost_unreported_requests. Rows are ordered by user_id, then rail, at most 1,000 per page; pass pagination.next_cursor back as cursor with the same window. The sums equal the usage events export for the same window.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, since: str("First UTC midnight (inclusive), ISO 8601"), until: str("End UTC midnight (exclusive), ISO 8601"), cursor: str("next_cursor of the previous page"), limit: { type: "integer", minimum: 1, maximum: 1000 } }, ["app_id", "since", "until"]) },
     { name: "weirgate_list_failures", title: "List failures", description: "List recent refused and failed metered requests, newest first, with request ids for request traces.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, since: str(), until: str(), cursor: str(), limit: integer() }, appRequired) },
     { name: "weirgate_get_pricing_insights", title: "Get pricing insights", description: "Read closed-window pricing evidence.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, since: str(), until: str() }, ["app_id", "since", "until"]) },
     { name: "weirgate_get_user_timeline", title: "Get user timeline", description: "Read one user's tenant-scoped operational timeline.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, external_id: str() }, ["app_id", "external_id"]) },
     { name: "weirgate_list_events", title: "List events", description: "List webhook delivery events for an app.", scope: "read", group: "webhooks", inputSchema: objectSchema({ ...app, status: str(), cursor: str(), limit: integer() }, appRequired) },
     { name: "weirgate_get_provider_health", title: "Get provider health", description: "Get configured provider health from non-secret slot metadata.", scope: "read", group: "provider_keys", inputSchema: objectSchema(app, appRequired) },
-    { name: "weirgate_list_audit_events", title: "List audit events", description: "List tenant-scoped management audit events.", scope: "read", group: "audit", inputSchema: objectSchema({ ...app, action: str(), since: str(), until: str(), cursor: str(), limit: integer() }) },
+    { name: "weirgate_list_audit_events", title: "List audit events", description: "List tenant-scoped management audit events. Weirgate's own access rows (platform_admin.request) are left out unless include_platform_access is true.", scope: "read", group: "audit", inputSchema: objectSchema({ ...app, action: str(), since: str(), until: str(), cursor: str(), limit: integer(), include_platform_access: { type: "boolean" } }) },
     { name: "weirgate_export_config", title: "Export config", description: "Export the visible tenant configuration.", scope: "read", group: "setup", inputSchema: objectSchema() },
     { name: "weirgate_propose_app", title: "Propose app", description: "Create a durable proposal to add or replace an app.", scope: "propose", group: "setup", inputSchema: objectSchema({ app: document() }, ["app"]) },
     { name: "weirgate_propose_auth", title: "Propose auth", description: "Create a durable proposal to change app authentication.", scope: "propose", group: "setup", inputSchema: objectSchema({ ...app, auth: document() }, ["app_id", "auth"]) },
@@ -121,6 +123,8 @@ export async function invokeTool(client, name, rawInput) {
             return client.request(`/v1/admin/apps/${a()}/sandbox/sessions/${pathPart(session.data.id)}/runs`, { method: "POST", body: { fixture: input.fixture } });
         }
         case "weirgate_query_usage": return client.request(`/v1/admin/apps/${a()}/usage`, { query: q(input, ["since", "until", "group_by", "bucket", "limit"]) });
+        case "weirgate_export_usage_events": return client.request(`/v1/admin/apps/${a()}/usage/events`, { query: q(input, ["since", "until", "cursor", "limit"]) });
+        case "weirgate_list_user_usage": return client.request(`/v1/admin/apps/${a()}/usage/users`, { query: q(input, ["since", "until", "cursor", "limit"]) });
         case "weirgate_list_failures": return client.request(`/v1/admin/apps/${a()}/failures`, { query: q(input, ["since", "until", "cursor", "limit"]) });
         case "weirgate_get_pricing_insights": return client.request(`/v1/admin/apps/${a()}/pricing-insights`, { query: q(input, ["since", "until"]) });
         case "weirgate_get_user_timeline": return client.request(`/v1/admin/apps/${a()}/users/${pathPart(input.external_id)}`);
@@ -131,7 +135,7 @@ export async function invokeTool(client, name, rawInput) {
             const target = findApp(config.data, String(input.app_id));
             return { ...config, data: { providers: slots.data, effective_feature_policy: Object.fromEntries(Object.entries(record(target.features)).map(([id, feature]) => [id, record(feature).provider_policy])) } };
         }
-        case "weirgate_list_audit_events": return client.request("/v1/admin/audit", { query: q(input, ["app_id", "action", "since", "until", "cursor", "limit"]) });
+        case "weirgate_list_audit_events": return client.request("/v1/admin/audit", { query: { ...q(input, ["app_id", "action", "since", "until", "cursor", "limit"]), include_platform_access: input.include_platform_access === true ? "true" : undefined } });
         case "weirgate_export_config": return client.request("/v1/admin/config");
         case "weirgate_propose_app": return mutateConfig(client, (tenant) => { const list = tenant.apps ?? []; const next = record(input.app); tenant.apps = [...list.filter((x) => x.app_id !== next.app_id), next]; });
         case "weirgate_propose_auth": return mutateConfig(client, (tenant) => { findApp(tenant, String(input.app_id)).auth = input.auth; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weirgate/cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Weirgate CLI and local stdio MCP server: scoped, proposal-first management of Weirgate apps.",
   "license": "MIT",
   "author": "Astraen Labs LLC",