agent-accelerator 0.2.0 → 0.4.0

package/src/types/response.ts

@@ -2,6 +2,19 @@ import type { TokenUsage } from "./core.ts";
 import type { ToolCallRecord, ToolResultRecord } from "./tool.ts";
 import type { ProviderRawData, ProviderId } from "./model.ts";
 
+/** One logged step inside a sub-agent worker run (surfaced via `agent.track(id)`). */
+export interface SubAgentStep {
+  turn: number;
+  type: "assistant" | "tool_call" | "tool_result";
+  name?: string;
+  text?: string;
+  thinking?: string;
+  isError?: boolean;
+  timestamp: number;
+  /** True while the worker is still streaming this step; finalized on turn end. */
+  partial?: boolean;
+}
+
 /** Per-worker result and usage metadata attached to an AgentResponse. */
 export interface SubAgentExecutionMetadata {
   name: string;
@@ -20,6 +33,69 @@ export interface SubAgentExecutionMetadata {
   raw?: ProviderRawData;
   isError?: boolean;
   error?: string;
+  /** Stable display id: `SUBAGENT-NAME-{TrackingID}` (32-char hex, see `createTrackingId`). */
+  trackingId?: string;
+  /** Provider session id used by this worker (≤64 chars, affinity-safe). */
+  sessionId?: string;
+  /** Parent session this worker was spawned from. */
+  parentSessionId?: string;
+  /** Ordered step log for this worker (also persisted in the session file). */
+  steps?: SubAgentStep[];
+}
+
+/** Canonical finish reasons surfaced on AgentResponse (provider-agnostic).
+ * Vendors use varied strings (`end_turn`, `stop_sequence`, `max_tokens`,
+ * `tool_use`, ...); adapters map them to these values and preserve the
+ * original in `rawFinishReason`. Unknown non-empty reasons map to `"error"`.
+ * The `(string & {})` extension keeps vendor passthrough assignable at
+ * provider call sites that forward raw strings (normalize with
+ * `normalizeFinishReason` to canonicalize). */
+export type FinishReason =
+  | "stop"
+  | "tool_calls"
+  | "length"
+  | "content_filter"
+  | "refusal"
+  | "max_turns"
+  | "error"
+  | (string & {});
+
+/** Maps a vendor finish reason to canonical FinishReason + raw passthrough.
+ * Known aliases collapse to the canonical set; empty/undefined stays
+ * undefined; any other non-empty string maps to `"error"` with the original
+ * preserved in `rawFinishReason` (Q-04). */
+export function normalizeFinishReason(raw?: string): {
+  finishReason?: FinishReason;
+  rawFinishReason?: string;
+} {
+  if (raw === undefined || raw === null || raw === "") return {};
+  const r = String(raw);
+  const lower = r.toLowerCase();
+  const map: Record<string, FinishReason> = {
+    stop: "stop",
+    end_turn: "stop",
+    stop_sequence: "stop",
+    completed: "stop",
+    complete: "stop",
+    done: "stop",
+    tool_calls: "tool_calls",
+    tool_use: "tool_calls",
+    function_call: "tool_calls",
+    tool_call: "tool_calls",
+    length: "length",
+    max_tokens: "length",
+    max_turns: "max_turns",
+    content_filter: "content_filter",
+    refusal: "refusal",
+    refused: "refusal",
+    error: "error",
+    failed: "error",
+    cancelled: "error",
+    canceled: "error",
+  };
+  const mapped = map[lower] ?? map[r];
+  if (mapped) return r === mapped ? { finishReason: mapped } : { finishReason: mapped, rawFinishReason: r };
+  return { finishReason: "error", rawFinishReason: r };
 }
 
 /** JSON representation returned by AgentResponse.toJSON(). */
@@ -34,7 +110,9 @@ export interface AgentResponseJSON {
   responseId?: string;
   model: string;
   provider: ProviderId | string;
-  finishReason?: string;
+  finishReason?: FinishReason;
+  /** Original vendor finish string when it differs from canonical `finishReason` (Q-04). */
+  rawFinishReason?: string;
   durationMs: number;
   raw: ProviderRawData;
   turns: number;
@@ -52,7 +130,9 @@ export class AgentResponse {
   readonly responseId?: string;
   readonly model: string;
   readonly provider: ProviderId | string;
-  readonly finishReason?: string;
+  readonly finishReason?: FinishReason;
+  /** Original vendor finish string when it differs from canonical `finishReason` (Q-04). */
+  readonly rawFinishReason?: string;
   readonly durationMs: number;
   readonly raw: ProviderRawData;
   readonly turns: number;
@@ -75,7 +155,8 @@ export class AgentResponse {
     responseId?: string;
     model: string;
     provider: ProviderId | string;
-    finishReason?: string;
+    finishReason?: FinishReason;
+    rawFinishReason?: string;
     durationMs: number;
     raw: ProviderRawData;
     turns?: number;
@@ -91,6 +172,7 @@ export class AgentResponse {
     this.model = data.model;
     this.provider = data.provider;
     this.finishReason = data.finishReason;
+    this.rawFinishReason = data.rawFinishReason;
     this.durationMs = data.durationMs;
     this.raw = data.raw;
     this.turns = data.turns ?? 1;
@@ -115,6 +197,7 @@ export class AgentResponse {
       model: this.model,
       provider: this.provider,
       finishReason: this.finishReason,
+      rawFinishReason: this.rawFinishReason,
       durationMs: this.durationMs,
       raw: this.raw,
       turns: this.turns,
@@ -135,7 +218,12 @@ export type StreamEventType =
   | "tool_call_delta"
   | "tool_call_complete"
   | "tool_result"
+  | "tool_start"
+  | "tool_end"
   | "subagent_complete"
+  | "subagent_delta"
+  | "steer_injected"
+  | "queued"
   | "usage"
   | "done"
   | "error";
@@ -143,16 +231,75 @@ export type StreamEventType =
 /** Payload for one streaming text, thinking, tool, usage, or lifecycle event. */
 export interface StreamEvent {
   type: StreamEventType;
+  /** Schema version for typed consumers (Q-40). Currently always 1 when present. */
+  schemaVersion?: 1;
   delta?: string;
   thinkingDelta?: string;
   toolCall?: ToolCallRecord;
   toolResult?: ToolResultRecord;
+  /** Batch tool calls for `tool_start` events (Q-40). */
+  toolCalls?: ToolCallRecord[];
+  /** Batch tool results for `tool_end` events (Q-40). */
+  toolResults?: ToolResultRecord[];
   subagent?: SubAgentExecutionMetadata;
+  /** Tracking id of the worker emitting a `subagent_delta` event. */
+  subagentTrackingId?: string;
+  /** Steered prompt text injected via `steer()` (`steer_injected` events). */
+  injectedPrompt?: string;
+  /** Queued prompt text accepted as a next-turn follow-up (`queued` events). */
+  queuedPrompt?: string;
+  /** Pending queue length at the time of a `queued`/`steer_injected` event. */
+  queueLength?: number;
   usage?: TokenUsage;
   responseId?: string;
+  /** Canonical finish reason when known; vendor strings pass through as-is
+   * for provider compat (normalize with `normalizeFinishReason`). */
   finishReason?: string;
+  /** Original vendor finish string when it differs from canonical (Q-04). */
+  rawFinishReason?: string;
   error?: Error | unknown;
   partialText?: string;
   partialThinking?: string;
   raw?: ProviderRawData;
 }
+
+/** Typed (discriminated) stream event schema, version 1 (Q-40).
+ * `StreamEvent` stays the permissive compat shape; use this union when you
+ * want exhaustive switching (e.g. `tool_start`/`tool_end` lifecycle). */
+export type StreamEventV2 =
+  | { schemaVersion: 1; type: "start"; responseId?: string }
+  | { schemaVersion: 1; type: "text_start"; responseId?: string }
+  | { schemaVersion: 1; type: "text_delta"; delta: string; partialText?: string }
+  | { schemaVersion: 1; type: "text_end"; partialText?: string }
+  | { schemaVersion: 1; type: "thinking_start"; responseId?: string }
+  | { schemaVersion: 1; type: "thinking_delta"; thinkingDelta: string; partialThinking?: string }
+  | { schemaVersion: 1; type: "thinking_end"; partialThinking?: string }
+  | { schemaVersion: 1; type: "tool_call_start"; toolCall: ToolCallRecord }
+  | { schemaVersion: 1; type: "tool_call_delta"; toolCall: ToolCallRecord; delta?: string }
+  | { schemaVersion: 1; type: "tool_call_complete"; toolCall: ToolCallRecord }
+  | { schemaVersion: 1; type: "tool_result"; toolResult: ToolResultRecord }
+  | { schemaVersion: 1; type: "tool_start"; toolCalls: ToolCallRecord[] }
+  | { schemaVersion: 1; type: "tool_end"; toolResults: ToolResultRecord[] }
+  | { schemaVersion: 1; type: "subagent_complete"; subagent: SubAgentExecutionMetadata }
+  | {
+      schemaVersion: 1;
+      type: "subagent_delta";
+      subagentTrackingId: string;
+      delta?: string;
+      thinkingDelta?: string;
+      partialText?: string;
+      partialThinking?: string;
+    }
+  | { schemaVersion: 1; type: "steer_injected"; injectedPrompt: string; queueLength?: number }
+  | { schemaVersion: 1; type: "queued"; queuedPrompt: string; queueLength?: number }
+  | { schemaVersion: 1; type: "usage"; usage: TokenUsage }
+  | {
+      schemaVersion: 1;
+      type: "done";
+      delta?: string;
+      usage?: TokenUsage;
+      finishReason?: FinishReason | string;
+      rawFinishReason?: string;
+      responseId?: string;
+    }
+  | { schemaVersion: 1; type: "error"; error: Error | unknown };

package/src/types/tool.ts

@@ -1,5 +1,16 @@
 import type { z } from "zod";
 
+/** Minimal logger surface accepted by tool contexts (Q-54/Q-55, additive). */
+export interface ToolLogger {
+  debug?: (...args: unknown[]) => void;
+  info?: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+}
+
+/** Live-event emitter handed to tools that stream progress (Q-55, additive). */
+export type ToolEmitFn = (event: { type: string; [k: string]: unknown }) => void;
+
 export interface ToolExecutionContext {
   /** Unique ID for the model-generated invocation. */
   toolCallId: string;
@@ -9,6 +20,15 @@ export interface ToolExecutionContext {
   signal?: AbortSignal;
   /** Session identifier associated with this invocation. */
   sessionId?: string;
+  /** Forwards live sub-agent deltas (used by `spawn_subagents` for realtime tracking). */
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+  // Q-55 Tool API v2 context additions (all optional, additive).
+  /** Stable id for this run (`newRunId`). Mirrors SubAgentRunIds.runId. */
+  runId?: string;
+  /** Live-event emitter for tools that stream progress. */
+  emit?: ToolEmitFn;
+  /** Structured logger for tool implementations (defaults to no-op). */
+  logger?: ToolLogger;
 }
 
 export type ToolExecuteFn<TInput = any, TOutput = any> = (
@@ -35,6 +55,57 @@ export interface ToolDefinition<TInput = any, TOutput = any> {
   maxConcurrency?: number | string;
   /** Function executed after validation; its result is made JSON-safe for model context. */
   execute: ToolExecuteFn<TInput, TOutput>;
+  // Q-55 Tool API v2 additions (all optional, additive; loop reads via `(toolDef as any).*`).
+  /**
+   * Canonical alias for `maxTries`. When both are set, `maxTries` wins.
+   * Normalized by `normalizeMaxAttempts` (see tools/tool.ts).
+   */
+  maxAttempts?: number | string;
+  /**
+   * Whether this tool is safe to retry on transient failures. Retry defaults
+   * to a single attempt unless this is `true` (bounded retries) or `maxTries`/
+   * `maxAttempts` explicitly overrides the attempt count.
+   */
+  idempotent?: boolean;
+  /**
+   * Explicit retry policy. Preferred over bare `maxTries` for new code;
+   * `maxTries`/`maxAttempts` map to `{ maxRetries: n - 1 }`.
+   */
+  retry?: { maxRetries?: number; baseDelayMs?: number; maxDelayMs?: number };
+  /**
+   * Whether an identical call may repeat across consecutive turns. Defaults to
+   * `true` for idempotent tools, `false` otherwise. Honored by repeat guards.
+   */
+  repeatable?: boolean;
+  /**
+   * Maximum characters of a string tool result kept for model context.
+   * Longer strings are truncated with a `[Truncated: ...]` marker.
+   * `0`/omitted uses the executor default (20000).
+   */
+  maxResultChars?: number | string;
+  /** Optional hook to redact/replace the error message sent back to the model. */
+  redactError?: (err: unknown) => string;
+  /**
+   * Canonical alias for `redactError`. When both are set, `redactError` wins.
+   * Kept short for Q-55 Tool API v2 parity.
+   */
+  redact?: (err: unknown) => string;
+  /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */
+  tags?: string[];
+  /**
+   * When true, the host must approve this call before execution (human-in-the-
+   * loop). The loop reads via `(toolDef as any).needsApproval`; enforcement
+   * is wired by the host, default open (undefined = no gate).
+   */
+  needsApproval?: boolean;
+  /**
+   * Optional output schema (Zod or JSON Schema) used to validate/coerce the
+   * tool's return value before it reaches model context. Stored as `unknown`
+   * so `zod` stays an optional peer for type-only consumers.
+   */
+  output?: unknown;
+  /** Opaque brand marker narrowing bare object literals to `tool()` output. */
+  readonly __brand?: "ToolDefinition";
 }
 
 export interface StandardToolDeclaration {

package/src/update-models.ts

@@ -8,10 +8,12 @@
  *   bun src/update-models.ts --ttl=24h
  */
 
-import { refreshModelCatalog, getCatalogStatus } from "./index.ts";
+import { refreshModelCatalog } from "./index.ts";
+import { ConfigError } from "./types/errors.ts";
 
 const args = process.argv.slice(2);
-const force = args.includes("--force") || !args.some((a) => a.startsWith("--ttl"));
+// Q-34: force is true only with explicit --force (previously also true when no --ttl).
+const force = args.includes("--force");
 
 let customTtlMs: number | undefined;
 for (const arg of args) {
@@ -24,6 +26,10 @@ for (const arg of args) {
     } else {
       customTtlMs = parseFloat(val);
     }
+    // Q-34: reject non-numeric TTLs (e.g. --ttl=abc) instead of silently caching NaN.
+    if (!Number.isFinite(customTtlMs)) {
+      throw new ConfigError(`Invalid --ttl value "${val}": expected a number with optional h/m suffix (e.g. --ttl=24h).`);
+    }
   }
 }
 

package/src/utils/cache.ts

@@ -8,7 +8,6 @@
  */
 
 import type { CacheRetention } from "../types/core.ts";
-import type { ModelSpec } from "../types/model.ts";
 import { getApiKey } from "./env.ts";
 
 const CACHE_KEY_MAX = 64;
@@ -144,3 +143,71 @@ export async function createExplicitCache(
 
   return (await response.json()) as CachedContentMetadata;
 }
+
+// ---------------------------------------------------------------------------
+// Central redaction helpers (Q-11, temporary home to avoid owner conflicts).
+// Providers must call these instead of maintaining local deny-lists.
+// ---------------------------------------------------------------------------
+
+/** Header-name deny-list (case-insensitive substring match). */
+const REDACT_HEADER_SUBSTRINGS = ["key", "token", "secret", "cookie", "authorization"];
+
+/** Secret-looking value prefixes. */
+const REDACT_VALUE_PREFIXES = ["sk-", "AIza", "gsk-", "xox-"];
+
+function headerNameIsSensitive(name: string): boolean {
+  const lower = String(name ?? "").toLowerCase();
+  return REDACT_HEADER_SUBSTRINGS.some((s) => lower.includes(s));
+}
+
+function valueLooksSensitive(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  if (REDACT_VALUE_PREFIXES.some((p) => v.includes(p))) return true;
+  // Bearer-style long tokens: "Bearer <20+ chars>"
+  if (/^bearer\s+\S{20,}/i.test(v)) return true;
+  return false;
+}
+
+/**
+ * Redacts a single value: sensitive strings become "[REDACTED]" (Q-11).
+ */
+export function redactValue(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  if (valueLooksSensitive(value)) return "[REDACTED]";
+  return value;
+}
+
+/**
+ * Redacts sensitive header values (Q-11). Returns a shallow copy; input untouched.
+ * Deny-list (name contains): *key*, *token*, *secret*, cookie, authorization.
+ * Value patterns (redacted regardless of name): sk-, AIza, gsk-, xox-.
+ */
+export function redactHeadersCentral(
+  headers: Record<string, unknown> | undefined | null
+): Record<string, unknown> {
+  if (!headers || typeof headers !== "object") return {};
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (headerNameIsSensitive(k) || valueLooksSensitive(v)) out[k] = "[REDACTED]";
+    else out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Redacts secret-looking substrings inside free text (Q-11).
+ * Replaces `sk-...`, `AIza...`, `gsk-...`, `xox-...` tokens with "[REDACTED]".
+ */
+export function redactText(text: string): string {
+  if (typeof text !== "string" || !text) return text;
+  // Note: longer prefixes (gsk-/gsk_) first so the generic sk- pattern
+  // does not partially match inside them (e.g. "gsk-abc" -> one token).
+  return text
+    .replace(/gsk_[A-Za-z0-9]{8,}/g, "[REDACTED]")
+    .replace(/gsk-[A-Za-z0-9-_]{8,}/g, "[REDACTED]")
+    .replace(/xox-[A-Za-z0-9-]{8,}/g, "[REDACTED]")
+    .replace(/AIza[A-Za-z0-9-_]{10,}/g, "[REDACTED]")
+    .replace(/sk-[A-Za-z0-9-_]{8,}/g, "[REDACTED]")
+    .replace(/Bearer\s+[A-Za-z0-9\-._~+/=]{20,}/gi, "Bearer [REDACTED]");
+}

package/src/utils/env.ts

@@ -2,7 +2,8 @@
  * Safe environment lookup for API keys and configurations
  */
 /**
- * Reads an environment/global value without assuming a Node-only runtime.
+ * Reads an environment value. Process env only. No globalThis fallback:
+ * DOM-clobberable in browsers (Q-05).
  *
  * @example `const apiKey = getEnv("OPENAI_API_KEY");`
  */
@@ -10,9 +11,6 @@ export function getEnv(key: string, fallback?: string): string | undefined {
   if (typeof process !== "undefined" && process.env && process.env[key]) {
     return process.env[key];
   }
-  if (typeof globalThis !== "undefined" && (globalThis as any)[key]) {
-    return (globalThis as any)[key];
-  }
   return fallback;
 }
 
@@ -53,8 +51,6 @@ export function getApiKey(provider: string, explicitKey?: string, env?: Provider
       return getEnv("OPENROUTER_API_KEY");
     case "openai":
       return getEnv("OPENAI_BASE_API_KEY") || getEnv("OPENAI_API_KEY");
-    case "anthropic":
-      return getEnv("ANTHROPIC_API_KEY");
     default:
       return getEnv(`${provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`);
   }

package/src/utils/headers.ts

@@ -18,14 +18,117 @@ export function isBrowserRuntime(): boolean {
   }
 }
 
+/** Package version for User-Agent strings. Reads the npm-injected env first. */
+export function getPackageVersion(): string {
+  try {
+    const v = (globalThis as any).process?.env?.npm_package_version;
+    if (typeof v === "string" && v) return v;
+  } catch {}
+  return "0.4.0";
+}
+
 function getAgentAccelUserAgent(): string {
+  const version = getPackageVersion();
   try {
     const os = (globalThis as any).process?.getBuiltinModule?.("node:os") ?? null;
     if (os) {
-      return `agent-accel (${os.platform()} ${os.release()}; ${os.arch()})`;
+      return `agent-accel/${version} (${os.platform()} ${os.release()}; ${os.arch()})`;
     }
   } catch {}
-  return "agent-accel (linux; x64)";
+  return `agent-accel/${version} (linux; x64)`;
+}
+
+// Re-exported for tests/diagnostics (unused by wire headers directly).
+export const AGENT_ACCEL_USER_AGENT = getAgentAccelUserAgent;
+
+// ---------------------------------------------------------------------------
+// Attribution (Q-17): configurable, default none except OpenRouter legacy.
+// ---------------------------------------------------------------------------
+
+/** Configurable attribution headers (OpenRouter `HTTP-Referer` / `X-Title`). */
+export interface AttributionConfig {
+  referer?: string;
+  title?: string;
+  userAgent?: string;
+}
+
+let attribution: AttributionConfig = {};
+
+/**
+ * Configures global attribution headers. Defaults to none (no hardcoded
+ * site); OpenRouter keeps its legacy `sashvat.com` / `Agent Accelerator`
+ * fallback when no custom attribution is set (backward compat).
+ * @example `setAttribution({ referer: "https://example.com", title: "My App" });`
+ */
+export function setAttribution(cfg: AttributionConfig): void {
+  attribution = { ...attribution, ...cfg };
+  if (cfg.referer === undefined && cfg.title === undefined && cfg.userAgent === undefined) {
+    // Explicit empty reset: `setAttribution({})` clears prior values.
+    if (Object.keys(cfg).length === 0) attribution = {};
+  }
+}
+
+/** Returns a copy of the current attribution config (default `{}`). */
+export function getAttribution(): AttributionConfig {
+  return { ...attribution };
+}
+
+/** First-class providers with documented session-affinity headers. */
+const FIRST_CLASS = new Set(["google", "openai", "openrouter"]);
+
+/** Case-insensitive header lookup. */
+function findHeaderKey(headers: Record<string, string>, name: string): string | undefined {
+  const lower = name.toLowerCase();
+  for (const k of Object.keys(headers)) {
+    if (k.toLowerCase() === lower) return k;
+  }
+  return undefined;
+}
+
+/**
+ * Sets a header case-insensitively (removes any case-variant duplicate
+ * first). Use when applying canonical `Authorization` / `Content-Type` over
+ * user-supplied `customHeaders` so `authorization` + `Authorization` never
+ * coexist on the wire.
+ * @example `setHeaderCaseInsensitive(headers, "Authorization", "Bearer k");`
+ */
+export function setHeaderCaseInsensitive(
+  headers: Record<string, string>,
+  name: string,
+  value: string
+): void {
+  const existing = findHeaderKey(headers, name);
+  if (existing !== undefined && existing !== name) delete headers[existing];
+  headers[name] = value;
+}
+
+// ---------------------------------------------------------------------------
+// Thought-signature namespacing (Q-18).
+// ---------------------------------------------------------------------------
+
+/**
+ * Tags a captured thought signature with its issuing provider so history
+ * builders echo it only on the same provider. Untagged (legacy) signatures
+ * echo everywhere for backward compat.
+ */
+export function withProviderSignature(
+  sig: string | undefined,
+  provider: string
+): { thoughtSignature?: string; thoughtSignatureProvider?: string } {
+  if (!sig) return {};
+  return { thoughtSignature: sig, thoughtSignatureProvider: provider };
+}
+
+/**
+ * Returns true when a stored signature may be echoed on `currentProvider`:
+ * untagged (legacy) echoes everywhere, tagged echoes only on a match.
+ */
+export function shouldEchoSignature(
+  storedProvider: unknown,
+  currentProvider: string
+): boolean {
+  if (!storedProvider) return true;
+  return storedProvider === currentProvider;
 }
 
 const BROWSER_DROPPED = new Set([
@@ -48,6 +151,13 @@ function stripForBrowser(headers: Record<string, string>): Record<string, string
 /**
  * Builds provider-specific session, cache-affinity, and attribution headers.
  *
+ * Q-17: attribution is configurable via `setAttribution()` (default none).
+ * OpenRouter keeps its legacy `https://sashvat.com` / `Agent Accelerator`
+ * fallback when no custom attribution is set. Custom (non-first-class)
+ * prefixes receive minimal `x-session-id`/`x-client-request-id` affinity only
+ * (no `session_id` alias, no attribution) when a session id is present.
+ * `customHeaders` merge case-insensitively against canonical names.
+ *
  * Browser note: custom `x-*` session/affinity headers force a CORS preflight
  * (`OPTIONS`) and providers only allow-list their own documented headers, so a
  * preflight failure surfaces as a bare `TypeError: Failed to fetch`. In browser
@@ -63,35 +173,59 @@ export function buildSessionHeaders(
   explicitSessionId?: string
 ): Record<string, string> {
   const browser = isBrowserRuntime();
-  const headers: Record<string, string> = {
-    ...(browser ? {} : { "User-Agent": "Agent-Accelerator/1.0" }),
-    ...(customHeaders ?? {}),
-  };
+  const attr = getAttribution();
+  const headers: Record<string, string> = {};
+  if (!browser) {
+    setHeaderCaseInsensitive(headers, "User-Agent", attr.userAgent ?? `Agent-Accelerator/${getPackageVersion()}`);
+  }
+  for (const [k, v] of Object.entries(customHeaders ?? {})) {
+    const existing = findHeaderKey(headers, k);
+    if (existing !== undefined && existing !== k) delete headers[existing];
+    headers[k] = v;
+  }
 
   const rawSessionId = explicitSessionId || cache?.sessionId;
   const sessionId = clampCacheKey(rawSessionId);
+  const isFirstClass = FIRST_CLASS.has(provider);
+
+  const getHeader = (name: string): string | undefined => {
+    const key = findHeaderKey(headers, name);
+    return key !== undefined ? headers[key] : undefined;
+  };
 
   if (sessionId && !browser) {
     if (provider === "openrouter") {
-      headers["x-session-id"] = sessionId;
-      headers["x-client-request-id"] = sessionId;
-      headers["HTTP-Referer"] = "https://sashvat.com";
-      headers["X-Title"] = "Agent Accelerator";
+      setHeaderCaseInsensitive(headers, "x-session-id", sessionId);
+      setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
+      const referer = attr.referer ?? "https://sashvat.com";
+      const title = attr.title ?? "Agent Accelerator";
+      if (getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = referer;
+      if (getHeader("X-Title") === undefined) headers["X-Title"] = title;
     } else if (provider === "google") {
-      headers["x-goog-api-client"] = "agent-accel/1.0";
-      headers["x-session-id"] = sessionId;
-      headers["x-client-request-id"] = sessionId;
+      if (getHeader("x-goog-api-client") === undefined) {
+        headers["x-goog-api-client"] = "agent-accel/1.0";
+      }
+      setHeaderCaseInsensitive(headers, "x-session-id", sessionId);
+      setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
+    } else if (isFirstClass) {
+      setHeaderCaseInsensitive(headers, "x-session-id", sessionId);
+      setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
+      setHeaderCaseInsensitive(headers, "session_id", sessionId);
     } else {
-      headers["x-session-id"] = sessionId;
-      headers["x-client-request-id"] = sessionId;
-      headers["session_id"] = sessionId;
+      // Custom OpenAI-compatible prefix: headers-only affinity. Bodies carry
+      // no affinity key on strict endpoints, so only the minimal pair is
+      // sent (no `session_id` alias, no attribution).
+      setHeaderCaseInsensitive(headers, "x-session-id", sessionId);
+      setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
     }
   } else if (provider === "openrouter") {
-    if (!headers["HTTP-Referer"]) headers["HTTP-Referer"] = "https://sashvat.com";
-    if (!headers["X-Title"]) headers["X-Title"] = "Agent Accelerator";
+    const referer = attr.referer ?? "https://sashvat.com";
+    const title = attr.title ?? "Agent Accelerator";
+    if (getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = referer;
+    if (getHeader("X-Title") === undefined) headers["X-Title"] = title;
   }
 
-  if (provider === "google" && !browser && !headers["x-goog-api-client"]) {
+  if (provider === "google" && !browser && getHeader("x-goog-api-client") === undefined) {
     headers["x-goog-api-client"] = "agent-accel/1.0";
   }