jeo-code 0.6.27 → 0.6.28

package/src/ai/providers/gemini.ts

@@ -1,7 +1,7 @@
 import type { Credential } from "../../auth";
 import type { CallOptions, Message, ProviderAdapter } from "../types";
 import { readSse } from "../sse";
-import { providerHttpError } from "./errors";
+import { providerHttpError, fetchWithArtifactFailSafe } from "./errors";
 import { jeoEnv } from "../../util/env";
 import { serializeToolCalls } from "../../agent/tool-schemas";
 
@@ -37,35 +37,62 @@ export function geminiThinkingBudget(model: string, effort?: CallOptions["reason
   return budget;
 }
 
+
+/** True when an assistant turn can replay native functionCall + thoughtSignature: it has
+ *  structured toolUse AND a same-model Gemini thoughtSignature artifact, AND thinking is on. */
+export function geminiNativizable(m: Message, modelKey: string, thinkingEnabled: boolean): boolean {
+  return thinkingEnabled
+    && !!m.toolUse?.length
+    && !!m.reasoningArtifacts?.some(a => a.provider === "gemini" && a.model === modelKey && !!a.thoughtSignature);
+}
 /** Shared Gemini request payload (contents + generationConfig + systemInstruction)
  *  used by BOTH the public generativelanguage path (API key) and the Cloud Code
  *  Assist path (OAuth) — only the envelope/endpoint differs. */
-export function buildGeminiPayload(messages: Message[], options: CallOptions): { geminiModel: string; payload: Record<string, unknown> } {
+export function buildGeminiPayload(messages: Message[], options: CallOptions, stripArtifacts = false): { geminiModel: string; payload: Record<string, unknown> } {
   const resolvedModel = options.model.replace(/^(google|gemini)\//, "");
   let geminiModel = resolvedModel;
   if (!geminiModel || geminiModel === "claude-3-5-sonnet") geminiModel = "gemini-2.0-flash";
 
   const systemPrompt = options.systemPrompt ?? messages.find(m => m.role === "system")?.content;
+  const thinkingBudget = geminiThinkingBudget(geminiModel, options.reasoningEffort, options.maxTokens);
+  const thinkingEnabled = thinkingBudget !== undefined && !stripArtifacts;
   // Gemini requires strictly ALTERNATING user/model turns. jeo histories can carry
   // consecutive same-role messages (a compaction summary prepended before a tool-result,
   // back-to-back tool results, etc.), so coalesce adjacent same-role turns into one
-  // content block — otherwise the API rejects the request mid-session.
-  const contents: { role: string; parts: ({ text: string } | { inlineData: { mimeType: string; data: string } })[] }[] = [];
-  for (const m of messages) {
-    if (m.role === "system") continue;
+  // content block — otherwise the API rejects the request mid-session. Native
+  // functionCall/functionResponse parts (with thoughtSignature) are reconstructed for
+  // same-model turns to preserve cross-step thought context; else plain text.
+  type GeminiPart = Record<string, unknown>;
+  const nonSystem = messages.filter(m => m.role !== "system");
+  const contents: { role: string; parts: GeminiPart[] }[] = [];
+  nonSystem.forEach((m, i) => {
     const role = m.role === "assistant" ? "model" : "user";
-    // Clipboard-pasted images become inlineData parts alongside the text part.
-    const parts: ({ text: string } | { inlineData: { mimeType: string; data: string } })[] = [
-      ...(m.images?.map(img => ({ inlineData: { mimeType: img.mediaType, data: img.data } })) ?? []),
-      { text: m.content },
-    ];
-    const prev = contents[contents.length - 1];
-    if (prev && prev.role === role) {
-      prev.parts.push(...parts);
+    let parts: GeminiPart[];
+    if (m.role === "assistant" && geminiNativizable(m, options.model, thinkingEnabled)) {
+      const sig = m.reasoningArtifacts!.find(a => a.provider === "gemini" && a.model === options.model && a.thoughtSignature)?.thoughtSignature;
+      parts = m.toolUse!.map((tu, idx) => {
+        const p: GeminiPart = { functionCall: { name: tu.tool, args: tu.arguments } };
+        if (idx === 0 && sig) p.thoughtSignature = sig; // bind the turn signature to the first call
+        return p;
+      });
+    } else if (m.role === "user" && m.toolResults?.length && i > 0
+        && nonSystem[i - 1].role === "assistant"
+        && geminiNativizable(nonSystem[i - 1], options.model, thinkingEnabled)) {
+      const prevToolUse = nonSystem[i - 1].toolUse ?? [];
+      parts = m.toolResults.map(tr => ({
+        functionResponse: { name: prevToolUse.find(tu => tu.id === tr.id)?.tool ?? "tool", response: { output: tr.output } },
+      }));
+      if (m.toolResultExtra) parts.push({ text: m.toolResultExtra });
     } else {
-      contents.push({ role, parts });
+      parts = [
+        ...(m.images?.map(img => ({ inlineData: { mimeType: img.mediaType, data: img.data } })) ?? []),
+        { text: m.content },
+      ];
     }
-  }
+    const prev = contents[contents.length - 1];
+    if (prev && prev.role === role) prev.parts.push(...parts);
+    else contents.push({ role, parts });
+  });
 
   const generationConfig: Record<string, unknown> = {
     temperature: options.temperature ?? 0.2,
@@ -74,7 +101,7 @@ export function buildGeminiPayload(messages: Message[], options: CallOptions): {
   // Function-calling and responseMimeType:json are mutually exclusive in the Gemini
   // API — when native tools are declared, the functionCall parts replace JSON-in-prose.
   if (options.jsonMode && !options.tools?.length) generationConfig.responseMimeType = "application/json";
-  const thinkingBudget = geminiThinkingBudget(geminiModel, options.reasoningEffort, options.maxTokens);
+
   // includeThoughts: required for Gemini to STREAM thought summaries (the `thought:true`
   // parts thoughtOf() routes to onReasoning) — without it the model thinks silently.
   if (thinkingBudget !== undefined) generationConfig.thinkingConfig = { includeThoughts: true, thinkingBudget };
@@ -91,8 +118,8 @@ export function buildGeminiPayload(messages: Message[], options: CallOptions): {
   return { geminiModel, payload };
 }
 
-export function geminiRequest(messages: Message[], options: CallOptions, credential: Credential, action: "generateContent" | "streamGenerateContent"): { url: string; headers: Record<string, string>; body: string } {
-  const { geminiModel, payload } = buildGeminiPayload(messages, options);
+export function geminiRequest(messages: Message[], options: CallOptions, credential: Credential, action: "generateContent" | "streamGenerateContent", stripArtifacts = false): { url: string; headers: Record<string, string>; body: string } {
+  const { geminiModel, payload } = buildGeminiPayload(messages, options, stripArtifacts);
   const oauth = credential.kind === "oauth" ? credential.token : undefined;
   const apiKey = credential.kind === "api_key" ? credential.token : undefined;
   let url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(geminiModel)}:${action}`;
@@ -123,8 +150,8 @@ export function getGeminiCliHeaders(modelId?: string): Record<string, string> {
  * plain `jeo auth login gemini` works without any GEMINI_API_KEY. The body
  * wraps the standard payload as `{ project, model, request }`.
  */
-export function geminiCliRequest(messages: Message[], options: CallOptions, accessToken: string, projectId: string): { url: string; headers: Record<string, string>; body: string } {
-  const { geminiModel, payload } = buildGeminiPayload(messages, options);
+export function geminiCliRequest(messages: Message[], options: CallOptions, accessToken: string, projectId: string, stripArtifacts = false): { url: string; headers: Record<string, string>; body: string } {
+  const { geminiModel, payload } = buildGeminiPayload(messages, options, stripArtifacts);
   return {
     url: `${CODE_ASSIST_ENDPOINT}/v1internal:streamGenerateContent?alt=sse`,
     headers: {
@@ -137,8 +164,22 @@ export function geminiCliRequest(messages: Message[], options: CallOptions, acce
   };
 }
 
+/** POST a Gemini request with a reasoning-artifact fail-safe (see fetchWithArtifactFailSafe). */
+function geminiFetchFailSafe(
+  make: (stripArtifacts: boolean) => { url: string; headers: Record<string, string>; body: string },
+  signal?: AbortSignal,
+): Promise<Response> {
+  return fetchWithArtifactFailSafe(
+    strip => {
+      const r = make(strip);
+      return fetch(r.url, { method: "POST", headers: r.headers, body: r.body, signal });
+    },
+    (status, body) => status === 400 && /thoughtsignature|thought_signature|functioncall|function_call|signature/i.test(body),
+  );
+}
+
 interface GeminiChunk {
-  candidates?: { content?: { parts?: { text?: string; thought?: boolean; functionCall?: { name?: string; args?: Record<string, unknown> } }[] }; finishReason?: string }[];
+  candidates?: { content?: { parts?: { text?: string; thought?: boolean; thoughtSignature?: string; functionCall?: { name?: string; args?: Record<string, unknown> } }[] }; finishReason?: string }[];
   promptFeedback?: { blockReason?: string };
   usageMetadata?: { promptTokenCount?: number; candidatesTokenCount?: number; thoughtsTokenCount?: number };
 }
@@ -157,6 +198,19 @@ function textOf(chunk: GeminiChunk): string {
 function thoughtOf(chunk: GeminiChunk): string {
   return chunk.candidates?.[0]?.content?.parts?.filter(p => p.thought).map(p => p.text ?? "").join("") ?? "";
 }
+
+/** Emit each NEW thoughtSignature seen on this chunk's parts as a replay artifact (Gemini
+ *  binds it to the functionCall part — replayed to keep cross-step thought context). `seen`
+ *  dedups across the streamed chunks of one turn. */
+function captureGeminiSignatures(chunk: GeminiChunk, options: CallOptions, seen: Set<string>): void {
+  for (const p of chunk.candidates?.[0]?.content?.parts ?? []) {
+    const sig = p.thoughtSignature;
+    if (sig && !seen.has(sig)) {
+      seen.add(sig);
+      options.onReasoningArtifact?.({ provider: "gemini", model: options.model, thoughtSignature: sig });
+    }
+  }
+}
 /** Native Gemini functionCall parts → {tool, arguments} (gjc/antigravity parity). Kept
  *  separate from textOf so the re-serialized canonical JSON envelope drives the loop. */
 function geminiFunctionCallsOf(chunk: GeminiChunk): { tool: string; arguments: Record<string, unknown> }[] {
@@ -197,14 +251,14 @@ function blockedReason(chunk: GeminiChunk): string | undefined {
 async function* ccaTurn(messages: Message[], options: CallOptions, credential: Credential & { kind: "oauth" }): AsyncGenerator<string> {
   const { resolveAntigravityProjectId } = await import("./antigravity");
   const projectId = await resolveAntigravityProjectId(credential, { signal: options.signal });
-  const { url, headers, body } = geminiCliRequest(messages, options, credential.token, projectId);
-  const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+  const response = await geminiFetchFailSafe(strip => geminiCliRequest(messages, options, credential.token, projectId, strip), options.signal);
   if (!response.ok) throw await providerHttpError("Gemini (Cloud Code Assist)", response);
   if (!response.body) return;
   let lastUsage: GeminiChunk["usageMetadata"];
   let yieldedAny = false;
   let lastEmptyReason: string | undefined;
   const fnCalls: { tool: string; arguments: Record<string, unknown> }[] = [];
+  const seenSigs = new Set<string>();
   for await (const data of readSse(response.body)) {
     let chunk: CcaChunk;
     try {
@@ -216,6 +270,7 @@ async function* ccaTurn(messages: Message[], options: CallOptions, credential: C
     if (!inner) continue;
     const thought = thoughtOf(inner);
     if (thought) options.onReasoning?.(thought);
+    captureGeminiSignatures(inner, options, seenSigs);
     const delta = textOf(inner);
     if (delta) {
       yieldedAny = true;
@@ -249,10 +304,10 @@ export const geminiAdapter: ProviderAdapter = {
       for await (const delta of ccaTurn(messages, options, credential)) out += delta;
       return out;
     }
-    const { url, headers, body } = geminiRequest(messages, options, credential, "generateContent");
-    const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+    const response = await geminiFetchFailSafe(strip => geminiRequest(messages, options, credential, "generateContent", strip), options.signal);
     if (!response.ok) throw await providerHttpError("Gemini", response);
     const result = (await response.json()) as GeminiChunk;
+    captureGeminiSignatures(result, options, new Set());
     if (result.usageMetadata) {
       options.onUsage?.({ inputTokens: result.usageMetadata.promptTokenCount, outputTokens: result.usageMetadata.candidatesTokenCount });
     }
@@ -271,14 +326,14 @@ export const geminiAdapter: ProviderAdapter = {
       yield* ccaTurn(messages, options, credential);
       return;
     }
-    const { url, headers, body } = geminiRequest(messages, options, credential, "streamGenerateContent");
-    const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+    const response = await geminiFetchFailSafe(strip => geminiRequest(messages, options, credential, "streamGenerateContent", strip), options.signal);
     if (!response.ok) throw await providerHttpError("Gemini", response, "(stream)");
     if (!response.body) return;
     let lastUsage: GeminiChunk["usageMetadata"];
     let yieldedAny = false;
     let lastEmptyReason: string | undefined;
     const fnCalls: { tool: string; arguments: Record<string, unknown> }[] = [];
+    const seenSigs = new Set<string>();
     for await (const data of readSse(response.body)) {
       let chunk: GeminiChunk;
       try {
@@ -288,6 +343,7 @@ export const geminiAdapter: ProviderAdapter = {
       }
       const thought = thoughtOf(chunk);
       if (thought) options.onReasoning?.(thought);
+      captureGeminiSignatures(chunk, options, seenSigs);
       const delta = textOf(chunk);
       if (delta) {
         yieldedAny = true;

package/src/ai/providers/openai-compatible-catalog.ts

@@ -23,6 +23,12 @@ export interface OpenAICompatProviderDef {
   readonly apiKeyEnv: string;
   /** Default model id (provider-prefixed) used by `--provider <name>`. */
   readonly defaultModel: string;
+  /** Extra well-known model ids (BARE, not provider-prefixed) for the OFFLINE
+   *  pick-list fallback shown by `/agents <role> provider <name>` and `--provider`.
+   *  Live `/models` discovery supersedes this once the provider is logged in, so
+   *  keep only stable/alias-style ids here (a stale id would 404 at inference).
+   *  `defaultModel` is always surfaced first regardless of this list. */
+  readonly knownModels?: readonly string[];
   /** Wire protocol: "openai" (/chat/completions, default) or "anthropic" (/v1/messages). */
   readonly protocol?: "openai" | "anthropic";
   /** True for subscription/plan products (coding-plan, portal, token-plan, code) rather than
@@ -35,12 +41,12 @@ export interface OpenAICompatProviderDef {
 }
 
 export const OPENAI_COMPAT_PROVIDERS: readonly OpenAICompatProviderDef[] = [
-  { name: "groq", label: "Groq", baseUrl: "https://api.groq.com/openai/v1", apiKeyEnv: "GROQ_API_KEY", defaultModel: "groq/llama-3.3-70b-versatile" },
-  { name: "deepseek", label: "DeepSeek", baseUrl: "https://api.deepseek.com/v1", apiKeyEnv: "DEEPSEEK_API_KEY", defaultModel: "deepseek/deepseek-chat" },
-  { name: "mistral", label: "Mistral", baseUrl: "https://api.mistral.ai/v1", apiKeyEnv: "MISTRAL_API_KEY", defaultModel: "mistral/mistral-large-latest" },
+  { name: "groq", label: "Groq", baseUrl: "https://api.groq.com/openai/v1", apiKeyEnv: "GROQ_API_KEY", defaultModel: "groq/llama-3.3-70b-versatile", knownModels: ["llama-3.3-70b-versatile", "llama-3.1-8b-instant", "openai/gpt-oss-120b", "openai/gpt-oss-20b"] },
+  { name: "deepseek", label: "DeepSeek", baseUrl: "https://api.deepseek.com/v1", apiKeyEnv: "DEEPSEEK_API_KEY", defaultModel: "deepseek/deepseek-chat", knownModels: ["deepseek-chat", "deepseek-reasoner"] },
+  { name: "mistral", label: "Mistral", baseUrl: "https://api.mistral.ai/v1", apiKeyEnv: "MISTRAL_API_KEY", defaultModel: "mistral/mistral-large-latest", knownModels: ["mistral-large-latest", "mistral-small-latest", "codestral-latest", "ministral-8b-latest"] },
   { name: "openrouter", label: "OpenRouter", baseUrl: "https://openrouter.ai/api/v1", apiKeyEnv: "OPENROUTER_API_KEY", defaultModel: "openrouter/openai/gpt-4o-mini", thinkingFormat: "openrouter" },
   { name: "together", label: "Together", baseUrl: "https://api.together.xyz/v1", apiKeyEnv: "TOGETHER_API_KEY", defaultModel: "together/meta-llama/Llama-3.3-70B-Instruct-Turbo" },
-  { name: "cerebras", label: "Cerebras", baseUrl: "https://api.cerebras.ai/v1", apiKeyEnv: "CEREBRAS_API_KEY", defaultModel: "cerebras/llama-3.3-70b" },
+  { name: "cerebras", label: "Cerebras", baseUrl: "https://api.cerebras.ai/v1", apiKeyEnv: "CEREBRAS_API_KEY", defaultModel: "cerebras/llama-3.3-70b", knownModels: ["llama-3.3-70b", "llama3.1-8b", "qwen-3-235b-a22b-instruct-2507"] },
   { name: "fireworks", label: "Fireworks", baseUrl: "https://api.fireworks.ai/inference/v1", apiKeyEnv: "FIREWORKS_API_KEY", defaultModel: "fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct" },
   { name: "nvidia", label: "NVIDIA", baseUrl: "https://integrate.api.nvidia.com/v1", apiKeyEnv: "NVIDIA_API_KEY", defaultModel: "nvidia/meta/llama-3.3-70b-instruct" },
   // Additional gjc-parity OpenAI-compatible clouds (authoritative base URLs + env vars).

package/src/ai/providers/openai-responses.ts

@@ -13,7 +13,7 @@
 import type { Credential } from "../../auth";
 import type { CallOptions, Message } from "../types";
 import { readSse } from "../sse";
-import { providerHttpError } from "./errors";
+import { providerHttpError, fetchWithArtifactFailSafe } from "./errors";
 import { serializeAccumulatedToolCalls } from "../../agent/tool-schemas";
 
 export const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
@@ -35,28 +35,64 @@ export function extractChatgptAccountId(token: string): string | undefined {
   }
 }
 
+
+type ResponsesInputItem = Record<string, unknown>;
+
+/** True when an assistant turn can replay stateless reasoning: it has structured toolUse AND
+ *  a same-model OpenAI reasoning item (id + encrypted_content) captured this session. */
+export function responsesNativizable(m: Message, modelKey: string): boolean {
+  return !!m.toolUse?.length
+    && !!m.reasoningArtifacts?.some(a => a.provider === "openai" && a.model === modelKey && !!a.itemId && !!a.encrypted);
+}
+
+/** Build the Responses `input` array, reconstructing native reasoning + function_call +
+ *  function_call_output items for same-model OpenAI turns (stateless reasoning replay).
+ *  stripArtifacts (fail-safe) or a non-matching model ⇒ the plain output_text/input_text shape. */
+export function buildResponsesInput(messages: Message[], modelKey: string, stripArtifacts = false): ResponsesInputItem[] {
+  const nonSystem = messages.filter(m => m.role !== "system");
+  const items: ResponsesInputItem[] = [];
+  const plain = (m: Message): ResponsesInputItem => ({
+    role: m.role,
+    content: [
+      { type: m.role === "assistant" ? "output_text" : "input_text", text: m.content },
+      ...(m.role !== "assistant" && m.images?.length
+        ? m.images.map(img => ({ type: "input_image", image_url: `data:${img.mediaType};base64,${img.data}` }))
+        : []),
+    ],
+  });
+  nonSystem.forEach((m, i) => {
+    if (!stripArtifacts && m.role === "assistant" && responsesNativizable(m, modelKey)) {
+      for (const a of m.reasoningArtifacts!) {
+        if (a.provider === "openai" && a.model === modelKey && a.itemId && a.encrypted) {
+          items.push({ type: "reasoning", id: a.itemId, encrypted_content: a.encrypted, summary: [] });
+        }
+      }
+      for (const tu of m.toolUse!) {
+        items.push({ type: "function_call", call_id: tu.id, name: tu.tool, arguments: JSON.stringify(tu.arguments) });
+      }
+      return;
+    }
+    if (!stripArtifacts && m.role === "user" && m.toolResults?.length && i > 0
+        && nonSystem[i - 1].role === "assistant" && responsesNativizable(nonSystem[i - 1], modelKey)) {
+      for (const tr of m.toolResults) items.push({ type: "function_call_output", call_id: tr.id, output: tr.output });
+      if (m.toolResultExtra) items.push({ role: "user", content: [{ type: "input_text", text: m.toolResultExtra }] });
+      return;
+    }
+    items.push(plain(m));
+  });
+  return items;
+}
 /** Build the Codex Responses request (url + headers + body) for an OAuth credential. */
 export function codexResponsesRequest(
   messages: Message[],
   options: CallOptions,
   credential: Credential,
+  stripArtifacts = false,
 ): { url: string; headers: Record<string, string>; body: string } {
   const model = options.model.startsWith("openai/") ? options.model.slice(7) : options.model;
   const token = credential.kind === "none" ? "" : credential.token;
   const systemPrompt = options.systemPrompt ?? messages.find(m => m.role === "system")?.content;
-  const input = messages
-    .filter(m => m.role !== "system")
-    .map(m => ({
-      role: m.role,
-      content: [
-        { type: m.role === "assistant" ? "output_text" : "input_text", text: m.content },
-        // Clipboard-pasted images ride along as input_image data URLs (user turns only —
-        // assistant history is always text in jeo).
-        ...(m.role !== "assistant" && m.images?.length
-          ? m.images.map(img => ({ type: "input_image", image_url: `data:${img.mediaType};base64,${img.data}` }))
-          : []),
-      ],
-    }));
+  const input = buildResponsesInput(messages, options.model, stripArtifacts);
   const payload: Record<string, unknown> = {
     model,
     instructions: systemPrompt ?? "You are a helpful coding assistant.",
@@ -81,6 +117,9 @@ export function codexResponsesRequest(
   // Both speak the same Responses schema (the body above), so only url+headers differ.
   if (credential.kind === "api_key") {
     const base = (options.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    // Stateless reasoning replay (public Responses API): ask for encrypted reasoning content
+    // so it can be captured and threaded back into a later `input` (store stays false).
+    payload.include = ["reasoning.encrypted_content"];
     return {
       url: `${base}/responses`,
       headers: { "content-type": "application/json", authorization: `Bearer ${token}`, accept: "text/event-stream" },
@@ -113,6 +152,8 @@ export interface ResponsesEvent {
   toolCallName?: string;
   toolCallArgsDelta?: string;
   toolCallIndex?: number;
+  /** A completed reasoning item carrying its id + encrypted_content (stateless replay capture). */
+  reasoningItem?: { id: string; encrypted: string };
 }
 
 /** Parse one Responses SSE `data:` payload into a delta / usage / error. */
@@ -120,7 +161,7 @@ export function parseResponsesEvent(data: string): ResponsesEvent {
   let o: {
     type?: string;
     delta?: unknown;
-    item?: { type?: string; name?: string };
+    item?: { type?: string; name?: string; id?: string; encrypted_content?: string };
     output_index?: number;
     response?: {
       usage?: { input_tokens?: number; output_tokens?: number };
@@ -137,6 +178,11 @@ export function parseResponsesEvent(data: string): ResponsesEvent {
   if (o.type === "response.output_item.added" && o.item?.type === "function_call") {
     return { toolCallName: o.item.name, toolCallIndex: o.output_index };
   }
+  // A completed reasoning item carries the encrypted_content we replay later (needs the
+  // request's `include: ["reasoning.encrypted_content"]`). Captured on output_item.done.
+  if (o.type === "response.output_item.done" && o.item?.type === "reasoning" && o.item.id && o.item.encrypted_content) {
+    return { reasoningItem: { id: o.item.id, encrypted: o.item.encrypted_content } };
+  }
   if (o.type === "response.function_call_arguments.delta" && typeof o.delta === "string") {
     return { toolCallArgsDelta: o.delta, toolCallIndex: o.output_index };
   }
@@ -185,10 +231,20 @@ function emptyCompletionError(reason: string | undefined): Error {
   return new Error(`OpenAI Codex returned no content${reason ? ` (${reason})` : ""}${hint}.`);
 }
 
+/** Fetch the Responses endpoint with a reasoning-artifact fail-safe (see fetchWithArtifactFailSafe). */
+function fetchResponses(messages: Message[], options: CallOptions, credential: Credential): Promise<Response> {
+  return fetchWithArtifactFailSafe(
+    strip => {
+      const { url, headers, body } = codexResponsesRequest(messages, options, credential, strip);
+      return fetch(url, { method: "POST", headers, body, signal: options.signal });
+    },
+    (status, body) => status === 400 && /reasoning|encrypted_content/i.test(body),
+  );
+}
+
 /** Non-streaming call over the Codex backend (collects the streamed output). */
 export async function codexResponsesCall(messages: Message[], options: CallOptions, credential: Credential): Promise<string> {
-  const { url, headers, body } = codexResponsesRequest(messages, options, credential);
-  const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+  const response = await fetchResponses(messages, options, credential);
   if (!response.ok) throw await providerHttpError("OpenAI", response);
   if (!response.body) return "";
   let out = "";
@@ -198,6 +254,7 @@ export async function codexResponsesCall(messages: Message[], options: CallOptio
     const ev = parseResponsesEvent(data);
     if (ev.delta) out += ev.delta;
     if (ev.reasoningDelta) options.onReasoning?.(ev.reasoningDelta);
+    if (ev.reasoningItem) options.onReasoningArtifact?.({ provider: "openai", model: options.model, itemId: ev.reasoningItem.id, encrypted: ev.reasoningItem.encrypted });
     accumulateResponsesToolCall(toolAcc, ev);
     if (ev.usage) options.onUsage?.(ev.usage);
     if (ev.incompleteReason) incompleteReason = ev.incompleteReason;
@@ -216,8 +273,7 @@ export async function* codexResponsesStream(
   options: CallOptions,
   credential: Credential,
 ): AsyncGenerator<string> {
-  const { url, headers, body } = codexResponsesRequest(messages, options, credential);
-  const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
+  const response = await fetchResponses(messages, options, credential);
   if (!response.ok) throw await providerHttpError("OpenAI", response, "(stream)");
   if (!response.body) return;
   let yieldedAny = false;
@@ -226,6 +282,7 @@ export async function* codexResponsesStream(
   for await (const data of readSse(response.body)) {
     const ev = parseResponsesEvent(data);
     if (ev.reasoningDelta) options.onReasoning?.(ev.reasoningDelta);
+    if (ev.reasoningItem) options.onReasoningArtifact?.({ provider: "openai", model: options.model, itemId: ev.reasoningItem.id, encrypted: ev.reasoningItem.encrypted });
     if (ev.delta) {
       yieldedAny = true;
       yield ev.delta;

package/src/ai/types.ts

@@ -19,9 +19,58 @@ export interface Message {
   images?: ImageAttachment[];
   /** Persisted reasoning/thinking text for an assistant turn (the thought before the
    *  answer). Survives /resume + export so the durable record shows "think → answer".
-   *  Display-only: NOT replayed to providers (anthropic/gemini thinking replay needs
-   *  the original signed block, which the streaming path does not capture). */
+   *  Display channel; the REPLAY channel is `reasoningArtifacts`. */
   reasoning?: string;
+  /** Provider-native, opaque reasoning artifacts captured during streaming (Anthropic
+   *  thinking signature, Gemini thoughtSignature, OpenAI Responses reasoning items).
+   *  Replayed to the SAME provider+model to preserve multi-step reasoning continuity;
+   *  dropped on cross-model replay. Display-agnostic, not written to markdown export. */
+  reasoningArtifacts?: ReasoningArtifact[];
+  /** Structured native tool calls this assistant turn made (with stable ids). `content`
+   *  keeps the canonical JSON envelope for display/compaction/fallback adapters; capable
+   *  adapters replay these as native tool_use / functionCall / function_call blocks. */
+  toolUse?: ToolUseRecord[];
+  /** Structured native tool results for a tool-feedback user turn (ids match the prior
+   *  assistant's `toolUse`). Capable adapters replay these as native tool_result /
+   *  functionResponse / function_call_output blocks. */
+  toolResults?: ToolResultRecord[];
+  /** Non-tool trailing text on a tool-feedback user turn (e.g. post-turn hook
+   *  diagnostics) — replayed as a trailing text block after the native tool results. */
+  toolResultExtra?: string;
+}
+
+/** A provider-native opaque reasoning artifact. Only replayed when `provider` AND
+ *  `model` match the active call (the adapter stamps the exact wire model id). */
+export interface ReasoningArtifact {
+  provider: ProviderName;
+  model: string;
+  /** Thought text (display is covered by Message.reasoning; kept here for fidelity). */
+  text?: string;
+  /** Anthropic: thinking block signature. */
+  signature?: string;
+  /** Anthropic: redacted_thinking opaque data. */
+  redacted?: string;
+  /** Gemini: per-part thoughtSignature (binds to the matching functionCall part). */
+  thoughtSignature?: string;
+  /** OpenAI Responses: reasoning item id. */
+  itemId?: string;
+  /** OpenAI Responses: reasoning item encrypted_content. */
+  encrypted?: string;
+}
+
+/** A structured native tool call (assistant turn). `id` is a stable synthetic id the
+ *  engine assigns so tool_use ↔ tool_result correlation survives replay. */
+export interface ToolUseRecord {
+  id: string;
+  tool: string;
+  arguments: Record<string, unknown>;
+}
+
+/** A structured native tool result (user turn). `id` matches a prior `ToolUseRecord`. */
+export interface ToolResultRecord {
+  id: string;
+  output: string;
+  isError: boolean;
 }
 
 export interface Usage {
@@ -67,6 +116,10 @@ export interface CallOptions {
    *  answer text). Surfaced as a transient dimmed view; absent for models that emit no
    *  thought text. */
   onReasoning?: (delta: string) => void;
+  /** Sink for provider-native reasoning ARTIFACTS captured during streaming (signature /
+   *  thoughtSignature / reasoning item id+encrypted). Separate from `onReasoning` (display
+   *  text) because these arrive on different SSE events and are opaque replay data. */
+  onReasoningArtifact?: (artifact: ReasoningArtifact) => void;
   /** NATIVE tool-calling: function declarations the model may call. Present only on the
    *  main agent step (never the prose wrap-up). Adapters with `supportsNativeTools` send
    *  these on the wire and re-serialize the structured tool call back into the engine's