UNPKG

@bitkyc08/opencodex

Version:

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

215 lines (198 loc) • 9.17 kB
/** * The tool selection a Responses request actually authorized, read from the final outbound body. * * The undeclared-tool guard answers whether a NAME was declared. This answers a different * question: whether this request still permits a client tool call at all, and which names it * permits. `tool_choice: "none"`, a forced selector and an `allowed_tools` allow-list each narrow * the catalog without removing a declaration, so a name can be declared and forbidden at the same * time — and a repair that rebuilds a terminal from collected items would otherwise hand the * client a call the caller ruled out. * * The scope is read from the OUTBOUND body, after every removal, rename and translation, because * that is the request the destination answered. A catalog that ends up empty there authorizes no * client call whatever the selector still says. */ import type { MuseToolNameAliases } from "../responses/muse-tool-name-alias"; import { museWireNameForOriginal } from "../responses/muse-tool-name-alias"; import type { RoutedNamespaceToolAliases, RoutedNamespaceToolIdentity, } from "../responses/namespace-tool-compat"; import { CLIENT_EXECUTED_CALL_TYPES, collectDeclaredWireToolNames, hasExplicitWireToolCatalog, } from "./responses-undeclared-tool-guard"; import { isPlainObject } from "./responses-snapshot-codec"; type ToolKind = "function" | "custom"; const BUILTIN_FUNCTIONS_NAMESPACE = "functions"; type ToolIdentity = Readonly<{ kind: ToolKind; name: string; namespace?: string; }>; export type RequestToolScopeCorrespondence = Readonly<{ clientToolAuthorizationBody?: unknown; routedNamespaceToolAliases?: RoutedNamespaceToolAliases; routedMuseToolNameAliases?: MuseToolNameAliases; convertedRoutedCustomToolNames?: ReadonlySet<string>; }>; function identityKey(identity: ToolIdentity): string { return JSON.stringify([identity.kind, identity.namespace ?? null, identity.name]); } function clientNamespace(value: unknown): string | undefined { return typeof value === "string" && value.length > 0 && value !== BUILTIN_FUNCTIONS_NAMESPACE ? value : undefined; } function selectorIdentity(selector: unknown): ToolIdentity | undefined { if (!isPlainObject(selector)) return undefined; if (selector.type !== "function" && selector.type !== "custom") return undefined; if (typeof selector.name !== "string" || selector.name.length === 0) return undefined; if ("namespace" in selector && typeof selector.namespace !== "string") return undefined; const namespace = clientNamespace(selector.namespace); return { kind: selector.type, name: selector.name, ...(namespace ? { namespace } : {}) }; } function callIdentity(item: Record<string, unknown>): ToolIdentity | undefined { const kind = item.type === "function_call" ? "function" : item.type === "custom_tool_call" ? "custom" : undefined; if (!kind || typeof item.name !== "string" || item.name.length === 0) return undefined; const namespace = clientNamespace(item.namespace); return { kind, name: item.name, ...(namespace ? { namespace } : {}) }; } function sameRestoredIdentity(left: ToolIdentity, right: RoutedNamespaceToolIdentity): boolean { return left.namespace === right.namespace && left.name === right.name && left.kind === right.kind; } /** * Exact identities this restored call could have used on the final outbound wire. * * Namespace spellings come only from namespace-tool-compat's request-scoped, ambiguity-checked * aliases. Muse aliases then compose over those wire names. A kind change is admitted only when * the request recorded that exact custom identity as converted to a function. */ function outboundCallIdentities( item: Record<string, unknown>, correspondence: RequestToolScopeCorrespondence, ): ReadonlySet<string> { const restored = callIdentity(item); if (!restored) return new Set(); const keys = new Set<string>([identityKey(restored)]); const museAliases = correspondence.routedMuseToolNameAliases ?? new Map(); const convertedCustom = correspondence.convertedRoutedCustomToolNames ?? new Set(); const originalSelection = isPlainObject(correspondence.clientToolAuthorizationBody) ? toolSelection(correspondence.clientToolAuthorizationBody) : UNRESTRICTED; const originalSelectionAllowsRestored = originalSelection.kind === "allow" && originalSelection.identities.has(identityKey(restored)); const addWireIdentity = ( preMuseName: string, clientKind: ToolKind, conversionIdentityVerified: boolean, ): void => { const name = museWireNameForOriginal(preMuseName, museAliases); if (name === undefined) return; const kind = clientKind === "custom" && convertedCustom.has(preMuseName) && conversionIdentityVerified ? "function" : clientKind; keys.add(identityKey({ kind, name })); }; if (restored.namespace === undefined) { addWireIdentity(restored.name, restored.kind, originalSelectionAllowsRestored); } for (const [wireName, identity] of correspondence.routedNamespaceToolAliases ?? new Map()) { // namespace-tool-compat emits only aliases authorized under the outbound selector's kind, // then restores `custom` provenance from the request's conversion set. That exact alias edge is // already the proof that this custom-to-function transition belongs to this identity. if (sameRestoredIdentity(restored, identity)) addWireIdentity(wireName, identity.kind, true); } return keys; } type ToolSelection = | { readonly kind: "unrestricted" } | { readonly kind: "deny_all" } | { readonly kind: "allow"; readonly identities: ReadonlySet<string> }; const UNRESTRICTED: ToolSelection = { kind: "unrestricted" }; /** * Read the selector only where it states a client-call boundary. * * `auto`, `required` and an absent selector restrict nothing. A hosted selector * (`{ type: "web_search" }`) forces a tool the PROVIDER runs and does not describe the client * calls this turn may contain, so it is left alone rather than read as a deny-all: a false * refusal would drop a call the caller could have executed. */ function toolSelection(body: Record<string, unknown>): ToolSelection { const choice = body.tool_choice; if (choice === "none") return { kind: "deny_all" }; if (!isPlainObject(choice)) return UNRESTRICTED; if (choice.type === "allowed_tools") { const identities = new Set<string>(); if (!Array.isArray(choice.tools)) return { kind: "allow", identities }; for (const entry of choice.tools) { const identity = selectorIdentity(entry); if (identity) identities.add(identityKey(identity)); } // An allow-list carrying no client tool — emptied by normalization, or hosted entries only — // still bounds this turn: it allows no client call. return { kind: "allow", identities }; } if (choice.type === "function" || choice.type === "custom") { const identity = selectorIdentity(choice); return { kind: "allow", identities: new Set(identity ? [identityKey(identity)] : []), }; } return UNRESTRICTED; } export type RequestToolScope = { /** * The name a client call is refused under, or undefined when this request permits it. * A nameless call type is not answered here: only the declaration guard knows those. */ forbiddenClientToolCallName(item: Record<string, unknown>): string | undefined; }; /** * The client-call boundary this request states, or undefined when it states none. * * Returning undefined for an unrestricted request keeps every ordinary turn on the path it * already had: a caller that selected nothing gets no new refusal. */ export function requestToolScope( body: unknown, correspondence: RequestToolScopeCorrespondence = {}, ): RequestToolScope | undefined { if (!isPlainObject(body)) return undefined; const selection = toolSelection(body); // A readable catalog that declares no client-executable name is authoritative, exactly as it is // for the declaration guard: an explicit empty list denies every client call. An absent catalog // says nothing — a passthrough request may omit `tools` and still receive a call the client // understands. const catalogDeniesClientCalls = hasExplicitWireToolCatalog(body) && collectDeclaredWireToolNames(body).size === 0; if (selection.kind === "unrestricted" && !catalogDeniesClientCalls) return undefined; return { forbiddenClientToolCallName(item: Record<string, unknown>): string | undefined { if (typeof item.type !== "string" || !CLIENT_EXECUTED_CALL_TYPES.has(item.type)) { return undefined; } const restored = callIdentity(item); const reported = restored?.name; if (reported === undefined) return undefined; if (catalogDeniesClientCalls || selection.kind === "deny_all") return reported; if (selection.kind === "allow") { const candidates = outboundCallIdentities(item, correspondence); return [...candidates].some(candidate => selection.identities.has(candidate)) ? undefined : reported; } return undefined; }, }; }