UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

211 lines (189 loc) • 10.4 kB
/** * Anthropic's typed Advisor server tool (`advisor_20260301`, beta `advisor-tool-2026-03-01`) on the * translated Messages lane (#8448). Claude Code declares it by default; Anthropic runs the advisor * model server-side inside the same request and returns `server_tool_use` (name `advisor`, empty * input) followed by `advisor_tool_result`. Both blocks are kept verbatim for the next turn. * * Pure helpers shared by the inbound replay (`src/claude/inbound-content-options.ts`), the * adapter (`src/adapters/anthropic.ts`) and the Claude outbound. Nothing here reads, logs or * rewrites a result's text or `encrypted_content`; validation only checks field types. */ import { credentialDomainFor } from "../../protocols/opaque-state"; import type { OcxProviderConfig } from "../../types"; import type { AdapterRequest } from "../base"; type Rec = Record<string, unknown>; export const ADVISOR_TOOL_BETA = "advisor-tool-2026-03-01"; export const ADVISOR_SERVER_TOOL_NAME = "advisor"; /** The serializer's admitted auth, before operator or plugin header rewrites. */ export const hostedAdvisorCredentials = new WeakMap<AdapterRequest, { readonly header: "authorization" | "x-api-key"; readonly value: string; }>(); /** Keep unrelated betas when a rewriter restores the withheld hosted Advisor beta. */ export function stripHostedAdvisorBeta(headers: Headers): void { const betas = headers.get("anthropic-beta")?.split(",").map(beta => beta.trim()); if (!betas?.includes(ADVISOR_TOOL_BETA)) return; const kept = betas.filter(beta => beta && beta !== ADVISOR_TOOL_BETA); if (kept.length) headers.set("anthropic-beta", kept.join(",")); else headers.delete("anthropic-beta"); } function isPlainRecord(value: unknown): value is Rec { if (value === null || typeof value !== "object" || Array.isArray(value)) return false; const prototype = Object.getPrototypeOf(value); return prototype === Object.prototype || prototype === null; } /** A typed Advisor declaration (`advisor_YYYYMMDD`), the same shape the native lane's scope check reads. */ export function isAdvisorServerToolType(type: unknown): boolean { return typeof type === "string" && /^advisor_\d{8}$/.test(type); } /** * Whether a destination receives the declaration: an `anthropic`-adapter provider on first-party * Anthropic by default, an Anthropic-compatible gateway only with `forwardAdvisorTool: true`. * An explicit `false` keeps it off even `api.anthropic.com` (a relay that borrows the * first-party body builder, like Zed's, sets it). */ export function advisorServerToolDestination(provider: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode" | "forwardAdvisorTool">): boolean { if (provider.adapter !== "anthropic" || provider.forwardAdvisorTool === false) return false; return provider.forwardAdvisorTool === true || credentialDomainFor(provider)?.firstPartyAnthropic === true; } /** The call input Anthropic documents: always an empty object. */ export function isAdvisorCallInput(input: unknown): input is Rec { return isPlainRecord(input) && Object.keys(input).length === 0; } /** A streamed call's assembled `input_json_delta` fragments; none at all is the empty input. */ export function advisorCallInputFromJson(json: string): Rec | undefined { if (json.trim() === "") return {}; try { const input = JSON.parse(json) as unknown; return isAdvisorCallInput(input) ? input : undefined; } catch { return undefined; } } const RESULT_FIELDS: Readonly<Record<string, { required: string; optional: readonly string[] }>> = { advisor_result: { required: "text", optional: ["stop_reason"] }, advisor_redacted_result: { required: "encrypted_content", optional: ["stop_reason"] }, advisor_tool_result_error: { required: "error_code", optional: [] }, }; /** * `advisor_tool_result.content`: exactly one documented variant with string fields and no others — * `advisor_result` (`text`), `advisor_redacted_result` (`encrypted_content`), each with an * optional `stop_reason`, or `advisor_tool_result_error` (`error_code`). */ export function isAdvisorResultContent(content: unknown): boolean { if (!isPlainRecord(content) || typeof content.type !== "string" || !Object.hasOwn(RESULT_FIELDS, content.type)) return false; const fields = RESULT_FIELDS[content.type]!; if (typeof content[fields.required] !== "string") return false; return Object.keys(content).every(key => key === "type" || key === fields.required || (fields.optional.includes(key) && typeof content[key] === "string")); } /** * A replayed Advisor block rebuilt from the fields Anthropic documents, so nothing a client added to * its history rides along; undefined for any other block, which the caller copies as before. */ export function advisorReplayBlock(block: Rec): Rec | undefined { if (block.type === "server_tool_use" && block.name === ADVISOR_SERVER_TOOL_NAME) { return { type: "server_tool_use", id: block.id, name: ADVISOR_SERVER_TOOL_NAME, input: block.input }; } if (block.type === "advisor_tool_result") { return { type: "advisor_tool_result", tool_use_id: block.tool_use_id, content: block.content }; } return undefined; } /** Whether a declared catalog or replay run names the Advisor. */ export function hasAdvisorDeclaration(tools: readonly Rec[] | undefined): boolean { return tools?.some(tool => isAdvisorServerToolType(tool.type)) === true; } function runHasAdvisor(run: readonly Rec[]): boolean { return run.some(block => block.type === "server_tool_use" && block.name === ADVISOR_SERVER_TOOL_NAME); } function runHasOtherServerTool(run: readonly Rec[]): boolean { return run.some(block => block.type === "server_tool_use" && block.name !== ADVISOR_SERVER_TOOL_NAME); } type AdvisorServerToolState = { _anthropicServerTools?: readonly Rec[]; _anthropicServerReplay?: ReadonlyMap<string, readonly Rec[]>; }; /** A declaration or completed replay can enable the hosted Advisor on this turn. */ export function hasAdvisorServerTools(parsed: AdvisorServerToolState): boolean { if (hasAdvisorDeclaration(parsed._anthropicServerTools)) return true; for (const run of parsed._anthropicServerReplay?.values() ?? []) { if (runHasAdvisor(run)) return true; } return false; } /** * Withhold the caller's hosted Advisor: its declaration and its call/result blocks in validated * replay runs. Keep other completed exchanges at their original anchor. Later legs must not * restore Advisor history or beta, whether a ceiling withheld it or the proxy owns its name. * Returns whether a declaration was withheld. */ export function withholdAdvisorServerTools(parsed: AdvisorServerToolState): boolean { const declared = hasAdvisorDeclaration(parsed._anthropicServerTools); if (declared) parsed._anthropicServerTools = parsed._anthropicServerTools!.filter(tool => !isAdvisorServerToolType(tool.type)); const replay = parsed._anthropicServerReplay; if (replay && [...replay.values()].some(runHasAdvisor)) { const kept = new Map<string, readonly Rec[]>(); for (const [anchor, run] of replay) { // Validation pairs every call/result by ID, including interleaved exchanges. Removing // both Advisor block types preserves the remaining complete pairs and their order. const remaining = runHasAdvisor(run) ? run.filter(block => block.type !== "advisor_tool_result" && !(block.type === "server_tool_use" && block.name === ADVISOR_SERVER_TOOL_NAME)) : run; if (remaining.length > 0) kept.set(anchor, remaining); } if (kept.size > 0) parsed._anthropicServerReplay = kept; else delete parsed._anthropicServerReplay; } return declared; } export interface AnthropicServerToolPlan { /** Typed declarations this destination receives, in caller order. */ declared: Rec[]; /** Replayable runs this destination receives. */ replay?: ReadonlyMap<string, readonly Rec[]>; /** Betas the forwarded Advisor declaration or history needs. */ betas: string[]; } /** * Split the caller's out-of-body server tools by destination. Web tools keep their own audience * (`webDestination`); the Advisor goes to `advisorServerToolDestination` unless a function tool of * the same name owns it this turn (the proxy Advisor's synthetic tool, or a client function). A * shadowed or ineligible turn drops both the declaration and the Advisor history, as before #8448. */ export function planAnthropicServerTools( provider: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode" | "forwardAdvisorTool">, declared: readonly Rec[] | undefined, replay: ReadonlyMap<string, readonly Rec[]> | undefined, functionNames: ReadonlySet<string>, webDestination: boolean, ): AnthropicServerToolPlan { const advisor = advisorServerToolDestination(provider) && !functionNames.has(ADVISOR_SERVER_TOOL_NAME); const tools = (declared ?? []).filter(tool => isAdvisorServerToolType(tool.type) ? advisor : webDestination); let runs: Map<string, readonly Rec[]> | undefined; let replaysAdvisor = false; for (const [anchor, run] of replay ?? []) { const hasAdvisor = runHasAdvisor(run); if ((hasAdvisor && !advisor) || (runHasOtherServerTool(run) && !webDestination)) continue; replaysAdvisor ||= hasAdvisor; (runs ??= new Map()).set(anchor, run); } const betas = advisor && (replaysAdvisor || hasAdvisorDeclaration(tools)) ? [ADVISOR_TOOL_BETA] : []; return { declared: tools, ...(runs ? { replay: runs } : {}), betas }; } /** * A streamed `advisor_tool_result` paired with the open `server_tool_use` of the same response. * Undefined when the call is missing, its id differs, its input is not the documented empty object, * or the result content is not a documented variant: the exchange is dropped, never synthesized. */ export function advisorServerExchange( call: { id: string; name?: string; json: string } | undefined, result: Rec, ): { blocks: { use: Rec; result: Rec }; completed: boolean } | undefined { if (!call || call.name !== ADVISOR_SERVER_TOOL_NAME || call.id !== result.tool_use_id) return undefined; const input = advisorCallInputFromJson(call.json); if (!input || !isAdvisorResultContent(result.content)) return undefined; return { blocks: { use: { type: "server_tool_use", id: call.id, name: ADVISOR_SERVER_TOOL_NAME, input }, result }, completed: (result.content as Rec).type !== "advisor_tool_result_error", }; }