@dan-ai-studio/dshopencodego 0.1.5

package/lib/types/config.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Configuration for one `dshopencodego` mount.
+ *
+ * DSH 0.1.7 hands the plugin *live references* for every declared field, so a
+ * profile edit reaches the next operation without a restart. This plugin
+ * targets that generation only: there is no settings-document path, no
+ * `installSection` fallback, and no plain-value codec.
+ *
+ * Self-contained constraints (URL shape, numeric bounds) fail at load for the
+ * composition layer and refuse the write for a profile edit.
+ *
+ * @module @dan-ai-studio/dshopencodego/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Credential reference resolving the OpenCode Go API key. */
+export declare const DEFAULT_API_KEY_ENV = "OPENCODE_GO_API_KEY";
+/** Requests and pickers share this cache lifetime; explicit discovery revalidates immediately. */
+export declare const DEFAULT_REFRESH_MINUTES = 60;
+/** Default maximum idle interval while one stream read is outstanding. */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Request-level bound on the base64-encoded image payload. */
+export declare const DEFAULT_MAX_REQUEST_IMAGE_BYTES: number;
+/** Total-pixel budget for one request image. */
+export declare const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 1440000;
+/** Raw encoded-byte target for one request image before base64 expansion. */
+export declare const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 400000;
+/**
+ * One model's configured capacities. Every field is optional so a deployment
+ * overrides only the value it needs; `null` explicitly selects the catalog
+ * value even when a lower layer supplies an override.
+ */
+export interface OpencodeGoModelLimit {
+    /** Context window in tokens, overriding what the catalog advertised. */
+    contextWindow?: number | null;
+    /** Output cap per request, overriding what the catalog advertised. */
+    maxTokens?: number | null;
+}
+/** Per-model capacities; a `null` entry selects both original catalog values. */
+export type OpencodeGoModelLimits = Record<string, OpencodeGoModelLimit | null>;
+/** Runtime configuration for one plugin mount. */
+export interface OpencodeGoConfig {
+    /**
+     * Whether this adapter serves its route at all. False withdraws the
+     * `opencode-go` route and its models from every picker without unloading the
+     * plugin, so the configuration that owns this switch stays reachable to turn
+     * it back on. Independent of the credential: a key present while this is
+     * false registers nothing.
+     */
+    enabled: boolean;
+    /** Per-model picker switches; absent entries default to enabled unless deprecated. */
+    modelVisibility: Record<string, boolean>;
+    /** Credential reference: the key resolves from this reference. */
+    apiKeyEnv: string;
+    /** The gateway endpoint; also the base of the live model listing. */
+    baseURL: string;
+    /** Request/picker cache lifetime in minutes; explicit discovery bypasses it. */
+    refreshMinutes: number;
+    /** Largest idle gap between stream events before the request fails. */
+    streamIdleTimeoutMs: number;
+    /** Request-level bound on base64-encoded image payload, in bytes. */
+    maxRequestImageBytes: number;
+    /** Total-pixel budget for one request image. */
+    requestImagePixelBudget: number;
+    /** Raw encoded-byte target for one request image before base64 expansion. */
+    requestImageMaxBytes: number;
+    /** Per-model capacity overrides; an absent field inherits the catalog value. */
+    modelLimits: OpencodeGoModelLimits;
+    /**
+     * Per-model wire-protocol overrides, winning over every inference level.
+     * The escape hatch for a model whose family rule guessed wrong.
+     */
+    modelProtocols: Record<string, string>;
+}
+/** Plain resolved values used by the adapter. */
+export declare const PlainConfig: z<OpencodeGoConfig>;
+/** 0.1.7's Loader retains these references when profile fields change. */
+export type LiveConfig = {
+    [K in keyof OpencodeGoConfig]-?: {
+        get(): OpencodeGoConfig[K];
+    };
+};
+/** Runtime schema for {@link OpencodeGoConfig}; every field stays live. */
+export declare const Config: z<Partial<OpencodeGoConfig>, LiveConfig>;
+/** Keep the Loader's references: reparsing them would detach live updates. */
+export declare function readConfig(config: LiveConfig): OpencodeGoConfig;
+/**
+ * Accept only an http(s) base without a query or fragment. Runs at load for the
+ * composition layer and on every profile edit, so a bad URL fails where it is
+ * written, never at first request.
+ * @param raw - the configured base URL.
+ * @returns the normalized base URL without trailing slashes.
+ */
+export declare function assertBaseURL(raw: string): string;

package/lib/types/config.js

@@ -0,0 +1,76 @@
+/**
+ * Configuration for one `dshopencodego` mount.
+ *
+ * DSH 0.1.7 hands the plugin *live references* for every declared field, so a
+ * profile edit reaches the next operation without a restart. This plugin
+ * targets that generation only: there is no settings-document path, no
+ * `installSection` fallback, and no plain-value codec.
+ *
+ * Self-contained constraints (URL shape, numeric bounds) fail at load for the
+ * composition layer and refuse the write for a profile edit.
+ *
+ * @module @dan-ai-studio/dshopencodego/config
+ */
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout';
+import z from '@deepseek-ai/schemastery';
+import { DEFAULT_BASE_URL } from "./catalog/constants.js";
+/** Credential reference resolving the OpenCode Go API key. */
+export const DEFAULT_API_KEY_ENV = 'OPENCODE_GO_API_KEY';
+/** Requests and pickers share this cache lifetime; explicit discovery revalidates immediately. */
+export const DEFAULT_REFRESH_MINUTES = 60;
+/** Default maximum idle interval while one stream read is outstanding. */
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000;
+/** Request-level bound on the base64-encoded image payload. */
+export const DEFAULT_MAX_REQUEST_IMAGE_BYTES = 6 * 1024 * 1024;
+/** Total-pixel budget for one request image. */
+export const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 1_440_000;
+/** Raw encoded-byte target for one request image before base64 expansion. */
+export const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 400_000;
+const fields = {
+    enabled: z.boolean().default(true),
+    modelVisibility: z.dict(z.boolean().required()).default({}),
+    apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
+    baseURL: z.string().default(DEFAULT_BASE_URL),
+    refreshMinutes: z.number().step(1).min(1).max(7 * 24 * 60).default(DEFAULT_REFRESH_MINUTES),
+    streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+    maxRequestImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_REQUEST_IMAGE_BYTES),
+    requestImagePixelBudget: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET),
+    requestImageMaxBytes: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_MAX_BYTES),
+    modelLimits: z.dict(z.union([z.const(null), z.object({
+            contextWindow: z.union([z.const(null), z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER)]),
+            maxTokens: z.union([z.const(null), z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER)]),
+        })])).default({}),
+    modelProtocols: z.dict(z.string()).default({}),
+};
+/** Plain resolved values used by the adapter. */
+export const PlainConfig = z.object(fields);
+/** Runtime schema for {@link OpencodeGoConfig}; every field stays live. */
+export const Config = z.object(Object.fromEntries(Object.entries(fields).map(([key, schema]) => [key, schema.volatile()])));
+/** Keep the Loader's references: reparsing them would detach live updates. */
+export function readConfig(config) {
+    return Object.fromEntries(Object.keys(fields)
+        .map(key => [key, config[key].get()]));
+}
+/**
+ * Accept only an http(s) base without a query or fragment. Runs at load for the
+ * composition layer and on every profile edit, so a bad URL fails where it is
+ * written, never at first request.
+ * @param raw - the configured base URL.
+ * @returns the normalized base URL without trailing slashes.
+ */
+export function assertBaseURL(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`dshopencodego: baseURL "${raw}" is not a valid URL`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`dshopencodego: baseURL "${raw}" must be http or https`);
+    }
+    if (url.search.length > 0 || url.hash.length > 0) {
+        throw new Error(`dshopencodego: baseURL "${raw}" must not carry a query or fragment`);
+    }
+    return url.toString().replace(/\/+$/, '');
+}

package/lib/types/conversion/context.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Harness request history converted into pi-ai's request vocabulary.
+ *
+ * Three shapes need care:
+ *
+ * - The system prompt has one home in pi-ai. `normalizeContext()` folds
+ *   `Context.systemPrompt` and `Context.tools` into a leading system message,
+ *   so this module only has to decide *which* text that is.
+ * - Tool results are their own message role and must carry the tool's *name*,
+ *   which the Harness records only on the preceding assistant tool call — so
+ *   names are recovered by walking the history.
+ * - Images go through the durable attachment service under the route's pixel
+ *   and encoded-byte budgets, and follow the host's offload protocol instead of
+ *   dropping content locally.
+ *
+ * The image helpers are reached through a namespace import on purpose: they are
+ * newer additions to the LLM seam, and a named import of one that a host build
+ * does not export fails at module instantiation — taking the whole plugin down
+ * before it can report anything. A namespace read fails only when the feature is
+ * actually used.
+ *
+ * @module @dan-ai-studio/dshopencodego/conversion/context
+ */
+import type { GenerateOptions, ImageAttachmentAccessResolver } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { Context as PiContext } from '@earendil-works/pi-ai';
+/** Image inputs that bind one request's attachments to the current tool world. */
+export interface PiImageRequestContext {
+    /** Durable provider resolving request-image bytes. */
+    readonly attachments: AttachmentStore;
+    /** Resolve current tool access separately from deterministic request images. */
+    readonly resolveImageAccess: ImageAttachmentAccessResolver;
+    /** Request-level bound on the base64 payload of retained images. */
+    readonly maxRequestImageBytes?: number;
+    /** Route pixel and encoded-byte budgets. */
+    readonly requestImagePolicy?: {
+        readonly maxPixels: number;
+        readonly maxBytes: number;
+    };
+}
+/**
+ * Convert Harness history into a pi-ai request context.
+ *
+ * The result is a plain `Context`; the adapter normalizes it into the branded
+ * transcript pi-ai's providers accept.
+ * @param options - the assembled request.
+ * @param images - attachment access; omitted selects the text-only conversion,
+ *   which refuses any image rather than silently dropping it.
+ * @param onReplayDegrade - called when stored replay metadata is unusable.
+ * @returns the pi-ai context.
+ * @throws {LlmError} `UNSUPPORTED_CONTENT` for an image this request cannot
+ *   carry, and `IMAGE_OFFLOAD_REQUIRED` when retained images still exceed the
+ *   base64 bound.
+ */
+export declare function toPiContext(options: GenerateOptions, images?: PiImageRequestContext, onReplayDegrade?: (reason: string) => void): Promise<PiContext>;

package/lib/types/conversion/context.js

@@ -0,0 +1,202 @@
+/**
+ * Harness request history converted into pi-ai's request vocabulary.
+ *
+ * Three shapes need care:
+ *
+ * - The system prompt has one home in pi-ai. `normalizeContext()` folds
+ *   `Context.systemPrompt` and `Context.tools` into a leading system message,
+ *   so this module only has to decide *which* text that is.
+ * - Tool results are their own message role and must carry the tool's *name*,
+ *   which the Harness records only on the preceding assistant tool call — so
+ *   names are recovered by walking the history.
+ * - Images go through the durable attachment service under the route's pixel
+ *   and encoded-byte budgets, and follow the host's offload protocol instead of
+ *   dropping content locally.
+ *
+ * The image helpers are reached through a namespace import on purpose: they are
+ * newer additions to the LLM seam, and a named import of one that a host build
+ * does not export fails at module instantiation — taking the whole plugin down
+ * before it can report anything. A namespace read fails only when the feature is
+ * actually used.
+ *
+ * @module @dan-ai-studio/dshopencodego/conversion/context
+ */
+import { brandString } from '@deepseek-ai/dsh-brand';
+import * as llm from '@deepseek-ai/dsh-llm';
+import { contentHasImage, LlmError, requestImageHandleText } from '@deepseek-ai/dsh-llm';
+import { requestImageDimensions } from '@deepseek-ai/dsh-attachment';
+import { toPiAssistant } from "./replay.js";
+/** Join the text blocks of one Harness message. */
+function flattenText(message) {
+    return message.content.filter(block => block.type === 'text').map(block => block.text).join('');
+}
+/** DSH 0.1.7 carries tool results under their own role. */
+function toolMessage(message) {
+    return message.role === 'tool' ? message : undefined;
+}
+/** pi-ai cannot replay an image attached to an assistant or system message. */
+function assertSupportedImageRoles(messages) {
+    for (const message of messages) {
+        if (message.role !== 'user' && toolMessage(message) === undefined && contentHasImage(message.content)) {
+            throw new LlmError(`pi-ai cannot represent an image in an in-history ${message.role} message`, 'UNSUPPORTED_CONTENT');
+        }
+    }
+}
+function toolsOf(options) {
+    return options.tools?.map(tool => ({
+        name: tool.name,
+        description: tool.description,
+        // ToolSchema.parameters is a JSON Schema object; pi-ai's TSchema is
+        // structurally JSON Schema, so it assigns directly.
+        parameters: tool.parameters,
+    }));
+}
+/**
+ * Select the system prompt for pi-ai.
+ *
+ * `options.system` wins when defined; otherwise a leading `system` message
+ * supplies it and leaves the converted history. An empty leading message sends
+ * no prompt at all.
+ */
+function splitSystemPrompt(options) {
+    if (options.system !== undefined)
+        return { systemPrompt: options.system, messages: options.messages };
+    const [first, ...rest] = options.messages;
+    if (first?.role !== 'system')
+        return { systemPrompt: undefined, messages: options.messages };
+    const text = flattenText(first);
+    return { systemPrompt: text.length > 0 ? text : undefined, messages: rest };
+}
+/** Every image occurrence this request will actually send. */
+function collectImageRefs(blocks, refs) {
+    for (const block of blocks) {
+        // An occurrence the surface already offloaded is a placeholder, not an image.
+        if (block.type === 'image' && block.offloaded !== true)
+            refs.set(block.attachment.attachmentId, block.attachment);
+    }
+}
+async function prepareRequestImages(messages, attachments, policy, signal) {
+    const refs = new Map();
+    for (const message of messages)
+        collectImageRefs(message.content, refs);
+    const ordered = [...refs.values()];
+    const prepared = await Promise.all(ordered.map(ref => attachments.readImageRequest(ref, { ...requestImageDimensions(ref.width, ref.height, policy.maxPixels), maxBytes: policy.maxBytes }, signal)));
+    const versions = new Map();
+    for (const [index, ref] of ordered.entries())
+        versions.set(ref.attachmentId, prepared[index]);
+    return versions;
+}
+/** Convert one message's content into pi-ai user content. */
+async function userContent(blocks, requestImages, resolveImageAccess) {
+    const content = [];
+    for (const block of blocks) {
+        if (block.type === 'text') {
+            if (block.text.length > 0)
+                content.push({ type: 'text', text: block.text });
+            continue;
+        }
+        if (block.type === 'image') {
+            const version = requestImages.get(block.attachment.attachmentId);
+            if (version === undefined) {
+                throw new LlmError('dshopencodego: an image in this request has no prepared bytes; image input requires the attachment service', 'UNSUPPORTED_CONTENT');
+            }
+            content.push({
+                type: 'text',
+                text: requestImageHandleText(block.attachment, version, resolveImageAccess(block.attachment)),
+            });
+            content.push({ type: 'image', data: Buffer.from(version.data).toString('base64'), mimeType: version.mediaType });
+        }
+        // Other block types are not user-input vocabulary for pi-ai.
+    }
+    return content.every(block => block.type === 'text')
+        ? content.map(block => block.text).join('')
+        : content;
+}
+/**
+ * Apply the host's image offload protocol to a request history.
+ *
+ * The host marks what the surface already offloaded. When the retained
+ * occurrences still exceed the base64 bound, the request fails with
+ * `IMAGE_OFFLOAD_REQUIRED` naming how many more must go — the host's retry
+ * protocol, not a local decision to drop content.
+ */
+function projectImagesForRequest(messages, images, requestImages) {
+    const offloadedImageText = llm.offloadedImageText;
+    const placeholder = (ref) => offloadedImageText(ref, images.resolveImageAccess(ref));
+    if (images.maxRequestImageBytes !== undefined) {
+        const over = llm.requiredImageOffload(messages, { representation: 'base64', maxBytes: images.maxRequestImageBytes, byteQuantum: 1 }, block => requestImages.get(block.attachment.attachmentId).bytes);
+        if (over > 0) {
+            throw new LlmError(`request images exceed the ${images.maxRequestImageBytes}-byte base64 bound;`
+                + ` ${over} more oldest occurrence(s) must be offloaded`, llm.IMAGE_OFFLOAD_REQUIRED_CODE, { offloadImages: over });
+        }
+    }
+    return llm.projectOffloadedImages(messages, placeholder);
+}
+/**
+ * Convert Harness history into a pi-ai request context.
+ *
+ * The result is a plain `Context`; the adapter normalizes it into the branded
+ * transcript pi-ai's providers accept.
+ * @param options - the assembled request.
+ * @param images - attachment access; omitted selects the text-only conversion,
+ *   which refuses any image rather than silently dropping it.
+ * @param onReplayDegrade - called when stored replay metadata is unusable.
+ * @returns the pi-ai context.
+ * @throws {LlmError} `UNSUPPORTED_CONTENT` for an image this request cannot
+ *   carry, and `IMAGE_OFFLOAD_REQUIRED` when retained images still exceed the
+ *   base64 bound.
+ */
+export async function toPiContext(options, images, onReplayDegrade) {
+    assertSupportedImageRoles(options.messages);
+    const split = splitSystemPrompt(options);
+    const resolveImageAccess = images?.resolveImageAccess ?? (() => undefined);
+    const policy = images?.requestImagePolicy ?? { maxPixels: 1_440_000, maxBytes: 400_000 };
+    const requestImages = images === undefined
+        ? new Map()
+        : await prepareRequestImages(split.messages, images.attachments, policy, options.signal);
+    const history = images === undefined
+        ? split.messages
+        : projectImagesForRequest(split.messages, images, requestImages);
+    const toolNames = new Map();
+    const messages = [];
+    for (const message of history) {
+        const tool = toolMessage(message);
+        if (tool !== undefined) {
+            const content = await userContent(tool.content, requestImages, resolveImageAccess);
+            messages.push({
+                role: 'toolResult',
+                toolCallId: tool.toolCallId,
+                toolName: toolNames.get(tool.toolCallId) ?? 'unknown',
+                content: typeof content === 'string'
+                    ? [{ type: 'text', text: content.length > 0 ? content : '(no output)' }]
+                    : content,
+                isError: tool.isError ?? false,
+                timestamp: 0,
+            });
+            continue;
+        }
+        if (message.role === 'system') {
+            // pi-ai keeps one leading system message; a later one folds into a user
+            // message so its position in the history survives.
+            messages.push({ role: 'user', content: flattenText(message), timestamp: 0 });
+            continue;
+        }
+        if (message.role === 'assistant') {
+            const assistant = toPiAssistant(message, onReplayDegrade);
+            for (const block of assistant.content) {
+                if (block.type === 'toolCall')
+                    toolNames.set(brandString(block.id), block.name);
+            }
+            messages.push(assistant);
+            continue;
+        }
+        const content = await userContent(message.content, requestImages, resolveImageAccess);
+        messages.push({ role: 'user', content, timestamp: 0 });
+    }
+    const tools = toolsOf(options);
+    return {
+        ...split.systemPrompt === undefined ? {} : { systemPrompt: split.systemPrompt },
+        messages,
+        ...tools === undefined || tools.length === 0 ? {} : { tools },
+    };
+}

package/lib/types/conversion/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Harness ⇄ pi-ai conversion.
+ * @module @dan-ai-studio/dshopencodego/conversion
+ */
+export { toPiContext } from './context.ts';
+export type { PiImageRequestContext } from './context.ts';
+export { classifyPiAiError, mapStopReason, mapUsage, toStreamChunks } from './stream.ts';
+export { toPiAssistant, toPiReplayState } from './replay.ts';
+export type { PiAiReplayBlock, PiAiReplayResponse } from './replay.ts';

package/lib/types/conversion/index.js

@@ -0,0 +1,7 @@
+/**
+ * Harness ⇄ pi-ai conversion.
+ * @module @dan-ai-studio/dshopencodego/conversion
+ */
+export { toPiContext } from "./context.js";
+export { classifyPiAiError, mapStopReason, mapUsage, toStreamChunks } from "./stream.js";
+export { toPiAssistant, toPiReplayState } from "./replay.js";

package/lib/types/conversion/replay.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Durable pi-ai replay metadata and assistant-history reconstruction.
+ *
+ * Harness content is the durable source of truth for text and tool calls; this
+ * module stores only the provider-native metadata needed to rebuild a pi-ai
+ * assistant message on a later request (signatures, response ids, native
+ * thinking level). When that metadata is unusable — another adapter wrote it, a
+ * future version wrote it, or it no longer matches the content — the message
+ * degrades to provider-neutral history instead of failing the request.
+ *
+ * @module @dan-ai-studio/dshopencodego/conversion/replay
+ */
+import type { Message, ReplayEnvelope } from '@deepseek-ai/dsh-llm';
+import type { Api, AssistantMessage } from '@earendil-works/pi-ai';
+/** Per-block half of the replay envelope, one entry per content block. */
+export type PiAiReplayBlock = {
+    type: 'text';
+    textSignature?: string;
+} | {
+    type: 'reasoning';
+    thinkingSignature?: string;
+    redacted?: boolean;
+} | {
+    type: 'tool-call';
+    thoughtSignature?: string;
+};
+/** Versioned response-level half of the replay envelope. */
+export interface PiAiReplayResponse {
+    kind: 'pi-ai';
+    version: 2;
+    api: Api;
+    provider: string;
+    /** Requested model identity, matching the durable assistant source. */
+    model: string;
+    /** Provider-reported model, when it differs from the request. */
+    responseModel?: string;
+    responseId?: string;
+    /** Provider-native effort, replayed as-is; absence stays absent. */
+    providerThinkingLevel?: string;
+    stopReason: AssistantMessage['stopReason'];
+}
+/**
+ * Project a successful pi-ai response into the minimal durable replay state.
+ * @param message - the completed native response.
+ * @param requestedModel - request identity stored on the assistant source.
+ * @returns the versioned lossless-JSON envelope; `blocks` is index-aligned with
+ *   the streamed blocks, so assembly prunes an entry with its block.
+ */
+export declare function toPiReplayState(message: AssistantMessage, requestedModel?: string): ReplayEnvelope;
+/**
+ * Convert one durable assistant message into pi-ai history.
+ * @param message - assistant content with its model source and optional replay metadata.
+ * @param onDegrade - called with the reason when unusable metadata falls back.
+ * @returns the native assistant message, or a provider-neutral reconstruction.
+ */
+export declare function toPiAssistant(message: Message, onDegrade?: (reason: string) => void): AssistantMessage;