@bitkyc08/opencodex 2.52.0-preview.20260911 → 2.52.0-preview.20260912

package/src/adapters/devin.ts

@@ -0,0 +1,326 @@
+/**
+ * Devin / Cognition / Windsurf adapter.
+ *
+ * Uses the unofficial cloud-direct Connect-RPC client (GetChatMessage).
+ * OpenCodex injects the OAuth API key onto provider.apiKey
+ * before runTurn. This adapter maps OcxContext <-> ChatHistoryItem and
+ * streams CloudChatEvent into AdapterEvent.
+ */
+import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTool, OcxToolCall, OcxToolResultMessage, OcxUsage } from "../types";
+import type { IncomingMeta, ProviderAdapter } from "./base";
+import { streamChatEvents, allocateCascadeId, CloudChatError, type ChatHistoryItem, type ToolDef } from "./devin/cloud-direct";
+import { getCachedCatalog } from "./devin/cloud-direct/catalog";
+import { DEVIN_DEFAULT_API_SERVER, resolveDevinApiServer } from "../oauth/devin";
+
+export const DEVIN_API_SERVER = DEVIN_DEFAULT_API_SERVER;
+
+const EFFORT_SUFFIXES = new Set(["low", "medium", "high", "xhigh", "max", "none", "1m", "max-1m", "none-1m", "fast"]);
+
+/**
+ * Cognition's catalog spells model ids with hyphens (`swe-1-7`), but the same
+ * models appear elsewhere - other proxies, hand-written config - with the dotted
+ * version number (`swe-1.7`). Left alone, a dotted id misses every catalog
+ * lookup and then gets an effort suffix appended to a name the server does not
+ * know, which Cognition answers with an opaque permission_denied.
+ */
+export function normalizeDevinModelId(modelId: string): string {
+  return modelId.replace(/\./g, "-");
+}
+
+function hasEffortSuffix(modelId: string): boolean {
+  const parts = modelId.split("-");
+  return parts.length > 1 && EFFORT_SUFFIXES.has(parts[parts.length - 1]!);
+}
+
+/**
+ * Resolve the wire model UID using the live catalog as the source of truth.
+ * Cognition's catalog lists most models with an effort suffix
+ * (e.g. `gpt-5-6-sol-high`); the base id alone is not accepted for those.
+ *
+ * If the catalog is available: use the exact UID when it exists, otherwise
+ * append the reasoning effort (or `medium` default) and pick a variant the
+ * account actually has.
+ *
+ * If the catalog is unavailable (degraded mode): append the effort suffix
+ * for any base id that doesn't already carry one, mirroring the catalog shape.
+ */
+async function resolveWireModelUid(
+  rawModelId: string,
+  apiKey: string,
+  host: string,
+  reasoningEffort?: string,
+): Promise<string> {
+  const modelId = normalizeDevinModelId(rawModelId);
+  if (hasEffortSuffix(modelId)) return modelId;
+  const catalog = await getCachedCatalog(apiKey, host);
+  if (catalog) {
+    if (catalog.byUid.has(modelId)) return modelId;
+    const effort = reasoningEffort && EFFORT_SUFFIXES.has(reasoningEffort) ? reasoningEffort : "medium";
+    const suffixed = `${modelId}-${effort}`;
+    if (catalog.byUid.has(suffixed)) return suffixed;
+    // Fall back to any enabled variant of this base model.
+    for (const uid of catalog.byUid.keys()) {
+      if (uid.startsWith(modelId + "-") && !catalog.byUid.get(uid)?.disabled) return uid;
+    }
+  }
+  // Degraded mode: append the default effort suffix.
+  const effort = reasoningEffort && EFFORT_SUFFIXES.has(reasoningEffort) ? reasoningEffort : "medium";
+  return `${modelId}-${effort}`;
+}
+
+export class DevinMissingCredentialError extends Error {
+  constructor() {
+    super("Devin live transport requires a Devin API key. Run ocx login devin to sign in with your Cognition/Devin account.");
+    this.name = "DevinMissingCredentialError";
+  }
+}
+
+export function resolveDevinToken(provider: OcxProviderConfig, headers?: Headers): string {
+  const providerKey = provider.apiKey?.trim();
+  if (providerKey) return providerKey;
+  const forwarded = headers?.get("authorization") ?? headers?.get("Authorization");
+  if (forwarded?.toLowerCase().startsWith("bearer ")) return forwarded.slice("bearer ".length).trim();
+  const envToken = process.env.OPENCODEX_DEVIN_TEST_TOKEN?.trim();
+  if (envToken) return envToken;
+  throw new DevinMissingCredentialError();
+}
+
+function textFromParts(content: string | OcxContentPart[] | undefined): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => (part.type === "text" ? part.text : "")).filter(Boolean).join("\n");
+}
+
+function toolResultText(message: OcxToolResultMessage): string {
+  const body = textFromParts(message.content);
+  return message.isError ? ("ERROR: " + body) : body;
+}
+
+function assistantToolCalls(message: OcxAssistantMessage): Array<{ id: string; name: string; arguments: string }> {
+  return message.content
+    .filter((part): part is OcxToolCall => part.type === "toolCall")
+    .map((part) => ({
+      id: part.id,
+      name: part.name,
+      arguments: JSON.stringify(part.arguments ?? {}),
+    }));
+}
+
+function assistantText(message: OcxAssistantMessage): string {
+  return message.content
+    // Thinking stays out of the replayed content. Cognition has no reasoning
+    // replay field, and folding chain-of-thought into assistant text sends it
+    // back as visible prior output - which the model then treats as something
+    // it said to the user.
+    .map((part) => (part.type === "text" ? part.text : ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function mapOcxMessagesToDevin(parsed: OcxParsedRequest): ChatHistoryItem[] {
+  const items: ChatHistoryItem[] = [];
+  const system = parsed.context.systemPrompt?.filter((line) => line.trim().length > 0).join("\n");
+  if (system) items.push({ role: "system", content: system });
+
+  for (const message of parsed.context.messages) {
+    const mapped = mapOneMessage(message);
+    if (mapped) items.push(mapped);
+  }
+  return items;
+}
+
+function mapOneMessage(message: OcxMessage): ChatHistoryItem | undefined {
+  if (message.role === "user" || message.role === "developer") {
+    const text = textFromParts(message.content).trim();
+    if (!text) return undefined;
+    return { role: message.role === "developer" ? "system" : "user", content: text };
+  }
+  if (message.role === "assistant") {
+    const toolCalls = assistantToolCalls(message);
+    const text = assistantText(message);
+    if (!text && toolCalls.length === 0) return undefined;
+    return {
+      role: "assistant",
+      content: text || "",
+      ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+    };
+  }
+  if (message.role === "toolResult") {
+    return {
+      role: "tool",
+      content: toolResultText(message),
+      tool_call_id: message.toolCallId,
+    };
+  }
+  return undefined;
+}
+
+export function mapOcxToolsToDevin(tools: OcxTool[] | undefined): ToolDef[] | undefined {
+  if (!tools || tools.length === 0) return undefined;
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description ?? "",
+    parameters: tool.parameters ?? { type: "object", properties: {} },
+  }));
+}
+
+export function createDevinAdapter(
+  provider: OcxProviderConfig,
+  context: { providerId?: string } = {},
+): ProviderAdapter {
+  // Which credential slot holds this row's tenant. Defaults to `devin` so every
+  // existing caller — including the tests that construct this adapter directly —
+  // behaves exactly as before.
+  const credentialProviderId = context.providerId ?? "devin";
+  const cascadeIds = new Map<string, string>();
+  const CASCADE_ID_MAX = 256;
+
+  return {
+    name: "devin",
+
+    buildRequest() {
+      return {
+        url: provider.baseUrl || DEVIN_API_SERVER,
+        method: "POST",
+        headers: {},
+        body: "",
+      };
+    },
+
+    async *parseStream(): AsyncGenerator<AdapterEvent> {
+      yield {
+        type: "error",
+        message: "Devin adapter uses runTurn; the fetch/parseStream path is disabled.",
+      };
+    },
+
+    async runTurn(parsed: OcxParsedRequest, incoming: IncomingMeta, emit: (event: AdapterEvent) => void) {
+      if (incoming.abortSignal?.aborted) {
+        emit({ type: "error", message: "Devin turn was aborted before start." });
+        return;
+      }
+      let apiKey: string;
+      try {
+        apiKey = resolveDevinToken(provider, incoming.headers);
+      } catch (error) {
+        emit({ type: "error", message: error instanceof Error ? error.message : String(error) });
+        return;
+      }
+
+      const threadKey = parsed._clientThreadId || parsed.previousResponseId || "default";
+      let cascadeId = cascadeIds.get(threadKey);
+      if (!cascadeId) {
+        // Evict oldest entries to bound memory in long-running proxy processes.
+        if (cascadeIds.size >= CASCADE_ID_MAX) {
+          const firstKey = cascadeIds.keys().next().value;
+          if (firstKey) cascadeIds.delete(firstKey);
+        }
+        cascadeId = allocateCascadeId();
+        cascadeIds.set(threadKey, cascadeId);
+      }
+
+      const rawModelId = parsed.modelId.includes("/") ? parsed.modelId.slice(parsed.modelId.lastIndexOf("/") + 1) : parsed.modelId;
+      // The signed-in account's tenant decides the host, not the static registry
+      // entry: an EU or FedStart account that used provider.baseUrl would send
+      // every RPC to the US server it is not provisioned on.
+      const host = resolveDevinApiServer(provider.baseUrl, credentialProviderId);
+      const modelUid = await resolveWireModelUid(rawModelId, apiKey, host, parsed.options.reasoning);
+      let openToolId: string | undefined;
+      let usage: OcxUsage | undefined;
+      let stopReason: string | undefined;
+
+      const closeOpenTool = () => {
+        if (!openToolId) return;
+        emit({ type: "tool_call_end" });
+        openToolId = undefined;
+      };
+
+      try {
+        for await (const event of streamChatEvents({
+          apiKey,
+          apiServerUrl: host,
+          modelUid,
+          messages: mapOcxMessagesToDevin(parsed),
+          tools: mapOcxToolsToDevin(parsed.context.tools),
+          cascadeId,
+          // Without these the request falls back to the encoder's defaults
+          // (8192 output, a 128k context window, temperature 0.7), so a client
+          // that asked for a 4k cap never got one.
+          completionOpts: {
+            ...(typeof parsed.options.maxOutputTokens === "number" ? { maxOutputTokens: parsed.options.maxOutputTokens } : {}),
+            ...(typeof parsed.options.temperature === "number" ? { temperature: parsed.options.temperature } : {}),
+            ...(typeof parsed.options.topP === "number" ? { topP: parsed.options.topP } : {}),
+          },
+          signal: incoming.abortSignal,
+        })) {
+          if (incoming.abortSignal?.aborted) {
+            // Emitting nothing here left the bridge to synthesize adapter_eof.
+            // Say what happened instead, the way the other runTurn-only adapter
+            // does, and carry any usage already seen.
+            closeOpenTool();
+            emit({ type: "error", message: "Devin turn was aborted.", ...(usage ? { usage } : {}) });
+            return;
+          }
+          if (event.kind === "text") {
+            closeOpenTool();
+            if (event.text) emit({ type: "text_delta", text: event.text });
+            continue;
+          }
+          if (event.kind === "reasoning") {
+            if (event.text) emit({ type: "thinking_delta", thinking: event.text });
+            continue;
+          }
+          if (event.kind === "tool_call_start") {
+            closeOpenTool();
+            openToolId = event.id;
+            emit({ type: "tool_call_start", id: event.id, name: event.name });
+            continue;
+          }
+          if (event.kind === "tool_call_args") {
+            if (event.argsDelta) emit({ type: "tool_call_delta", arguments: event.argsDelta });
+            continue;
+          }
+          if (event.kind === "finish") {
+            closeOpenTool();
+            // A natural completion carries no stopReason: the bridge reads any
+            // truthy value as "this turn did not reach a final answer", so
+            // reporting "stop" costs every clean Devin turn its final_answer
+            // phase.
+            stopReason = event.reason === "length" ? "max_tokens" : event.reason === "stop" ? undefined : event.reason;
+            continue;
+          }
+          if (event.kind === "usage") {
+            const total = event.totalTokens ?? ((event.promptTokens ?? 0) + (event.completionTokens ?? 0));
+            usage = {
+              inputTokens: event.promptTokens ?? 0,
+              outputTokens: event.completionTokens ?? 0,
+              ...(total > 0 ? { totalTokens: total } : {}),
+              ...(event.cachedInputTokens !== undefined ? { cachedInputTokens: event.cachedInputTokens } : {}),
+              ...(event.cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens: event.cacheCreationInputTokens } : {}),
+              ...(event.reasoningTokens !== undefined ? { reasoningOutputTokens: event.reasoningTokens } : {}),
+            };
+            continue;
+          }
+        }
+        closeOpenTool();
+        if (incoming.abortSignal?.aborted) {
+          emit({ type: "error", message: "Devin turn was aborted.", ...(usage ? { usage } : {}) });
+        } else {
+          emit({ type: "done", ...(usage ? { usage } : {}), ...(stopReason ? { stopReason } : {}) });
+        }
+      } catch (error) {
+        closeOpenTool();
+        if (incoming.abortSignal?.aborted) {
+          emit({ type: "error", message: "Devin turn was aborted.", ...(usage ? { usage } : {}) });
+          return;
+        }
+        const message = error instanceof CloudChatError
+          ? ("Devin cloud error" + (error.code ? " " + error.code : "") + ": " + error.message)
+          : error instanceof Error ? error.message : String(error);
+        // Usage that already arrived is still real; dropping it loses the
+        // accounting for a turn that did most of its work before failing.
+        emit({ type: "error", message, ...(usage ? { usage } : {}) });
+      }
+    },
+  };
+}

package/src/adapters/google.ts

@@ -109,7 +109,7 @@ function stripAntigravityRejectedClaudeSdkParagraph(systemText: string): string
  * Unknown ids return `undefined` deliberately. An earlier revision returned a 16,384 floor for
  * anything unmatched, which silently truncated aliases, gateway ids, and any model added after
  * this table was written — the operator asked for N tokens and got 16,384 with no signal. A cap
- * we cannot justify is worse than no cap: `structure/02_config-and-codex-home.md` is explicit
+ * we cannot justify is worse than no cap: `structure/config.md` is explicit
  * that an explicit request value wins, so an unrecognized model passes through untouched and the
  * upstream remains the authority on its own limit.
  *

package/src/adapters/openai-chat.ts

@@ -96,7 +96,14 @@ function openAIChatTransport(provider: OcxProviderConfig): {
   };
   if (hasCredential) headers.Authorization = `Bearer ${provider.apiKey}`;
   if (provider.headers) Object.assign(headers, provider.headers);
-  return { url: openaiChatCompletionsUrl(provider.baseUrl), headers, hasCredential };
+  // A configured relative path wins, mirroring how the Responses adapter honours
+  // `responsesPath`. An upstream can serve both wires under different prefixes, and a
+  // per-model wire override only swaps the adapter, so without this the opted-in Chat
+  // request would be sent to the Responses base with `/chat/completions` appended.
+  const url = provider.chatCompletionsPath === undefined
+    ? openaiChatCompletionsUrl(provider.baseUrl)
+    : `${provider.baseUrl.replace(/\/$/, "")}${provider.chatCompletionsPath}`;
+  return { url, headers, hasCredential };
 }
 
 /**
@@ -140,6 +147,16 @@ export function buildOpenAIChatPassthroughRequest(
   // ingress enforces exactly that. A prefix match here would strip response_format from
   // `<listed>:<tag>` siblings the operator never opted out, silently returning prose.
   if (provider.noStructuredOutputModels?.includes(modelId)) delete body.response_format;
+  // Narrower neighbour: the model takes `json_object` but rejects `json_schema`. Downgrade
+  // rather than drop, so a caller that asked for JSON still gets JSON. The type check also
+  // makes the kill switch above win without an else — after its `delete` there is no type
+  // left to match.
+  const passthroughFormat = body.response_format;
+  if (provider.noJsonSchemaModels?.includes(modelId)
+      && typeof passthroughFormat === "object" && passthroughFormat !== null
+      && (passthroughFormat as { type?: unknown }).type === "json_schema") {
+    body.response_format = { type: "json_object" };
+  }
 
   // Run the same complete Fast policy as the translated Chat path, including explicit
   // fastMode and foreign-tier handling. On inherited canonical Fast, the passthrough still
@@ -1582,15 +1599,19 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         if (textFormat?.type === "json_object") {
           body.response_format = { type: "json_object" };
         } else if (textFormat?.type === "json_schema") {
-          body.response_format = {
-            type: "json_schema",
-            json_schema: {
-              name: textFormat.name ?? "response",
-              ...(textFormat.description !== undefined ? { description: textFormat.description } : {}),
-              ...(textFormat.schema !== undefined ? { schema: textFormat.schema } : {}),
-              ...(textFormat.strict !== undefined ? { strict: textFormat.strict } : {}),
-            },
-          };
+          // Same downgrade as the passthrough path: the schema is dropped because the
+          // upstream rejects it, but the JSON-mode request itself survives.
+          body.response_format = provider.noJsonSchemaModels?.includes(parsed.modelId)
+            ? { type: "json_object" }
+            : {
+              type: "json_schema",
+              json_schema: {
+                name: textFormat.name ?? "response",
+                ...(textFormat.description !== undefined ? { description: textFormat.description } : {}),
+                ...(textFormat.schema !== undefined ? { schema: textFormat.schema } : {}),
+                ...(textFormat.strict !== undefined ? { strict: textFormat.strict } : {}),
+              },
+            };
         }
       }
 

package/src/adapters/openai-responses.ts

@@ -1,4 +1,5 @@
 import { normalizeRoutedAgentMessages } from "./routed-agent-messages";
+import { stripBracketedModelSuffix } from "./openai-chat";
 import { normalizeOpenCodeGoAdditionalTools } from "./opencode-go-additional-tools";
 import { isXaiResponsesDestination } from "../providers/xai-transport";
 import { createHash } from "node:crypto";
@@ -2541,7 +2542,21 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         actualServiceTier === null ? null : "service-tier",
         actualServiceTier,
       );
-      const body = JSON.stringify(finalBody);
+      // The Responses adapter is passthrough: it forwards `parsed._rawBody` rather than
+      // rebuilding the body from `parsed.modelId`, and the router writes the routed id into
+      // that raw body. So a provider whose upstream rejects bracketed ids has to be honoured
+      // here, on the serialized body, not on the parsed selector. One place covers both the
+      // HTTP and the WebSocket outbound, because the WS path transports this same request
+      // instead of rebuilding it.
+      const body = JSON.stringify(
+        provider.modelSuffixBracketStrip
+          && finalBody !== null
+          && typeof finalBody === "object"
+          && !Array.isArray(finalBody)
+          && typeof (finalBody as { model?: unknown }).model === "string"
+          ? { ...(finalBody as Record<string, unknown>), model: stripBracketedModelSuffix((finalBody as { model: string }).model) }
+          : finalBody,
+      );
       const releaseBodyObservation = translatorBudget.observeExternallyCapped(
         "passthrough_serialization",
         new TextEncoder().encode(body).byteLength,

package/src/adapters/registry.ts

@@ -6,6 +6,8 @@ import { createCodeBuddyAdapter } from "./codebuddy/adapter";
 import { createQoderAdapter } from "./qoder/adapter";
 import { createCommandCodeAdapter } from "./command-code";
 import { createCursorAdapter } from "./cursor";
+import { createDevinCliAdapter } from "./devin-cli/adapter";
+import { createDevinAdapter } from "./devin";
 import { createGoogleAdapter } from "./google";
 import { createKiroAdapter } from "./kiro";
 import { createMimoFreeAdapter } from "./mimo-free";
@@ -19,6 +21,16 @@ export type AdapterCacheRetention = "none" | "short" | "long";
 
 export interface AdapterFactoryContext {
   cacheRetention?: AdapterCacheRetention;
+  /**
+   * The configured provider row this adapter serves.
+   *
+   * Needed when one adapter backs two provider ids whose credentials differ:
+   * `devin` and `devin-cli` share a transport and a token format but sign in to
+   * different accounts and can sit on different Cognition tenants, and the tenant
+   * is recorded on the credential rather than in the registry. Optional, and
+   * every other adapter ignores it.
+   */
+  providerId?: string;
 }
 
 export type AdapterWire =
@@ -30,7 +42,9 @@ export type AdapterWire =
   | "openai-responses"
   | "google"
   | "kiro"
-  | "cursor";
+  | "cursor"
+  | "devin-cli"
+  | "devin";
 
 export type AdapterMutationContract =
   | "codex-owned"
@@ -112,6 +126,16 @@ export const ADAPTER_REGISTRY = {
     mutation: "codex-owned-with-gated-native-fallback",
     create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createCursorAdapter(provider),
   },
+  "devin-cli": {
+    wire: "devin-cli",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createDevinCliAdapter(provider),
+  },
+  devin: {
+    wire: "devin",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, context: AdapterFactoryContext) => createDevinAdapter(provider, context),
+  },
   "mimo-free": {
     contractParent: "openai-chat",
     create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createMimoFreeAdapter(provider),

package/src/bridge.ts

@@ -1293,7 +1293,10 @@ export function bridgeToResponsesSSE(
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
-              if (currentToolCall) closeCurrentToolCall();
+              if (currentToolCall) {
+                if (isTruncatedStopReason(event.stopReason)) failCurrentToolCall();
+                else closeCurrentToolCall();
+              }
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
               releasePendingWebSources();
               // Redacted-only turns (or hidden thinking without a trailing signature event) still
@@ -2055,7 +2058,10 @@ function buildResponseJSONWithBudget(
   // must one left open by a stream that stopped without any terminal at all. That case previously
   // fell through to "completed", handing back a function_call whose arguments were half-written
   // JSON, inside a turn also marked completed.
-  if (currentToolCallId) flushToolCall(errorEvent || incompleteEvent || !sawTerminal ? "incomplete" : "completed");
+  if (currentToolCallId) {
+    flushToolCall(errorEvent || incompleteEvent || !sawTerminal || isTruncatedStopReason(rawStopReason)
+      ? "incomplete" : "completed");
+  }
   if (batchKiroRedacted) {
     // pushOutput reserves the item itself and releases the retained raw blob it replaces.
     pushOutput({

package/src/claude/inbound-cache-stabilize.ts

@@ -0,0 +1,130 @@
+/**
+ * Claude Code appends growing `<total_tokens>…</total_tokens>` footers (and
+ * occasional TaskCreate nudges) into system text that becomes Responses
+ * `instructions`. That churn breaks Muse/Go prefix cache on the instructions
+ * prefix even when tools stay stable. Strip dynamics from instructions;
+ * surface the latest notice on `input` instead.
+ *
+ * Relocation is identified by harness shape: only a trailing, unfenced,
+ * canonical notice at the end of instructions is moved. An unmatched fence
+ * opener covers through EOF. No match → the original string is returned
+ * byte-for-byte. The matcher is content identity only; `translateAnthropicRequest`
+ * requires `claudeCode.stabilizePromptCache: true` before this helper runs. Claude Code
+ * writes `<total_tokens>N tokens left</total_tokens>`.
+ *
+ * TaskCreate nudge text has drifted across Claude Code builds; match the
+ * known exact paragraphs (legacy + 2.1.263 "tracking progress" form) as
+ * trailing alternatives so a mid-session nudge cannot pin older footers
+ * above it and flip `instructions` after a previously stable peel.
+ */
+
+const TOTAL_NOTICE_RE = /^<total_tokens>[0-9]+ tokens left<\/total_tokens>$/;
+
+/** Legacy Claude Code TaskCreate reminder (pre-"tracking progress"). */
+const TASKCREATE_NUDGE_LEGACY =
+  "The task tools haven't been used recently. If you're working on tasks that would benefit from tracking, consider using TaskCreate to add them. Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable.";
+
+/**
+ * Claude Code 2.1.263+ TaskCreate reminder observed on hitrate S/T4
+ * (FREEZE-DIFF + tip0847 pilots). Mentions TaskUpdate and stale-list cleanup.
+ */
+const TASKCREATE_NUDGE_CC_2_1_263 =
+  "The task tools haven't been used recently. If you're working on tasks that would benefit from tracking progress, consider using TaskCreate to add new tasks and TaskUpdate to update task status (set to in_progress when starting, completed when done). Also consider cleaning up the task list if it has become stale. Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable.";
+
+interface FenceRange {
+  start: number;
+  end: number;
+}
+
+const FENCE_OPEN_RE = /^( {0,3})(`{3,}|~{3,})/;
+const FENCE_CLOSE_RE = /^( {0,3})(`{3,}|~{3,})[ \t]*$/;
+
+/**
+ * Markdown fence ranges. An unmatched opener covers through EOF: unfinished
+ * fenced examples are code content, not a harness suffix. A closer must be a
+ * standalone fence line (no info string) of the same character and at least
+ * the opener's length.
+ */
+function fencedRanges(source: string): FenceRange[] {
+  const ranges: FenceRange[] = [];
+  let offset = 0;
+  let openAt: number | null = null;
+  let openFence = "";
+  while (offset <= source.length) {
+    const nl = source.indexOf("\n", offset);
+    const lineEnd = nl === -1 ? source.length : nl;
+    const line = source.slice(offset, lineEnd).replace(/\r$/, "");
+    if (openAt === null) {
+      const open = FENCE_OPEN_RE.exec(line);
+      if (open) {
+        openAt = offset;
+        openFence = open[2]!;
+      }
+    } else {
+      const close = FENCE_CLOSE_RE.exec(line);
+      if (
+        close
+        && close[2]![0] === openFence[0]
+        && close[2]!.length >= openFence.length
+      ) {
+        ranges.push({ start: openAt, end: lineEnd });
+        openAt = null;
+        openFence = "";
+      }
+    }
+    if (nl === -1) break;
+    offset = nl + 1;
+  }
+  if (openAt !== null) ranges.push({ start: openAt, end: source.length });
+  return ranges;
+}
+
+/** A backwards cursor consumes each line and fence range at most once. */
+export function stabilizeClaudeInstructionsForPromptCache(
+  instructions: string,
+): { instructions: string; dynamicNotice: string | null } {
+  const ranges = fencedRanges(instructions);
+  let fenceIndex = ranges.length - 1;
+  let end = instructions.length;
+  let latestTotal: string | null = null;
+  let latestNudge: string | null = null;
+  let peeled = false;
+
+  for (;;) {
+    // This is speculative: a failed candidate must not trim the retained prefix.
+    let lineEnd = end;
+    while (lineEnd > 0 && instructions[lineEnd - 1] === "\n") {
+      lineEnd--;
+      if (lineEnd > 0 && instructions[lineEnd - 1] === "\r") lineEnd--;
+    }
+    if (lineEnd === 0) break;
+    const lineStart = instructions.lastIndexOf("\n", lineEnd - 1) + 1;
+    let contentStart = lineStart;
+    let contentEnd = lineEnd;
+    while (contentStart < contentEnd && (instructions[contentStart] === " " || instructions[contentStart] === "\t")) contentStart++;
+    while (contentEnd > contentStart && (instructions[contentEnd - 1] === " " || instructions[contentEnd - 1] === "\t")) contentEnd--;
+    const notice = instructions.slice(contentStart, contentEnd);
+    const total = TOTAL_NOTICE_RE.test(notice);
+    const nudge = notice === TASKCREATE_NUDGE_LEGACY || notice === TASKCREATE_NUDGE_CC_2_1_263;
+    if (!total && !nudge) break;
+
+    while (fenceIndex >= 0 && ranges[fenceIndex]!.start > contentStart) fenceIndex--;
+    if (fenceIndex >= 0 && contentStart < ranges[fenceIndex]!.end) break;
+    if (total && latestTotal === null) latestTotal = notice;
+    if (nudge && latestNudge === null) latestNudge = notice;
+    peeled = true;
+
+    // Commit only the recognized notice and its immediately preceding LF/CRLF separators.
+    end = lineStart;
+    while (end > 0 && instructions[end - 1] === "\n") {
+      end--;
+      if (end > 0 && instructions[end - 1] === "\r") end--;
+    }
+  }
+
+  if (!peeled) return { instructions, dynamicNotice: null };
+  const noticeParts: string[] = [];
+  if (latestTotal) noticeParts.push(latestTotal);
+  if (latestNudge) noticeParts.push(latestNudge);
+  return { instructions: instructions.slice(0, end), dynamicNotice: noticeParts.join("\n\n") };
+}