@zocomputer/agent-sdk 0.5.0

package/platform/runtime-ai/gateway.ts

@@ -0,0 +1,76 @@
+import { createGateway } from "ai";
+import { eveSessionFetch } from "./session-fetch";
+
+// Names the built-in tool behind a proxied gateway call, so the metering capture can
+// label the resulting usage event (e.g. an image-model generation as `generate_image`)
+// instead of seeing anonymous traffic. Sent by the tool wrappers on their own gateway
+// calls; the api proxy strips it before forwarding upstream and stashes it in
+// UsageEvent.metadata. Only tools that make their OWN gateway call need it — a
+// server-side tool like web_search rides the model turn and is already named in that
+// turn's `gatewayToolCalls`.
+export const ZO_TOOL_HEADER = "x-zo-tool";
+
+export const DEFAULT_ZO_AI_BASE_URL = "http://localhost:4000/runtime/ai/v4/ai";
+export const DEFAULT_ZO_AI_KEY = "dev-proxy";
+
+// The agent-token header + env var — deliberate duplicates of
+// @zocomputer/runtime-auth's constants (this package is vendored self-contained;
+// same rationale as ZO_TOOL_HEADER above and session-fetch's EVE_SESSION_HEADER).
+// Whoever launches the runtime mints the token and injects ZO_AGENT_TOKEN (the
+// dev launchers; deploys bake it into the project env); attaching it here is
+// what makes every zoGateway call attributed — the api proxy rejects anonymous
+// calls once RUNTIME_AUTH_SECRET is configured.
+const AGENT_TOKEN_HEADER = "x-zo-agent-token";
+const AGENT_TOKEN_ENV = "ZO_AGENT_TOKEN";
+
+/**
+ * The runtime's agent-token header, from its launcher-injected env — `{}` when
+ * none was minted (secretless dev). Exported for tests.
+ */
+export function agentAuthHeaders(
+  token: string | undefined = process.env[AGENT_TOKEN_ENV],
+): Record<string, string> {
+  const trimmed = token?.trim();
+  return trimmed ? { [AGENT_TOKEN_HEADER]: trimmed } : {};
+}
+
+type GatewaySettings = NonNullable<Parameters<typeof createGateway>[0]>;
+
+export interface ZoGatewayOptions
+  extends Omit<GatewaySettings, "apiKey" | "baseURL"> {
+  readonly apiKey?: string | null;
+  readonly baseURL?: string | null;
+}
+
+export function resolveZoGatewayBaseUrl(
+  baseURL: string | null | undefined = process.env.ZO_AI_BASE_URL,
+): string {
+  const trimmed = baseURL?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_ZO_AI_BASE_URL;
+}
+
+export function resolveZoGatewayApiKey(
+  apiKey: string | null | undefined = process.env.ZO_AI_KEY,
+): string {
+  const trimmed = apiKey?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_ZO_AI_KEY;
+}
+
+// Explicit return type: the inferred one names @ai-sdk/gateway's GatewayProvider
+// through a store-internal path, which the d.ts build rejects as non-portable.
+export function zoGateway(
+  options: ZoGatewayOptions = {},
+): ReturnType<typeof createGateway> {
+  return createGateway({
+    ...options,
+    // The runtime's own agent token rides every call (attribution); explicit
+    // caller headers win on collision.
+    headers: { ...agentAuthHeaders(), ...options.headers },
+    apiKey: resolveZoGatewayApiKey(options.apiKey),
+    baseURL: resolveZoGatewayBaseUrl(options.baseURL),
+    // Stamp the ambient eve session id on every call (see session-fetch.ts) — the
+    // join key apps/api uses to recover the session's owner when persisting usage.
+    // A caller-supplied fetch still gets wrapped, so custom fetches keep the stamp.
+    fetch: eveSessionFetch(undefined, options.fetch),
+  });
+}

package/platform/runtime-ai/index.ts

@@ -0,0 +1,20 @@
+export {
+  DEFAULT_ZO_AI_BASE_URL,
+  DEFAULT_ZO_AI_KEY,
+  ZO_TOOL_HEADER,
+  resolveZoGatewayApiKey,
+  resolveZoGatewayBaseUrl,
+  zoGateway,
+} from "./gateway";
+export type { ZoGatewayOptions } from "./gateway";
+export {
+  EVE_SESSION_HEADER,
+  EVE_TURN_HEADER,
+  ambientEveSessionId,
+  ambientEveTurnId,
+  eveSessionFetch,
+} from "./session-fetch";
+
+// `./register` is deliberately NOT re-exported here: it's a side-effect module
+// (import it for what it does, not for a value), and a barrel re-export would
+// run the registration on any value import from this package.

package/platform/runtime-ai/register.ts

@@ -0,0 +1,26 @@
+import { zoGateway } from "./gateway";
+
+// Register the Zo gateway as the AI SDK's default provider
+// (`globalThis.AI_SDK_DEFAULT_PROVIDER`, read as `?? gateway` by
+// `resolveLanguageModel` in `ai`). With the slot pointed at our /runtime/ai
+// proxy, agent.ts can use a bare catalog slug — eve classifies a string model
+// as gateway-routed, so provider-executed built-ins like web_search stay
+// attached and the context window auto-resolves. A wrapped gateway *instance*
+// instead gets web_search silently deleted (eve can't map its "gateway/…" id
+// to a search backend). Import once, first, from agent.ts; never set the slot
+// anywhere else. A missed override fails loud, not leaky: agents hold no real
+// gateway key, so calls 401 at the real gateway instead of bypassing metering.
+// See plans/ray/eve-web-search-under-gateway-models.md (Option B).
+
+const SLOT = "AI_SDK_DEFAULT_PROVIDER";
+
+if (!(SLOT in globalThis)) {
+  Object.defineProperty(globalThis, SLOT, {
+    value: zoGateway(),
+    // Locked down so a later accidental assignment throws instead of silently
+    // rerouting model traffic.
+    writable: false,
+    configurable: false,
+    enumerable: false,
+  });
+}

package/platform/runtime-ai/session-fetch.ts

@@ -0,0 +1,124 @@
+// Stamps the ambient eve session id onto each proxied gateway call, so apps/api can
+// join the metered usage back to the session's owner (`eveSessionId` →
+// `Conversation`/`BuilderConversation`; see plans/ray/usage-event-persistence.md).
+//
+// Why a fetch wrapper: `createGateway`'s `headers` is a static record resolved once at
+// construction, but the session id changes per call — the custom `fetch` option is the
+// per-request seam. The fetch runs inside eve's AsyncLocalStorage scope during a model
+// call ("model callbacks observe the unified context" — eve's own contract), so the
+// ambient read is race-free under concurrent sessions, unlike capturing the id into
+// module state from a hook.
+//
+// Why no `eve` import: this package is vendored source-only into the agent working
+// copy, where `ai` + Node built-ins are the only guaranteed deps. eve 0.16 doesn't
+// export `getContext`/`SessionIdKey` publicly anyway — but it deliberately publishes
+// its context storage process-wide (`Symbol.for("eve.context-storage")`, "used by
+// every eve module copy") exactly so out-of-tree code can share it. We read that slot
+// with runtime checks; `session-fetch.test.ts` locks the contract against the
+// installed eve so an upgrade that moves it fails loudly in `test:packages`.
+
+/**
+ * Mirrors `@zocomputer/runtime-auth`'s `EVE_SESSION_HEADER` — a deliberate duplicate
+ * for the same reason `ZO_TOOL_HEADER` is (see `gateway.ts`): this package can't
+ * import workspace siblings. apps/api reads it into the gateway attribution and strips
+ * it before forwarding upstream.
+ */
+export const EVE_SESSION_HEADER = "x-zo-eve-session";
+
+/**
+ * Mirrors `@zocomputer/runtime-auth`'s `EVE_TURN_HEADER` (same duplication rule).
+ * Descriptive metering detail — it lands in `UsageEvent.metadata.turnId` and pins a
+ * Zo-paid tool's own gateway call (invisible to eve's step machinery) to its turn.
+ */
+export const EVE_TURN_HEADER = "x-zo-eve-turn";
+
+/** The process-wide slot eve publishes its context `AsyncLocalStorage` under. */
+const EVE_CONTEXT_STORAGE_KEY = Symbol.for("eve.context-storage");
+
+/** `SessionIdKey.name` in eve — a durable serialized key, so it can't drift casually. */
+const SESSION_ID_KEY_NAME = "eve.sessionId";
+
+/** `SessionKey.name` in eve — the durable session object carrying `turn.id`. */
+const SESSION_KEY_NAME = "eve.session";
+
+/** Narrow structural check: a non-null object carrying a function under `name`. */
+function hasMethod<K extends string>(
+  value: unknown,
+  name: K,
+): value is Record<K, (...args: unknown[]) => unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Record<string, unknown>)[name] === "function"
+  );
+}
+
+/**
+ * The eve session id of the call currently in scope, or `undefined` when there isn't
+ * one. Never throws: a fetch outside any session (e.g. the gateway provider's
+ * background model-metadata refresh) or a runtime without eve simply reads no slot.
+ */
+export function ambientEveSessionId(): string | undefined {
+  const value = ambientContextValue(SESSION_ID_KEY_NAME);
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+/**
+ * The eve turn id of the call currently in scope, or `undefined`. Read from the
+ * durable session object (`SessionKey` → `{ sessionId, turn: { id } }`) with the
+ * same runtime checks as the session read — never throws, never trusts shape.
+ */
+export function ambientEveTurnId(): string | undefined {
+  const session = ambientContextValue(SESSION_KEY_NAME);
+  if (typeof session !== "object" || session === null) return undefined;
+  const turn = (session as Record<string, unknown>)["turn"];
+  if (typeof turn !== "object" || turn === null) return undefined;
+  const id = (turn as Record<string, unknown>)["id"];
+  return typeof id === "string" && id.trim().length > 0 ? id : undefined;
+}
+
+/** One guarded read of eve's process-wide context slot by key name. */
+function ambientContextValue(keyName: string): unknown {
+  const storage: unknown = Reflect.get(globalThis, EVE_CONTEXT_STORAGE_KEY);
+  if (!hasMethod(storage, "getStore")) return undefined;
+  const store = storage.getStore();
+  // The store is eve's context container; `get` reads a key by its `.name`.
+  if (!hasMethod(store, "get")) return undefined;
+  return store.get({ name: keyName });
+}
+
+/**
+ * Wrap a fetch so every request carries the current eve session id, when there is one.
+ * No session in scope (or a blank id) → the request passes through untouched.
+ *
+ * `Object.assign` onto the wrapper keeps the base fetch's extra surface (Bun types a
+ * `preconnect` on `fetch`), so the result satisfies `typeof globalThis.fetch`.
+ */
+type FetchInput = Parameters<typeof globalThis.fetch>[0];
+type FetchInit = Parameters<typeof globalThis.fetch>[1];
+
+export function eveSessionFetch(
+  getSessionId: () => string | undefined = ambientEveSessionId,
+  baseFetch: typeof globalThis.fetch = globalThis.fetch,
+  getTurnId: () => string | undefined = ambientEveTurnId,
+): typeof globalThis.fetch {
+  return Object.assign((input: FetchInput, init?: FetchInit) => {
+    const sessionId = getSessionId()?.trim();
+    if (!sessionId) return baseFetch(input, init);
+    // Merge order matches fetch semantics: `init.headers` (when present) replaces a
+    // Request input's headers wholesale, so start from whichever would win.
+    const headers = new Headers(
+      init?.headers ?? (input instanceof Request ? input.headers : undefined),
+    );
+    headers.set(EVE_SESSION_HEADER, sessionId);
+    // The turn only rides with a session — a turn id with no session id would be
+    // unjoinable noise, so the whole stamp is gated on the session being present.
+    // Like the session header, the ambient value is AUTHORITATIVE either way: a
+    // stale pre-existing turn header is overwritten when a turn is in scope and
+    // removed when one isn't, so it can never mislabel a row's metadata.turnId.
+    const turnId = getTurnId()?.trim();
+    if (turnId) headers.set(EVE_TURN_HEADER, turnId);
+    else headers.delete(EVE_TURN_HEADER);
+    return baseFetch(input, { ...init, headers });
+  }, baseFetch);
+}

package/platform/runtime-auth/index.ts

@@ -0,0 +1,331 @@
+import { SignJWT, jwtVerify, type JWTPayload } from "jose";
+
+// @zocomputer/runtime-auth — the agent-token contract shared by the minter and the verifier.
+//
+// `apps/api` mints the agent token (and verifies it), the launcher that starts an
+// agent process mints one too (dev), and `@zocomputer/agent-sandbox` carries it on the
+// header. Putting the format in one package keeps those in lockstep — the claims,
+// the header names, and the reserved Builder identity all have a single source of
+// truth, rather than `apps/api` owning the format and everyone else re-deriving it.
+//
+// The crypto is pure and injectable (secret + clock passed in) so it unit-tests
+// without env. `apps/api` is the sole verifier; a runtime carries the token but
+// never holds the signing secret. See plans/rc2/runtime-auth-context.md.
+
+// ── headers ──────────────────────────────────────────────────────────────────
+
+/** The agent token, kept off `Authorization` so it never shadows a WorkOS session. */
+export const AGENT_TOKEN_HEADER = "x-zo-agent-token";
+
+/** The eve session the agent's call is for — carried onto the context as `eveSessionId`. */
+export const EVE_SESSION_HEADER = "x-zo-eve-session";
+
+/**
+ * The eve turn the agent's call belongs to. Descriptive metering detail (it lands
+ * in `UsageEvent.metadata.turnId`, never attribution/ownership): a model step's
+ * usage row is turn-linkable via its generation id against eve's stored steps,
+ * but a Zo-paid tool's own gateway call is invisible to eve's step machinery —
+ * this header is what pins a `tool_use` row to its exact turn.
+ */
+export const EVE_TURN_HEADER = "x-zo-eve-turn";
+
+/** Env var a runtime reads its agent token from (injected by its launcher). */
+export const AGENT_TOKEN_ENV = "ZO_AGENT_TOKEN";
+
+// ── actor + context ──────────────────────────────────────────────────────────
+
+/** A running eve agent acting as itself. */
+export interface AgentActor {
+  readonly kind: "agent";
+  /** Which agent (the durable product object). */
+  readonly agentProjectId: string;
+  /** The org that owns the agent — always present. */
+  readonly ownerOrgId: string;
+  /** The running deployment, once hosted deploys mint one. */
+  readonly deploymentId?: string;
+}
+
+/** A human calling the API directly (browser/native), no agent in between. */
+export interface UserActor {
+  readonly kind: "user";
+  readonly userId: string;
+  readonly orgId: string;
+}
+
+/** The resolved identity for a request. */
+export interface RuntimeAuthContext {
+  readonly actor: AgentActor | UserActor;
+  /**
+   * The eve session this call is acting for, when an agent actor reports one — the
+   * join key from which a route resolves the `Conversation` (and through it the
+   * user, org, installation). Carried per request on `EVE_SESSION_HEADER`, not a
+   * token claim and not verified (self-asserted, scoped by the actor's org, the same
+   * trust the sandbox route gives its eve session key). Absent on a direct user call.
+   */
+  readonly eveSessionId?: string;
+}
+
+// ── reserved identities ──────────────────────────────────────────────────────
+
+/**
+ * The reserved Zo platform org. Zo's own first-party usage (the Builder, internal
+ * jobs) is scoped to it. A real `Org` row, seeded at DB setup, so anything written
+ * against it (a `SandboxResource`, later usage rows) satisfies the foreign key. Its
+ * id is a fixed, well-known string (not a minted TypeID) so it can be referenced as
+ * a constant from both the minter and the seed.
+ */
+export const ZO_PLATFORM_ORG = {
+  id: "org_zo",
+  name: "Zo",
+  slug: "zo",
+} as const;
+
+/**
+ * The Builder's hardcoded agent identity. The Builder is Zo's own first-party agent
+ * (it edits other agents) — not a customer-built one — so it has no `AgentProject`
+ * row and a fixed identity instead: a well-known project id and the platform org as
+ * owner. `agentProjectId` is never persisted by the sandbox path (only `ownerOrgId`
+ * is, against the FK), so it needs no seeded row of its own.
+ */
+export const BUILDER_AGENT_IDENTITY: AgentTokenClaims = {
+  agentProjectId: "agt_builder",
+  ownerOrgId: ZO_PLATFORM_ORG.id,
+};
+
+/**
+ * The dev BUILT agent's hardcoded identity (the `apps/local-agent` working copy
+ * on :2000, launched by `packages/fixtures`). Like the Builder it's a first-party
+ * dev process with no `AgentProject` row — a fixed identity scoped to the platform
+ * org, so its gateway calls are attributed (and metered) instead of anonymous.
+ * Which USER's session a call belongs to still comes from the session join, never
+ * this token.
+ */
+export const LOCAL_AGENT_IDENTITY: AgentTokenClaims = {
+  agentProjectId: "agt_local",
+  ownerOrgId: ZO_PLATFORM_ORG.id,
+};
+
+/**
+ * Reserved first-party project ids that deliberately have NO `AgentProject` row
+ * (#81: no fake product rows) — consumers must never write them into an
+ * AgentProject foreign key. One list so a new reserved identity can't be missed
+ * at one of the call sites.
+ */
+export const RESERVED_AGENT_PROJECT_IDS: readonly string[] = [
+  BUILDER_AGENT_IDENTITY.agentProjectId,
+  LOCAL_AGENT_IDENTITY.agentProjectId,
+];
+
+// ── token wire shapes ────────────────────────────────────────────────────────
+
+const ISSUER = "zo-api";
+const AGENT_TOKEN_TYP = "zo-agent";
+
+/** What the agent token asserts about the actor. */
+export interface AgentTokenClaims {
+  readonly agentProjectId: string;
+  readonly ownerOrgId: string;
+  readonly deploymentId?: string;
+}
+
+/** Seconds-since-epoch clock, injected so tests are deterministic. */
+export type Clock = () => number;
+
+const defaultClock: Clock = () => Math.floor(Date.now() / 1000);
+
+/** Encode the HMAC secret string for jose's Web Crypto key input. */
+function key(secret: string): Uint8Array {
+  return new TextEncoder().encode(secret);
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+// ── mint ─────────────────────────────────────────────────────────────────────
+
+export interface MintAgentTokenInput {
+  readonly claims: AgentTokenClaims;
+  readonly secret: string;
+  /** Token lifetime in seconds. */
+  readonly ttlSeconds: number;
+  readonly clock?: Clock;
+}
+
+/** Mint the agent token (the actor credential injected into a runtime's env). */
+export async function mintAgentToken(input: MintAgentTokenInput): Promise<string> {
+  const now = (input.clock ?? defaultClock)();
+  const payload: JWTPayload = {
+    typ: AGENT_TOKEN_TYP,
+    agentProjectId: input.claims.agentProjectId,
+    ownerOrgId: input.claims.ownerOrgId,
+    ...(input.claims.deploymentId ? { deploymentId: input.claims.deploymentId } : {}),
+  };
+  return new SignJWT(payload)
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuer(ISSUER)
+    .setIssuedAt(now)
+    .setExpirationTime(now + input.ttlSeconds)
+    .sign(key(input.secret));
+}
+
+// ── verify ───────────────────────────────────────────────────────────────────
+
+/** Verify the agent token's signature, issuer, expiry, and `typ`. Returns the claims,
+ * or `null` when the token is invalid/expired/wrong-typ. */
+export async function verifyAgentToken(
+  token: string,
+  secret: string,
+  clock: Clock = defaultClock,
+): Promise<AgentTokenClaims | null> {
+  try {
+    const { payload } = await jwtVerify(token, key(secret), {
+      issuer: ISSUER,
+      currentDate: new Date(clock() * 1000),
+    });
+    if (payload.typ !== AGENT_TOKEN_TYP) return null;
+    const agentProjectId = asString(payload.agentProjectId);
+    const ownerOrgId = asString(payload.ownerOrgId);
+    if (!agentProjectId || !ownerOrgId) return null;
+    const deploymentId = asString(payload.deploymentId);
+    return { agentProjectId, ownerOrgId, ...(deploymentId ? { deploymentId } : {}) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a verified agent token into a `RuntimeAuthContext`, or `null` when the
+ * token is invalid. `eveSessionId` is the session the runtime reports for this call
+ * (per request — see the field doc); it's carried onto the context so consumers can
+ * join to the `Conversation`. It's not part of the token and is not verified here.
+ */
+export async function resolveAgentContext(
+  agentToken: string,
+  secret: string,
+  eveSessionId: string | undefined,
+  clock: Clock = defaultClock,
+): Promise<RuntimeAuthContext | null> {
+  const claims = await verifyAgentToken(agentToken, secret, clock);
+  if (!claims) return null;
+  return {
+    actor: {
+      kind: "agent",
+      agentProjectId: claims.agentProjectId,
+      ownerOrgId: claims.ownerOrgId,
+      ...(claims.deploymentId ? { deploymentId: claims.deploymentId } : {}),
+    },
+    ...(eveSessionId ? { eveSessionId } : {}),
+  };
+}
+
+// ── identity bearer ──────────────────────────────────────────────────────────
+//
+// The second first-party token (credential A): a short-lived signed identity the
+// browser carries on the Builder's eve traffic (`@zocomputer/auth-core`'s
+// IDENTITY_BEARER_HEADER) asserting "this user is building this agent". Needed
+// because eve's client fetch sends no credentials, so the builder eve-proxy can't
+// see the WorkOS session cookie — the browser trades its cookie for this bearer
+// over an authenticated `POST /agents/:id/builder/identity-token`, and the proxy
+// verifies it offline, then injects the resolved identity as the plaintext
+// `x-zo-initiator` header (credential B, below). apps/api both mints and verifies
+// (same HMAC secret as the agent token); web only ferries the opaque string. See
+// plans/sachin/builder-initiator-binding-implementation.md.
+
+const IDENTITY_BEARER_TYP = "zo-identity";
+
+/** What the identity bearer asserts: which user is building which agent. */
+export interface IdentityClaims {
+  readonly userId: string;
+  readonly agentId: string;
+}
+
+export interface MintIdentityBearerInput {
+  readonly claims: IdentityClaims;
+  readonly secret: string;
+  /** Bearer lifetime in seconds. */
+  readonly ttlSeconds: number;
+  readonly clock?: Clock;
+}
+
+/** Mint the identity bearer (the browser-side identity credential). */
+export async function mintIdentityBearer(
+  input: MintIdentityBearerInput,
+): Promise<string> {
+  const now = (input.clock ?? defaultClock)();
+  const payload: JWTPayload = {
+    typ: IDENTITY_BEARER_TYP,
+    userId: input.claims.userId,
+    agentId: input.claims.agentId,
+  };
+  return new SignJWT(payload)
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuer(ISSUER)
+    .setIssuedAt(now)
+    .setExpirationTime(now + input.ttlSeconds)
+    .sign(key(input.secret));
+}
+
+/** Verify an identity bearer's signature, issuer, expiry, and `typ`. Returns the
+ * claims, or `null` when it's invalid/expired/wrong-typ (incl. an agent token
+ * presented where an identity bearer belongs — `typ` keeps them unconfusable). */
+export async function verifyIdentityBearer(
+  bearer: string,
+  secret: string,
+  clock: Clock = defaultClock,
+): Promise<IdentityClaims | null> {
+  try {
+    const { payload } = await jwtVerify(bearer, key(secret), {
+      issuer: ISSUER,
+      currentDate: new Date(clock() * 1000),
+    });
+    if (payload.typ !== IDENTITY_BEARER_TYP) return null;
+    const userId = asString(payload.userId);
+    const agentId = asString(payload.agentId);
+    if (!userId || !agentId) return null;
+    return { userId, agentId };
+  } catch {
+    return null;
+  }
+}
+
+// ── initiator header (proxy → Builder) ─────────────────────────────────────────
+//
+// Credential B: the plaintext identity the builder eve-proxy injects on the
+// forwarded request after verifying the identity bearer (credential A). The
+// Builder's channel auth reads it and stamps `session.auth.initiator`. Not signed
+// — the Builder holds no secret and trusts it because only the edge-authenticated
+// proxy can reach it (Deployment Protection). The proxy always strips any
+// client-supplied value before setting its own. One JSON header so the identity
+// is atomic: `parseInitiator` returns the whole `{ userId, agentId }` or `null`,
+// never a half-present pair.
+
+/** The proxy → Builder initiator header. */
+export const INITIATOR_HEADER = "x-zo-initiator";
+
+/** The initiator identity carried on `INITIATOR_HEADER`. */
+export interface InitiatorIdentity {
+  readonly userId: string;
+  readonly agentId: string;
+}
+
+/** Serialize the initiator identity for `INITIATOR_HEADER`. */
+export function formatInitiator(identity: InitiatorIdentity): string {
+  return JSON.stringify({ userId: identity.userId, agentId: identity.agentId });
+}
+
+/** Parse-then-narrow the `INITIATOR_HEADER` value; `null` on absent/malformed. */
+export function parseInitiator(value: string | null | undefined): InitiatorIdentity | null {
+  if (!value) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const { userId, agentId } = parsed as Record<string, unknown>;
+  if (typeof userId !== "string" || !userId) return null;
+  if (typeof agentId !== "string" || !agentId) return null;
+  return { userId, agentId };
+}