dsh-magpie-connect 0.2.0

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

@@ -0,0 +1,65 @@
+/**
+ * Pure decisions behind the model-list editor.
+ *
+ * Kept out of the `.tsx` component so `node --test` can import them directly
+ * (Node runs `.ts` but not `.tsx`), which is where the visibility rules that
+ * the dialog actually depends on get their coverage.
+ */
+/** One model row as the models route reports it. */
+export interface ModelRow {
+    id: string;
+    displayName: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    image: boolean;
+    responsesOnly: boolean;
+    reasoning: boolean;
+    efforts: string[];
+    hidden: boolean;
+}
+/** One discovered candidate: a {@link ModelRow} without this plugin's own visibility flag. */
+export type CandidateRow = Omit<ModelRow, 'hidden'>;
+/**
+ * Which candidates a fresh fetch should start checked.
+ *
+ * This plugin's list decides *visibility*, not membership, so the dialog
+ * answers "which models should the picker offer" and every candidate the
+ * picker already offers starts ticked. The upstream pi-ai editor inverts this
+ * (known rows start unchecked) because there a row is an explicit catalog
+ * entry — adopting there would rewrite the user's own capacities.
+ * @param candidates - the models the gateway just listed.
+ * @param visibleIds - ids the picker currently offers.
+ * @returns the ids that should start checked.
+ */
+export declare function initialPicked(candidates: readonly CandidateRow[], visibleIds: ReadonlySet<string>): Set<string>;
+/**
+ * The hidden set an adopted selection produces.
+ *
+ * Only the offered candidates are considered: the saved hidden set is pruned
+ * to the live directory on write, so an id the gateway did not just offer is
+ * not something this save should carry. Leaving one in would resurrect a
+ * stale entry the settings page can no longer show or clear.
+ * @param candidates - the candidates the dialog offered.
+ * @param picked - the candidate ids the user left checked.
+ * @returns the hidden ids to save.
+ */
+export declare function hiddenAfterAdopt(candidates: readonly CandidateRow[], picked: ReadonlySet<string>): string[];
+/**
+ * Hide one model. The list shows only enabled models, so its delete button is
+ * this: the row leaves the list and rejoins via the fetch dialog.
+ * @param hidden - the hidden set before the action.
+ * @param id - the model to hide.
+ * @returns the hidden set after the action.
+ */
+export declare function hideOne(hidden: readonly string[], id: string): string[];
+/**
+ * Toggle every visible candidate, used by the dialog's select-all action.
+ *
+ * Clearing removes only what the current query shows, so a filtered
+ * select-all followed by a filtered clear does not silently un-pick matches
+ * the query was hiding.
+ * @param current - the checked set before the action.
+ * @param visible - the candidates the query currently shows.
+ * @returns the checked set after the action.
+ */
+export declare function toggleAllPicked(current: ReadonlySet<string>, visible: readonly CandidateRow[]): Set<string>;

package/lib/types/client/nav-icon.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The Magpie glyph in the settings nav rail.
+ *
+ * `settings.section` projects only `id` / `order` / `label` (see
+ * `SettingsRoot` in `dsh-client-ui-settings-general`), and its nav glyph is a
+ * hardcoded `navIcon(id)` map — `account`, `models`, `agent-presets`,
+ * `plugins`, `archived-sessions`, then a fallback gear for every other id.
+ * A registrant cannot supply an icon, so this plugin's row would draw the
+ * fallback gear.
+ *
+ * Until that slot grows an `icon` field, the row is claimed after the dialog
+ * mounts and the gear is swapped for the mark: the same technique
+ * `dshmarket` and `dsh-better-sidebar` use. Scope is deliberately narrow —
+ * only the row whose visible text equals this plugin's own localized section
+ * label is marked, the marker and the stylesheet belong to a `ctx.effect` so
+ * they are removed with the fiber, and a locale switch re-claims the row
+ * through the MutationObserver so the label and the glyph never disagree.
+ *
+ * Delete this module (and its call in `client/index.ts`) the day
+ * `settings.section` grows an `icon` field.
+ */
+/**
+ * Whether a nav row is this plugin's own.
+ *
+ * Pure, and the only decision this feature makes: the row whose visible text
+ * is the section label the shell is currently projecting. An empty label
+ * matches nothing — a locale that has not resolved yet must not mark the
+ * whole nav.
+ * @param rowText - the row's visible text.
+ * @param wantedLabel - this plugin's current section label.
+ * @returns whether the row belongs to this plugin.
+ */
+export declare function isOwnNavRow(rowText: unknown, wantedLabel: unknown): boolean;
+/** Minimal surface this feature needs from the client context. */
+export interface NavIconContext {
+    effect(fn: () => () => void, label?: string): unknown;
+}
+/**
+ * Install the nav glyph.
+ * @param ctx - client context, for effect ownership.
+ * @param resolveLabel - this plugin's current section label (the same thunk the
+ *   `settings.section` registration passes), re-read on every sync so a locale
+ *   switch is picked up without re-registering.
+ */
+export declare function installSettingsNavIcon(ctx: NavIconContext, resolveLabel: () => string): void;

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

@@ -0,0 +1,6 @@
+import { NS } from './i18n.ts';
+import { type ModelRow } from './model-list.tsx';
+export declare const PLUGIN_VERSION: string;
+export type { ModelRow };
+export declare function MagpieSettings(): unknown;
+export { NS };

package/lib/types/client/write-queue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Serialize one value's writes so rapid edits cannot race or lose the last one.
+ *
+ * The model list autosaves: every remove and every dialog adoption posts the
+ * hidden set. Clicking remove three times in a second must not fire three
+ * overlapping requests whose responses land out of order — the last state the
+ * user saw has to be the last state that reaches the disk.
+ *
+ * The policy is deliberately "one in flight, keep only the newest pending":
+ * intermediate states are not worth uploading, and the final one always is.
+ * @param write - performs one write for a value; its rejection is reported.
+ * @returns a scheduler with `push`, `idle`, and a `status` reader.
+ */
+export declare function createWriteQueue<T>(write: (value: T) => Promise<void>, onSettled?: (outcome: {
+    ok: true;
+} | {
+    ok: false;
+    error: unknown;
+}) => void): {
+    push: (value: T) => void;
+    /** Resolves when nothing is in flight and nothing is queued. */
+    idle: () => Promise<void>;
+    /** Whether a write is running or waiting. */
+    pending: () => boolean;
+};

package/lib/types/config.d.ts

@@ -0,0 +1,66 @@
+export interface DshMagpieConnectConfig {
+    /**
+     * Provider route id registered into DSH (the grouping key in the model
+     * picker). Changing it after sessions already reference the old id will
+     * orphan those model selections — prefer `displayName` for a cosmetic
+     * rename.
+     */
+    providerId?: string;
+    /**
+     * Display name shown in the model picker for this provider.
+     * Defaults to the explicit `providerId` when one is given,
+     * otherwise to `'magpie'`.
+     */
+    displayName?: string;
+    /**
+     * Versioned API root, e.g. `http://api.lan/v1`. The version is part of the
+     * value, not something this plugin adds: a gateway that later serves `/v2`
+     * or `/v3` is reached by changing this one string. Trailing slashes are
+     * stripped; the path is kept. Empty = not configured.
+     */
+    baseUrl?: string;
+    /** Gateway credential. Required: empty means not configured (key or URL missing both gate). */
+    apiKey?: string;
+    /**
+     * Plugin state directory (status snapshot, settings file, catalog cache).
+     * Defaults to `~/.dsh-magpie-connect`.
+     */
+    dataDir?: string;
+    /** Model list refresh interval in seconds. */
+    refreshSeconds?: number;
+    /**
+     * Connection-setup retries for transient upstream failures (429/5xx with
+     * backoff). Turn-level retries stay owned by DSH.
+     */
+    maxRetries?: number;
+    /** Overall upstream request cap in milliseconds. */
+    timeoutMs?: number;
+    /**
+     * Stall watchdog: max wait for the first upstream event in milliseconds
+     * (queueing happens here). Non-positive disables that phase.
+     */
+    firstEventTimeoutMs?: number;
+    /**
+     * Stall watchdog: max silence between upstream events in milliseconds.
+     * Non-positive disables that phase.
+     */
+    idleTimeoutMs?: number;
+}
+export declare const defaults: {
+    readonly providerId: "dsh-magpie-connect";
+    readonly displayName: "magpie";
+    readonly baseUrl: "";
+    readonly apiKey: "";
+    readonly refreshSeconds: 300;
+    readonly maxRetries: 2;
+    readonly timeoutMs: 300000;
+    readonly firstEventTimeoutMs: 90000;
+    readonly idleTimeoutMs: 60000;
+};
+export type ResolvedConfig = Required<Pick<DshMagpieConnectConfig, 'providerId' | 'refreshSeconds'>> & DshMagpieConnectConfig & {
+    displayName: string;
+    baseUrl: string;
+    apiKey: string;
+    dataDir: string;
+};
+export declare function resolveConfig(config?: DshMagpieConnectConfig): ResolvedConfig;

package/lib/types/index.d.ts

@@ -0,0 +1,88 @@
+import { ModelCatalog } from './adapter/catalog.ts';
+import { type DshMagpieConnectConfig } from './config.ts';
+import { SettingsStore } from './settings.ts';
+/**
+ * dsh-magpie-connect DSH cordis plugin entry.
+ *
+ * Registers a DSH LlmAdapter streaming directly from the Magpie LAN gateway
+ * (marketplace shape: no child process, no binary, no proxy). The model
+ * catalog warms up in the background (live gateway list with disk cache +
+ * static snapshot fallback).
+ *
+ * The Settings sidebar page (client half) talks to the REST routes below:
+ * connection endpoint (baseUrl/apiKey) applies live without restart, and the
+ * hidden-model list filters the picker immediately.
+ *
+ * dispose(): stop the catalog refresh loop. The cordis fiber disposal
+ * guarantees this runs on plugin reload/unload and on DSH shutdown.
+ */
+export interface PluginContext {
+    logger: {
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+        error(...args: unknown[]): void;
+    };
+    llm?: {
+        registerAdapter(providers: string[], adapter: unknown): unknown;
+    };
+    get?(key: string): unknown;
+    inject?(deps: string[], fn: (ctx: Record<string, unknown>) => unknown): unknown;
+    effect?(fn: () => () => void): unknown;
+    on?(event: string, listener: (...args: never[]) => unknown): () => void;
+    /**
+     * Cordis `ctx.emit` (mixed in from the events service). Used to publish
+     * `llm/adapters-updated` when this plugin's own catalog moves, without
+     * touching the adapter registry.
+     */
+    emit?(event: string, ...args: unknown[]): unknown;
+}
+export declare const name = "dsh-magpie-connect";
+export declare const inject: readonly ["llm"];
+/** Browser-facing REST root for the settings page (served under the shared /api channel). */
+export declare const SETTINGS_API = "/api/magpie-settings";
+export declare const MODELS_API = "/api/magpie-models";
+export declare const TEST_API = "/api/magpie-test";
+/**
+ * Candidate discovery: asks the endpoint the form currently shows (including a
+ * key typed but not yet saved) what it serves. The reply is candidates the
+ * user picks from — never configuration written behind them.
+ */
+export declare const DISCOVER_API = "/api/magpie-discover";
+/** Backend generation behind the shared settings routes (newest wins). */
+export interface SettingsBackend {
+    store: SettingsStore;
+    catalog: ModelCatalog;
+    patchEndpoint: {
+        baseUrl: string;
+        apiKey: string;
+    };
+    effective: () => {
+        baseUrl: string;
+        apiKey: string;
+    };
+    applyPageSettings: () => void;
+}
+interface ModelRow {
+    id: string;
+    displayName: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    image: boolean;
+    responsesOnly: boolean;
+    reasoning: boolean;
+    efforts: string[];
+    hidden: boolean;
+}
+/** One discovered candidate: a {@link ModelRow} without this plugin's own visibility flag. */
+export type CandidateRow = Omit<ModelRow, 'hidden'>;
+/** @internal Test hook: forget installed routes so the next apply reinstalls. */
+export declare function __resetSettingsRoutes(): void;
+export declare function apply(ctx: PluginContext, config?: DshMagpieConnectConfig): {
+    ready: Promise<{
+        version: string;
+    }>;
+};
+export { MagpieAdapter } from './adapter/magpie-adapter.ts';
+export { ModelCatalog } from './adapter/catalog.ts';
+export { SettingsStore, isConfigured, resolveEffectiveEndpoint } from './settings.ts';
+export { resolveConfig, type DshMagpieConnectConfig, } from './config.ts';

package/lib/types/settings.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Page-owned runtime settings, persisted to a local JSON file.
+ *
+ * Precedence for the effective endpoint: settings page (this file, only the
+ * fields the user actually saved) > cordis patch config > built-in defaults.
+ * Hidden models only ever come from this file — the patch config has no such
+ * field, so an empty/absent list means "show everything".
+ */
+export interface MagpiePageSettings {
+    baseUrl?: string;
+    apiKey?: string;
+    hiddenModels?: string[];
+}
+export interface EffectiveEndpoint {
+    baseUrl: string;
+    apiKey: string;
+}
+export declare const SETTINGS_FILE = "settings.json";
+export declare function defaultSettingsPath(dataDir: string): string;
+/**
+ * Normalize an API base URL: must be http(s), no trailing slash, path kept.
+ *
+ * The path is load-bearing, not a mistake to be trimmed: the gateway versions
+ * its API (`/v1`, and later `/v2`, `/v3`), so this value *is* the prefix every
+ * request is built on. The plugin appends only the resource (`/models`,
+ * `/chat/completions`), never a version of its own — an origin-only value
+ * would make a future `/v2` unreachable.
+ */
+export declare function normalizeBaseUrl(raw: unknown): string;
+/** Normalize a hidden-model list: strings only, deduped, order kept. */
+export declare function normalizeHiddenModels(raw: unknown): string[];
+/** Validate + normalize a page payload (full or partial). Unknown keys are dropped. */
+export declare function normalizePageSettings(raw: unknown): MagpiePageSettings;
+/**
+ * Merge patch config with page settings: page wins per-field, but only for
+ * fields it actually saved (absent page fields fall back to patch/defaults).
+ */
+export declare function resolveEffectiveEndpoint(patch: {
+    baseUrl: string;
+    apiKey: string;
+}, page: MagpiePageSettings): EffectiveEndpoint;
+/** Fully configured only when both URL and key are present. Either missing gates everything. */
+export declare function isConfigured(endpoint: EffectiveEndpoint): boolean;
+/** In-memory settings with file persistence. Synchronous reads for the hot path. */
+export declare class SettingsStore {
+    #private;
+    constructor(options?: {
+        path?: string;
+    });
+    /** Load persisted settings (missing/corrupt file reads as empty, never throws). */
+    load(): Promise<MagpiePageSettings>;
+    get(): MagpiePageSettings;
+    /** Merge a partial payload, persist, and notify listeners. */
+    save(partial: unknown): Promise<MagpiePageSettings>;
+    /** Replace the whole document (used at startup after load). */
+    replace(next: MagpiePageSettings): void;
+    onChange(listener: () => void): () => void;
+    persist(): Promise<void>;
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "dsh-magpie-connect",
+  "description": "Magpie LAN gateway models for DeepSeek Harness (DSH): native dsh-llm adapter plugin with image + responses + thinking levels.",
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bitxeno/dsh-magpie-connect.git"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "dsh.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "deploy:local": "pnpm run build && rsync -a --delete lib/ ~/.dsh/profiles/web/node_modules/dsh-magpie-connect/lib/ && echo 'Deployed to ~/.dsh/profiles/web/node_modules/dsh-magpie-connect/lib — restart dsh web to load the new host half'",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"test/*.test.ts\"",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run build"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "magpie",
+    "lan-gateway",
+    "cordis",
+    "cordis-plugin",
+    "llm-adapter",
+    "llm-provider",
+    "llm",
+    "ai-models",
+    "typescript",
+    "nodejs"
+  ],
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.82.1"
+  },
+  "pnpm": {
+    "ignoredBuiltDependencies": [
+      "@google/genai",
+      "protobufjs"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.0"
+  }
+}