dsh-plugin-subscriptions 0.5.0 → 0.5.2

package/lib/providers/grok.d.ts

@@ -101,13 +101,17 @@ export declare function fetchGrokCliCatalog(session: GrokSession, fetchFn?: Fetc
  * metadata (display name, context window, reasoning efforts). The api.x.ai
  * list stays authoritative for which models exist; the CLI catalog is
  * enrichment only, so its failure degrades to a plain list instead of taking
- * discovery down — models it does not cover simply expose no efforts.
+ * discovery down. When enrichment is missing, last-known capability metadata
+ * is carried forward so a transient CLI outage cannot strip efforts a
+ * session already selected.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param onWarn - warning sink for a failed CLI catalog fetch.
+ * @param previous - last-known catalog used to keep enrichment when the CLI
+ *   catalog is down or omits a model.
  * @returns discovered chat models in endpoint order.
  */
-export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void): Promise<DiscoveredModel[]>;
+export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void, previous?: readonly DiscoveredModel[]): Promise<DiscoveredModel[]>;
 /** Constructor dependencies for {@link GrokAdapter}. */
 export interface GrokAdapterOptions {
     models: readonly ModelEntry[];
@@ -131,6 +135,7 @@ export declare class GrokAdapter extends LlmAdapter {
     constructor(options: GrokAdapterOptions);
     /** Discovery fetcher: resolves the session through the refresh-aware path. */
     private fetchCatalog;
+    private listed;
     providerInfo(provider: string): LlmProviderInfo;
     private staticModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;

package/lib/providers/grok.js

@@ -7,7 +7,8 @@ import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmErr
 import { decodeJwtPayload } from '../auth/jwt.js';
 import { resolveImages } from '../translate/resolved.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, discoverOrRetryAuth, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
+import { proxiedFetch } from '../http.js';
 export const GROK_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828';
 export const GROK_DISCOVERY_URL = 'https://auth.x.ai/.well-known/openid-configuration';
 export const GROK_API_URL = 'https://api.x.ai/v1/responses';
@@ -40,7 +41,7 @@ let discoveryCache;
 export async function grokDiscovery() {
     if (discoveryCache !== undefined)
         return discoveryCache;
-    const response = await fetch(GROK_DISCOVERY_URL);
+    const response = await proxiedFetch(GROK_DISCOVERY_URL);
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok OIDC discovery');
     const document = await response.json();
@@ -147,7 +148,7 @@ function grokSession(tokens, tokenEndpoint, fallbackRefreshToken) {
  */
 export async function exchangeGrokCode(code, verifier, redirectUri, challenge) {
     const discovery = await grokDiscovery();
-    const response = await fetch(discovery.tokenEndpoint, {
+    const response = await proxiedFetch(discovery.tokenEndpoint, {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({
@@ -174,7 +175,7 @@ export async function exchangeGrokCode(code, verifier, redirectUri, challenge) {
  * @returns the fresh session to store.
  */
 export async function refreshGrok(session) {
-    const response = await fetch(session.tokenEndpoint, {
+    const response = await proxiedFetch(session.tokenEndpoint, {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({
@@ -223,7 +224,7 @@ function grokResetsAt(value) {
  * @param signal - caller cancellation from the RPC transport.
  * @returns the mapped usage snapshot.
  */
-export async function fetchGrokUsage(session, fetchFn = fetch, signal) {
+export async function fetchGrokUsage(session, fetchFn = proxiedFetch, signal) {
     const response = await fetchFn(GROK_BILLING_URL, {
         headers: {
             'authorization': `Bearer ${session.accessToken}`,
@@ -313,7 +314,7 @@ function grokCliReasoning(entry) {
  * @param fetchFn - fetch implementation (injectable for tests).
  * @returns model id → contributed metadata.
  */
-export async function fetchGrokCliCatalog(session, fetchFn = fetch) {
+export async function fetchGrokCliCatalog(session, fetchFn = proxiedFetch) {
     const response = await fetchFn(GROK_CLI_MODELS_URL, {
         headers: {
             'authorization': `Bearer ${session.accessToken}`,
@@ -355,18 +356,40 @@ export async function fetchGrokCliCatalog(session, fetchFn = fetch) {
 function isChatModel(id) {
     return !/imagine|image-|video|embed/i.test(id);
 }
+/**
+ * CLI-contributed fields carried forward from a previously discovered model.
+ * @param prior - the last-known entry for this id, if any.
+ * @returns enrichment to apply when the live CLI catalog cannot contribute.
+ */
+function grokPriorMeta(prior) {
+    if (prior === undefined)
+        return {};
+    return {
+        ...(prior.name.length > 0 ? { name: prior.name } : {}),
+        ...(prior.description === undefined ? {} : { description: prior.description }),
+        ...(prior.contextWindow === undefined ? {} : { contextWindow: prior.contextWindow }),
+        ...(prior.reasoning === undefined ? {} : { reasoning: prior.reasoning }),
+    };
+}
 /**
  * Fetch the live grok model list, enriched with the CLI catalog's per-model
  * metadata (display name, context window, reasoning efforts). The api.x.ai
  * list stays authoritative for which models exist; the CLI catalog is
  * enrichment only, so its failure degrades to a plain list instead of taking
- * discovery down — models it does not cover simply expose no efforts.
+ * discovery down. When enrichment is missing, last-known capability metadata
+ * is carried forward so a transient CLI outage cannot strip efforts a
+ * session already selected.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param onWarn - warning sink for a failed CLI catalog fetch.
+ * @param previous - last-known catalog used to keep enrichment when the CLI
+ *   catalog is down or omits a model.
  * @returns discovered chat models in endpoint order.
  */
-export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
+export async function fetchGrokModels(session, fetchFn = proxiedFetch, onWarn, previous) {
+    const previousById = previous === undefined || previous.length === 0
+        ? undefined
+        : new Map(previous.map(model => [model.id, model]));
     const [response, cliCatalog] = await Promise.all([
         fetchFn(GROK_MODELS_URL, {
             headers: {
@@ -376,7 +399,9 @@ export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
             },
         }),
         fetchGrokCliCatalog(session, fetchFn).catch((error) => {
-            onWarn?.(`grok CLI catalog fetch failed; reasoning efforts are unavailable (${errorChain(error)})`);
+            onWarn?.(previousById === undefined
+                ? `grok CLI catalog fetch failed; reasoning efforts are unavailable (${errorChain(error)})`
+                : `grok CLI catalog fetch failed; keeping last-known reasoning efforts (${errorChain(error)})`);
             return undefined;
         }),
     ]);
@@ -393,7 +418,12 @@ export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
         if (!isChatModel(entry.id))
             continue;
         seen.add(entry.id);
-        discovered.push({ id: entry.id, name: entry.id, ...cliCatalog?.get(entry.id) });
+        const cli = cliCatalog?.get(entry.id);
+        discovered.push({
+            id: entry.id,
+            name: entry.id,
+            ...(cli ?? grokPriorMeta(previousById?.get(entry.id))),
+        });
     }
     // An empty catalog from a 200 response is treated as a discovery failure so
     // the adapter falls back to the static catalog instead of vanishing from
@@ -413,7 +443,16 @@ export class GrokAdapter extends LlmAdapter {
     }
     /** Discovery fetcher: resolves the session through the refresh-aware path. */
     async fetchCatalog() {
-        return fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn);
+        return fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn, this.catalog.lastKnown());
+    }
+    listed(provider, discovered) {
+        return discovered.map(model => ({
+            provider,
+            id: model.id,
+            name: model.name,
+            ...model.description === undefined ? {} : { description: model.description },
+            inputModalities: grokModalities(model.id),
+        }));
     }
     providerInfo(provider) {
         return { id: provider, name: 'Grok (Subscription)' };
@@ -437,23 +476,13 @@ export class GrokAdapter extends LlmAdapter {
             // The fetcher runs only on a cache miss, and resolves the session
             // through the refresh-aware path so an expired access token renews here
             // instead of failing discovery into the static fallback.
-            const discovered = await this.catalog.get(() => this.fetchCatalog());
-            return discovered.map(model => ({
-                provider,
-                id: model.id,
-                name: model.name,
-                ...model.description === undefined ? {} : { description: model.description },
-                inputModalities: grokModalities(model.id),
-            }));
+            return this.listed(provider, await discoverOrRetryAuth(force => this.options.tokens.session(force), this.catalog, () => this.catalog.get(() => this.fetchCatalog())));
         }
         catch (error) {
             // A permanent refresh failure deletes the stored session: the provider
             // is logged out, so hide it instead of showing a stale static catalog.
-            if (error instanceof LlmError
-                && (error.code === 'MISSING_CREDENTIAL' || error.code === 'INVALID_CREDENTIAL'))
+            if (isMissingOrInvalidCredential(error))
                 return [];
-            if (error instanceof OAuthEndpointError && error.status === 401)
-                this.catalog.invalidate();
             this.options.onWarn?.(`grok model discovery failed; using the built-in catalog (${errorChain(error)})`);
             return this.staticModels(provider);
         }
@@ -534,7 +563,7 @@ export class GrokAdapter extends LlmAdapter {
             store: false,
             stream: true,
         };
-        return fetch(GROK_API_URL, {
+        return proxiedFetch(GROK_API_URL, {
             method: 'POST',
             headers: {
                 'authorization': `Bearer ${session.accessToken}`,

package/lib/tools/image-generate.js

@@ -18,6 +18,7 @@ import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { AttachmentId } from '@deepseek-ai/dsh-attachment';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { httpLlmError, TokenManager } from '../providers/common.js';
+import { proxiedFetch } from '../http.js';
 /** Endpoint the codex generation request is posted to. */
 export const IMAGE_GENERATE_URL = 'https://chatgpt.com/backend-api/codex/images/generations';
 /** The image model the codex subscription endpoint serves. */
@@ -241,7 +242,7 @@ export function createImageGenerateTool(options) {
             content: result.content.filter(block => block.type === 'text'),
         }),
         async execute(args, exec) {
-            const fetchFn = options.fetchFn ?? fetch;
+            const fetchFn = options.fetchFn ?? proxiedFetch;
             // Provider selection: the preferred provider (default gpt) when logged
             // in, the other one as the fallback. A configured-but-logged-out manager
             // still resolves through `session()` below so the standard log-in hint

package/lib/tools/video-generate.js

@@ -13,6 +13,7 @@ import { basename, join } from 'node:path';
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { httpLlmError, TokenManager } from '../providers/common.js';
+import { proxiedFetch } from '../http.js';
 /** Endpoint the generation request is posted to. */
 export const VIDEO_GENERATE_URL = 'https://api.x.ai/v1/videos/generations';
 /** The video model the grok subscription endpoint serves. */
@@ -197,7 +198,7 @@ export function createVideoGenerateTool(options) {
         async execute(args, exec) {
             const body = buildVideoGenerateBody(args);
             const session = await options.tokens.session();
-            const fetchFn = options.fetchFn ?? fetch;
+            const fetchFn = options.fetchFn ?? proxiedFetch;
             const headers = {
                 'authorization': `Bearer ${session.accessToken}`,
                 'accept': 'application/json',

package/lib/tools/x-search.js

@@ -6,6 +6,7 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { httpLlmError, TokenManager } from '../providers/common.js';
+import { proxiedFetch } from '../http.js';
 /** Endpoint the search request is posted to. */
 export const X_SEARCH_URL = 'https://api.x.ai/v1/responses';
 /** Grok model the search runs on (a catalog model of the grok provider). */
@@ -172,7 +173,7 @@ export function createXSearchTool(options) {
         async execute(args, exec) {
             const request = buildXSearchRequest(args);
             const session = await options.tokens.session();
-            const response = await (options.fetchFn ?? fetch)(X_SEARCH_URL, {
+            const response = await (options.fetchFn ?? proxiedFetch)(X_SEARCH_URL, {
                 method: 'POST',
                 headers: {
                     'authorization': `Bearer ${session.accessToken}`,

package/lib/translate/anthropic.d.ts

@@ -13,6 +13,25 @@ import type { TranslatableMessage } from './resolved.js';
  * system entry on every request.
  */
 export declare const CLAUDE_CODE_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude.";
+/** Tags wrapping a mid-conversation system message where it sits in the history. */
+export declare const SYSTEM_REMINDER_OPEN = "<system-reminder>";
+export declare const SYSTEM_REMINDER_CLOSE = "</system-reminder>";
+/**
+ * How far apart consecutive message breakpoints sit, in content blocks.
+ *
+ * A breakpoint looks back at most 20 blocks for an entry an earlier request
+ * wrote, so marks must stay closer than that: one agentic turn can append a
+ * dozen tool_use/tool_result blocks at once, and a single trailing mark would
+ * silently fall out of range and rebuild the whole prefix.
+ */
+export declare const CACHE_BLOCK_STRIDE = 15;
+/**
+ * Message breakpoints per request. Anthropic allows four in total and the
+ * last `system` block takes the fourth, so three are left for the history —
+ * enough to tolerate a turn appending roughly {@link CACHE_BLOCK_STRIDE} × 3
+ * blocks before a read is lost.
+ */
+export declare const MESSAGE_CACHE_BREAKPOINTS = 3;
 /** One Anthropic request message. */
 export interface AnthropicMessage {
     role: 'user' | 'assistant';
@@ -21,27 +40,49 @@ export interface AnthropicMessage {
 /**
  * Convert harness messages into Anthropic messages. Consecutive same-role
  * messages merge into one message with multiple content blocks; tool results
- * arrive as user messages with `tool_result` blocks; system-role messages are
- * handled by {@link toAnthropicSystem} and skipped here. Reasoning blocks are
- * not replayed (v1). Images must arrive pre-resolved
+ * arrive as user messages with `tool_result` blocks, which a merged user
+ * message keeps in one leading run ({@link leadWithToolResults}); system-role
+ * messages before the conversation starts are handled by
+ * {@link toAnthropicSystem} and skipped here, while a later one rides in
+ * place as a user-role `<system-reminder>` block.
+ * Reasoning blocks are not replayed (v1). Images must arrive pre-resolved
  * ({@link TranslatableMessage}); an unresolved ImageBlock is skipped because
  * its bytes are unreachable here.
  * @param messages - ordered conversation messages with resolved images.
  * @returns Anthropic messages in conversation order.
  */
 export declare function toAnthropicMessages(messages: readonly TranslatableMessage[]): AnthropicMessage[];
+/**
+ * Mark the conversation's cache breakpoints in place: the last content block,
+ * then one every {@link CACHE_BLOCK_STRIDE} blocks backwards, {@link
+ * MESSAGE_CACHE_BREAKPOINTS} in total.
+ *
+ * The history is append-only, so the block one request marks last is
+ * byte-identical in the next — that entry is what the next request reads.
+ * Marks are counted across the flattened block sequence, not per message,
+ * because the lookback window Anthropic walks counts blocks the same way.
+ * @param messages - assembled Anthropic messages, marked in place.
+ */
+export declare function markMessageCache(messages: readonly AnthropicMessage[]): void;
 /**
  * Build the Anthropic `system` array: the mandatory Claude Code identity
  * block, then the explicit system prompt, then any system-role messages.
  * @param system - explicit system prompt, when set.
- * @param messages - conversation messages; their system-role text is appended.
+ * @param messages - conversation messages; the system-role text preceding the
+ * conversation is appended, and a later one is left to {@link toAnthropicMessages}.
  * @returns the system content blocks.
  */
 export declare function toAnthropicSystem(system?: string, messages?: readonly TranslatableMessage[]): Record<string, unknown>[];
 /**
- * Map harness tool schemas to Anthropic tools.
+ * Map harness tool schemas to Anthropic tools, in name order.
+ *
+ * `tools` renders at position 0 of the cached prefix, so any reordering
+ * invalidates every cache entry behind it — `system` and the whole
+ * conversation included. Registration order belongs to the caller and plugin
+ * load order can differ between processes, so the wire order is fixed here
+ * instead. Anthropic selects a tool by name; the array order carries nothing.
  * @param tools - tool schemas from the request.
- * @returns Anthropic `tools` array entries.
+ * @returns Anthropic `tools` array entries, ordered by tool name.
  */
 export declare function toAnthropicTools(tools: readonly ToolSchema[]): Record<string, unknown>[];
 /** The subset of Anthropic SSE event shapes this translator reads. */

package/lib/translate/anthropic.js

@@ -12,6 +12,25 @@ import { parseSse } from './sse.js';
  * system entry on every request.
  */
 export const CLAUDE_CODE_IDENTITY = 'You are Claude Code, Anthropic\'s official CLI for Claude.';
+/** Tags wrapping a mid-conversation system message where it sits in the history. */
+export const SYSTEM_REMINDER_OPEN = '<system-reminder>';
+export const SYSTEM_REMINDER_CLOSE = '</system-reminder>';
+/**
+ * How far apart consecutive message breakpoints sit, in content blocks.
+ *
+ * A breakpoint looks back at most 20 blocks for an entry an earlier request
+ * wrote, so marks must stay closer than that: one agentic turn can append a
+ * dozen tool_use/tool_result blocks at once, and a single trailing mark would
+ * silently fall out of range and rebuild the whole prefix.
+ */
+export const CACHE_BLOCK_STRIDE = 15;
+/**
+ * Message breakpoints per request. Anthropic allows four in total and the
+ * last `system` block takes the fourth, so three are left for the history —
+ * enough to tolerate a turn appending roughly {@link CACHE_BLOCK_STRIDE} × 3
+ * blocks before a read is lost.
+ */
+export const MESSAGE_CACHE_BREAKPOINTS = 3;
 /** Flatten a tool result's content to plain text for `tool_result`. */
 function toolResultText(block) {
     return block.content.map(part => (part.type === 'text' ? part.text : '')).join('');
@@ -30,12 +49,55 @@ function parseToolInput(raw) {
         return {};
     }
 }
+/**
+ * Move a user message's `tool_result` blocks into one contiguous run at the
+ * front, preserving the relative order of both groups.
+ *
+ * Anthropic answers every `tool_use` against the blocks that *lead* the next
+ * message, so a block of any other kind before or between the results reads
+ * as a call left unanswered and the request is rejected. The harness merges
+ * everything queued for one user turn into a single message, and a parallel
+ * tool batch arrives as one result message per call, so any context spliced
+ * mid-batch lands between two results. Restoring the run here keeps that
+ * independent of delivery order. Order *among* the results does not matter.
+ * @param message - one assembled user message, reordered in place.
+ */
+function leadWithToolResults(message) {
+    const firstOther = message.content.findIndex(block => block.type !== 'tool_result');
+    if (firstOther === -1)
+        return;
+    if (!message.content.slice(firstOther).some(block => block.type === 'tool_result'))
+        return;
+    message.content = [
+        ...message.content.filter(block => block.type === 'tool_result'),
+        ...message.content.filter(block => block.type !== 'tool_result'),
+    ];
+}
+/**
+ * Index of the first non-system message; `messages.length` when every message
+ * is a system one.
+ *
+ * A system message before the conversation starts is the operator's opening
+ * instruction and belongs in the `system` slot. One that arrives later is
+ * mid-conversation context, and hoisting it into `system` would move bytes in
+ * front of the whole history — invalidating every cached turn behind it — so
+ * it stays where it is, as a reminder block in `messages`.
+ * @param messages - ordered conversation messages.
+ * @returns the boundary index separating the two.
+ */
+function conversationStart(messages) {
+    const index = messages.findIndex(message => message.role !== 'system');
+    return index === -1 ? messages.length : index;
+}
 /**
  * Convert harness messages into Anthropic messages. Consecutive same-role
  * messages merge into one message with multiple content blocks; tool results
- * arrive as user messages with `tool_result` blocks; system-role messages are
- * handled by {@link toAnthropicSystem} and skipped here. Reasoning blocks are
- * not replayed (v1). Images must arrive pre-resolved
+ * arrive as user messages with `tool_result` blocks, which a merged user
+ * message keeps in one leading run ({@link leadWithToolResults}); system-role
+ * messages before the conversation starts are handled by
+ * {@link toAnthropicSystem} and skipped here, while a later one rides in
+ * place as a user-role `<system-reminder>` block.
+ * Reasoning blocks are not replayed (v1). Images must arrive pre-resolved
  * ({@link TranslatableMessage}); an unresolved ImageBlock is skipped because
  * its bytes are unreachable here.
  * @param messages - ordered conversation messages with resolved images.
@@ -43,24 +105,41 @@ function parseToolInput(raw) {
  */
 export function toAnthropicMessages(messages) {
     const out = [];
-    for (const message of messages) {
-        if (message.role === 'system')
+    const start = conversationStart(messages);
+    for (const [index, message] of messages.entries()) {
+        // A leading system message is an opening instruction; toAnthropicSystem
+        // owns those. A later one rides here so the cached prefix ahead of it
+        // stays byte-identical.
+        if (message.role === 'system' && index < start)
             continue;
-        const role = message.role;
+        const role = message.role === 'system' ? 'user' : message.role;
         const blocks = [];
         for (const block of message.content) {
             switch (block.type) {
                 case 'text':
-                    blocks.push({ type: 'text', text: block.text });
-                    break;
-                case 'tool-call':
                     blocks.push({
-                        type: 'tool_use',
-                        id: String(block.id),
-                        name: block.name,
-                        input: parseToolInput(block.arguments),
+                        type: 'text',
+                        text: message.role === 'system'
+                            ? `${SYSTEM_REMINDER_OPEN}${block.text}${SYSTEM_REMINDER_CLOSE}`
+                            : block.text,
                     });
                     break;
+                case 'tool-call':
+                    // Anthropic accepts `tool_use` only in assistant messages, and only
+                    // when a matching `tool_result` follows. A tool call in any other
+                    // role is replayed narrative — a settled subagent's closing message
+                    // spliced into the parent as a user-role notice carries the calls it
+                    // died holding, which no result will ever answer — so it rides as
+                    // descriptive text instead of a call the API would reject.
+                    blocks.push(role === 'assistant'
+                        ? {
+                            type: 'tool_use',
+                            id: String(block.id),
+                            name: block.name,
+                            input: parseToolInput(block.arguments),
+                        }
+                        : { type: 'text', text: `[tool call ${block.name}: ${block.arguments}]` });
+                    break;
                 case 'tool-result':
                     blocks.push({
                         type: 'tool_result',
@@ -92,36 +171,72 @@ export function toAnthropicMessages(messages) {
         else
             out.push({ role, content: blocks });
     }
+    for (const message of out) {
+        if (message.role === 'user')
+            leadWithToolResults(message);
+    }
     return out;
 }
+/**
+ * Mark the conversation's cache breakpoints in place: the last content block,
+ * then one every {@link CACHE_BLOCK_STRIDE} blocks backwards, {@link
+ * MESSAGE_CACHE_BREAKPOINTS} in total.
+ *
+ * The history is append-only, so the block one request marks last is
+ * byte-identical in the next — that entry is what the next request reads.
+ * Marks are counted across the flattened block sequence, not per message,
+ * because the lookback window Anthropic walks counts blocks the same way.
+ * @param messages - assembled Anthropic messages, marked in place.
+ */
+export function markMessageCache(messages) {
+    const blocks = messages.flatMap(message => message.content);
+    for (let mark = 0; mark < MESSAGE_CACHE_BREAKPOINTS; mark++) {
+        const at = blocks.length - 1 - mark * CACHE_BLOCK_STRIDE;
+        if (at < 0)
+            return;
+        blocks[at].cache_control = { type: 'ephemeral' };
+    }
+}
 /**
  * Build the Anthropic `system` array: the mandatory Claude Code identity
  * block, then the explicit system prompt, then any system-role messages.
  * @param system - explicit system prompt, when set.
- * @param messages - conversation messages; their system-role text is appended.
+ * @param messages - conversation messages; the system-role text preceding the
+ * conversation is appended, and a later one is left to {@link toAnthropicMessages}.
  * @returns the system content blocks.
  */
 export function toAnthropicSystem(system, messages) {
     const blocks = [{ type: 'text', text: CLAUDE_CODE_IDENTITY }];
     if (system !== undefined && system.length > 0)
         blocks.push({ type: 'text', text: system });
-    for (const message of messages ?? []) {
-        if (message.role !== 'system')
-            continue;
+    const history = messages ?? [];
+    for (const message of history.slice(0, conversationStart(history))) {
         for (const block of message.content) {
             if (block.type === 'text')
                 blocks.push({ type: 'text', text: block.text });
         }
     }
+    // `tools` renders ahead of `system`, so this one marker caches both. It is
+    // deliberately separate from the message marks: a tool_choice or thinking
+    // change invalidates the messages tier only, and this entry survives it.
+    blocks[blocks.length - 1].cache_control = { type: 'ephemeral' };
     return blocks;
 }
 /**
- * Map harness tool schemas to Anthropic tools.
+ * Map harness tool schemas to Anthropic tools, in name order.
+ *
+ * `tools` renders at position 0 of the cached prefix, so any reordering
+ * invalidates every cache entry behind it — `system` and the whole
+ * conversation included. Registration order belongs to the caller and plugin
+ * load order can differ between processes, so the wire order is fixed here
+ * instead. Anthropic selects a tool by name; the array order carries nothing.
  * @param tools - tool schemas from the request.
- * @returns Anthropic `tools` array entries.
+ * @returns Anthropic `tools` array entries, ordered by tool name.
  */
 export function toAnthropicTools(tools) {
-    return tools.map(tool => ({
+    return [...tools]
+        .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+        .map(tool => ({
         name: tool.name,
         description: tool.description,
         input_schema: tool.parameters,

package/lib/translate/antigravity.d.ts

@@ -0,0 +1,110 @@
+/**
+ * DeepSeek Harness message/tool vocabulary to Antigravity's Gemini-shaped
+ * v1internal request envelope, plus response/SSE translation back to the
+ * harness streaming contract.
+ */
+import type { GenerateOptions, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { TranslatableMessage } from './resolved.js';
+/** Minimal Gemini part shape used by v1internal. */
+export interface AntigravityPart {
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+    functionCall?: {
+        id?: string;
+        name?: string;
+        args?: unknown;
+    };
+    functionResponse?: {
+        id: string;
+        name: string;
+        response: unknown;
+    };
+}
+/** Full Antigravity request envelope. */
+export interface AntigravityRequest {
+    project: string;
+    requestId: string;
+    model: string;
+    userAgent: 'antigravity';
+    requestType: 'agent';
+    request: {
+        contents: {
+            role: 'user' | 'model';
+            parts: AntigravityPart[];
+        }[];
+        sessionId: string;
+        systemInstruction?: {
+            parts: {
+                text: string;
+            }[];
+        };
+        tools?: {
+            functionDeclarations: Record<string, unknown>[];
+        }[];
+        toolConfig?: {
+            functionCallingConfig: {
+                mode: 'VALIDATED';
+            };
+        };
+        generationConfig?: Record<string, unknown>;
+    };
+}
+/** Map harness tool schemas to Gemini function declarations. */
+export declare function toAntigravityTools(tools: readonly ToolSchema[]): {
+    functionDeclarations: Record<string, unknown>[];
+}[];
+/**
+ * Convert resolved harness messages into Gemini contents. Function response
+ * names are recovered from prior tool calls because DSH correlates results by
+ * id while the Gemini wire requires both id and name.
+ */
+export declare function toAntigravityContents(messages: readonly TranslatableMessage[]): {
+    role: 'user' | 'model';
+    parts: AntigravityPart[];
+}[];
+/** Build one v1internal generateContent/streamGenerateContent request. */
+export declare function toAntigravityRequest(options: GenerateOptions, messages: readonly TranslatableMessage[], projectId: string): AntigravityRequest;
+/** Antigravity SSE/non-stream response subset. */
+export interface AntigravityResponseEvent {
+    response?: {
+        candidates?: {
+            content?: {
+                parts?: AntigravityPart[];
+            };
+            finishReason?: string;
+        }[];
+        usageMetadata?: {
+            promptTokenCount?: number;
+            candidatesTokenCount?: number;
+            thoughtsTokenCount?: number;
+            totalTokenCount?: number;
+            cachedContentTokenCount?: number;
+        };
+    };
+}
+/** Map Gemini usage metadata to the harness's disjoint counters. */
+export declare function mapAntigravityUsage(metadata: NonNullable<NonNullable<AntigravityResponseEvent['response']>['usageMetadata']>): TokenUsage;
+/** Push translator for both parsed SSE events and one non-stream response. */
+export declare class AntigravityStreamTranslator {
+    private blocks;
+    private closed;
+    private nextIndex;
+    private sawContent;
+    private sawToolCall;
+    terminated: boolean;
+    private open;
+    private close;
+    private closeAll;
+    private finish;
+    /** Process one decoded Antigravity response frame. */
+    push(event: AntigravityResponseEvent): StreamChunk[];
+}
+/** Consume Antigravity's SSE response into the DSH streaming contract. */
+export declare function streamAntigravity(stream: ReadableStream<Uint8Array>, onActivity?: () => void): AsyncGenerator<StreamChunk>;
+/** Translate a non-stream generateContent response using the same state machine. */
+export declare function parseAntigravityResponse(event: AntigravityResponseEvent): StreamChunk[];