@bitkyc08/opencodex 2.84.0 → 2.86.0

package/src/advisor/settings.ts

@@ -0,0 +1,135 @@
+/**
+ * The single reader of `advisor` config.
+ *
+ * Nothing else reads the `advisor` key directly: the sidecar planner, the management API and the
+ * CLI all resolve through here, so they cannot disagree about defaults or validity. Type-only
+ * config import keeps this module free of runtime edges.
+ */
+import type { OcxConfig } from "../types";
+import { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION } from "./disclosure";
+
+export { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION };
+
+export type AdvisorPolicy = "manual" | "preflight";
+
+export const ADVISOR_EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultra"] as const;
+export type AdvisorEffort = (typeof ADVISOR_EFFORTS)[number];
+
+export const ADVISOR_POLICIES = ["manual", "preflight"] as const;
+
+export interface AdvisorSettings {
+  enabled: boolean;
+  model: string;
+  effort: AdvisorEffort;
+  policy: AdvisorPolicy;
+  timeoutMs: number;
+  /**
+   * Current context-sharing consent, or null when absent, stale, or malformed.
+   * `enabled` does not imply this. Only the current version allows data transfer.
+   */
+  contextSharingConsent: typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION | null;
+  /** Where each resolved value came from, so the GUI/CLI can show real runtime state. */
+  sources: {
+    enabled: "default" | "configured";
+    model: "default" | "configured";
+    effort: "default" | "configured";
+    policy: "default" | "configured";
+    contextSharingConsent: "default" | "configured";
+  };
+}
+
+export const DEFAULT_ADVISOR_SETTINGS: Readonly<AdvisorSettings> = Object.freeze({
+  enabled: false,
+  model: "",
+  effort: "max",
+  policy: "manual",
+  timeoutMs: 120_000,
+  contextSharingConsent: null,
+  sources: Object.freeze({
+    enabled: "default",
+    model: "default",
+    effort: "default",
+    policy: "default",
+    contextSharingConsent: "default",
+  }),
+});
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function isValidAdvisorEffort(value: unknown): value is AdvisorEffort {
+  return typeof value === "string" && (ADVISOR_EFFORTS as readonly string[]).includes(value);
+}
+
+export function isValidAdvisorPolicy(value: unknown): value is AdvisorPolicy {
+  return typeof value === "string" && (ADVISOR_POLICIES as readonly string[]).includes(value);
+}
+
+/** True only for the current context-sharing consent version. Anything else is not a grant. */
+export function isCurrentAdvisorContextSharingConsent(
+  value: unknown,
+): value is typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION {
+  return value === ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}
+
+/**
+ * Resolve advisor settings with conservative defaults for every absent or malformed field.
+ * A malformed block resolves to fully disabled defaults rather than throwing: the advisor is
+ * optional and must never take the request path down with it.
+ */
+export function resolveAdvisorSettings(config: Pick<OcxConfig, "advisor">): AdvisorSettings {
+  const raw: unknown = config.advisor;
+  if (!isRec(raw)) return { ...DEFAULT_ADVISOR_SETTINGS, sources: { ...DEFAULT_ADVISOR_SETTINGS.sources } };
+  const enabled = typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_ADVISOR_SETTINGS.enabled;
+  const model = typeof raw.model === "string" ? raw.model.trim() : DEFAULT_ADVISOR_SETTINGS.model;
+  const effort = isValidAdvisorEffort(raw.effort) ? raw.effort : DEFAULT_ADVISOR_SETTINGS.effort;
+  const policy = isValidAdvisorPolicy(raw.policy) ? raw.policy : DEFAULT_ADVISOR_SETTINGS.policy;
+  const timeoutRaw = raw.timeoutMs;
+  const timeoutMs = typeof timeoutRaw === "number" && Number.isFinite(timeoutRaw) && timeoutRaw >= 1_000
+    ? Math.min(Math.floor(timeoutRaw), 600_000)
+    : DEFAULT_ADVISOR_SETTINGS.timeoutMs;
+  // A present but non-current value (stale version, wrong type) resolves as no consent.
+  // The stored bytes are left untouched; this reader never writes an upgrade.
+  const consentConfigured = Object.prototype.hasOwnProperty.call(raw, "contextSharingConsent");
+  const contextSharingConsent = isCurrentAdvisorContextSharingConsent(raw.contextSharingConsent)
+    ? raw.contextSharingConsent
+    : null;
+  return {
+    enabled,
+    model,
+    effort,
+    policy,
+    timeoutMs,
+    contextSharingConsent,
+    sources: {
+      enabled: typeof raw.enabled === "boolean" ? "configured" : "default",
+      model: typeof raw.model === "string" && raw.model.trim() !== "" ? "configured" : "default",
+      effort: isValidAdvisorEffort(raw.effort) ? "configured" : "default",
+      policy: isValidAdvisorPolicy(raw.policy) ? "configured" : "default",
+      contextSharingConsent: consentConfigured ? "configured" : "default",
+    },
+  };
+}
+
+/**
+ * Whether a consultation may send task context. Requires the switch, a model, and the
+ * current context-sharing consent. `enabled` is not consent. A miss fails closed for the
+ * data transfer and leaves the worker request itself running.
+ */
+export function advisorRunnable(settings: AdvisorSettings): boolean {
+  return settings.enabled
+    && settings.model.trim() !== ""
+    && settings.contextSharingConsent === ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}
+
+/**
+ * Enabled, with a model, but without current consent. The management surface reports
+ * `advisor_context_sharing_consent_required` and the runtime sends no task context.
+ */
+export function advisorContextSharingBlocked(settings: AdvisorSettings): boolean {
+  return settings.enabled
+    && settings.model.trim() !== ""
+    && settings.contextSharingConsent !== ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}

package/src/advisor/state.ts

@@ -0,0 +1,369 @@
+import { createHash } from "node:crypto";
+import { advisorResultIsAdvice } from "./context";
+
+/**
+ * Conversation- and task-scoped advisor state.
+ *
+ * Three scopes, deliberately separate:
+ *
+ * 1. REQUEST-scoped state lives in the per-request plan closure (see runtime.ts) — consultation
+ *    count, dedup fingerprints, the preflight flag. Born and dies with one request.
+ *
+ * 2. TASK-scoped preflight ledger (this file): a bounded, process-local claim table that makes
+ *    "at most one automatic consultation per task" atomic across concurrent requests. A claim
+ *    requires a STABLE conversation identity plus the current task boundary; a client that sends
+ *    no identity never enters this ledger (see `advisorLedgerKey`) and therefore fails open —
+ *    it may be consulted once per request rather than risk two independent tasks suppressing
+ *    each other through a shared guess.
+ *
+ * 3. PROVENANCE, split by authority:
+ *    - MANUAL advice is verifiable history: a `toolResult` whose `toolName` is the synthetic
+ *      advisor tool and whose content parses as a runtime-written advice object. Ordinary tool
+ *      output, developer text, user text, and failure notices can never match it. Bytes inside
+ *      the quoted advice field cannot change the runtime-owned status.
+ *    - AUTOMATIC preflight dedup is NOT decided from history at all. The developer transport
+ *      envelope labels the payload for the worker; any client could echo or forge such a message,
+ *      so the ledger below is the authoritative source for "this task was already consulted" —
+ *      `success`, `inflight` and `cooldown` states. A conversation with no stable identity gets
+ *      no ledger and therefore fails open (at most one extra attempt). A forged marker or a
+ *      forged developer message cannot suppress the policy.
+ *
+ * Ledger entries are plain state records — no message bodies, no credentials. Every state is
+ * bounded by entry count and its own TTL.
+ */
+
+/** Long-lived success suppression: the task lifetime approximation (also the ledger TTL cap). */
+export const ADVISOR_SUCCESS_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Failure cooldown. One minute is the repository's standing minute-scale unit (tray polling,
+ * subagent availability polling); it turns a transient 503 into a short pause instead of
+ * silencing the policy for the rest of the coding session.
+ */
+export const ADVISOR_FAILURE_COOLDOWN_MS = 60 * 1000;
+/**
+ * In-flight claim expiry. Longer than the largest configurable consultation timeout (600s
+ * upper bound on `advisor.timeoutMs`, default 120s) so a slow-but-alive consultation is never
+ * mistaken for a wedged one, while a crashed claim cannot block a task forever.
+ */
+export const ADVISOR_INFLIGHT_TTL_MS = 10 * 60 * 1000;
+
+const MAX_ENTRIES = 512;
+
+export type AdvisorClaimState =
+  /** The caller now owns the consultation for this task. */
+  | "claimed"
+  /** Another request for the same task is consulting right now. */
+  | "inflight"
+  /** This task already received advice; suppression holds until the success TTL expires. */
+  | "complete"
+  /** A recent consultation failed; suppression holds for the short failure cooldown. */
+  | "cooldown"
+  /**
+   * The ledger is full of live claims and granted nothing. Fail-open: the worker continues
+   * without a new automatic consultation rather than evicting a claim that is still running.
+   */
+  | "saturated";
+
+/**
+ * The result of a claim attempt. `token` identifies THIS claim and is present only on
+ * `"claimed"`; settlement must present it, so a slow consultation whose in-flight entry expired
+ * cannot settle the successor claim that took its place.
+ */
+export interface AdvisorClaim {
+  state: AdvisorClaimState;
+  token?: string;
+}
+
+interface LedgerEntry {
+  state: "inflight" | "success" | "failed";
+  at: number;
+  /** Present on in-flight entries: which claim owns this entry. */
+  token?: string;
+}
+
+export interface AdvisorPreflightLedger {
+  /**
+   * Atomically try to own the consultation for a task key. Returns `claimed` exactly once per
+   * task (with the ownership token) until a matching settlement releases it, so two concurrent
+   * requests cannot both consult.
+   */
+  claim(key: string, now?: number): AdvisorClaim;
+  /**
+   * Settle a claim the caller owns. A settlement whose token does not match the current entry
+   * is a no-op: the entry now belongs to a successor claim (the caller's in-flight window
+   * expired), and it must not be able to erase or overwrite that successor's state.
+   */
+  complete(key: string, token: string, now?: number): void;
+  fail(key: string, token: string, now?: number): void;
+  release(key: string, token: string, now?: number): void;
+  /**
+   * Fact, not settlement: this task received advice (used by a successful MANUAL consultation,
+   * which owns no preflight claim). Records success regardless of the current entry, because
+   * "the task was advised" is true whichever consultation produced it.
+   */
+  markAdvised(key: string, now?: number): void;
+  /** Test/observability seam: current entry count. */
+  size(): number;
+}
+
+export function createAdvisorPreflightLedger(): AdvisorPreflightLedger {
+  const entries = new Map<string, LedgerEntry>();
+  let claimSequence = 0;
+
+  const isExpired = (entry: LedgerEntry, now: number): boolean => {
+    const ttl = entry.state === "success"
+      ? ADVISOR_SUCCESS_TTL_MS
+      : entry.state === "failed"
+        ? ADVISOR_FAILURE_COOLDOWN_MS
+        : ADVISOR_INFLIGHT_TTL_MS;
+    return now - entry.at > ttl;
+  };
+
+  /**
+   * Make room for ONE new claim without ever evicting a live in-flight entry, because that entry
+   * is the only thing preventing a second automatic consultation for its task. Order: expired
+   * entries first, then settled ones (success before failure), oldest first. Returns false when
+   * every entry is a live claim — the caller then reports `saturated` instead of breaking the
+   * "at most one in-flight consultation per task" guarantee.
+   */
+  const makeRoom = (now: number): boolean => {
+    if (entries.size < MAX_ENTRIES) return true;
+    for (const [key, entry] of entries) {
+      if (isExpired(entry, now)) entries.delete(key);
+    }
+    if (entries.size < MAX_ENTRIES) return true;
+    for (const state of ["success", "failed"] as const) {
+      for (const [key, entry] of entries) {
+        if (entry.state === state) {
+          entries.delete(key);
+          return true;
+        }
+      }
+    }
+    return false;
+  };
+
+  const liveEntry = (key: string, now: number): LedgerEntry | undefined => {
+    const entry = entries.get(key);
+    if (!entry) return undefined;
+    if (isExpired(entry, now)) {
+      entries.delete(key);
+      return undefined;
+    }
+    return entry;
+  };
+
+  // Replacing an existing key never grows the map, and every NEW key is admitted only through
+  // claim()'s makeRoom gate, so the table cannot exceed MAX_ENTRIES.
+  const set = (key: string, state: LedgerEntry["state"], now: number, token?: string): void => {
+    if (entries.has(key)) entries.delete(key);
+    entries.set(key, { state, at: now, ...(token !== undefined ? { token } : {}) });
+  };
+
+  /** True when the caller's token still owns the current in-flight entry for this key. */
+  const owns = (key: string, token: string, now: number): boolean => {
+    const entry = liveEntry(key, now);
+    return entry?.state === "inflight" && entry.token === token;
+  };
+
+  return {
+    claim(key, now = Date.now()) {
+      const entry = liveEntry(key, now);
+      if (entry?.state === "success") return { state: "complete" };
+      if (entry?.state === "failed") return { state: "cooldown" };
+      if (entry?.state === "inflight") return { state: "inflight" };
+      if (!makeRoom(now)) return { state: "saturated" };
+      claimSequence += 1;
+      const token = `claim-${claimSequence.toString(36)}`;
+      set(key, "inflight", now, token);
+      return { state: "claimed", token };
+    },
+    complete(key, token, now = Date.now()) {
+      // A settlement that no longer owns the entry is a no-op: the claim it belonged to expired
+      // and a successor now owns the state.
+      if (owns(key, token, now)) set(key, "success", now);
+    },
+    fail(key, token, now = Date.now()) {
+      if (owns(key, token, now)) set(key, "failed", now);
+    },
+    release(key, token, now = Date.now()) {
+      if (owns(key, token, now)) entries.delete(key);
+    },
+    markAdvised(key, now = Date.now()) {
+      // Recording the FACT must respect the same cap as claiming: a key that is not present and a
+      // table holding nothing but live claims means no room, so the record is skipped rather than
+      // evicting a claim that is still running. Fail-open: at worst one extra automatic attempt.
+      const present = liveEntry(key, now) !== undefined;
+      if (!present && !makeRoom(now)) return;
+      set(key, "success", now);
+    },
+    size() {
+      return entries.size;
+    },
+  };
+}
+
+/**
+ * Stable conversation identity for the ledger, reusing the repository's existing request
+ * identities in specificity order: the client's own thread, the shared parent thread, the
+ * Cursor conversation, the Cursor client thread, then the reasoning-replay scope's thread.
+ * Returns undefined for a client that sends no identity at all — such a caller stays out of the
+ * process-global ledger on purpose (fail-open, see the module header).
+ */
+export function advisorConversationIdentity(parsed: {
+  _codexOwnThreadId?: string;
+  _clientThreadId?: string;
+  _cursorConversationId?: string;
+  _cursorClientThreadId?: string;
+  _reasoningReplayScope?: { clientThreadId?: string };
+}): string | undefined {
+  return parsed._codexOwnThreadId
+    ?? parsed._clientThreadId
+    ?? parsed._cursorConversationId
+    ?? parsed._cursorClientThreadId
+    ?? parsed._reasoningReplayScope?.clientThreadId
+    ?? undefined;
+}
+
+/**
+ * Domain-separated SHA-256 digest. Task identity and suppression are CORRECTNESS boundaries, so a
+ * 32-bit non-cryptographic hash is not an acceptable primary digest: distinct tasks must not
+ * collide because of a short fold. The ledger stores only this digest, never the raw text, so a
+ * captured key reveals nothing about the conversation. The domain prefix keeps digests from
+ * different purposes apart even if their inputs coincide.
+ */
+function sha256Hex(domain: string, value: string, hexChars: number): string {
+  return createHash("sha256").update(`${domain}\0${value}`, "utf8").digest("hex").slice(0, hexChars);
+}
+
+/**
+ * The current task boundary inside a conversation: how many user turns the history carries and a
+ * digest of the FULL latest user text. A new user message moves the boundary (a new task gets its
+ * own claim); the same turn re-sent by a stateless full-history client keeps the same boundary,
+ * and a `previous_response_id` expansion replays the same user turns, so continuations dedup.
+ * The whole text participates — no truncation — so two tasks that share an opening prefix still
+ * get different boundaries.
+ */
+export function advisorTaskBoundary(parsed: {
+  context: { messages: readonly { role: string; content: unknown }[] };
+}): string {
+  let userTurns = 0;
+  let lastUserText = "";
+  for (const message of parsed.context.messages) {
+    if (message.role !== "user") continue;
+    userTurns += 1;
+    lastUserText = contentText(message.content);
+  }
+  return `t${userTurns}:${sha256Hex("advisor-task-boundary", lastUserText, 32)}`;
+}
+
+/**
+ * The ledger key: one domain-separated SHA-256 digest over conversation identity + task boundary
+ * + worker model. Returns undefined when the caller has no stable conversation identity — the
+ * caller then relies on request-scoped dedup and genuine in-history provenance instead of a
+ * shared guess (documented fail-open).
+ */
+export function advisorLedgerKey(
+  parsed: {
+    context: { messages: readonly { role: string; content: unknown }[] };
+    _codexOwnThreadId?: string;
+    _clientThreadId?: string;
+    _cursorConversationId?: string;
+    _cursorClientThreadId?: string;
+    _reasoningReplayScope?: { clientThreadId?: string };
+  },
+  workerModelId: string,
+): string | undefined {
+  const identity = advisorConversationIdentity(parsed);
+  if (!identity) return undefined;
+  const material = `${identity}\0${advisorTaskBoundary(parsed)}\0${workerModelId}`;
+  return `ak-${sha256Hex("advisor-task-key", material, 40)}`;
+}
+
+/** Text projection for string-or-parts content; used only for hashing, never transmitted. */
+export function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part): part is { type: "text"; text: string } =>
+      !!part && typeof part === "object" && (part as { type?: unknown }).type === "text"
+      && typeof (part as { text?: unknown }).text === "string")
+    .map(part => part.text)
+    .join("");
+}
+
+/**
+ * Legacy marker spellings. Failure text still neutralizes them so an upstream error cannot
+ * look like an old wrapper. They are not suppression authority and are not emitted.
+ */
+export const ADVISOR_PREFLIGHT_MARKER = "<opencodex_advisor_preflight>";
+
+/** The synthetic advisor tool's wire name; kept in sync with the tool definition by test. */
+export const ADVISOR_RESULT_TOOL_NAME = "advisor";
+
+/** Legacy manual wrapper spelling. Detection does not search for this substring. */
+export const ADVISOR_ADVICE_MARKER = "<opencodex_advisor>";
+
+/**
+ * Detect an ALREADY-PRESENT MANUAL advisor result — by provenance, never by a bare string.
+ * The message must be a `toolResult` whose `toolName` is the synthetic advisor tool, and its
+ * content must parse as a runtime-written advice object (`status === "advice"` on the sibling
+ * field the runtime sets). Text inside `advice` cannot flip that field.
+ *
+ * Only messages after the latest user turn count. Manual advice from an earlier task in the
+ * same thread does not suppress preflight for a later task; the ledger keys those separately.
+ * Developer messages are deliberately NOT inspected. Automatic preflight dedup lives in the
+ * ledger. A client-echoed developer envelope, a shell result, or a failure notice matches nothing.
+ */
+export function historyHasManualAdvisorResult(parsed: {
+  context: { messages: readonly { role: string; content?: unknown; toolName?: string }[] };
+}): boolean {
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i]!;
+    if (message.role === "user") break;
+    if (message.role !== "toolResult") continue;
+    if (message.toolName !== ADVISOR_RESULT_TOOL_NAME) continue;
+    if (advisorResultIsAdvice(contentText(message.content))) return true;
+  }
+  return false;
+}
+
+/** Kept for callers that only need the first user text (payload building, tests). */
+export function firstUserText(parsed: { context: { messages: readonly { role: string; content: unknown }[] } }): string {
+  for (const message of parsed.context.messages) {
+    if (message.role !== "user") continue;
+    const text = contentText(message.content);
+    if (text.trim() !== "") return text;
+  }
+  return "";
+}
+
+/**
+ * Deterministic preflight trigger: has this conversation already produced orientation evidence
+ * since the latest user message? The documented approximation for "before the first substantive
+ * implementation" — the protocol layer offers no safe pre-mutation checkpoint, so OpenCodex fires
+ * the automatic attempt on the first worker reasoning turn that arrives with that evidence.
+ * Evidence is an assistant tool call OR a tool result after the latest user message (both forms
+ * are genuinely accepted; the docs say so). Only text/toolResult content is inspected — never
+ * reasoning, never encrypted items.
+ */
+export function hasOrientationEvidence(parsed: { context: { messages: readonly { role: string; content: unknown }[] } }): boolean {
+  let latestUserIndex = -1;
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    if (parsed.context.messages[i]?.role === "user") {
+      latestUserIndex = i;
+      break;
+    }
+  }
+  if (latestUserIndex < 0) return false;
+  for (let i = latestUserIndex + 1; i < parsed.context.messages.length; i += 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "toolResult") return true;
+    if (message.role === "assistant" && Array.isArray(message.content)
+      && message.content.some(part =>
+        !!part && typeof part === "object" && (part as { type?: unknown }).type === "toolCall")) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/advisor/synthetic-tool.ts

@@ -0,0 +1,33 @@
+/**
+ * The synthetic `advisor` tool injected into routed worker turns.
+ *
+ * Mirrors src/web-search/synthetic-tool.ts: the proxy OWNS this tool — the worker only expresses
+ * "I want to consult the expert" (optionally with a focus), and OpenCodex builds everything else
+ * (task context, conversation, tool catalog, identities) itself. The worker never passes a
+ * transcript, provider, model, or files.
+ */
+import type { OcxTool } from "../types";
+
+export const ADVISOR_TOOL_NAME = "advisor";
+
+export function buildAdvisorTool(): OcxTool {
+  return {
+    name: ADVISOR_TOOL_NAME,
+    description:
+      "Consult an independent expert advisor model about the current task. The advisor receives a "
+      + "summary of what you have done so far (task, conversation, tool results) and returns "
+      + "strategic advice, critique, root-cause reasoning, or alternative approaches. Use it when "
+      + "you are stuck, before starting substantive implementation on a hard task, or when you want "
+      + "a second opinion on a plan or diagnosis. The advisor cannot execute tools or edit files; "
+      + "you remain responsible for all execution. Optionally pass a short `question` to focus the "
+      + "consultation.",
+    parameters: {
+      type: "object",
+      properties: {
+        question: { type: "string", description: "Optional short focus question for the advisor." },
+      },
+      required: [],
+    },
+    advisor: true,
+  };
+}

package/src/bridge/errors.ts

@@ -13,6 +13,7 @@ import {
   CYBER_POLICY_ERROR_CODE,
   isCyberPolicyCode,
   SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE,
+  UNDECLARED_TOOL_CALL_ERROR_CODE,
   type OcxErrorPayload,
 } from "../lib/errors";
 
@@ -31,6 +32,10 @@ export function formatErrorResponse(
     error.code = CYBER_POLICY_ERROR_CODE;
     error.type = cyberPolicyErrorType(type);
   }
+  // The undeclared-tool refusal is deterministic, not a transient upstream failure: its code
+  // survives so the Anthropic translator can classify it instead of folding it into a
+  // retryable overload (and so clients see the SSE path's rejection identity).
+  if (options?.code === UNDECLARED_TOOL_CALL_ERROR_CODE) error.code = options.code;
   // Only the allowlisted transport verdicts survive this formatter. Do not forward
   // arbitrary provider codes, and preserve the existing cyber-policy precedence.
   const replayBlocked = error.code !== CYBER_POLICY_ERROR_CODE

package/src/chat/inbound.ts

@@ -36,7 +36,7 @@ export function assertChatCompletionsRoutingBody(raw: unknown): asserts raw is C
 const OUTPUT_CONFIG_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
 const OUTPUT_CONFIG_SUMMARIES = new Set(["auto", "concise", "detailed", "none"]);
 
-function contentToText(content: unknown): string {
+export function contentToText(content: unknown): string {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return "";
   const parts: string[] = [];
@@ -62,7 +62,7 @@ const imageUrlFromPart = chatImageUrlFromPart;
  * understanding is requested by (#3271). The object form is the only one that
  * can carry it — `video_url` as a bare string has nowhere to put it.
  */
-function videoFromPart(part: Rec): { url: string; processing?: string } | null {
+export function videoFromPart(part: Rec): { url: string; processing?: string } | null {
   if (part.type !== "video_url") return null;
   const videoUrl = part.video_url;
   if (typeof videoUrl === "string" && videoUrl.length > 0) return { url: videoUrl };
@@ -123,7 +123,7 @@ function userContentToBlocks(content: unknown): Rec[] {
  * was dropped in silence (#5212). A part with no inline bytes is still not translatable and is
  * left to the untranslated-media refusal, which runs before this loop.
  */
-function fileFromPart(part: Rec): Rec | null {
+export function fileFromPart(part: Rec): Rec | null {
   if (part.type !== "file" && part.type !== "input_file") return null;
   const file = isRec(part.file) ? part.file : part;
   const fileData = file.file_data;
@@ -143,7 +143,7 @@ function fileFromPart(part: Rec): Rec | null {
  * Only representable plaintext is read. No signature, encrypted payload or
  * provider-issued item id is reconstructed — see the reasoning item built below.
  */
-function assistantReasoningText(msg: Rec): string | undefined {
+export function assistantReasoningText(msg: Rec): string | undefined {
   if (typeof msg.reasoning_content === "string" && msg.reasoning_content.length > 0) {
     return msg.reasoning_content;
   }
@@ -601,6 +601,32 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
     ...(legacyFunctionsToResponses(raw.functions) ?? []),
   ];
   if (tools.length > 0) body.tools = tools;
+  applyChatSettings(raw, body);
+  return body;
+}
+
+/**
+ * The request settings of a Chat body as a Responses body with no conversation: `input` is
+ * empty and there are no `instructions` or `tools`. The Antigravity direct lane hands this to
+ * the Responses core so routing, effort policy, tier and logging keep reading the fields they
+ * read today, while the conversation is decoded straight into the IR
+ * (`src/protocols/codecs/chat-ir.ts`). Field order and validation are the bridge body's own:
+ * both are built by `applyChatSettings`.
+ */
+export function chatSettingsToResponsesBody(raw: unknown): Rec {
+  assertChatCompletionsRoutingBody(raw);
+  const body: Rec = {
+    model: raw.model,
+    input: [],
+    stream: raw.stream === true,
+    store: false,
+  };
+  applyChatSettings(raw, body);
+  return body;
+}
+
+/** Everything after the conversation and tool catalog: choice, limits, sampling, reasoning, format. */
+function applyChatSettings(raw: ChatCompletionsRoutingBody, body: Rec): void {
   if (raw.tool_choice !== undefined) toolChoiceToResponses(raw.tool_choice, body);
   else legacyFunctionChoiceToResponses(raw.function_call, body);
 
@@ -637,6 +663,4 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
 
   const text = responseFormatToText(raw.response_format);
   if (text) body.text = text;
-
-  return body;
 }

package/src/chat/outbound.ts

@@ -19,6 +19,7 @@ import {
   CYBER_POLICY_ERROR_CODE,
   isCyberPolicyCode,
   isCyberPolicyMessage,
+  UNDECLARED_TOOL_CALL_ERROR_CODE,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { createSseBlockBuffer, sseDataPayload } from "../server/sse-payload-rewrite";
@@ -196,6 +197,10 @@ export function chatCompletionsStreamErrorPayload(
   } else if (isCyberPolicyCode(details?.code) || classified.code === CYBER_POLICY_ERROR_CODE) {
     classified.code = CYBER_POLICY_ERROR_CODE;
     classified.type = cyberPolicyErrorType(details?.type);
+  } else if (details?.code === UNDECLARED_TOOL_CALL_ERROR_CODE) {
+    // The guard's deterministic refusal keeps its wire identity past classifyError's
+    // generic 5xx remap — same code the buffered Chat error and the SSE frame carry.
+    classified.code = UNDECLARED_TOOL_CALL_ERROR_CODE;
   } else if (details?.code !== undefined && details.code !== null && !classified.code) {
     classified.code = details.code;
   }