feat(usage): expose per-account vicoop-codex usage via the bridge (#360)

Add an admin/owner-only API to read a connected vicoop-codex agent's
per-account Codex usage through the bridge server.

The usage data lives on the client (vicoop-codex `serve`'s GET /usage), so a
minimal request/response RPC is layered over the WS protocol:

- protocol: `usage.request` (Down) + `usage.response` (Up), correlated by
  requestId; `usage` payload is opaque (z.unknown), forwarded verbatim.
- client: `Backend` gains an optional `usage()`; the vicoop-codex backend
  implements it by GETting its serve `/usage` (read-only, no quota cost). The
  client answers `usage.request` with `usage.response` (ok | unsupported |
  usage_failed).
- server: `usage-rpc.ts` correlates request↔response (offline/timeout/error,
  with a responding-agent id-binding guard); `ws.ts` routes `usage.response`;
  new `GET /admin-api/agents/:id/usage` is owner-session authed and allowed
  only for the bridge admin (`isAdmin`) or the agent's owner
  (`conn.ownerPrincipal`), and only for the `vicoop-codex` backend. Errors map
  to 404 (not found/unauthorized), 400 (wrong backend), 503 (offline),
  504 (timeout).

Tests: usage-rpc correlation (offline/success/error/timeout/id-binding/stale);
client dispatch (ok/unsupported/usage_failed); vicoop-codex usage() GET + error.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ost006

.changeset/vicoop-codex-usage-api.md

@@ -0,0 +1,5 @@
+---
+"@vicoop-bridge/client": minor
+---
+
+vicoop-codex backend: report per-account Codex usage to the bridge on request. The client answers the new `usage.request` frame by querying its local `vicoop-codex serve` `/usage` endpoint, which backs the server's admin/owner-only `GET /admin-api/agents/:id/usage` API.

packages/client/src/backend.ts

@@ -42,4 +42,10 @@ export interface Backend {
   // implementations should send a kill signal / close a socket and return
   // immediately rather than wait for graceful shutdown.
   stop?(): void;
+  // Optional: return the backend's current usage / rate-limit snapshot, served
+  // on demand in response to a server-initiated `usage.request` frame. Only
+  // backends that have such a concept implement this (today: vicoop-codex,
+  // which queries its local `serve`'s GET /usage). The returned value is opaque
+  // and forwarded verbatim to the caller, so the shape can evolve freely.
+  usage?(): Promise<unknown>;
 }

packages/client/src/backends/vicoop-codex.test.ts

@@ -1235,3 +1235,53 @@ test('envelope.model is dropped when the probed list does NOT advertise it (#302
   );
   assert.equal(body.model, undefined);
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// usage(): GET <serve baseUrl>/usage (uses the global fetch, not the injected
+// streaming fetchFn). The fake spawn provides the serve baseUrl; we stub
+// globalThis.fetch to script the /usage response.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Drive the lazy `ensureServe()` (which spawns synchronously and awaits the
+// listening line) by emitting that line on the next microtask, then await the
+// in-flight usage() promise.
+async function runUsage(stubFetch: typeof globalThis.fetch): Promise<unknown> {
+  const fake = makeFakeSpawn();
+  const backend = createVicoopCodexBackend({ spawn: fake.spawn });
+  const orig = globalThis.fetch;
+  globalThis.fetch = stubFetch;
+  try {
+    const p = backend.usage!();
+    await new Promise<void>((resolve) => queueMicrotask(() => {
+      driveServeListening(fake.lastChild());
+      resolve();
+    }));
+    return await p;
+  } finally {
+    globalThis.fetch = orig;
+  }
+}
+
+test('usage(): GETs the serve /usage endpoint and returns the parsed JSON', async () => {
+  const calls: Array<{ url: string; method: string }> = [];
+  const payload = { accounts: [{ key: 'k1', email: 'a@x.com', primary: { remaining_percent: 80 } }] };
+  const usage = await runUsage((async (url, init) => {
+    calls.push({ url: String(url), method: (init?.method as string) ?? 'GET' });
+    return new Response(JSON.stringify(payload), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as typeof globalThis.fetch);
+  assert.deepEqual(usage, payload);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].method, 'GET');
+  assert.match(calls[0].url, /^http:\/\/127\.0\.0\.1:8787\/usage$/);
+});
+
+test('usage(): a non-OK serve response throws (with status in the message)', async () => {
+  await assert.rejects(
+    runUsage((async () =>
+      new Response('nope', { status: 503 })) as typeof globalThis.fetch),
+    /HTTP 503/,
+  );
+});

packages/client/src/backends/vicoop-codex.ts

@@ -1038,6 +1038,25 @@ export function createVicoopCodexBackend(
       }
     },
 
+    // Per-account Codex usage, served on demand for the bridge's usage API.
+    // Reuses the shared `serve` singleton and hits its read-only GET /usage
+    // (which does not consume quota). The payload is forwarded verbatim.
+    async usage() {
+      const handle = await ensureServe();
+      const res = await fetch(`${handle.baseUrl}/usage`, {
+        method: 'GET',
+        headers: { accept: 'application/json' },
+      });
+      if (!res.ok) {
+        const detail = await res.text().catch(() => '');
+        throw new Error(
+          `vicoop-codex serve /usage returned HTTP ${res.status}` +
+            (detail ? `: ${detail.slice(0, 300)}` : ''),
+        );
+      }
+      return res.json();
+    },
+
     async resolveCapabilities() {
       const ids = await probeVicoopCodexModels({
         command,

packages/client/src/client.test.ts

@@ -7,6 +7,7 @@ import type { AddressInfo } from 'node:net';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer, type WebSocket } from 'ws';
 import {
+  encodeFrame,
   parseUpFrame,
   type Part,
   type TaskAssignFrame,
@@ -1157,3 +1158,88 @@ test('processTask: forwards non-terminal frames (e.g. task.artifact, task.status
     ['task.status', 'task.artifact', 'task.complete'],
   );
 });
+
+// ── usage.request → usage.response dispatch ──────────────────────────────────
+// Stand up a fake bridge server that, on hello, sends a `usage.request` down
+// the wire, and capture the client's `usage.response`.
+async function runUsageDispatch(backend: Backend): Promise<UpFrame[]> {
+  const server = createServer();
+  const wss = new WebSocketServer({ server, path: '/connect' });
+  const serverUrl = await listen(server);
+  const upFrames: UpFrame[] = [];
+  wss.on('connection', (ws) => {
+    ws.on('message', (raw) => {
+      const f = parseUpFrame(typeof raw === 'string' ? raw : raw.toString('utf8'));
+      if (f.type === 'hello') {
+        ws.send(encodeFrame({ type: 'usage.request', requestId: 'req-1' }));
+      } else {
+        upFrames.push(f);
+      }
+    });
+  });
+  const c = makeSink();
+  const client = new Client({
+    serverUrl,
+    token: 'client-token',
+    agentId: 'agent-1',
+    backendKind: backend.name,
+    backend,
+    logSink: c.sink,
+    logLevel: 'info',
+    reconnectDelayMs: 10,
+    reconnectMaxDelayMs: 10,
+    reconnectJitterRatio: 0,
+    reconnectStableMs: 0,
+    heartbeatIntervalMs: 0,
+  });
+  try {
+    client.start();
+    await waitFor(
+      () => upFrames.some((f) => f.type === 'usage.response'),
+      'expected a usage.response frame',
+    );
+    return upFrames;
+  } finally {
+    client.stop();
+    await closeServer(server, wss);
+  }
+}
+
+test('usage.request: client queries backend.usage() and replies usage.response', async () => {
+  const payload = { accounts: [{ key: 'k1', email: 'a@x.com' }] };
+  const backend: Backend = {
+    name: 'vicoop-codex',
+    handle: async () => {},
+    usage: async () => payload,
+  };
+  const frames = await runUsageDispatch(backend);
+  const resp = frames.find((f) => f.type === 'usage.response');
+  assert.ok(resp && resp.type === 'usage.response');
+  assert.equal(resp.requestId, 'req-1');
+  assert.equal(resp.ok, true);
+  assert.deepEqual(resp.usage, payload);
+});
+
+test('usage.request: backend without usage() replies ok:false / unsupported', async () => {
+  const frames = await runUsageDispatch(backendOf('echo', async () => {}));
+  const resp = frames.find((f) => f.type === 'usage.response');
+  assert.ok(resp && resp.type === 'usage.response');
+  assert.equal(resp.ok, false);
+  assert.equal(resp.error?.code, 'unsupported');
+});
+
+test('usage.request: a throwing backend.usage() replies ok:false / usage_failed', async () => {
+  const backend: Backend = {
+    name: 'vicoop-codex',
+    handle: async () => {},
+    usage: async () => {
+      throw new Error('serve down');
+    },
+  };
+  const frames = await runUsageDispatch(backend);
+  const resp = frames.find((f) => f.type === 'usage.response');
+  assert.ok(resp && resp.type === 'usage.response');
+  assert.equal(resp.ok, false);
+  assert.equal(resp.error?.code, 'usage_failed');
+  assert.match(resp.error?.message ?? '', /serve down/);
+});

packages/client/src/client.ts

@@ -358,6 +358,9 @@ export class Client {
         case 'ping':
           this.send({ type: 'pong' });
           break;
+        case 'usage.request':
+          this.handleUsageRequest(frame);
+          break;
       }
     });
 
@@ -554,6 +557,45 @@ export class Client {
     this.ws.send(encodeFrame(frame));
   }
 
+  // Answer a server-initiated usage.request by querying the backend's optional
+  // usage() capability. Fire-and-forget (errors surface as usage.response with
+  // ok:false rather than throwing) so it never stalls the message loop.
+  private handleUsageRequest(
+    frame: import('@vicoop-bridge/protocol').UsageRequestFrame,
+  ): void {
+    const backend = this.opts.backend;
+    if (!backend.usage) {
+      this.send({
+        type: 'usage.response',
+        requestId: frame.requestId,
+        ok: false,
+        error: {
+          code: 'unsupported',
+          message: `backend '${backend.name}' does not support usage queries`,
+        },
+      });
+      return;
+    }
+    this.logger.info(`usage.request requestId=${safeToken(frame.requestId)}`);
+    backend.usage().then(
+      (usage) => {
+        this.send({ type: 'usage.response', requestId: frame.requestId, ok: true, usage });
+      },
+      (err: unknown) => {
+        const message = err instanceof Error ? err.message : String(err);
+        this.logger.error(
+          `usage.request failed requestId=${safeToken(frame.requestId)}: ${safeToken(message)}`,
+        );
+        this.send({
+          type: 'usage.response',
+          requestId: frame.requestId,
+          ok: false,
+          error: { code: 'usage_failed', message },
+        });
+      },
+    );
+  }
+
   private async runTask(frame: import('@vicoop-bridge/protocol').DownFrame): Promise<void> {
     if (frame.type !== 'task.assign') return;
     const controller = new AbortController();

packages/protocol/src/index.ts

@@ -227,11 +227,29 @@ export const TaskFailFrame = z.object({
 
 export const PongFrame = z.object({ type: z.literal('pong') });
 
+// Response to a server-initiated `usage.request` (see DownFrame). Correlated by
+// `requestId`. `usage` is the backend's opaque usage payload (e.g. the
+// vicoop-codex `{ accounts: [...] }` shape) — kept `unknown` so the payload can
+// evolve without a protocol bump; the server passes it through verbatim.
+export const UsageResponseFrame = z.object({
+  type: z.literal('usage.response'),
+  requestId: z.string(),
+  ok: z.boolean(),
+  usage: z.unknown().optional(),
+  error: z
+    .object({
+      code: z.string(),
+      message: z.string(),
+    })
+    .optional(),
+});
+
 export type HelloFrame = z.infer<typeof HelloFrame>;
 export type TaskStatusFrame = z.infer<typeof TaskStatusFrame>;
 export type TaskArtifactFrame = z.infer<typeof TaskArtifactFrame>;
 export type TaskCompleteFrame = z.infer<typeof TaskCompleteFrame>;
 export type TaskFailFrame = z.infer<typeof TaskFailFrame>;
+export type UsageResponseFrame = z.infer<typeof UsageResponseFrame>;
 
 export const UpFrame = z.discriminatedUnion('type', [
   HelloFrame,
@@ -240,6 +258,7 @@ export const UpFrame = z.discriminatedUnion('type', [
   TaskCompleteFrame,
   TaskFailFrame,
   PongFrame,
+  UsageResponseFrame,
 ]);
 export type UpFrame = z.infer<typeof UpFrame>;
 
@@ -258,13 +277,23 @@ export const TaskCancelFrame = z.object({
 
 export const PingFrame = z.object({ type: z.literal('ping') });
 
+// Server→client request for the backend's current usage snapshot. The client
+// replies with a `usage.response` UpFrame carrying the same `requestId`. Only
+// backends that implement `usage()` can satisfy it; others reply with an error.
+export const UsageRequestFrame = z.object({
+  type: z.literal('usage.request'),
+  requestId: z.string(),
+});
+
 export type TaskAssignFrame = z.infer<typeof TaskAssignFrame>;
 export type TaskCancelFrame = z.infer<typeof TaskCancelFrame>;
+export type UsageRequestFrame = z.infer<typeof UsageRequestFrame>;
 
 export const DownFrame = z.discriminatedUnion('type', [
   TaskAssignFrame,
   TaskCancelFrame,
   PingFrame,
+  UsageRequestFrame,
 ]);
 export type DownFrame = z.infer<typeof DownFrame>;
 

packages/server/src/http.tsx

@@ -14,7 +14,8 @@ import {
 } from '@a2x/sdk';
 import type { ClientConnection, Registry } from './registry.js';
 import { createAdminA2XAgent } from './admin.js';
-import { getAdminWallets } from './admin-scope.js';
+import { getAdminWallets, isAdmin } from './admin-scope.js';
+import { requestUsage, UsageRpcError } from './usage-rpc.js';
 import {
   AdminApiError,
   addCaller,
@@ -424,6 +425,41 @@ export function createHttpApp(opts: ServerHttpOptions): Hono {
     }
   });
 
+  // Per-account backend usage for a connected agent. Restricted to the bridge
+  // admin or the agent's owning user. Only the `vicoop-codex` backend supports
+  // it; the data is pulled from the client over the WS (usage-rpc) and the
+  // client's serve `/usage` payload is returned verbatim.
+  app.get('/admin-api/agents/:id/usage', async (c) => {
+    const auth = await authOwnerSession(c);
+    if (!auth.ok) return adminApiUnauthorized(c, auth);
+    const agentId = c.req.param('id');
+    const conn = opts.registry.getAgent(agentId);
+    // Collapse "not connected" and "not authorized" into one 404 so a
+    // non-owner can't probe which agent ids exist / are online.
+    if (!conn || !(isAdmin(auth.principalId) || conn.ownerPrincipal === auth.principalId)) {
+      return c.json({ error: 'Agent not found, not connected, or not authorized.' }, 404);
+    }
+    if (conn.backendKind !== 'vicoop-codex') {
+      return c.json(
+        {
+          error: `Usage is not available for backend '${conn.backendKind ?? 'unknown'}' (supported: vicoop-codex).`,
+        },
+        400,
+      );
+    }
+    try {
+      const usage = await requestUsage(opts.registry, agentId);
+      return c.json(usage as Record<string, unknown>);
+    } catch (err) {
+      if (err instanceof UsageRpcError) {
+        const status = err.code === 'offline' ? 503 : err.code === 'timeout' ? 504 : 502;
+        return c.json({ error: err.message, code: err.code }, status);
+      }
+      logEvent('admin_api_error', { error: String(err) });
+      return c.json({ error: 'Internal error' }, 500);
+    }
+  });
+
   app.post('/admin-api/agents/:id/callers', async (c) => {
     const auth = await authOwnerSession(c);
     if (!auth.ok) return adminApiUnauthorized(c, auth);