pi-credits 0.1.2 → 0.2.0

package/README.md

@@ -11,11 +11,12 @@ A [pi](https://pi.dev/) extension that shows the active model provider's credit
 ## Supported providers
 
 - DeepSeek
+- Fireworks
 - OpenAI Codex
 - OpenRouter
 - Vercel AI Gateway
 
-The provider-specific fetching approaches are strongly inspired by [CodexBar](https://github.com/steipete/codexbar).
+Most provider-specific fetching approaches references [CodexBar](https://github.com/steipete/codexbar). Fireworks is an exception: its balance lives behind an internal gRPC API, so the approach was reverse-engineered from the `firectl` binary — see [docs/fireworks.md](./docs/fireworks.md).
 
 ## Install
 

package/docs/fireworks.md

@@ -0,0 +1,99 @@
+# Reverse-Engineering Fireworks Credits
+
+> This doc is AI-generated by the [pi](https://pi.dev/) coding agent.
+
+Most providers in pi-credits expose a documented HTTP endpoint that returns a balance. [Fireworks](https://fireworks.ai/) does not. Its dashboard shows account credit, but there is no public REST route for it. This note records how the balance API was found by reverse-engineering the official `firectl` CLI, and how the provider is implemented on top of it.
+
+## Where the binary came from
+
+Fireworks ships a command-line tool, [`firectl`](https://docs.fireworks.ai/tools-sdks/firectl/). The [Homebrew tap formula](https://github.com/fw-ai/homebrew-firectl/blob/main/Formula/firectl.rb) points at per-platform binaries; the `darwin-amd64` build was used here.
+
+It is a Go binary, and crucially an **unstripped** one, which keeps the symbol table, the `pclntab` (function/line metadata), and the full module dependency list. None of that yields original source, but it exposes the program's structure in detail.
+
+```sh
+go version -m firectl        # build info: firectl 1.7.22, Go 1.25.0, module path
+go tool nm firectl           # 81k symbols, including package-qualified names
+go tool objdump -s SYM firectl   # disassembly annotated with file:line
+go run github.com/goretk/redress@latest source firectl   # folder/file/function tree
+```
+
+## Locating the credit feature
+
+The CLI is a Cobra app that is a thin client over a gRPC service named `gateway.Gateway`. Listing the RPC method paths embedded in the binary surfaced the relevant calls:
+
+```sh
+strings firectl | grep -oE '/gateway\.Gateway/[A-Za-z]+' | sort -u
+# ... /gateway.Gateway/GetBalance
+# ... /gateway.Gateway/GetLedger
+# ... /gateway.Gateway/ListCreditRedemptions
+# ... /gateway.Gateway/ListAccounts
+```
+
+`GetBalance` is exactly what the dashboard shows, but checking the symbol table revealed that **no CLI command is wired to it** — it exists in the gateway client yet is not reachable through any `firectl` subcommand. So the goal became calling it directly.
+
+## Working out authentication
+
+Two facts had to be recovered: the host and the credential format.
+
+The binary contains several Fireworks hostnames. The inference API (`api.fireworks.ai`) is the well-known one, but the control plane uses a separate host:
+
+```sh
+strings firectl | grep -oE '[a-z0-9.-]+\.fireworks\.ai' | sort -u
+# api.fireworks.ai          (inference)
+# gateway.fireworks.ai      (control-plane gRPC)  <- this one
+# app.fireworks.ai, device-auth.fireworks.ai
+```
+
+For the credential, the disassembly of the client's auth interceptor showed it sets gRPC metadata and references both `authorization` (Bearer) and `x-api-key`. The Bearer slot expects an OIDC ID token, which is what interactive `firectl signin` produces. API-key auth uses the `x-api-key` header instead.
+
+This matched what happened on the wire while probing the endpoint with a saved API key:
+
+- `api.fireworks.ai:443` returned HTTP 404 — wrong host for this service.
+- `gateway.fireworks.ai:443` with `authorization: Bearer <key>` returned `UNAUTHENTICATED: invalid id token` — the key is not a JWT.
+- `gateway.fireworks.ai:443` with `x-api-key: <key>` authenticated, then returned `INVALID_ARGUMENT` — auth worked; the request body was incomplete.
+
+## Reconstructing the messages
+
+The Go protobuf structs carry their field tags as string literals, so the message shapes can be read straight out of the binary:
+
+```sh
+strings firectl | grep -oE 'protobuf:"[^"]*name=(name|money|currency_code|units|nanos)[^"]*"'
+```
+
+That, plus the generated getter names (`(*Balance).GetMoney`, `(*GetBalanceRequest).GetName`), gives:
+
+```proto
+message GetBalanceRequest { string name = 1; }     // "accounts/<account_id>"
+message Balance           { Money money = 1; }
+message Money { string currency_code = 1; int64 units = 2; int32 nanos = 3; }  // google.type.Money
+```
+
+`GetBalance` needs a `name` like `accounts/<account_id>`. Rather than ask the user for their account id, `ListAccounts` (which the same API key can call) returns it:
+
+```proto
+message Account              { string name = 1; string display_name = 2; }
+message ListAccountsResponse { repeated Account accounts = 1; }
+```
+
+## Confirming end to end
+
+A minimal Node.js client using `@grpc/grpc-js` and `@grpc/proto-loader` confirmed the full flow against the live service:
+
+1. `ListAccounts` with `x-api-key` → `accounts/<id>`.
+2. `GetBalance { name }` → `Balance { money: { currency_code, units, nanos } }`.
+
+The amount is `units + nanos / 1e9` (the standard `google.type.Money` encoding), e.g., `units=9, nanos=694293840` → `$9.69`.
+
+## How the provider is implemented in pi-credits
+
+The provider lives in [`src/providers/fireworks.ts`](../src/providers/fireworks.ts) and follows the same `CreditsProvider` contract as the HTTP-based providers; only the transport differs.
+
+- **Transport.** A single, reused `@grpc/grpc-js` client dials `gateway.fireworks.ai:443` over TLS. The service is declared in [`fireworks.proto`](../src/providers/fireworks.proto) — the minimal slice needed, loaded at runtime with `@grpc/proto-loader`. The `.proto` is resolved relative to the module via `import.meta.url`, so it ships and loads from the package directory.
+- **Auth.** Each call sends `x-api-key: <key>` in gRPC metadata. The key comes from pi's `modelRegistry.getApiKeyForProvider("fireworks")` (env `FIREWORKS_API_KEY`), handled by the manager.
+- **Account resolution.** `ListAccounts` is called once and the resolved `accounts/<id>` is cached per API key, so steady-state refreshes are a single `GetBalance` round trip.
+- **Cancellation.** The shared `AbortSignal` cancels the in-flight gRPC call, and a defensive deadline bounds each request.
+- **Result.** `Money` is converted to a dollar amount and returned as `{ type: "balance", remaining }`, which the status line renders like any other balance provider.
+
+## Caveats
+
+`GetBalance` is an internal API: it is intentionally absent from `firectl`, undocumented, and not part of any public contract. Its host, request shape, and behavior can change at any time without notice, which would break this provider. The narrow `.proto` keeps the blast radius small if that happens.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-credits",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A pi extension that shows the active provider's credit balance or rate-limit usage",
   "keywords": [
     "pi-coding-agent",
@@ -15,6 +15,7 @@
   "files": [
     "index.ts",
     "src",
+    "docs",
     "assets",
     "README.md",
     "LICENSE"
@@ -28,6 +29,10 @@
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.4",
+    "@grpc/proto-loader": "^0.8.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",

package/src/providers/fireworks.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+// Minimal slice of the Fireworks control-plane gateway API (`gateway.Gateway`), reconstructed from
+// the `firectl` binary. Only the messages and RPCs needed to read an account's credit balance are
+// declared here.
+package gateway;
+
+// Mirrors google.type.Money.
+message Money {
+  string currency_code = 1;
+  int64 units = 2;
+  int32 nanos = 3;
+}
+
+message Balance {
+  Money money = 1;
+}
+
+message GetBalanceRequest {
+  string name = 1; // resource name, e.g., "accounts/<account_id>"
+}
+
+message Account {
+  string name = 1; // resource name, e.g., "accounts/<account_id>"
+  string display_name = 2;
+}
+
+message ListAccountsRequest {
+  int32 page_size = 1;
+  string page_token = 2;
+}
+
+message ListAccountsResponse {
+  repeated Account accounts = 1;
+  string next_page_token = 2;
+  int32 total_size = 3;
+}
+
+service Gateway {
+  rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse);
+  rpc GetBalance(GetBalanceRequest) returns (Balance);
+}

package/src/providers/fireworks.ts

@@ -0,0 +1,111 @@
+import { fileURLToPath } from "node:url";
+
+import { credentials, loadPackageDefinition, Metadata } from "@grpc/grpc-js";
+import { loadSync } from "@grpc/proto-loader";
+
+import { toNumber } from "../utils";
+
+import type { ClientUnaryCall, ServiceClientConstructor, ServiceError } from "@grpc/grpc-js";
+import type { Credits, CreditsProvider } from "../types";
+
+type GatewayClient = InstanceType<ServiceClientConstructor>;
+
+const PROVIDER = "fireworks";
+
+/**
+ * The control-plane gateway is a gRPC service, distinct from the inference API at
+ * `api.fireworks.ai`. Credit balance lives here, behind the `x-api-key` header.
+ */
+const TARGET = "gateway.fireworks.ai:443";
+const DEADLINE_MS = 20_000;
+
+interface Money {
+  currency_code?: string;
+  units?: string | number;
+  nanos?: string | number;
+}
+
+interface Balance {
+  money?: Money | null;
+}
+
+interface Account {
+  name?: string;
+}
+
+interface ListAccountsResponse {
+  accounts?: Account[] | null;
+}
+
+/** gRPC clients are reusable and multiplex over one connection, so build once. */
+let client: GatewayClient | undefined;
+
+/** The API key maps to a fixed account, so cache the resolved resource name. */
+const accountByKey = new Map<string, string>();
+
+function getClient(): GatewayClient {
+  if (client) return client;
+
+  const protoPath = fileURLToPath(new URL("./fireworks.proto", import.meta.url));
+  const definition = loadSync(protoPath, { keepCase: true, longs: String, defaults: true });
+  const proto = loadPackageDefinition(definition) as unknown as { gateway: { Gateway: ServiceClientConstructor } };
+  client = new proto.gateway.Gateway(TARGET, credentials.createSsl());
+
+  return client;
+}
+
+async function unary<T>(method: string, request: object, apiKey: string, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const metadata = new Metadata();
+    metadata.set("x-api-key", apiKey);
+
+    const deadline = new Date(Date.now() + DEADLINE_MS);
+    const gateway = getClient();
+    const invoke = gateway[method] as (
+      request: object,
+      metadata: Metadata,
+      options: { deadline: Date },
+      callback: (error: ServiceError | null, response: T) => void,
+    ) => ClientUnaryCall;
+
+    const call = invoke.call(gateway, request, metadata, { deadline }, (error, response) => {
+      if (error) reject(new Error(error.details || error.message));
+      else resolve(response);
+    });
+
+    if (signal.aborted) call.cancel();
+    else signal.addEventListener("abort", () => call.cancel(), { once: true });
+  });
+}
+
+async function resolveAccount(apiKey: string, signal: AbortSignal): Promise<string> {
+  const cached = accountByKey.get(apiKey);
+  if (cached) return cached;
+
+  const response = await unary<ListAccountsResponse>("ListAccounts", {}, apiKey, signal);
+  const name = response.accounts?.[0]?.name;
+  if (!name) throw new Error("no account found");
+
+  accountByKey.set(apiKey, name);
+  return name;
+}
+
+function moneyToNumber(money: Money | null | undefined): number | undefined {
+  if (!money) return undefined;
+
+  const units = toNumber(money.units) ?? 0;
+  const nanos = toNumber(money.nanos) ?? 0;
+  return units + nanos / 1e9;
+}
+
+export const fireworksProvider: CreditsProvider = {
+  provider: PROVIDER,
+  label: "Fireworks",
+
+  async fetch(_ctx, apiKey, signal): Promise<Credits> {
+    const name = await resolveAccount(apiKey, signal);
+    const balance = await unary<Balance>("GetBalance", { name }, apiKey, signal);
+
+    return { type: "balance", remaining: moneyToNumber(balance.money) };
+  },
+};

package/src/providers/index.ts

@@ -1,4 +1,5 @@
 import { deepseekProvider } from "./deepseek";
+import { fireworksProvider } from "./fireworks";
 import { openaiCodexProvider } from "./openai-codex";
 import { openrouterProvider } from "./openrouter";
 import { vercelAiGatewayProvider } from "./vercel-ai-gateway";
@@ -7,6 +8,7 @@ import type { CreditsProvider } from "../types";
 
 const PROVIDERS: CreditsProvider[] = [
   deepseekProvider,
+  fireworksProvider,
   openaiCodexProvider,
   openrouterProvider,
   vercelAiGatewayProvider,