cartethyia 2.8.0 → 2.8.1

package/src/providers/integrations/buddy/{buddy-identity.ts → headers.ts}

@@ -2,32 +2,13 @@ import type { ProviderDispatchContext } from "../../provider-contracts";
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { decodeJwtPayload } from "../../authentication/oauth-flow-store";
-import { buddyAccountUid } from "./buddy-oauth-shared";
+import { buddyAccountUid } from "./account";
 import type { CanonicalRequest } from "../../../protocol/canonical-model";
 
-/**
- * Which upstream client a buddy provider presents itself as.
- *
- * `desktop` is what every buddy provider sends today and stays the default for
- * all four. `cli` is the identity the reference gateways use for CLI traffic: a
- * different header set, a different User-Agent formula, and a different CN
- * upstream.
- *
- * Nothing flips to `cli` implicitly. Being wrong here is what gets an account
- * blocked upstream, so a provider changes identity only when an operator or an
- * account says so.
- */
+// ── buddy-identity ──────────────────────────────────────────
+
 export type BuddyIdentity = "desktop" | "cli";
 
-/**
- * Resolves the identity one buddy dispatch presents.
- *
- * Precedence is account then provider: an account authorized as a CLI keeps
- * that identity even when the provider default changes, because the upstream
- * recorded it at login. The provider-level flag is
- * `compatibilityProfile.cli_identity`, already declared, validated, and
- * defaulted — it just never reached these adapters before.
- */
 export function resolveBuddyIdentity(
   context: ProviderDispatchContext | undefined,
   profileIdentity?: boolean | undefined,
@@ -38,18 +19,6 @@ export function resolveBuddyIdentity(
   return profileIdentity === true ? "cli" : "desktop";
 }
 
-/**
- * The upstream's `X-User-Id` for a buddy dispatch.
- *
- * The reference CLI sends the literal `anonymous` when it has no uid rather
- * than omitting the header, so an unauthenticated dispatch still looks like a
- * client rather than like a caller that forgot a header.
- *
- * When the credential carries a JWT, the `sub` claim is the upstream uid and
- * wins over the gateway's internal account id — the two can differ after an
- * import, and the channel check keys on the upstream identity. Opaque API keys
- * carry no identity, so the internal account id is the fallback.
- */
 export function buddyUserId(context?: ProviderDispatchContext): string {
   const secret = context?.credential?.secret;
   const token = secret ? new TextDecoder().decode(secret).trim() : "";
@@ -59,15 +28,6 @@ export function buddyUserId(context?: ProviderDispatchContext): string {
   return accountId !== undefined && accountId.length > 0 ? accountId : "anonymous";
 }
 
-/**
- * Claim names a buddy access token may carry the enterprise id under.
- *
- * A list of candidates rather than one name because the upstream's token shape
- * is not pinned anywhere this codebase can verify, and guessing one name would
- * silently report "personal" for every account whose token spells it another
- * way. Every candidate is a plausible spelling of the same fact; the first that
- * holds a non-empty string wins, and a token carrying none yields no enterprise.
- */
 const ENTERPRISE_CLAIMS: readonly string[] = [
   "enterprise_id",
   "enterpriseId",
@@ -78,24 +38,6 @@ const ENTERPRISE_CLAIMS: readonly string[] = [
   "organization_id",
 ];
 
-/**
- * The enterprise this buddy account belongs to, or `undefined` for a personal
- * one.
- *
- * Two sources, in this order:
- *
- * 1. **`auth_state.enterpriseId`** — written when the account was authorized, or
- *    set by an operator for an account whose token does not carry the fact.
- *    Wins because it is the one a human can correct.
- * 2. **A claim on the access token** — for accounts authorized before this
- *    existed, whose `auth_state` was never populated.
- *
- * Deliberately conservative: no enterprise id means *personal*, and personal is
- * what the gateway already sends. An unknown account is therefore unchanged
- * rather than being given an enterprise it may not have — claiming one the
- * upstream does not recognise is the kind of mismatch that draws a channel
- * check.
- */
 export function buddyEnterprise(context?: ProviderDispatchContext): string | undefined {
   const stored = context?.credential.auth_state?.["enterpriseId"];
   if (typeof stored === "string" && stored.trim().length > 0) return stored.trim();
@@ -110,29 +52,6 @@ export function buddyEnterprise(context?: ProviderDispatchContext): string | und
   return undefined;
 }
 
-/**
- * Per-account device binding (`qimei36`) for the buddy providers.
- *
- * The desktop auth state sends `X-Device-Id-List: {"qimei36":"…"}` alongside
- * the Turing token — a second, independent device identity. Pinning it per
- * account makes every account in a pool present a distinct device to the
- * upstream risk control instead of sharing the machine's single fingerprint.
- *
- * Resolution order:
- * 1. `auth_state.qimei36` — explicit operator-set binding (imported or edited).
- * 2. Derived deterministically from the internal account id (sha256 → 32 hex).
- *    This keeps the binding stable across restarts without a database write,
- *    and gives each freshly-added account its own id automatically.
- *
- * IMPORTANT — the derived fallback is **not portable across instances**:
- * export/import mints a NEW account id, so the derived binding changes and the
- * upstream channel check (11128) rejects the re-imported account. The export
- * path therefore materializes the raw result of this resolver into
- * `auth_state.qimei36` whenever an account relies on the derivation, so a
- * re-import carries the exact same device identity.
- *
- * Returns `undefined` only when no account id is available (unauthenticated).
- */
 export function resolveBuddyDeviceBinding(context?: ProviderDispatchContext): string | undefined {
   const explicit = context?.credential.auth_state?.["qimei36"];
   if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
@@ -141,9 +60,6 @@ export function resolveBuddyDeviceBinding(context?: ProviderDispatchContext): st
   return createHash("sha256").update(`wb2a:qimei36:${accountId}`).digest("hex").slice(0, 32);
 }
 
-/** Materializes the portable binding for an account into a stored auth-state
- * map, when the account does not already pin one explicitly. Used by the
- * export path so a re-import keeps the exact qimei36 device identity. */
 export function materializeBuddyDeviceBinding(
   accountId: string,
   authState: Readonly<Record<string, unknown>> | undefined,
@@ -155,19 +71,6 @@ export function materializeBuddyDeviceBinding(
   return { ...(authState ?? {}), qimei36: derived };
 }
 
-/**
- * The OAuth identity header family the reference ships on every cloud API call
- * (`runIdentityHeaders`): `X-User-Id` plus the base64 `X-Userinfo` envelope and
- * the auth-method / id-source markers.
- *
- * The JWT `sub` is the uid; the base64 envelope mirrors the reference exactly:
- * `{ uin, owner_uin?, id_source?, token_source? }` — one leg per identity
- * field that exists, so a personal account sends `{uin}` while an enterprise
- * account adds `owner_uin`. `X-Auth-Method` / `X-Id-Source` are only sent when
- * the operator pinned them in `auth_state` (there is no reliable source to
- * invent them from). An opaque API key carries no uid and yields nothing.
- */
-/** A short printable identity claim from a JWT payload, or `undefined`. */
 function identityClaim(claims: Record<string, unknown> | undefined, name: string): string | undefined {
   if (claims === undefined) return undefined;
   const value = claims[name];
@@ -210,25 +113,10 @@ export function buddyOAuthIdentityHeaders(
   return headers;
 }
 
-/**
- * Whether this dispatch is in the reference's private-data mode. The CLI only
- * sends `X-Private-Data: true` while the session is private; otherwise the
- * header is deleted, never sent as `false`. The gateway has no session-level
- * private flag, so the operator pins one per account in `auth_state.privateData`.
- */
 export function buddyPrivateData(context?: ProviderDispatchContext): boolean {
   return context?.credential.auth_state?.["privateData"] === true;
 }
 
-/**
- * The effective agent purpose for one dispatch, matching the reference's
- * `getEffectiveAgentPurpose` behavior as closely as the gateway can:
- *
- * - `PERSONAL_AGENT_ROLE` set → `person_agent` (same env the CLI reads);
- * - otherwise an inbound `x-agent-purpose` header is preserved (the caller
- *   already stated a purpose — same shape the reference passes through);
- * - otherwise the header is omitted. The reference does not invent `conversation`.
- */
 export function buddyAgentPurpose(
   context?: ProviderDispatchContext,
   request?: CanonicalRequest,
@@ -243,17 +131,10 @@ export function buddyAgentPurpose(
   return undefined;
 }
 
-/**
- * Desktop risk token, sent only when the account actually has one.
- *
- * The account's own `auth_state` wins. When it carries none, a file the
- * desktop client writes (`CARTETHYIA_DEVICE_TOKEN_FILE`, default
- * `/app/data/device_token`) is read instead — cached for five minutes, and
- * ignored when it is larger than 1 KB, because a token file that size is not
- * a token. A missing file is the normal case and reads as "no token".
- */
 const DEVICE_TOKEN_FILE_MAX_BYTES = 1024;
+
 const DEVICE_TOKEN_FILE_TTL_MS = 5 * 60_000;
+
 let deviceTokenFileCache: { readonly value: string | undefined; readonly readAt: number } | undefined;
 
 export function readBuddyDeviceToken(context?: ProviderDispatchContext): string | undefined {
@@ -263,22 +144,6 @@ export function readBuddyDeviceToken(context?: ProviderDispatchContext): string
   return readDeviceTokenFile();
 }
 
-/**
- * The reference `X-Device-Token` pair, per the official desktop app.
- *
- * The desktop client always presents one of the
- * two on chat traffic — a real token from the TuringShield SDK, or an
- * `X-Device-Token-Error` when the SDK cannot produce one. It never omits both,
- * and it sends the header on every realm (Intl and CN alike).
- *
- * The TuringShield SDK was a proprietary native addon shipped under
- * `vendor/turing-sdk/`; it has been removed. The fallback path below is the
- * captured token (auth_state / `CARTETHYIA_DEVICE_TOKEN_FILE`) and then the
- * official failure state.
- *
- * - Legacy token (auth_state/file) → used when no SDK is available.
- * - CLI identity never carries a device token (the CLI has no device).
- */
 export async function buddyDeviceTokenHeaders(args: {
   realm: "intl" | "cn";
   context: ProviderDispatchContext | undefined;
@@ -311,3 +176,136 @@ function readDeviceTokenFile(): string | undefined {
   deviceTokenFileCache = { value, readAt: now };
   return value;
 }
+
+// ── buddy-cli-headers ──────────────────────────────────────────
+
+export function buddyCliTraceHeaders(
+  conversation: Readonly<Record<string, string>>,
+): Record<string, string> {
+  const traceId = conversation["x-trace-id"] ?? conversation["x-b3-traceid"];
+  const spanId = conversation["x-b3-spanid"];
+  if (traceId === undefined) return {};
+  const b3 = `${traceId}-${spanId ?? traceId.slice(0, 16)}-1-${traceId.slice(0, 16)}`;
+  return { ...(spanId === undefined ? {} : { "X-B3-ParentSpanId": spanId }), b3 };
+}
+
+export function buddyCliHeaders(args: {
+  readonly userId: string;
+  readonly enterpriseId?: string | undefined;
+  readonly privateData?: boolean;
+}): Record<string, string> {
+  const enterpriseId =
+    args.enterpriseId !== undefined && args.enterpriseId.trim().length > 0
+      ? args.enterpriseId.trim()
+      : undefined;
+  return {
+    "X-Agent-Intent": "craft",
+    "X-Agent-Type": "main",
+    // The reference enum is local-agent / cloud-agent / agent-agent, and its
+    // parser returns "other" for anything unknown or absent. A gateway is none
+    // of the three, so "other" is the honest value rather than a guess.
+    "X-Agent-Runtime": "other",
+    "X-User-Id": args.userId,
+    ...(args.privateData === true ? { "X-Private-Data": "true" } : {}),
+    ...(enterpriseId === undefined
+      ? {}
+      : {
+          "X-Enterprise-Id": enterpriseId,
+          // The tenant falls back to the enterprise: the two are the same value
+          // for an account that belongs to one enterprise, and the upstream
+          // reads both.
+          "X-Tenant-Id": enterpriseId,
+        }),
+  };
+}
+
+// ── buddy-conversation-headers ──────────────────────────────────────────
+
+function newMessageId(): string {
+  return crypto.randomUUID().replaceAll("-", "");
+}
+
+function toUuidHex(hex: string): string {
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function isValidTraceId(value: string): boolean {
+  if (value.length !== 16 && value.length !== 32) return false;
+  return /^[0-9a-fA-F]+$/.test(value);
+}
+
+export interface BuddyConversationIds {
+  /**
+   * Conversation-scoped id, stable across turns. `undefined` means the client
+   * sent none, and the header is then omitted rather than fabricated.
+   */
+  readonly conversationId?: string | undefined;
+  /**
+   * Turn-scoped aggregation key. When absent a fresh one is generated, because
+   * the header is mandatory and a call without it is what drew `11128`.
+   */
+  readonly conversationRequestId?: string | undefined;
+  /** Inbound trace id to pass through; falls back to the conversation request id. */
+  readonly traceId?: string | undefined;
+  /**
+   * Wire format for the two message-scoped ids (`x-conversation-message-id`,
+   * `x-request-id`).
+   *
+   * The reference emits these as dashed UUIDs on the desktop product
+   * and as 32-hex on CLI traffic (`build_attempt_headers` converts only the
+   * message/request ids, and only for the desktop profiles). The turn
+   * aggregation key (`x-conversation-request-id` / `x-root-request-id`) and the
+   * B3/W3C trace ids stay hex in both styles, because B3's spec accepts only
+   * hex. Default `"hex"`.
+   */
+  readonly messageIdStyle?: "hex" | "uuid" | undefined;
+}
+
+export function buddyConversationHeaders(
+  ids: BuddyConversationIds = {},
+): Record<string, string> {
+  const conversationRequestId =
+    ids.conversationRequestId && ids.conversationRequestId.trim().length > 0
+      ? ids.conversationRequestId.trim()
+      : newMessageId();
+  const messageId = newMessageId();
+  // The message-scoped ids may render as a dashed UUID (WorkBuddy desktop) or
+  // as 32-hex (CLI); the raw hex is still what the B3/W3C trace ids derive from.
+  const messageHeaderValue = ids.messageIdStyle === "uuid" ? toUuidHex(messageId) : messageId;
+  const traceId =
+    ids.traceId && ids.traceId.trim().length > 0 ? ids.traceId.trim() : conversationRequestId;
+  const b3TraceId = isValidTraceId(conversationRequestId) ? conversationRequestId : messageId;
+
+  const headers: Record<string, string> = {
+    "x-conversation-request-id": conversationRequestId,
+    "x-conversation-message-id": messageHeaderValue,
+    "x-request-id": messageHeaderValue,
+    "x-root-request-id": conversationRequestId,
+    "x-trace-id": traceId,
+    // W3C trace context alongside the B3 set below: the upstream reads both,
+    // and every reference request carries `traceparent`, so sending only the
+    // B3 half leaves a header the channel check expects absent.
+    traceparent: `00-${b3TraceId}-${messageId.slice(0, 16)}-01`,
+    "x-b3-traceid": b3TraceId,
+    "x-b3-spanid": messageId.slice(0, 16),
+    "x-b3-sampled": "1",
+  };
+  // Always sent, invented when the caller gave none.
+  //
+  // `x-conversation-id` is mandatory, and a chat request without it is refused
+  // with `400 · 11-128 "request illegal"` — an error that names neither the
+  // header nor the channel, and which reads like a block rather than a missing
+  // field. Isolated against the live API by removing one header at a time:
+  // only `x-conversation-id`, `x-conversation-request-id` and
+  // `x-conversation-message-id` are required; the B3/W3C trace set, the
+  // stainless set, the agent block and the IDE block are all optional.
+  //
+  // Inventing one when the caller has none is still the right default: the id
+  // is per-dispatch here, so a caller with no session is not claiming a session
+  // it never had — and withholding the header only guarantees a refusal.
+  headers["x-conversation-id"] =
+    ids.conversationId !== undefined && ids.conversationId.trim().length > 0
+      ? ids.conversationId.trim()
+      : newMessageId();
+  return headers;
+}