dsh-magpie-connect 0.2.0

package/lib/types/adapter/events.d.ts

@@ -0,0 +1,164 @@
+/**
+ * pi-ai AssistantMessageEvent -> harness StreamChunks.
+ * The chunk stream must end with `usage` then `finish`.
+ */
+export type HarnessChunk = {
+    type: 'block-start';
+    index: number;
+    blockType: 'text' | 'reasoning' | 'tool-call';
+} | {
+    type: 'text-delta';
+    index: number;
+    text: string;
+} | {
+    type: 'block-end';
+    index: number;
+    block: {
+        type: 'text';
+        text: string;
+    } | {
+        type: 'reasoning';
+        text: string;
+    } | {
+        type: 'tool-call';
+        id: string;
+        name: string;
+        arguments: string;
+    };
+} | {
+    type: 'reasoning-delta';
+    index: number;
+    text: string;
+} | {
+    type: 'tool-call-delta';
+    index: number;
+    id: string;
+    name?: string;
+    argumentsDelta: string;
+} | {
+    type: 'usage';
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+} | {
+    type: 'finish';
+    reason: FinishReason;
+    replayState?: unknown;
+};
+export type FinishReason = {
+    kind: 'stop';
+} | {
+    kind: 'max-tokens';
+} | {
+    kind: 'tool-calls';
+} | {
+    kind: 'aborted';
+    failure: {
+        message: string;
+        code: string;
+    };
+} | {
+    kind: 'error';
+    failure: {
+        message: string;
+        code: string;
+    };
+};
+/** pi-ai AssistantMessageEvent vocabulary (subset we consume). */
+export type PiEvent = {
+    type: 'start';
+    partial: PiAssistantPartial;
+} | {
+    type: 'text_start';
+    contentIndex: number;
+    partial: PiAssistantPartial;
+} | {
+    type: 'text_delta';
+    contentIndex: number;
+    delta: string;
+    partial: PiAssistantPartial;
+} | {
+    type: 'text_end';
+    contentIndex: number;
+    content: string;
+    partial: PiAssistantPartial;
+} | {
+    type: 'thinking_start';
+    contentIndex: number;
+    partial: PiAssistantPartial;
+} | {
+    type: 'thinking_delta';
+    contentIndex: number;
+    delta: string;
+    partial: PiAssistantPartial;
+} | {
+    type: 'thinking_end';
+    contentIndex: number;
+    content: string;
+    partial: PiAssistantPartial;
+} | {
+    type: 'toolcall_start';
+    contentIndex: number;
+    partial: PiAssistantPartial;
+} | {
+    type: 'toolcall_delta';
+    contentIndex: number;
+    delta: string;
+    partial: PiAssistantPartial;
+} | {
+    type: 'toolcall_end';
+    contentIndex: number;
+    toolCall: {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+    partial: PiAssistantPartial;
+} | {
+    type: 'done';
+    message: PiDoneMessage;
+} | {
+    type: 'error';
+    error: PiDoneMessage;
+};
+export interface PiAssistantPartial {
+    content: Array<{
+        type: string;
+        id?: string;
+        name?: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+/** pi-ai AssistantMessage content block (done/error messages carry these). */
+export type PiAssistantBlock = {
+    type: string;
+    [key: string]: unknown;
+};
+export interface PiDoneMessage {
+    api: string;
+    provider: string;
+    model: string;
+    responseModel?: string;
+    responseId?: string;
+    content: PiAssistantBlock[];
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        totalTokens: number;
+    };
+    stopReason: 'stop' | 'length' | 'toolUse' | 'error' | 'aborted';
+    errorMessage?: string;
+    [key: string]: unknown;
+}
+/**
+ * Translate one pi-ai event stream into harness chunks. pi-ai never throws
+ * mid-stream: failures arrive as `error` events and become error/aborted
+ * finish chunks.
+ */
+export declare function toStreamChunks(events: AsyncIterable<PiEvent>, contextWindow: number): AsyncGenerator<HarnessChunk>;

package/lib/types/adapter/magpie-adapter.d.ts

@@ -0,0 +1,173 @@
+import { ModelCatalog } from './catalog.ts';
+import { type HarnessChunk, type PiEvent } from './events.ts';
+import { type AttachmentStore, type HarnessGenerateOptions } from './messages.ts';
+/**
+ * Magpie LAN gateway adapter: registers as a DSH LlmAdapter and streams
+ * directly from the configured API root (e.g. `…/v1`) — chat completions for most models plus the
+ * Responses API for responses-only models (Muse Spark / Codex / Grok lanes).
+ *
+ * Adapter contract: dsh-llm LlmAdapter (providerInfo/listModels/resolveModel/
+ * prepareCall/stream) — structural, no host import.
+ *
+ * Images resolve through the harness attachment service; thinking levels come
+ * from the gateway catalog and forward verbatim (including the `none`/`ultra`
+ * extensions pi-ai does not model).
+ */
+/** Structural pi-ai provider surface the adapter consumes. */
+export interface PiProviderLike {
+    stream(model: unknown, context: unknown, options: unknown): AsyncIterable<PiEvent>;
+    streamSimple(model: unknown, context: unknown, options: unknown): AsyncIterable<PiEvent>;
+}
+/** Live endpoint read per request so the settings page applies without restart. */
+export interface RuntimeEndpoint {
+    /** Versioned API root, e.g. `http://api.lan/v1` (no trailing slash). */
+    baseUrl(): string;
+    /** Bearer key sent to the gateway. */
+    apiKey(): string;
+}
+export declare const PROVIDER_ID = "dsh-magpie-connect";
+/** Default picker label for the default route id. */
+export declare const DEFAULT_DISPLAY_NAME = "magpie";
+export interface MagpieModelInfo {
+    id: string;
+    name: string;
+    contextWindow: number;
+    maxTokens: number;
+}
+export interface CatalogLike {
+    list(): string[];
+    decision(model: string): {
+        allowed: boolean;
+        source: string;
+        known: boolean;
+    };
+    getEntry?(model: string): {
+        nativeEndpoints: string[];
+    } | undefined;
+    reasoningFor?(model: string): {
+        efforts: Array<{
+            id: string;
+            name: string;
+            description?: string;
+        }>;
+        defaultEffort: string;
+    } | undefined;
+    thinks?(model: string): boolean;
+    supportsImage?(model: string): boolean;
+    supportsEffort?(model: string, effort: string): boolean;
+    requiresResponsesApi?(model: string): boolean;
+    contextWindowFor?(model: string): number;
+    maxTokensFor?(model: string): number;
+}
+/** Connection-setup retries (429/5xx with backoff, interruptible by abort). */
+export declare const DEFAULT_MAX_RETRIES = 2;
+/** Overall SDK request cap (replaces the OpenAI SDK 10 min default). */
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+/** Max wait for the first upstream event (queueing happens here). */
+export declare const DEFAULT_FIRST_EVENT_TIMEOUT_MS = 90000;
+/** Max silence between upstream events once streaming. */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 60000;
+/**
+ * Plan the wire `reasoning_effort` for one request. Returns the effort to
+ * send via `provider.stream`, or undefined to omit the field (gateway
+ * default applies).
+ *
+ * - `off` aliases `none` (explicitly disable thinking).
+ * - `none` sends only when the model lists it; otherwise omitted.
+ * - `ultra` sends when listed; otherwise degrades to the highest listed
+ *   strength level (`max` → … → `minimal`).
+ * - Known strength levels send verbatim when listed or when the model thinks
+ *   without a ladder (gateway decides); otherwise clamped up-then-down to
+ *   the nearest listed level so a stale remembered value never 400s.
+ * - Unknown values and non-reasoning models omit.
+ */
+export declare function planReasoningEffort(requested: unknown, model: string, catalog: Pick<CatalogLike, 'thinks' | 'supportsEffort' | 'reasoningFor'>): string | undefined;
+export declare class MagpieAdapter {
+    #private;
+    constructor(catalog: CatalogLike, options?: {
+        magpieBaseUrl?: string;
+        baseUrl?: string;
+        providerOverride?: unknown;
+        /** Route id registered into DSH (model `provider` field + pi-ai provider tag). */
+        providerId?: string;
+        /** Display name reported via providerInfo (model picker grouping label). */
+        displayName?: string;
+        /** Gateway credential (LAN needs none). */
+        apiKey?: string;
+        /**
+         * Live endpoint read per request (settings page). Falls back to the
+         * static `magpieBaseUrl`/`apiKey` options when absent.
+         */
+        runtime?: RuntimeEndpoint;
+        /** Connection-setup retries for 429/5xx (default 2). */
+        maxRetries?: number;
+        /** Overall SDK request cap in ms (default 300000). */
+        timeoutMs?: number;
+        /** Stall watchdog: max wait for the first upstream event in ms (default 90000; <=0 disables). */
+        firstEventTimeoutMs?: number;
+        /** Stall watchdog: max silence between upstream events in ms (default 60000; <=0 disables). */
+        idleTimeoutMs?: number;
+        /** Harness attachment service for image bytes (wired in index.ts). */
+        resolveAttachments?: () => AttachmentStore | undefined;
+    });
+    providerInfo(provider: string): {
+        id: string;
+        name: string;
+    };
+    /**
+     * dsh-llm calls this unconditionally at registration.
+     * undefined = the host default retry policy.
+     */
+    providerRetryPolicy(_provider: string): undefined;
+    /** Advisory catalog for the DSH model picker (deduped; dsh-llm rejects duplicates). */
+    listModels(provider: string): Array<{
+        provider: string;
+        id: string;
+        name: string;
+        inputModalities: string[];
+    }>;
+    resolveModel(provider: string, model: string): {
+        provider: string;
+        id: string;
+        name: string;
+        inputModalities: string[];
+        context: {
+            contextWindow: number;
+        };
+        defaultMaxTokens: number;
+        reasoning?: {
+            efforts: ReadonlyArray<{
+                id: string;
+                name: string;
+                description?: string;
+            }>;
+            defaultEffort?: string;
+        };
+    };
+    prepareCall(provider: string, model: string, _signal?: AbortSignal): Promise<{
+        model: ReturnType<MagpieAdapter['resolveModel']>;
+        stream: (options: HarnessGenerateOptions) => AsyncGenerator<HarnessChunk>;
+    }>;
+    /**
+     * Stream one chat turn from the Magpie gateway: a single pi-ai stream,
+     * translated to harness chunks verbatim. Upstream failures (rate limit,
+     * auth, timeout, transport) arrive as classified finish reasons, and
+     * turn-level retries stay owned by DSH.
+     *
+     * A stall watchdog races every upstream event against a timer: on expiry
+     * the upstream is aborted and the turn ends fast with a TIMEOUT error
+     * instead of hanging to the SDK/harness timeout.
+     */
+    stream(options: HarnessGenerateOptions): AsyncGenerator<HarnessChunk>;
+    /** Expose the live catalog snapshot for diagnostics. */
+    catalogStatus(): {
+        total: number;
+        exposed: number;
+    };
+    decisionFor(model: string): {
+        allowed: boolean;
+        source: string;
+    };
+}
+/** Build the adapter over a live catalog. */
+export declare function createMagpieAdapter(catalog: ModelCatalog): MagpieAdapter;

package/lib/types/adapter/messages.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Harness GenerateOptions -> pi-ai Context conversion, with image support.
+ *
+ * Text-only requests convert synchronously (`toPiContext`); requests carrying
+ * durable image blocks resolve bytes through the harness attachment service
+ * (`toPiContextWithImages`, async). pi-ai then encodes images as OpenAI
+ * `image_url` (completions) or `input_image` (responses) parts.
+ */
+export interface ImageAttachmentRef {
+    attachmentId: string;
+    mediaType: string;
+    bytes: number;
+    width: number;
+    height: number;
+    name?: string;
+}
+export interface FileAttachmentRef {
+    attachmentId: string;
+    name: string;
+    bytes: number;
+}
+export interface HarnessTool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+export type HarnessBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+} | {
+    type: 'tool-call';
+    id: string;
+    name: string;
+    arguments: string;
+} | {
+    type: 'image';
+    attachment: ImageAttachmentRef;
+    offloaded?: true;
+    [key: string]: unknown;
+} | {
+    type: 'file';
+    attachment: FileAttachmentRef;
+    [key: string]: unknown;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    content: HarnessBlock[];
+    isError?: boolean;
+    [key: string]: unknown;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface HarnessMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool' | 'developer';
+    content: HarnessBlock[];
+    source?: {
+        kind: string;
+        provider?: string;
+        model?: string;
+        callId?: string;
+        [key: string]: unknown;
+    };
+    toolCallId?: string;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+export interface HarnessGenerateOptions {
+    provider: string;
+    model: string;
+    messages: HarnessMessage[];
+    system?: string;
+    tools?: HarnessTool[];
+    maxTokens?: number;
+    temperature?: number;
+    reasoningEffort?: string;
+    signal?: AbortSignal;
+    [key: string]: unknown;
+}
+/** pi-ai message vocabulary (subset we emit). */
+export type PiMessage = {
+    role: 'user';
+    content: string | PiContentBlock[];
+    timestamp: number;
+} | {
+    role: 'assistant';
+    content: PiAssistantBlock[];
+    api: 'openai-completions' | 'openai-responses';
+    provider: string;
+    model: string;
+    usage: PiUsage;
+    stopReason: 'stop' | 'toolUse';
+    timestamp: number;
+} | {
+    role: 'toolResult';
+    toolCallId: string;
+    toolName: string;
+    content: PiContentBlock[];
+    isError: boolean;
+    timestamp: number;
+};
+export type PiAssistantBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    thinking: string;
+} | {
+    type: 'toolCall';
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+export type PiContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+};
+export interface PiUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export interface PiTool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+export interface PiContext {
+    systemPrompt?: string;
+    messages: PiMessage[];
+    tools?: PiTool[];
+}
+/** Attachment service surface we consume (structural subset of dsh-attachment). */
+export interface AttachmentStore {
+    readImageRequest(ref: ImageAttachmentRef, target: {
+        width: number;
+        height: number;
+        maxBytes: number;
+    }, signal?: AbortSignal): Promise<{
+        data: Uint8Array;
+        mediaType: string;
+        bytes: number;
+        width: number;
+        height: number;
+    }>;
+}
+export interface RequestImageVersion {
+    data: Uint8Array;
+    mediaType: string;
+    bytes: number;
+    width: number;
+    height: number;
+}
+export declare function zeroUsage(): PiUsage;
+/** True when any message carries a retained (non-offloaded) image block. */
+export declare function contentHasImage(messages: readonly HarnessMessage[]): boolean;
+/** Request target for one attachment: fit within the pixel budget, cap bytes. */
+export declare function requestImageTarget(ref: ImageAttachmentRef): {
+    width: number;
+    height: number;
+    maxBytes: number;
+};
+/**
+ * Resolve every retained image to request bytes. Offloaded occurrences need
+ * no bytes (placeholder text only) and are skipped here.
+ */
+export declare function prepareRequestImages(messages: readonly HarnessMessage[], attachments: AttachmentStore, signal?: AbortSignal): Promise<Map<string, RequestImageVersion>>;
+/** User/tool-result content with images resolved to handle text + bytes. */
+export declare function userContentWithImages(blocks: HarnessBlock[], requestImages: Map<string, RequestImageVersion>): string | PiContentBlock[];
+/**
+ * Text-only conversion (no image bytes needed). Images without resolved
+ * bytes cannot be sent — callers must route image-bearing requests through
+ * `toPiContextWithImages` instead.
+ */
+export declare function toPiContext(options: HarnessGenerateOptions, entryEndpoints?: readonly string[]): PiContext;
+/**
+ * Image-aware conversion: retained images resolve to request bytes via the
+ * attachment service; offloaded images become placeholder text.
+ */
+export declare function toPiContextWithImages(options: HarnessGenerateOptions, attachments: AttachmentStore, entryEndpoints?: readonly string[]): Promise<PiContext>;

package/lib/types/adapter/watchdog.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Stall watchdog for upstream event streams.
+ *
+ * pi-ai surfaces transport failures as `error` events, but a silently
+ * stalled SSE connection (headers sent, then no bytes ever again) produces
+ * *no* event at all: the consumer's `for await` blocks until the SDK-level
+ * overall timeout or the harness timeout. This wrapper races every `next()`
+ * against a timer and, on expiry, aborts the upstream (best effort, via
+ * `onTimeout`) and yields a synthetic `error` event so the normal chunk
+ * translation turns the stall into a fast `TIMEOUT` finish instead of a
+ * minutes-long hang.
+ *
+ * Two phases: time-to-first-event (queueing happens here) and idle-between-
+ * events (a healthy stream emits frequently). Either phase accepts a
+ * non-positive value to disable its timer (wait forever, the old behavior).
+ */
+import type { PiEvent } from './events.ts';
+export interface StallTimeouts {
+    /** Max wait for the first upstream event (connection + queueing). */
+    firstEventTimeoutMs: number;
+    /** Max silence between two upstream events once streaming. */
+    idleTimeoutMs: number;
+}
+export declare function withStallTimeout(events: AsyncIterable<PiEvent>, timeouts: StallTimeouts, options?: {
+    model?: string;
+    onTimeout?: () => void;
+}): AsyncGenerator<PiEvent>;

package/lib/types/client/i18n.d.ts

@@ -0,0 +1,15 @@
+export declare const NS = "magpie-connect";
+type Dict = Record<string, string>;
+export declare const EN: Dict;
+export declare const ZH: Dict;
+export interface LocaleRuntime {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): {
+        active?: string;
+        revision?: number;
+    };
+}
+export declare function setLocaleRuntime(runtime: LocaleRuntime | undefined): void;
+export declare function text(key: string, params?: Record<string, unknown>): string;
+export declare function useLocaleRevision(): void;
+export {};

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

@@ -0,0 +1,31 @@
+import { NS } from './i18n.ts';
+interface Slots {
+    inject(name: string, fn: () => unknown): unknown;
+    register(entry: {
+        name: string;
+        id: string;
+        order: number;
+        locale?: string;
+        label?: () => string;
+    }, component: unknown): unknown;
+}
+interface ClientLocale {
+    register(ns: string, dicts: {
+        zh: Record<string, string>;
+        en: Record<string, string>;
+    }): unknown;
+    register(ns: string, lang: string, dict: Record<string, string>): () => void;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): {
+        active?: string;
+        revision?: number;
+    };
+}
+export interface ClientContext {
+    locale: ClientLocale;
+    slots: Slots;
+    effect(fn: () => () => void, label?: string): unknown;
+}
+export declare function apply(ctx: ClientContext): void;
+export declare const inject: string[];
+export { NS };

package/lib/types/client/model-list.d.ts

@@ -0,0 +1,53 @@
+import { type CandidateRow, type ModelRow } from './model-visibility.ts';
+/**
+ * The model list of the Magpie gateway, plus the action that asks the gateway
+ * what it serves.
+ *
+ * The list shows only *enabled* models: this plugin's picker is the gateway's
+ * whole catalog minus a hidden set, so a hidden row would be a row that is
+ * invisible everywhere it matters. Hidden models live in the fetch dialog
+ * instead, which is the one surface that can both show and re-enable them.
+ * That is also why a row's control is a delete button rather than a
+ * checkbox — with nothing hidden on screen, unticking and deleting are the
+ * same act, and only deleting reads correctly.
+ *
+ * Fetching asks the endpoint **the form currently shows** — including a key
+ * typed but not yet saved — so filling in a gateway is one pass instead of
+ * save-then-return. The reply is candidates the user picks from, never
+ * configuration written behind them.
+ */
+export type { CandidateRow, ModelRow };
+/** Props of {@link ModelListEditor}. */
+export interface ModelListEditorProps {
+    /** The rows as currently drafted (the gateway's directory). */
+    models: readonly ModelRow[];
+    /** The ids the picker currently offers (the drafted rows minus the hidden set). */
+    visibleIds: ReadonlySet<string>;
+    /**
+     * Ask the gateway for its current catalog. Rejects with a display-ready
+     * message; the editor owns showing it.
+     */
+    onFetch: () => Promise<readonly CandidateRow[]>;
+    /** Hide one model (the list's delete action). */
+    onRemove: (id: string) => void;
+    /** Replace the whole hidden set (the dialog's adopt action). */
+    onHiddenChange: (hidden: string[]) => void;
+    /** Disable every control (a pending save/probe). */
+    disabled: boolean;
+    /** Whether the connection fields are filled in enough to ask the gateway. */
+    fetchable: boolean;
+    /**
+     * Autosave state for the list itself. Shown inline on this card, not on the
+     * connection card above: the user's eye is here when they remove a row, and
+     * a write failure must land where the change was made.
+     */
+    status: 'idle' | 'saving' | 'saved' | 'error';
+    /** Autosave failure message, when {@link status} is `error`. */
+    failure?: string | undefined;
+}
+/**
+ * Render the model list with its fetch action.
+ * @param props - the drafted rows, the current visibility set, and the fetch/toggle callbacks.
+ * @returns the model-list editor.
+ */
+export declare function ModelListEditor(props: ModelListEditorProps): unknown;