agent-relay-runner 0.76.0 → 0.77.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.76.0",
+  "version": "0.77.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.51"
+    "agent-relay-sdk": "0.2.52"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.76.0",
+  "version": "0.77.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/claude.ts

@@ -47,7 +47,7 @@ export class ClaudeAdapter implements ProviderAdapter {
       stderr: "inherit",
     });
     void proc.exited.then((code) => this.statusCb(code === 0 ? "offline" : "error"));
-    return { pid: proc.pid, process: proc, meta: { monitor: config.monitor } };
+    return { pid: proc.pid, process: proc, meta: { monitor: config.monitor, env: args.env } };
   }
 
   async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
@@ -335,9 +335,8 @@ export class ClaudeAdapter implements ProviderAdapter {
     }
 
     return {
-      pid: undefined,
-      process: undefined,
-      meta: {
+      pid: undefined, process: undefined, meta: {
+        env: spawnArgs.env,
         monitor: config.monitor,
         // When the profile disables the relay plugin, the bundled monitor never
         // loads, so no monitor will ever connect — deliver() must use tmux injection.

package/src/quota.ts

@@ -1,20 +1,46 @@
 import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import type { ContextProbeMetrics, QuotaState, QuotaWindowName } from "agent-relay-sdk";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { dirname, join } from "node:path";
+import type { ContextProbeMetrics, ProviderQuotaError, ProviderQuotaUpdateInput, QuotaState, QuotaWindowName } from "agent-relay-sdk";
 import { errMessage, isRecord, quotaStateFromProbeMetrics, stringValue } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { ManagedProcess } from "./adapter";
+import { agentRelayHome, runnerOutboxDirWithInfoFallback } from "./config";
 
 const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
 const CLAUDE_OAUTH_BETA = "oauth-2025-04-20";
-const QUOTA_POLL_INTERVAL_MS = 15 * 60 * 1000;
+const QUOTA_POLL_INTERVAL_MS = 5 * 60 * 1000;
+const QUOTA_FAST_RETRY_MS = 15 * 1000;
 const QUOTA_FAILURE_LOG_INTERVAL_MS = 5 * 60 * 1000;
+const QUOTA_LOCK_STALE_MS = 60 * 1000;
 
 type CodexQuotaClient = {
   isConnected?: () => boolean;
   accountRateLimitsRead?: () => Promise<unknown>;
 };
 
+type QuotaIdentity = {
+  provider: string;
+  accountKey: string;
+  credentialsPath?: string;
+};
+
+type RunnerQuotaSample = {
+  quota?: QuotaState;
+  accountKey?: string;
+};
+
+type SharedQuotaEntry = {
+  provider: string;
+  accountKey: string;
+  lastAttemptAt?: number;
+  nextAttemptAt?: number;
+  quota?: QuotaState;
+  lastError?: ProviderQuotaError | null;
+};
+
 export class RunnerQuotaPoller {
   private quotaState?: QuotaState;
   private timer?: Timer;
@@ -28,6 +54,9 @@ export class RunnerQuotaPoller {
     getProcess: () => ManagedProcess | undefined;
     onUpdate: () => void;
     log: (message: string) => void;
+    reportProviderQuota?: (input: ProviderQuotaUpdateInput) => Promise<unknown>;
+    quotaStateDir?: string;
+    fetchImpl?: typeof fetch;
   }) {}
 
   get current(): QuotaState | undefined {
@@ -64,26 +93,91 @@ export class RunnerQuotaPoller {
   private async refresh(): Promise<void> {
     if (this.inFlight) return;
     this.inFlight = true;
+    const now = Date.now();
+    let identity: QuotaIdentity | undefined;
+    let lockDir: string | undefined;
     try {
-      const quota = await collectRunnerQuotaState({
+      const process = this.options.getProcess();
+      identity = await resolveRunnerQuotaIdentity({
+        provider: this.options.provider,
+        process,
+      });
+      const attempt = beginSharedQuotaAttempt(identity, this.options.quotaStateDir, now);
+      if (!attempt.poll) {
+        if (attempt.entry?.quota && this.active) {
+          this.quotaState = attempt.entry.quota;
+          this.options.onUpdate();
+        }
+        this.schedule(attempt.retryInMs);
+        return;
+      }
+      lockDir = attempt.lockDir;
+      const sample = await collectRunnerQuotaSample({
         provider: this.options.provider,
         agentId: this.options.agentId,
-        process: this.options.getProcess(),
+        process,
+        credentialsPath: identity.credentialsPath,
+        fetchImpl: this.options.fetchImpl,
       });
-      if (quota && this.active) {
+      const quota = sample.quota;
+      if (!quota) throw new QuotaCollectionError("creds_not_ready", `${this.options.provider} quota source is not ready`);
+      if (this.active) {
+        const update: ProviderQuotaUpdateInput = {
+          provider: identity.provider,
+          accountKey: sample.accountKey ?? identity.accountKey,
+          quota,
+          lastAttemptAt: quota.updatedAt,
+          sourceAgentId: this.options.agentId,
+        };
+        await this.reportProviderQuota(update);
+        finishSharedQuotaAttempt(identity, {
+          provider: update.provider,
+          accountKey: update.accountKey,
+          quota,
+          lastAttemptAt: update.lastAttemptAt,
+          nextAttemptAt: now + QUOTA_POLL_INTERVAL_MS,
+          lastError: null,
+        }, this.options.quotaStateDir);
         this.quotaState = quota;
         this.options.onUpdate();
       }
       this.schedule();
     } catch (error) {
       const retryAfterMs = quotaRetryAfterMs(error);
+      const lastError = providerQuotaErrorFromCollectorError(error, retryAfterMs);
+      const lastAttemptAt = Date.now();
+      const retryDelayMs = retryAfterMs ?? (identity && !readSharedQuotaEntry(identity, this.options.quotaStateDir)?.lastAttemptAt ? QUOTA_FAST_RETRY_MS : QUOTA_POLL_INTERVAL_MS);
+      if (identity) {
+        await this.reportProviderQuota({
+          provider: identity.provider,
+          accountKey: identity.accountKey,
+          lastAttemptAt,
+          lastError,
+          sourceAgentId: this.options.agentId,
+        }).catch((publishError) => {
+          this.options.log(`quota status publish failed: ${errMessage(publishError)}`);
+        });
+        finishSharedQuotaAttempt(identity, {
+          provider: identity.provider,
+          accountKey: identity.accountKey,
+          lastAttemptAt,
+          nextAttemptAt: lastAttemptAt + retryDelayMs,
+          lastError,
+        }, this.options.quotaStateDir);
+      }
       if (this.active) this.logFailure(error, retryAfterMs);
-      this.schedule(retryAfterMs ?? QUOTA_POLL_INTERVAL_MS);
+      this.schedule(retryDelayMs);
     } finally {
+      if (lockDir) releaseQuotaLock(lockDir);
       this.inFlight = false;
     }
   }
 
+  private async reportProviderQuota(input: ProviderQuotaUpdateInput): Promise<void> {
+    if (!this.options.reportProviderQuota) return;
+    await this.options.reportProviderQuota(input);
+  }
+
   private logFailure(error: unknown, retryAfterMs: number | undefined): void {
     const key = retryAfterMs !== undefined ? `retry-after:${retryAfterMs}` : errMessage(error);
     const now = Date.now();
@@ -101,31 +195,91 @@ export class QuotaRetryAfterError extends Error {
   }
 }
 
-export function quotaRetryAfterMs(error: unknown): number | undefined {
+class QuotaCollectionError extends Error {
+  constructor(readonly type: ProviderQuotaError["type"], message: string) {
+    super(message);
+    this.name = "QuotaCollectionError";
+  }
+}
+
+function quotaRetryAfterMs(error: unknown): number | undefined {
   return error instanceof QuotaRetryAfterError ? error.retryAfterMs : undefined;
 }
 
-export async function collectRunnerQuotaState(input: {
+function providerQuotaErrorFromCollectorError(error: unknown, retryAfterMs: number | undefined): ProviderQuotaError {
+  if (retryAfterMs !== undefined) {
+    return { type: "rate_limited", message: errMessage(error), retryAfterMs };
+  }
+  if (error instanceof QuotaCollectionError) {
+    return { type: error.type, message: error.message };
+  }
+  return { type: "other", message: errMessage(error) };
+}
+
+export async function resolveRunnerQuotaIdentity(input: {
+  provider: string;
+  process?: ManagedProcess;
+}): Promise<QuotaIdentity> {
+  const provider = input.provider.trim().toLowerCase();
+  if (provider === "claude") {
+    const credentialsPath = claudeCredentialsPathFromProcess(input.process);
+    const token = await readClaudeOAuthAccessToken(credentialsPath);
+    return {
+      provider,
+      accountKey: token ? `credential:${shortHash(token)}` : hostProviderAccountKey(provider),
+      credentialsPath,
+    };
+  }
+  return {
+    provider,
+    accountKey: codexAccountKeyFromProcess(input.process) ?? hostProviderAccountKey(provider),
+  };
+}
+
+async function collectRunnerQuotaSample(input: {
   provider: string;
   agentId: string;
   process?: ManagedProcess;
-}): Promise<QuotaState | undefined> {
-  if (input.provider === "claude") return collectClaudeQuotaState({ agentId: input.agentId });
-  if (input.provider !== "codex") return undefined;
+  credentialsPath?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<RunnerQuotaSample> {
+  if (input.provider === "claude") return collectClaudeQuotaSample({ agentId: input.agentId, credentialsPath: input.credentialsPath, fetchImpl: input.fetchImpl });
+  if (input.provider !== "codex") return {};
   const client = input.process?.meta?.client as CodexQuotaClient | undefined;
-  if (!client?.isConnected?.() || typeof client.accountRateLimitsRead !== "function") return undefined;
-  return collectCodexQuotaState({
+  if (!client?.isConnected?.() || typeof client.accountRateLimitsRead !== "function") return {};
+  return collectCodexQuotaSample({
     agentId: codexProcessAgentId(input.process, input.agentId),
     rateLimitsRead: () => client.accountRateLimitsRead!(),
   });
 }
 
+async function collectClaudeQuotaSample(options: {
+  agentId: string;
+  credentialsPath?: string;
+  fetchImpl?: typeof fetch;
+  now?: number;
+}): Promise<RunnerQuotaSample> {
+  const payload = await fetchClaudeUsagePayload(options);
+  if (payload === undefined) return {};
+  return {
+    quota: claudeUsageQuotaState(payload, options.agentId, options.now ?? Date.now()),
+    accountKey: providerPayloadAccountKey(payload),
+  };
+}
+
 export async function collectClaudeQuotaState(options: {
   agentId: string;
   credentialsPath?: string;
   fetchImpl?: typeof fetch;
   now?: number;
 }): Promise<QuotaState | undefined> {
+  return (await collectClaudeQuotaSample(options)).quota;
+}
+
+async function fetchClaudeUsagePayload(options: {
+  credentialsPath?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<unknown | undefined> {
   const accessToken = await readClaudeOAuthAccessToken(options.credentialsPath ?? defaultClaudeCredentialsPath());
   if (!accessToken) return undefined;
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -140,8 +294,9 @@ export async function collectClaudeQuotaState(options: {
   if (response.status === 429) {
     throw new QuotaRetryAfterError(retryAfterHeaderMs(response.headers.get("retry-after")) ?? 60_000, "Claude quota source returned 429");
   }
-  if (!response.ok) return undefined;
-  return claudeUsageQuotaState(await response.json(), options.agentId, options.now ?? Date.now());
+  if (response.status === 401 || response.status === 403) throw new QuotaCollectionError("auth", `Claude quota source returned ${response.status}`);
+  if (!response.ok) throw new QuotaCollectionError("other", `Claude quota source returned ${response.status}`);
+  return response.json();
 }
 
 export function claudeUsageQuotaState(payload: unknown, agentId: string, now = Date.now()): QuotaState | undefined {
@@ -163,8 +318,20 @@ export async function collectCodexQuotaState(input: {
   rateLimitsRead: () => Promise<unknown>;
   now?: number;
 }): Promise<QuotaState | undefined> {
+  return (await collectCodexQuotaSample(input)).quota;
+}
+
+async function collectCodexQuotaSample(input: {
+  agentId: string;
+  rateLimitsRead: () => Promise<unknown>;
+  now?: number;
+}): Promise<RunnerQuotaSample> {
   try {
-    return codexRateLimitsQuotaState(await input.rateLimitsRead(), input.agentId, input.now ?? Date.now());
+    const payload = await input.rateLimitsRead();
+    return {
+      quota: codexRateLimitsQuotaState(payload, input.agentId, input.now ?? Date.now()),
+      accountKey: providerPayloadAccountKey(payload),
+    };
   } catch (error) {
     const retryAfter = codexRetryAfterMs(error);
     if (retryAfter !== undefined) throw new QuotaRetryAfterError(retryAfter, "Codex quota source returned 429");
@@ -190,7 +357,143 @@ export function codexRateLimitsQuotaState(payload: unknown, agentId: string, now
 }
 
 function defaultClaudeCredentialsPath(): string {
-  return join(homedir(), ".claude", ".credentials.json");
+  return join(defaultClaudeConfigDir(), ".credentials.json");
+}
+
+export function defaultClaudeConfigDir(): string {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+}
+
+function claudeCredentialsPathFromProcess(proc: ManagedProcess | undefined): string {
+  const env = processEnvFromMeta(proc);
+  const configDir = stringValue(env?.CLAUDE_CONFIG_DIR) ?? process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+  return join(configDir, ".credentials.json");
+}
+
+function codexAccountKeyFromProcess(proc: ManagedProcess | undefined): string | undefined {
+  const env = processEnvFromMeta(proc);
+  const codexHome = stringValue(env?.CODEX_HOME) ?? process.env.CODEX_HOME;
+  return codexHome ? `home:${shortHash(codexHome)}` : undefined;
+}
+
+function processEnvFromMeta(proc: ManagedProcess | undefined): Record<string, unknown> | undefined {
+  const direct = isRecord(proc?.meta?.env) ? proc.meta.env : undefined;
+  if (direct) return direct;
+  const config = isRecord(proc?.meta?.config) ? proc.meta.config : undefined;
+  return isRecord(config?.env) ? config.env : undefined;
+}
+
+function hostProviderAccountKey(provider: string): string {
+  return `host:${hostname()}:${provider}`;
+}
+
+export function beginSharedQuotaAttempt(identity: QuotaIdentity, stateDir?: string, now = Date.now()): {
+  poll: boolean;
+  retryInMs: number;
+  entry?: SharedQuotaEntry;
+  lockDir?: string;
+} {
+  const entry = readSharedQuotaEntry(identity, stateDir);
+  const nextAttemptAt = entry?.nextAttemptAt;
+  if (nextAttemptAt !== undefined && nextAttemptAt > now) {
+    return { poll: false, retryInMs: nextAttemptAt - now, entry };
+  }
+
+  const lockDir = sharedQuotaLockDir(identity, stateDir);
+  if (!acquireQuotaLock(lockDir, now)) {
+    return { poll: false, retryInMs: QUOTA_FAST_RETRY_MS, entry };
+  }
+  return { poll: true, retryInMs: 0, entry, lockDir };
+}
+
+function finishSharedQuotaAttempt(identity: QuotaIdentity, entry: SharedQuotaEntry, stateDir?: string): void {
+  const path = sharedQuotaStatePath(identity, stateDir);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(entry, null, 2));
+}
+
+function readSharedQuotaEntry(identity: QuotaIdentity, stateDir?: string): SharedQuotaEntry | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(sharedQuotaStatePath(identity, stateDir), "utf8")) as unknown;
+    if (!isRecord(parsed)) return undefined;
+    const provider = stringValue(parsed.provider);
+    const accountKey = stringValue(parsed.accountKey);
+    if (!provider || !accountKey) return undefined;
+    return {
+      provider,
+      accountKey,
+      ...(typeof parsed.lastAttemptAt === "number" && Number.isFinite(parsed.lastAttemptAt) ? { lastAttemptAt: parsed.lastAttemptAt } : {}),
+      ...(typeof parsed.nextAttemptAt === "number" && Number.isFinite(parsed.nextAttemptAt) ? { nextAttemptAt: parsed.nextAttemptAt } : {}),
+      ...(isQuotaState(parsed.quota) ? { quota: parsed.quota } : {}),
+      ...(parsed.lastError === null || isRecord(parsed.lastError) ? { lastError: parsed.lastError as ProviderQuotaError | null } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function sharedQuotaStatePath(identity: QuotaIdentity, stateDir?: string): string {
+  return join(sharedQuotaStateDir(stateDir), `${sharedQuotaKey(identity)}.json`);
+}
+
+function sharedQuotaLockDir(identity: QuotaIdentity, stateDir?: string): string {
+  return join(sharedQuotaStateDir(stateDir), `${sharedQuotaKey(identity)}.lock`);
+}
+
+function sharedQuotaStateDir(stateDir?: string): string {
+  return stateDir ?? join(runnerOutboxDirWithInfoFallback() ?? agentRelayHome(), "quota");
+}
+
+function sharedQuotaKey(identity: QuotaIdentity): string {
+  return sanitizeFsName(`${identity.provider}-${identity.accountKey}`);
+}
+
+function acquireQuotaLock(lockDir: string, now = Date.now()): boolean {
+  try {
+    mkdirSync(lockDir, { recursive: false });
+    writeFileSync(join(lockDir, "owner"), String(now));
+    return true;
+  } catch {
+    const ownerPath = join(lockDir, "owner");
+    try {
+      const lockedAt = Number(readFileSync(ownerPath, "utf8"));
+      if (Number.isFinite(lockedAt) && now - lockedAt <= QUOTA_LOCK_STALE_MS) return false;
+      rmSync(lockDir, { recursive: true, force: true });
+      mkdirSync(lockDir, { recursive: false });
+      writeFileSync(ownerPath, String(now));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+function releaseQuotaLock(lockDir: string): void {
+  rmSync(lockDir, { recursive: true, force: true });
+}
+
+function isQuotaState(value: unknown): value is QuotaState {
+  return isRecord(value) && Array.isArray(value.windows) && typeof value.updatedAt === "number";
+}
+
+export function providerPayloadAccountKey(payload: unknown): string | undefined {
+  if (!isRecord(payload)) return undefined;
+  const direct = stringValue(payload.accountKey) ??
+    stringValue(payload.account_key) ??
+    stringValue(payload.accountId) ??
+    stringValue(payload.account_id) ??
+    stringValue(payload.orgId) ??
+    stringValue(payload.org_id) ??
+    stringValue(payload.organizationId) ??
+    stringValue(payload.organization_id);
+  if (direct) return direct;
+  const account = isRecord(payload.account) ? payload.account : undefined;
+  const org = isRecord(payload.org) ? payload.org : isRecord(payload.organization) ? payload.organization : undefined;
+  return stringValue(account?.id) ?? stringValue(org?.id);
+}
+
+function shortHash(value: string): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
 }
 
 function quotaProviderSupported(provider: string): boolean {

package/src/runner-core.ts

@@ -353,7 +353,7 @@ export class AgentRunner {
       clearProviderTurn: (reason) => this.forceClearProviderTurn(reason),
       sessionDebug: (message) => this.sessionDebug(message),
     });
-    this.quotaPoller = new RunnerQuotaPoller({ provider: options.provider, agentId: this.agentId, getProcess: () => this.process, onUpdate: () => this.publishStatus(), log: (message) => this.logRunnerDiagnostic(message) });
+    this.quotaPoller = new RunnerQuotaPoller({ provider: options.provider, agentId: this.agentId, getProcess: () => this.process, onUpdate: () => this.publishStatus(), log: (message) => this.logRunnerDiagnostic(message), reportProviderQuota: (input) => this.http.upsertProviderQuota(input).then(() => {}) });
     this.bus = new RelayBusClient({
       url: relayBusUrl(options.relayUrl),
       role: "provider",
@@ -2126,7 +2126,6 @@ export class AgentRunner {
       ...(terminalSocket ? { tmuxSocket: terminalSocket } : {}),
     };
     if (context) meta.context = context;
-    if (quota) meta.quota = quota;
     return meta;
   }