dsh-subscriptions 0.1.0

package/lib/tools/video-generate.js

@@ -0,0 +1,257 @@
+/**
+ * `video_generate` tool: generate videos through the grok subscription's
+ * Imagine video endpoint and save them as MP4 files under the harness home.
+ * The xAI API is asynchronous: POST `/v1/videos/generations` returns a
+ * `request_id`, GET `/v1/videos/{request_id}` is polled until the status
+ * leaves `pending`, and the completed response carries a temporary MP4 URL
+ * that is downloaded promptly (the URL expires). The canonical result is the
+ * saved file path; videos have no attachment surface, so the result stays
+ * text-only (unlike image_generate).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { httpLlmError } from '../providers/common.js';
+import { AccountTokenManager } from '../providers/accounts.js';
+import { hostFetch } 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. */
+export const VIDEO_GENERATE_MODEL = 'grok-imagine-video-1.5';
+/** Polling endpoint for one generation request. */
+export function videoStatusUrl(requestId) {
+    return `https://api.x.ai/v1/videos/${encodeURIComponent(requestId)}`;
+}
+/** Default delay between two status polls. */
+export const DEFAULT_POLL_INTERVAL_MS = 3_000;
+/** Default overall deadline for one generation (submit → done). */
+export const DEFAULT_MAX_WAIT_MS = 10 * 60_000;
+/** xAI's supported clip length range in seconds. */
+const DURATION_RANGE = { min: 1, max: 15 };
+/**
+ * Assemble the request body from tool arguments (hand-checks the non-empty
+ * prompt and the duration range the schema DSL cannot express).
+ */
+export function buildVideoGenerateBody(args) {
+    const prompt = args.prompt.trim();
+    if (prompt.length === 0)
+        throw new Error('video_generate: prompt must be a non-empty string');
+    if (args.duration !== undefined
+        && (!Number.isInteger(args.duration)
+            || args.duration < DURATION_RANGE.min
+            || args.duration > DURATION_RANGE.max)) {
+        throw new Error(`video_generate: duration must be an integer between ${String(DURATION_RANGE.min)} and ${String(DURATION_RANGE.max)} seconds`);
+    }
+    const imageUrl = args.image_url?.trim();
+    return {
+        prompt,
+        model: VIDEO_GENERATE_MODEL,
+        ...args.duration === undefined ? {} : { duration: args.duration },
+        ...args.aspect_ratio === undefined ? {} : { aspect_ratio: args.aspect_ratio },
+        ...args.resolution === undefined ? {} : { resolution: args.resolution },
+        ...imageUrl === undefined || imageUrl.length === 0 ? {} : { image: { url: imageUrl } },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Extract the request id from the submit response. Throws when the payload
+ * carries none.
+ */
+export function parseVideoStartResponse(payload) {
+    const body = isRecord(payload) ? payload : {};
+    if (typeof body.request_id !== 'string' || body.request_id.length === 0) {
+        throw new Error('video_generate: the response carried no request_id');
+    }
+    return body.request_id;
+}
+/**
+ * Decode one poll response. A `done` payload without a video URL and an
+ * unrecognized status both throw (the poll loop cannot make progress on
+ * either).
+ */
+export function parseVideoStatusResponse(payload) {
+    const body = isRecord(payload) ? payload : {};
+    switch (body.status) {
+        case 'pending':
+            return { status: 'pending' };
+        case 'done': {
+            const video = isRecord(body.video) ? body.video : {};
+            if (typeof video.url !== 'string' || video.url.length === 0) {
+                throw new Error('video_generate: the completed response carried no video URL');
+            }
+            return {
+                status: 'done',
+                url: video.url,
+                ...typeof video.duration === 'number' ? { duration: video.duration } : {},
+            };
+        }
+        case 'failed':
+        case 'expired': {
+            const error = isRecord(body.error) ? body.error : {};
+            const detail = typeof error.message === 'string' && error.message.length > 0
+                ? error.message
+                : typeof body.error === 'string' && body.error.length > 0 ? body.error : undefined;
+            return { status: body.status, ...detail === undefined ? {} : { detail } };
+        }
+        default:
+            throw new Error(`video_generate: unexpected status ${JSON.stringify(body.status)}`);
+    }
+}
+/** Directory the downloaded MP4 files are written to. */
+export function videosDirectory() {
+    return dshHomePath('plugins', 'subscriptions', 'videos');
+}
+/** Timestamped, collision-safe file name for one generated video. */
+function videoFileName() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `video-${stamp}-${Math.random().toString(36).slice(2, 8)}.mp4`;
+}
+/** Bound a call-card title's prompt. */
+function truncate(text, max = 60) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/** Abort-aware sleep between two polls. */
+function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error ? signal.reason : new Error('video_generate: aborted'));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Build the `video_generate` tool definition.
+ * @param options - grok session source, fetch implementation, and video directory.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export function createVideoGenerateTool(options) {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    return defineTool({
+        name: 'video_generate',
+        description: `Generate a short video (1-15 seconds) with the grok subscription (${VIDEO_GENERATE_MODEL}) `
+            + 'and save it as an MP4 file. Generation is asynchronous and may take a minute or more; '
+            + 'the tool waits for completion and returns the saved file path. '
+            + 'Optionally animate a still image by passing image_url (image-to-video).',
+        parameters: {
+            prompt: { type: 'string', required: true, description: 'What the video should show.' },
+            duration: {
+                type: 'integer',
+                description: 'Clip length in seconds (1-15); omit for the provider default.',
+            },
+            aspect_ratio: {
+                type: 'string',
+                enum: ['16:9', '9:16', '1:1', '4:3', '3:4', '3:2', '2:3'],
+                description: 'Output aspect ratio; omit for the provider default (16:9).',
+            },
+            resolution: {
+                type: 'string',
+                enum: ['480p', '720p', '1080p'],
+                description: 'Output resolution; omit for the provider default (480p). Higher is slower.',
+            },
+            image_url: {
+                type: 'string',
+                description: 'Optional public URL or base64 data URL of a JPEG/PNG/WebP image to animate '
+                    + '(image-to-video); the image becomes the starting frame.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', required: true },
+                    url: { type: 'string', required: true },
+                    duration: { type: 'number' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Saved video to ${value.path}`
+                        + (value.duration === undefined ? '' : ` (${String(value.duration)}s)`)
+                        + `\nTemporary provider URL (expires soon): ${value.url}`,
+                }],
+            // The client toolview fetches the bytes by bare file name through the
+            // `/subscriptions-auth` `video` endpoint; meta hands it that name.
+            presentationMeta: (_args, value) => ({
+                fileName: basename(value.path),
+                ...value.duration === undefined ? {} : { duration: value.duration },
+            }),
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `video_generate: ${truncate(args.prompt)}`,
+        }),
+        async execute(args, exec) {
+            const body = buildVideoGenerateBody(args);
+            const session = await options.tokens.session();
+            const fetchFn = options.fetchFn ?? hostFetch;
+            const headers = {
+                'authorization': `Bearer ${session.accessToken}`,
+                'accept': 'application/json',
+            };
+            const submit = await fetchFn(VIDEO_GENERATE_URL, {
+                method: 'POST',
+                headers: { ...headers, 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: exec.signal,
+            });
+            if (!submit.ok)
+                throw await httpLlmError(submit, 'video_generate');
+            const requestId = parseVideoStartResponse(await submit.json());
+            const deadline = Date.now() + maxWaitMs;
+            let done;
+            for (;;) {
+                await sleep(pollIntervalMs, exec.signal);
+                const poll = await fetchFn(videoStatusUrl(requestId), {
+                    method: 'GET',
+                    headers,
+                    signal: exec.signal,
+                });
+                if (!poll.ok)
+                    throw await httpLlmError(poll, 'video_generate');
+                const status = parseVideoStatusResponse(await poll.json());
+                if (status.status === 'done') {
+                    done = status;
+                    break;
+                }
+                if (status.status === 'failed' || status.status === 'expired') {
+                    throw new Error(`video_generate: generation ${status.status} (request ${requestId})`
+                        + (status.detail === undefined ? '' : `: ${status.detail}`));
+                }
+                if (Date.now() >= deadline) {
+                    throw new Error(`video_generate: timed out after ${String(maxWaitMs)}ms waiting for request ${requestId}`);
+                }
+            }
+            // The MP4 lives on a separate signed host: no auth header on purpose.
+            const download = await fetchFn(done.url, { method: 'GET', signal: exec.signal });
+            if (!download.ok)
+                throw await httpLlmError(download, 'video_generate download');
+            const data = Buffer.from(await download.arrayBuffer());
+            const directory = options.videosDir ?? videosDirectory();
+            await mkdir(directory, { recursive: true });
+            const path = join(directory, videoFileName());
+            await writeFile(path, data);
+            const value = {
+                path,
+                url: done.url,
+                ...done.duration === undefined ? {} : { duration: done.duration },
+            };
+            return value;
+        },
+    });
+}

package/lib/tools/x-search.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `x_search` tool: run xAI's hosted X (Twitter) search through the grok
+ * subscription's OAuth session. The wire call is a non-streaming Responses
+ * request carrying the built-in `x_search` tool definition; the canonical
+ * output is `{ answer, citations }`.
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { GrokSession } from '../auth/store.js';
+import { AccountTokenManager } from '../providers/accounts.js';
+import type { FetchFn } from '../providers/common.js';
+/** Endpoint the search request is posted to. */
+export declare const X_SEARCH_URL = "https://api.x.ai/v1/responses";
+/** Grok model the search runs on (a catalog model of the grok provider). */
+export declare const X_SEARCH_MODEL = "grok-4";
+/** Dependencies of the `x_search` tool. */
+export interface XSearchToolOptions {
+    /** Grok session source; a missing session throws the log-in hint. */
+    tokens: AccountTokenManager<GrokSession>;
+    /** Fetch implementation (injectable for tests). */
+    fetchFn?: FetchFn;
+}
+/** Normalized, validated arguments of one search call. */
+interface XSearchRequest {
+    query: string;
+    tool: Record<string, unknown>;
+}
+/**
+ * Validate and assemble the request facts from tool arguments. Throws plain
+ * Errors for argument problems the schema DSL cannot express (non-empty
+ * query, handle caps, mutually exclusive filters).
+ */
+export declare function buildXSearchRequest(args: {
+    query: string;
+    allowed_x_handles?: string[];
+    excluded_x_handles?: string[];
+    from_date?: string;
+    to_date?: string;
+    enable_image_understanding?: boolean;
+    enable_video_understanding?: boolean;
+}): XSearchRequest;
+/** The canonical output of one successful search. */
+interface XSearchOutput {
+    answer: string;
+    citations: string[];
+}
+/**
+ * Extract the answer text and citation URLs from a Responses payload: the
+ * `output_text` shortcut or message output parts for the answer, and both
+ * top-level `citations` and inline `url_citation` annotations for sources.
+ */
+export declare function parseXSearchResponse(payload: unknown): XSearchOutput;
+/**
+ * Build the `x_search` tool definition.
+ * @param options - grok session source and fetch implementation.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export declare function createXSearchTool(options: XSearchToolOptions): ToolDefinition;
+export {};

package/lib/tools/x-search.js

@@ -0,0 +1,197 @@
+/**
+ * `x_search` tool: run xAI's hosted X (Twitter) search through the grok
+ * subscription's OAuth session. The wire call is a non-streaming Responses
+ * request carrying the built-in `x_search` tool definition; the canonical
+ * output is `{ answer, citations }`.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { httpLlmError } from '../providers/common.js';
+import { AccountTokenManager } from '../providers/accounts.js';
+import { hostFetch } 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). */
+export const X_SEARCH_MODEL = 'grok-4';
+/** xAI caps each handle filter list at ten entries. */
+const MAX_HANDLES = 10;
+/**
+ * Validate and assemble the request facts from tool arguments. Throws plain
+ * Errors for argument problems the schema DSL cannot express (non-empty
+ * query, handle caps, mutually exclusive filters).
+ */
+export function buildXSearchRequest(args) {
+    const query = args.query.trim();
+    if (query.length === 0)
+        throw new Error('x_search: query must be a non-empty string');
+    const allowed = normalizeHandles(args.allowed_x_handles, 'allowed_x_handles');
+    const excluded = normalizeHandles(args.excluded_x_handles, 'excluded_x_handles');
+    if (allowed.length > 0 && excluded.length > 0) {
+        throw new Error('x_search: allowed_x_handles and excluded_x_handles cannot be used together');
+    }
+    const tool = { type: 'x_search' };
+    if (allowed.length > 0)
+        tool.allowed_x_handles = allowed;
+    if (excluded.length > 0)
+        tool.excluded_x_handles = excluded;
+    if (args.from_date !== undefined && args.from_date.trim().length > 0)
+        tool.from_date = args.from_date.trim();
+    if (args.to_date !== undefined && args.to_date.trim().length > 0)
+        tool.to_date = args.to_date.trim();
+    if (args.enable_image_understanding === true)
+        tool.enable_image_understanding = true;
+    if (args.enable_video_understanding === true)
+        tool.enable_video_understanding = true;
+    return { query, tool };
+}
+/** Strip `@` prefixes, drop blanks, and enforce the provider's handle cap. */
+function normalizeHandles(value, field) {
+    if (value === undefined)
+        return [];
+    const handles = value.map(handle => handle.trim().replace(/^@+/, '')).filter(handle => handle.length > 0);
+    if (handles.length > MAX_HANDLES)
+        throw new Error(`x_search: ${field} supports at most ${MAX_HANDLES} handles`);
+    return handles;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Extract the answer text and citation URLs from a Responses payload: the
+ * `output_text` shortcut or message output parts for the answer, and both
+ * top-level `citations` and inline `url_citation` annotations for sources.
+ */
+export function parseXSearchResponse(payload) {
+    const body = isRecord(payload) ? payload : {};
+    let answer = typeof body.output_text === 'string' ? body.output_text.trim() : '';
+    const citations = [];
+    const push = (url) => {
+        if (typeof url === 'string' && url.length > 0 && !citations.includes(url))
+            citations.push(url);
+    };
+    if (Array.isArray(body.citations)) {
+        for (const citation of body.citations)
+            push(citation);
+    }
+    const parts = [];
+    if (Array.isArray(body.output)) {
+        for (const item of body.output) {
+            if (!isRecord(item) || item.type !== 'message' || !Array.isArray(item.content))
+                continue;
+            for (const part of item.content) {
+                if (!isRecord(part))
+                    continue;
+                if ((part.type === 'output_text' || part.type === 'text')
+                    && typeof part.text === 'string' && part.text.trim().length > 0) {
+                    parts.push(part.text.trim());
+                }
+                if (Array.isArray(part.annotations)) {
+                    for (const annotation of part.annotations) {
+                        if (isRecord(annotation) && annotation.type === 'url_citation')
+                            push(annotation.url);
+                    }
+                }
+            }
+        }
+    }
+    if (answer.length === 0)
+        answer = parts.join('\n\n');
+    return { answer, citations };
+}
+/** Bound a call-card title's query. */
+function truncate(text, max = 60) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/**
+ * Build the `x_search` tool definition.
+ * @param options - grok session source and fetch implementation.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export function createXSearchTool(options) {
+    return defineTool({
+        name: 'x_search',
+        description: "Search X (Twitter) posts, profiles, and threads using the grok subscription's hosted xAI x_search. "
+            + 'Use this for current discussion, reactions, or claims on X rather than general web pages.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'What to look up on X.' },
+            allowed_x_handles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'X handles to include exclusively (max 10).',
+            },
+            excluded_x_handles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'X handles to exclude (max 10).',
+            },
+            from_date: { type: 'string', description: 'Optional start date in YYYY-MM-DD format.' },
+            to_date: { type: 'string', description: 'Optional end date in YYYY-MM-DD format.' },
+            enable_image_understanding: {
+                type: 'boolean',
+                description: 'Whether xAI should analyze images attached to matching posts.',
+            },
+            enable_video_understanding: {
+                type: 'boolean',
+                description: 'Whether xAI should analyze videos attached to matching posts.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    answer: { type: 'string', required: true },
+                    citations: { type: 'array', items: { type: 'string' }, required: true },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: value.citations.length > 0
+                        ? `${value.answer}\n\nSources:\n${value.citations.map(citation => `- ${citation}`).join('\n')}`
+                        : value.answer,
+                }],
+            presentationMeta: (_args, value) => ({ answer: value.answer, citations: value.citations }),
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `x_search: ${truncate(args.query)}`,
+            kind: 'search',
+        }),
+        presentResult: (_args, result) => {
+            if (result.isError || !isRecord(result.meta))
+                return undefined;
+            const citations = Array.isArray(result.meta.citations) ? result.meta.citations : [];
+            return {
+                card: 'web',
+                kind: 'search',
+                sources: citations.filter((citation) => typeof citation === 'string')
+                    .map(url => ({ url })),
+                ...typeof result.meta.answer === 'string' && result.meta.answer.length > 0
+                    ? { answer: result.meta.answer }
+                    : {},
+                truncated: false,
+            };
+        },
+        async execute(args, exec) {
+            const request = buildXSearchRequest(args);
+            const session = await options.tokens.session();
+            const response = await (options.fetchFn ?? hostFetch)(X_SEARCH_URL, {
+                method: 'POST',
+                headers: {
+                    'authorization': `Bearer ${session.accessToken}`,
+                    'content-type': 'application/json',
+                    'accept': 'application/json',
+                },
+                body: JSON.stringify({
+                    model: X_SEARCH_MODEL,
+                    input: [{ role: 'user', content: request.query }],
+                    tools: [request.tool],
+                    store: false,
+                }),
+                signal: exec.signal,
+            });
+            if (!response.ok)
+                throw await httpLlmError(response, 'x_search');
+            return parseXSearchResponse(await response.json());
+        },
+    });
+}

package/lib/translate/anthropic.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Translate between the harness message vocabulary and the Anthropic Messages
+ * API wire format used by the claude provider: request message assembly, tool
+ * schema mapping, and a push-model SSE-event → StreamChunk state machine
+ * ({@link AnthropicStreamTranslator}) so tests need no streams.
+ */
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import type { StreamChunk, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { TranslatableMessage } from './resolved.js';
+/**
+ * The Claude Code identity block. The subscription endpoint rejects requests
+ * that do not present as Claude Code, so this block is REQUIRED as the first
+ * 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';
+    content: Record<string, unknown>[];
+}
+/**
+ * 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, 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; 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, 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, ordered by tool name.
+ */
+export declare function toAnthropicTools(tools: readonly ToolSchema[]): Record<string, unknown>[];
+/** The subset of Anthropic SSE event shapes this translator reads. */
+export interface AnthropicStreamEvent {
+    type: string;
+    index?: number;
+    message?: {
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+        };
+    };
+    content_block?: {
+        type?: string;
+        id?: string;
+        name?: string;
+    };
+    delta?: {
+        type?: string;
+        text?: string;
+        thinking?: string;
+        partial_json?: string;
+        stop_reason?: string;
+    };
+    usage?: {
+        output_tokens?: number;
+    };
+    error?: {
+        type?: string;
+        message?: string;
+    };
+}
+/**
+ * Classify an Anthropic `error` event into a thrown LlmError.
+ * @param error - the wire error object.
+ * @returns the mapped error.
+ */
+export declare function anthropicFailure(error: {
+    type?: string;
+    message?: string;
+} | undefined): LlmError;
+/**
+ * Push-model Anthropic SSE translator: feed each parsed event object to
+ * {@link push} and collect the emitted harness StreamChunks. Block indexes
+ * are allocated in first-seen order; `usage` is emitted before the terminal
+ * `finish`, and nothing is emitted after it. `error` events throw
+ * {@link LlmError}.
+ */
+export declare class AnthropicStreamTranslator {
+    private blocks;
+    private nextIndex;
+    private sawAnyBlock;
+    private pendingUsage;
+    private outputTokens;
+    private stopReason;
+    private usageEmitted;
+    /** Set once `message_stop` produced the terminal finish chunk. */
+    terminated: boolean;
+    private open;
+    private emitUsage;
+    /**
+     * Process one parsed Anthropic SSE event.
+     * @param event - the parsed event object.
+     * @returns the StreamChunks this event produced (possibly none).
+     */
+    push(event: AnthropicStreamEvent): StreamChunk[];
+}
+/**
+ * Consume an Anthropic SSE byte stream and yield harness StreamChunks.
+ * @param stream - raw response body.
+ * @param onActivity - transport-activity callback for the idle watchdog.
+ * @returns the chunk stream; throws when the stream ends before `message_stop`.
+ */
+export declare function streamAnthropic(stream: ReadableStream<Uint8Array>, onActivity?: () => void): AsyncGenerator<StreamChunk>;