@zvada/agent-server 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Harness-agnostic agent execution engine: run Claude Code, Codex (SDK/CLI + app-server), and any ACP agent behind one interface with a normalized event stream, multi-turn sessions, and resume. Root export is the wire contract; /core, /server, /client are the seats.",
 	"license": "MIT",
 	"type": "module",
@@ -25,7 +25,13 @@
 	"engines": {
 		"bun": ">=1.2.0"
 	},
-	"files": ["src", "docs", "README.md", "CHANGELOG.md", "LICENSE"],
+	"files": [
+		"src",
+		"docs",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
 	"publishConfig": {
 		"access": "public"
 	},

package/src/core/agents/codex-app-server/client.ts

@@ -1,6 +1,9 @@
 import { type ChildProcess, spawn as nodeSpawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
 
+/** Cap the retained stderr tail — enough for the CLI's error, never a log flood. */
+const STDERR_TAIL_MAX = 2048;
+
 /** A JSON-RPC notification (server → client, no id). */
 export interface CodexNotification {
 	method: string;
@@ -54,6 +57,11 @@ export class CodexAppServerClient {
 	private readonly closeHandlers = new Set<(error?: Error) => void>();
 	private requestHandler?: ServerRequestHandler;
 	private exited = false;
+	/** Bounded rolling tail of the subprocess's stderr — folded into the exit
+	 *  error so failures carry the CLI's own explanation. */
+	private stderrTail = "";
+	/** Chunk-boundary-safe UTF-8 decoding for the stderr tail; reset per spawn. */
+	private stderrDecoder = new StringDecoder("utf8");
 
 	constructor(private readonly opts: CodexAppServerClientOptions = {}) {}
 
@@ -140,14 +148,32 @@ export class CodexAppServerClient {
 			stdio: ["pipe", "pipe", "pipe"],
 		});
 		this.proc = proc;
+		this.stderrTail = "";
+		this.stderrDecoder = new StringDecoder("utf8");
 		proc.stdout?.on("data", (chunk: Buffer) => this.onStdout(chunk));
 		proc.stdin?.on("error", (err) => this.onExit(err));
 		proc.stdout?.on("error", (err) => this.onExit(err));
-		proc.stderr?.on("data", () => {});
+		// Keep a bounded tail of stderr: it is the ONLY place the CLI explains
+		// itself (a missing/expired login prints there and exits 1). Discarding
+		// it reduced every failure to "exited (code=1)" — indistinguishable
+		// from a crash for the integrator staring at the turn error. Decoded
+		// via StringDecoder so a UTF-8 sequence split across chunks survives.
+		proc.stderr?.on("data", (chunk: Buffer) => {
+			this.stderrTail = (this.stderrTail + this.stderrDecoder.write(chunk)).slice(-STDERR_TAIL_MAX);
+		});
 		proc.on("error", (err) => this.onExit(err));
-		proc.on("exit", (code, signal) =>
-			this.onExit(new Error(`codex app-server exited (code=${code} signal=${signal})`)),
-		);
+		// Build the exit error on CLOSE, not exit: `exit` can fire before the
+		// stderr stream flushes its final data, and the final flush is usually
+		// the line that says WHY. `close` is guaranteed after both.
+		proc.on("close", (code, signal) => {
+			this.stderrTail = (this.stderrTail + this.stderrDecoder.end()).slice(-STDERR_TAIL_MAX);
+			const tail = this.stderrTail.trim().replace(/\s+/g, " ");
+			this.onExit(
+				new Error(
+					`codex app-server exited (code=${code} signal=${signal})${tail ? `: ${tail}` : ""}`,
+				),
+			);
+		});
 	}
 
 	private onStdout(chunk: Buffer): void {

package/src/core/proxy/anthropic-proxy.ts

@@ -4,6 +4,26 @@ import { type ApiKeyStore, apiKeyStore } from "./api-key-store.ts";
 /** Placeholder key handed to the agent subprocess; swapped for the real one here. */
 export const PROXY_PLACEHOLDER_KEY = "sk-proxy-managed";
 
+/**
+ * The `anthropic-beta` capability that must accompany OAuth bearer traffic.
+ * Anthropic's gateway guidance: proxies carrying subscription-OAuth requests
+ * must advertise this capability or the upstream rejects the bearer token.
+ */
+export const ANTHROPIC_OAUTH_BETA = "oauth-2025-04-20";
+
+/** Append a capability to `anthropic-beta` without clobbering existing ones. */
+function appendAnthropicBeta(headers: Headers, capability: string): void {
+	const existing = headers.get("anthropic-beta");
+	const values = existing
+		? existing
+				.split(",")
+				.map((value) => value.trim())
+				.filter(Boolean)
+		: [];
+	if (!values.includes(capability)) values.push(capability);
+	headers.set("anthropic-beta", values.join(","));
+}
+
 /** Minimal fetch shape (`globalThis.fetch` qualifies; injectable for tests/platforms). */
 export type FetchLike = (
 	input: string | URL | Request,
@@ -68,10 +88,19 @@ export function createAnthropicProxy(
 		}
 
 		const headers = new Headers(request.headers);
-		headers.set("x-api-key", entry.apiKey);
-		headers.delete("authorization");
 		headers.delete("host");
 		headers.delete("content-length");
+		if (entry.kind === "oauth") {
+			// Subscription token: bearer auth + the OAuth capability. The
+			// x-api-key the CLI sent carries only the placeholder — it must go,
+			// or the upstream sees two conflicting credentials.
+			headers.delete("x-api-key");
+			headers.set("authorization", `Bearer ${entry.apiKey}`);
+			appendAnthropicBeta(headers, ANTHROPIC_OAUTH_BETA);
+		} else {
+			headers.set("x-api-key", entry.apiKey);
+			headers.delete("authorization");
+		}
 
 		const init: RequestInit & { duplex?: "half" } = {
 			method: request.method,

package/src/core/proxy/api-key-store.ts

@@ -1,20 +1,52 @@
-/** A real upstream key + base URL, keyed by an opaque proxy session id. */
+/** How a stored credential is presented to the upstream API. */
+export type ApiCredentialKind = "api_key" | "oauth";
+
+/** A real upstream credential + base URL, keyed by an opaque proxy session id. */
 export interface ApiKeyEntry {
 	apiKey: string;
 	upstreamBaseUrl: string;
+	/**
+	 * `api_key` → sent as `x-api-key` (Anthropic API keys).
+	 * `oauth` → sent as `Authorization: Bearer` with the OAuth capability
+	 * advertised in `anthropic-beta` (Claude subscription tokens from
+	 * `claude setup-token`, `sk-ant-oat01-…`).
+	 */
+	kind: ApiCredentialKind;
+}
+
+export interface ApiKeyStoreSetOptions {
+	upstreamBaseUrl?: string;
+	kind?: ApiCredentialKind;
 }
 
 /**
  * In-memory map of proxy-session → real credentials. The agent subprocess is
  * given a placeholder key and pointed at the local proxy; the proxy swaps in the
- * real key from this store before forwarding upstream, so the key never lives in
- * the subprocess environment. (BYOK pattern from the echo/agnt sidecars.)
+ * real credential from this store before forwarding upstream, so it never lives
+ * in the subprocess environment. (BYOK pattern from the echo/agnt sidecars.)
+ * That no-exfiltration property is exactly why subscription OAuth tokens ride
+ * the same store instead of the child env: the child keeps the placeholder
+ * either way, only the upstream header shape differs.
  */
 export class ApiKeyStore {
 	private readonly entries = new Map<string, ApiKeyEntry>();
 
-	set(sessionId: string, apiKey: string, upstreamBaseUrl = "https://api.anthropic.com"): void {
-		this.entries.set(sessionId, { apiKey, upstreamBaseUrl });
+	set(
+		sessionId: string,
+		apiKey: string,
+		// A plain string third argument (the base URL) remains supported: the
+		// pre-kind signature every existing sidecar call site uses.
+		optionsOrBaseUrl: string | ApiKeyStoreSetOptions = {},
+	): void {
+		const options =
+			typeof optionsOrBaseUrl === "string"
+				? { upstreamBaseUrl: optionsOrBaseUrl }
+				: optionsOrBaseUrl;
+		this.entries.set(sessionId, {
+			apiKey,
+			upstreamBaseUrl: options.upstreamBaseUrl ?? "https://api.anthropic.com",
+			kind: options.kind ?? "api_key",
+		});
 	}
 
 	get(sessionId: string): ApiKeyEntry | undefined {

package/src/core/proxy/index.ts

@@ -1,6 +1,13 @@
 // @zvada/agent-server/core/proxy — optional BYOK Anthropic proxy building block.
-export { type ApiKeyEntry, ApiKeyStore, apiKeyStore } from "./api-key-store.ts";
 export {
+	type ApiCredentialKind,
+	type ApiKeyEntry,
+	ApiKeyStore,
+	type ApiKeyStoreSetOptions,
+	apiKeyStore,
+} from "./api-key-store.ts";
+export {
+	ANTHROPIC_OAUTH_BETA,
 	type AnthropicProxyOptions,
 	createAnthropicProxy,
 	PROXY_PLACEHOLDER_KEY,