dsh-plugin-subscriptions 0.1.0

package/lib/translate/resolved.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Resolved-image plumbing for the wire translators. ImageBlocks carry only an
+ * attachment reference; the bytes live in the attachment service, which is
+ * async I/O. Adapters resolve images BEFORE calling the (pure, synchronous)
+ * translators, so the translators see {@link ResolvedImagePart}s with inline
+ * base64 data.
+ */
+import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+/** An image block with its bytes resolved to inline base64 for the wire. */
+export interface ResolvedImagePart {
+    type: 'image';
+    /** MIME type verified by the attachment service (e.g. `image/png`). */
+    mediaType: string;
+    /** Base64-encoded image bytes. */
+    dataBase64: string;
+}
+/** Translator input block: a harness block, with images pre-resolved. */
+export type TranslatableBlock = ContentBlock | ResolvedImagePart;
+/** Translator input message: role plus resolved blocks. */
+export interface TranslatableMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: readonly TranslatableBlock[];
+}
+/**
+ * Resolve every ImageBlock's attachment reference to inline base64 bytes.
+ * Messages without images pass through unchanged. A request carrying an image
+ * with no attachment service available fails loudly rather than silently
+ * dropping the image.
+ * @param messages - the request's conversation messages.
+ * @param attachments - the deployment's attachment service, when mounted.
+ * @param signal - cancellation for the storage reads.
+ * @returns the same messages with image blocks resolved for the translators.
+ */
+export declare function resolveImages(messages: readonly Message[], attachments: AttachmentStore | undefined, signal?: AbortSignal): Promise<readonly TranslatableMessage[]>;

package/lib/translate/resolved.js

@@ -0,0 +1,40 @@
+/**
+ * Resolved-image plumbing for the wire translators. ImageBlocks carry only an
+ * attachment reference; the bytes live in the attachment service, which is
+ * async I/O. Adapters resolve images BEFORE calling the (pure, synchronous)
+ * translators, so the translators see {@link ResolvedImagePart}s with inline
+ * base64 data.
+ */
+import { LlmError } from '@deepseek-ai/dsh-llm';
+/**
+ * Resolve every ImageBlock's attachment reference to inline base64 bytes.
+ * Messages without images pass through unchanged. A request carrying an image
+ * with no attachment service available fails loudly rather than silently
+ * dropping the image.
+ * @param messages - the request's conversation messages.
+ * @param attachments - the deployment's attachment service, when mounted.
+ * @param signal - cancellation for the storage reads.
+ * @returns the same messages with image blocks resolved for the translators.
+ */
+export async function resolveImages(messages, attachments, signal) {
+    if (!messages.some(message => message.content.some(block => block.type === 'image'))) {
+        return messages;
+    }
+    if (attachments === undefined) {
+        throw new LlmError('dsh-plugin-subscriptions: the request carries an image but no attachments service is mounted; '
+            + 'image input requires the harness attachment store', 'UNSUPPORTED');
+    }
+    return Promise.all(messages.map(async (message) => ({
+        role: message.role,
+        content: await Promise.all(message.content.map(async (block) => {
+            if (block.type !== 'image')
+                return block;
+            const stored = await attachments.readImage(block.attachment, signal);
+            return {
+                type: 'image',
+                mediaType: stored.ref.mediaType,
+                dataBase64: Buffer.from(stored.data).toString('base64'),
+            };
+        })),
+    })));
+}

package/lib/translate/responses.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Translate between the harness message vocabulary and the OpenAI Responses
+ * API wire format shared by the codex and grok providers: request input
+ * assembly, tool schema mapping, and a push-model SSE-event → StreamChunk
+ * state machine ({@link ResponsesStreamTranslator}) so tests need no streams.
+ */
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import type { StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { TranslatableMessage } from './resolved.js';
+/** Assembled `instructions` + `input` pair for one Responses request. */
+export interface ResponsesRequestInput {
+    /** System text for the top-level `instructions` field; absent when there is none. */
+    instructions?: string;
+    /** Responses `input` items in conversation order. */
+    input: Record<string, unknown>[];
+}
+/**
+ * Convert harness messages into Responses `instructions` + `input` items.
+ * System-role messages become `instructions`; an explicit `system` argument
+ * wins over them when both exist. 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.
+ * @param system - explicit system prompt, which takes precedence.
+ * @returns request fields ready to merge into the request body.
+ */
+export declare function toResponsesInput(messages: readonly TranslatableMessage[], system?: string): ResponsesRequestInput;
+/**
+ * Map harness tool schemas to Responses function tools.
+ * @param tools - tool schemas from the request.
+ * @returns Responses `tools` array entries.
+ */
+export declare function toResponsesTools(tools: readonly ToolSchema[]): Record<string, unknown>[];
+/** The subset of Responses SSE event shapes this translator reads. */
+export interface ResponsesStreamEvent {
+    type: string;
+    item_id?: string;
+    content_index?: number;
+    summary_index?: number;
+    delta?: string;
+    item?: {
+        type?: string;
+        id?: string;
+        call_id?: string;
+        name?: string;
+        arguments?: string;
+        content?: Array<{
+            type?: string;
+            text?: string;
+        }>;
+    };
+    response?: {
+        status?: string;
+        usage?: ResponsesUsage;
+        error?: {
+            code?: string;
+            message?: string;
+        };
+        incomplete_details?: {
+            reason?: string;
+        };
+    };
+    code?: string;
+    message?: string;
+}
+/** Responses `usage` object shape. */
+export interface ResponsesUsage {
+    input_tokens: number;
+    output_tokens: number;
+    input_tokens_details?: {
+        cached_tokens?: number;
+    };
+    output_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+}
+/**
+ * Map Responses usage to disjoint harness counts (cached input is subtracted
+ * out of `inputTokens` and reported as `cacheReadTokens`).
+ * @param usage - wire usage from `response.completed`.
+ * @returns harness token usage.
+ */
+export declare function mapResponsesUsage(usage: ResponsesUsage): TokenUsage;
+/**
+ * Classify a Responses failure payload into a thrown LlmError.
+ * @param code - provider error code, when present.
+ * @param message - provider error message, when present.
+ * @returns the mapped error (context overflow, quota, otherwise SERVER).
+ */
+export declare function responsesFailure(code: string | undefined, message: string | undefined): LlmError;
+/**
+ * Push-model Responses 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. Terminal provider failures
+ * throw {@link LlmError}.
+ */
+export declare class ResponsesStreamTranslator {
+    private blocks;
+    private order;
+    private nextIndex;
+    private sawToolCall;
+    /** Set once `response.completed` produced the terminal finish chunk. */
+    terminated: boolean;
+    private open;
+    private textBlock;
+    private reasoningBlock;
+    private close;
+    /** Close every still-open block for one output item (prefix match on the key). */
+    private closeItem;
+    /** Close every still-open block (provider ended the response without done events). */
+    private closeAll;
+    private closeKeyIfOpen;
+    /**
+     * Process one parsed Responses SSE event.
+     * @param event - the parsed event object.
+     * @returns the StreamChunks this event produced (possibly none).
+     */
+    push(event: ResponsesStreamEvent): StreamChunk[];
+}
+/**
+ * Consume a Responses 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 `response.completed`.
+ */
+export declare function streamResponses(stream: ReadableStream<Uint8Array>, onActivity?: () => void): AsyncGenerator<StreamChunk>;

package/lib/translate/responses.js

@@ -0,0 +1,352 @@
+/**
+ * Translate between the harness message vocabulary and the OpenAI Responses
+ * API wire format shared by the codex and grok providers: request input
+ * assembly, tool schema mapping, and a push-model SSE-event → StreamChunk
+ * state machine ({@link ResponsesStreamTranslator}) so tests need no streams.
+ */
+import { CallId, CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError, QUOTA_EXCEEDED_CODE, } from '@deepseek-ai/dsh-llm';
+import { parseSse } from './sse.js';
+/** Flatten a tool result's content to plain text for `function_call_output`. */
+function toolResultText(block) {
+    return block.content.map(part => (part.type === 'text' ? part.text : '')).join('');
+}
+/**
+ * Convert harness messages into Responses `instructions` + `input` items.
+ * System-role messages become `instructions`; an explicit `system` argument
+ * wins over them when both exist. 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.
+ * @param system - explicit system prompt, which takes precedence.
+ * @returns request fields ready to merge into the request body.
+ */
+export function toResponsesInput(messages, system) {
+    const input = [];
+    const systemTexts = [];
+    for (const message of messages) {
+        if (message.role === 'system') {
+            for (const block of message.content) {
+                if (block.type === 'text')
+                    systemTexts.push(block.text);
+            }
+            continue;
+        }
+        const role = message.role;
+        let content = [];
+        const flushMessage = () => {
+            if (content.length === 0)
+                return;
+            input.push({ type: 'message', role, content });
+            content = [];
+        };
+        for (const block of message.content) {
+            switch (block.type) {
+                case 'text':
+                    content.push({ type: role === 'assistant' ? 'output_text' : 'input_text', text: block.text });
+                    break;
+                case 'tool-call':
+                    flushMessage();
+                    input.push({
+                        type: 'function_call',
+                        call_id: String(block.id),
+                        name: block.name,
+                        arguments: block.arguments,
+                    });
+                    break;
+                case 'tool-result':
+                    flushMessage();
+                    input.push({
+                        type: 'function_call_output',
+                        call_id: String(block.toolCallId),
+                        output: toolResultText(block),
+                    });
+                    break;
+                case 'image':
+                    if ('dataBase64' in block) {
+                        content.push({
+                            type: 'input_image',
+                            image_url: `data:${block.mediaType};base64,${block.dataBase64}`,
+                        });
+                    }
+                    // An unresolved ImageBlock carries only an attachment reference; the
+                    // adapter resolves images before translation, so this is skipped.
+                    break;
+                default:
+                    // reasoning (not replayed), unknown blocks.
+                    break;
+            }
+        }
+        flushMessage();
+    }
+    const instructions = system ?? (systemTexts.length > 0 ? systemTexts.join('\n\n') : undefined);
+    return { ...instructions === undefined ? {} : { instructions }, input };
+}
+/**
+ * Map harness tool schemas to Responses function tools.
+ * @param tools - tool schemas from the request.
+ * @returns Responses `tools` array entries.
+ */
+export function toResponsesTools(tools) {
+    return tools.map(tool => ({
+        type: 'function',
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+    }));
+}
+/**
+ * Map Responses usage to disjoint harness counts (cached input is subtracted
+ * out of `inputTokens` and reported as `cacheReadTokens`).
+ * @param usage - wire usage from `response.completed`.
+ * @returns harness token usage.
+ */
+export function mapResponsesUsage(usage) {
+    const cached = usage.input_tokens_details?.cached_tokens;
+    const reasoning = usage.output_tokens_details?.reasoning_tokens;
+    return {
+        inputTokens: usage.input_tokens - (cached ?? 0),
+        outputTokens: usage.output_tokens,
+        ...cached !== undefined ? { cacheReadTokens: cached } : {},
+        ...reasoning !== undefined ? { reasoningTokens: reasoning } : {},
+    };
+}
+/**
+ * Classify a Responses failure payload into a thrown LlmError.
+ * @param code - provider error code, when present.
+ * @param message - provider error message, when present.
+ * @returns the mapped error (context overflow, quota, otherwise SERVER).
+ */
+export function responsesFailure(code, message) {
+    const text = message ?? code ?? 'the provider reported a failed response';
+    const detail = `${code ?? ''} ${message ?? ''}`;
+    if (code === 'context_window_exceeded' || isContextWindowExceededError(detail)) {
+        return new LlmError(text, CONTEXT_WINDOW_EXCEEDED_CODE);
+    }
+    if ((code !== undefined && /insufficient|quota/i.test(code)) || isQuotaExceededError(detail)) {
+        return new LlmError(text, QUOTA_EXCEEDED_CODE);
+    }
+    return new LlmError(text, 'SERVER');
+}
+/** Assemble the final ContentBlock for one open block. */
+function closeBlock(block) {
+    switch (block.kind) {
+        case 'text':
+            return { type: 'text', text: block.text };
+        case 'reasoning':
+            return { type: 'reasoning', text: block.text };
+        case 'tool-call':
+            return {
+                type: 'tool-call',
+                id: CallId(block.callId),
+                name: block.name ?? '',
+                arguments: block.text,
+            };
+    }
+}
+/**
+ * Push-model Responses 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. Terminal provider failures
+ * throw {@link LlmError}.
+ */
+export class ResponsesStreamTranslator {
+    blocks = new Map();
+    order = [];
+    nextIndex = 0;
+    sawToolCall = false;
+    /** Set once `response.completed` produced the terminal finish chunk. */
+    terminated = false;
+    open(key, kind, chunks, callId = '', name) {
+        const block = {
+            index: this.nextIndex++,
+            kind,
+            text: '',
+            callId,
+            ...name === undefined ? {} : { name },
+        };
+        this.blocks.set(key, block);
+        this.order.push(block);
+        chunks.push({ type: 'block-start', index: block.index, blockType: kind });
+        return block;
+    }
+    textBlock(key, chunks) {
+        return this.blocks.get(key) ?? this.open(key, 'text', chunks);
+    }
+    reasoningBlock(key, chunks) {
+        return this.blocks.get(key) ?? this.open(key, 'reasoning', chunks);
+    }
+    close(key, chunks) {
+        const block = this.blocks.get(key);
+        if (block === undefined)
+            return;
+        this.blocks.delete(key);
+        chunks.push({ type: 'block-end', index: block.index, block: closeBlock(block) });
+    }
+    /** Close every still-open block for one output item (prefix match on the key). */
+    closeItem(itemId, chunks) {
+        for (const key of [...this.blocks.keys()]) {
+            if (key.startsWith(`${itemId}:`))
+                this.close(key, chunks);
+        }
+    }
+    /** Close every still-open block (provider ended the response without done events). */
+    closeAll(chunks) {
+        for (const block of this.order)
+            this.closeKeyIfOpen(block, chunks);
+    }
+    closeKeyIfOpen(block, chunks) {
+        for (const [key, candidate] of this.blocks) {
+            if (candidate === block) {
+                this.blocks.delete(key);
+                chunks.push({ type: 'block-end', index: block.index, block: closeBlock(block) });
+                return;
+            }
+        }
+    }
+    /**
+     * Process one parsed Responses SSE event.
+     * @param event - the parsed event object.
+     * @returns the StreamChunks this event produced (possibly none).
+     */
+    push(event) {
+        if (this.terminated)
+            return [];
+        const chunks = [];
+        switch (event.type) {
+            case 'response.output_item.added': {
+                const item = event.item;
+                if (item?.type === 'function_call' && item.id !== undefined) {
+                    this.sawToolCall = true;
+                    const callId = item.call_id ?? '';
+                    const block = this.open(`${item.id}:call`, 'tool-call', chunks, callId, item.name);
+                    chunks.push({
+                        type: 'tool-call-delta',
+                        index: block.index,
+                        id: CallId(callId),
+                        ...item.name === undefined ? {} : { name: item.name },
+                        argumentsDelta: '',
+                    });
+                }
+                return chunks;
+            }
+            case 'response.output_text.delta': {
+                const key = `${event.item_id ?? ''}:text:${String(event.content_index ?? 0)}`;
+                const block = this.textBlock(key, chunks);
+                block.text += event.delta ?? '';
+                chunks.push({ type: 'text-delta', index: block.index, text: event.delta ?? '' });
+                return chunks;
+            }
+            case 'response.reasoning_summary_text.delta':
+            case 'response.reasoning_text.delta': {
+                const sub = event.summary_index ?? event.content_index ?? 0;
+                const key = `${event.item_id ?? ''}:reason:${String(sub)}`;
+                const block = this.reasoningBlock(key, chunks);
+                block.text += event.delta ?? '';
+                chunks.push({ type: 'reasoning-delta', index: block.index, text: event.delta ?? '' });
+                return chunks;
+            }
+            case 'response.function_call_arguments.delta': {
+                const key = `${event.item_id ?? ''}:call`;
+                let block = this.blocks.get(key);
+                if (block === undefined) {
+                    // The item.added event was missed; open the block from the delta alone.
+                    this.sawToolCall = true;
+                    block = this.open(key, 'tool-call', chunks);
+                }
+                block.text += event.delta ?? '';
+                chunks.push({
+                    type: 'tool-call-delta',
+                    index: block.index,
+                    id: CallId(block.callId),
+                    ...block.name === undefined ? {} : { name: block.name },
+                    argumentsDelta: event.delta ?? '',
+                });
+                return chunks;
+            }
+            case 'response.output_item.done': {
+                const item = event.item;
+                if (item === undefined || item.id === undefined)
+                    return chunks;
+                if (item.type === 'function_call') {
+                    const key = `${item.id}:call`;
+                    // The provider may deliver the complete arguments only on done.
+                    const block = this.blocks.get(key);
+                    if (block !== undefined && block.text.length === 0 && item.arguments !== undefined) {
+                        block.text = item.arguments;
+                    }
+                    this.close(key, chunks);
+                }
+                else if (item.type === 'message') {
+                    if (![...this.blocks.keys()].some(key => key.startsWith(`${item.id}:text:`))) {
+                        // No deltas arrived for this item; synthesize blocks from the done payload.
+                        for (const [partIndex, part] of (item.content ?? []).entries()) {
+                            if (part?.type !== 'output_text' || typeof part.text !== 'string' || part.text.length === 0)
+                                continue;
+                            const block = this.open(`${item.id}:text:${partIndex}`, 'text', chunks);
+                            block.text = part.text;
+                            this.close(`${item.id}:text:${partIndex}`, chunks);
+                        }
+                    }
+                    this.closeItem(item.id, chunks);
+                }
+                else {
+                    this.closeItem(item.id, chunks);
+                }
+                return chunks;
+            }
+            case 'response.completed': {
+                this.terminated = true;
+                this.closeAll(chunks);
+                const usage = event.response?.usage;
+                if (usage !== undefined)
+                    chunks.push({ type: 'usage', usage: mapResponsesUsage(usage) });
+                if (this.order.length === 0) {
+                    chunks.push({
+                        type: 'finish',
+                        reason: {
+                            kind: 'error',
+                            failure: { message: 'model returned a completed response with no content', code: EMPTY_RESPONSE_CODE },
+                        },
+                    });
+                }
+                else {
+                    chunks.push({ type: 'finish', reason: { kind: this.sawToolCall ? 'tool-calls' : 'stop' } });
+                }
+                return chunks;
+            }
+            case 'response.failed':
+                throw responsesFailure(event.response?.error?.code, event.response?.error?.message);
+            case 'response.incomplete':
+                throw responsesFailure(event.response?.incomplete_details?.reason, event.response?.error?.message
+                    ?? `the provider reported an incomplete response (${event.response?.incomplete_details?.reason ?? 'unknown reason'})`);
+            case 'error':
+                throw responsesFailure(event.code, event.message);
+            default:
+                // response.created, response.in_progress, content_part events, etc.: no chunks.
+                return chunks;
+        }
+    }
+}
+/**
+ * Consume a Responses 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 `response.completed`.
+ */
+export async function* streamResponses(stream, onActivity) {
+    const translator = new ResponsesStreamTranslator();
+    for await (const sseEvent of parseSse(stream, onActivity)) {
+        let event;
+        try {
+            event = JSON.parse(sseEvent.data);
+        }
+        catch {
+            throw new LlmError(`malformed SSE payload: ${sseEvent.data.slice(0, 120)}`, 'MALFORMED_RESPONSE');
+        }
+        yield* translator.push(event);
+        if (translator.terminated)
+            return;
+    }
+    throw new LlmError('Responses SSE stream ended before response.completed', 'STREAM_CLOSED');
+}

package/lib/translate/sse.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Minimal SSE byte-stream parser (~30 lines of framing): reassembles chunks,
+ * splits CRLF/LF lines, joins multi-`data:` payloads, skips comments and
+ * non-data fields, and dispatches an event only on its blank-line terminator.
+ * An unterminated tail at EOF is truncation and is dropped, matching the
+ * spec-strict framing the harness's own adapters use.
+ */
+/** One parsed SSE event. */
+export interface SseEvent {
+    /** Joined `data:` lines of the event. */
+    data: string;
+    /** The `event:` field, when present. */
+    event?: string;
+}
+/**
+ * Decode an SSE byte stream into events.
+ * @param stream - raw response bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @param onActivity - called on every received chunk and comment line; drives the idle watchdog.
+ * @returns events in arrival order.
+ */
+export declare function parseSse(stream: ReadableStream<Uint8Array>, onActivity?: () => void): AsyncGenerator<SseEvent>;

package/lib/translate/sse.js

@@ -0,0 +1,56 @@
+/**
+ * Minimal SSE byte-stream parser (~30 lines of framing): reassembles chunks,
+ * splits CRLF/LF lines, joins multi-`data:` payloads, skips comments and
+ * non-data fields, and dispatches an event only on its blank-line terminator.
+ * An unterminated tail at EOF is truncation and is dropped, matching the
+ * spec-strict framing the harness's own adapters use.
+ */
+/**
+ * Decode an SSE byte stream into events.
+ * @param stream - raw response bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @param onActivity - called on every received chunk and comment line; drives the idle watchdog.
+ * @returns events in arrival order.
+ */
+export async function* parseSse(stream, onActivity) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    let dataLines = [];
+    let eventName;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            onActivity?.();
+            pending += decoder.decode(value, { stream: true });
+            let newline = pending.indexOf('\n');
+            while (newline >= 0) {
+                let line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                newline = pending.indexOf('\n');
+                if (line.endsWith('\r'))
+                    line = line.slice(0, -1);
+                if (line.length === 0) {
+                    if (dataLines.length > 0) {
+                        yield { data: dataLines.join('\n'), ...eventName === undefined ? {} : { event: eventName } };
+                    }
+                    dataLines = [];
+                    eventName = undefined;
+                }
+                else if (line.startsWith(':')) {
+                    onActivity?.();
+                }
+                else if (line.startsWith('data:')) {
+                    dataLines.push(line.slice(5).replace(/^ /, ''));
+                }
+                else if (line.startsWith('event:')) {
+                    eventName = line.slice(6).replace(/^ /, '');
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}