The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(adapters): stamp agent id via X-Anthropic-Agent-Id for claude_local (#8322)
Zen Processf13fd1157bbe
diff --git a/server/src/adapters/claude-agent-id-header.test.ts b/server/src/adapters/claude-agent-id-header.test.tsnew file mode 100644index 0000000000..a7371e0810--- /dev/null+++ b/server/src/adapters/claude-agent-id-header.test.ts@@ -0,0 +1,107 @@+import { describe, expect, it, vi } from "vitest";+import { stampClaudeAgentIdHeader } from "./claude-agent-id-header.js";++type ExecuteCtx = {+ agent?: { id?: string };+ config?: { env?: Record<string, unknown>; [key: string]: unknown };+ [key: string]: unknown;+};++function recordingInner() {+ const sentinel = Symbol("inner-result");+ const inner = vi.fn((ctx: ExecuteCtx) => Promise.resolve(sentinel));+ return { inner, sentinel };+}++function customHeaders(ctx: ExecuteCtx): string | undefined {+ const value = ctx.config?.env?.ANTHROPIC_CUSTOM_HEADERS;+ return typeof value === "string" ? value : undefined;+}++describe("stampClaudeAgentIdHeader", () => {+ it("merges X-Anthropic-Agent-Id into config.env (the env the adapter forwards)", async () => {+ const { inner, sentinel } = recordingInner();+ const wrapped = stampClaudeAgentIdHeader(inner as never);++ const result = await wrapped({+ agent: { id: "agent-123" },+ config: { cwd: "/work", env: { EXISTING: "keep" } },+ } as never);++ expect(result).toBe(sentinel);+ const forwarded = inner.mock.calls[0]?.[0] as ExecuteCtx;+ expect(customHeaders(forwarded)).toBe("X-Anthropic-Agent-Id: agent-123");+ // Unrelated config + env entries are preserved.+ expect(forwarded.config?.cwd).toBe("/work");+ expect(forwarded.config?.env?.EXISTING).toBe("keep");+ });++ it("appends to a pre-existing ANTHROPIC_CUSTOM_HEADERS value", async () => {+ const { inner } = recordingInner();+ const wrapped = stampClaudeAgentIdHeader(inner as never);++ await wrapped({+ agent: { id: "agent-9" },+ config: { env: { ANTHROPIC_CUSTOM_HEADERS: "X-Trace: abc" } },+ } as never);++ const forwarded = inner.mock.calls[0]?.[0] as ExecuteCtx;+ expect(customHeaders(forwarded)).toBe("X-Trace: abc\nX-Anthropic-Agent-Id: agent-9");+ });++ it("strips CR/LF and bounds length to prevent header injection", async () => {+ const { inner } = recordingInner();+ const wrapped = stampClaudeAgentIdHeader(inner as never);++ await wrapped({+ agent: { id: "evil\r\nX-Injected: 1" },+ config: { env: {} },+ } as never);++ const forwarded = inner.mock.calls[0]?.[0] as ExecuteCtx;+ expect(customHeaders(forwarded)).toBe("X-Anthropic-Agent-Id: evilX-Injected: 1");+ expect(customHeaders(forwarded)).not.toContain("\n");+ });++ it("bounds an oversized agent id to 256 characters", async () => {+ const { inner } = recordingInner();+ const wrapped = stampClaudeAgentIdHeader(inner as never);++ await wrapped({+ agent: { id: "a".repeat(500) },+ config: { env: {} },+ } as never);++ const forwarded = inner.mock.calls[0]?.[0] as ExecuteCtx;+ expect(customHeaders(forwarded)).toBe(`X-Anthropic-Agent-Id: ${"a".repeat(256)}`);+ });++ it("passes through unchanged when no agent id is available", async () => {+ const { inner } = recordingInner();+ const wrapped = stampClaudeAgentIdHeader(inner as never);++ const ctx = { agent: {}, config: { env: { EXISTING: "keep" } } } as never;+ await wrapped(ctx);++ // Same ctx object forwarded; no header added.+ expect(inner.mock.calls[0]?.[0]).toBe(ctx);+ expect(customHeaders(inner.mock.calls[0]?.[0] as ExecuteCtx)).toBeUndefined();+ });++ it("does not append a duplicate when X-Anthropic-Agent-Id is already present", async () => {+ const { inner } = recordingInner();+ const wrapped = stampClaudeAgentIdHeader(inner as never);++ const ctx = {+ agent: { id: "agent-7" },+ config: { env: { ANTHROPIC_CUSTOM_HEADERS: "X-Anthropic-Agent-Id: manual-override" } },+ } as never;+ await wrapped(ctx);++ // Manual override is respected — ctx forwarded untouched.+ expect(inner.mock.calls[0]?.[0]).toBe(ctx);+ expect(customHeaders(inner.mock.calls[0]?.[0] as ExecuteCtx)).toBe(+ "X-Anthropic-Agent-Id: manual-override",+ );+ });+});diff --git a/server/src/adapters/claude-agent-id-header.ts b/server/src/adapters/claude-agent-id-header.tsnew file mode 100644index 0000000000..dfd89eff66--- /dev/null+++ b/server/src/adapters/claude-agent-id-header.ts@@ -0,0 +1,39 @@+import type { ServerAdapterModule } from "./types.js";++type ClaudeExecute = ServerAdapterModule["execute"];++const AGENT_ID_HEADER = "X-Anthropic-Agent-Id";++/**+ * Wraps the claude_local execute so every request the spawned Claude Code makes+ * carries `X-Anthropic-Agent-Id: <agentId>` via ANTHROPIC_CUSTOM_HEADERS. A proxy+ * such as better-ccflare reads that header to attribute requests per agent for+ * downstream cost/token telemetry.+ *+ * The header is merged into `config.env` — the env the adapter actually forwards+ * into the spawned process — not `agent.adapterConfig.env`, which is resolved+ * upstream before execute runs and is never read by the Claude adapter.+ */+export function stampClaudeAgentIdHeader(inner: ClaudeExecute): ClaudeExecute {+ return (ctx) => {+ const agent = (ctx as { agent?: { id?: string } }).agent;+ // Strip CR/LF and bound length to prevent HTTP header injection — agentId is+ // interpolated into ANTHROPIC_CUSTOM_HEADERS, which is forwarded as a header.+ const agentId = agent?.id+ ? String(agent.id).replace(/[\r\n]/g, "").trim().slice(0, 256)+ : undefined;+ if (!agentId) return inner(ctx);+ const config = ((ctx as { config?: unknown }).config ?? {}) as Record<string, unknown>;+ const env: Record<string, unknown> = {+ ...((config.env as Record<string, unknown> | undefined) ?? {}),+ };+ const existing =+ typeof env.ANTHROPIC_CUSTOM_HEADERS === "string" ? env.ANTHROPIC_CUSTOM_HEADERS : "";+ // Respect an X-Anthropic-Agent-Id already set via manual override — appending a+ // second line would send a duplicate header to the proxy.+ if (/(^|\n)\s*X-Anthropic-Agent-Id\s*:/i.test(existing)) return inner(ctx);+ const header = `${AGENT_ID_HEADER}: ${agentId}`;+ env.ANTHROPIC_CUSTOM_HEADERS = existing ? `${existing}\n${header}` : header;+ return inner({ ...ctx, config: { ...config, env } } as Parameters<ClaudeExecute>[0]);+ };+}diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.tsindex 09f6b2a299..1c232d7d09 100644--- a/server/src/adapters/registry.ts+++ b/server/src/adapters/registry.ts@@ -5,6 +5,7 @@ import type {ServerAdapterModule,} from "./types.js";import { parseAdapterModelsEnv } from "../services/adapter-models-env.js";+import { stampClaudeAgentIdHeader } from "./claude-agent-id-header.js";import {buildSandboxNpmInstallCommand,getAdapterSessionManagement,@@ -266,7 +267,7 @@ async function listAcpxModels(): Promise<AdapterModel[]> {const claudeLocalAdapter: ServerAdapterModule = {type: "claude_local",- execute: claudeExecute,+ execute: stampClaudeAgentIdHeader(claudeExecute),testEnvironment: claudeTestEnvironment,listSkills: listClaudeSkills,syncSkills: syncClaudeSkills,