dsh-plugin-model-proxy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dsh-plugin-model-proxy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# dsh-plugin-model-proxy
+
+Community DSH plugin: route **specific provider/model pairs** through specific proxies (`http://`, `https://`, `socks5://`, `socks5h://`) — with a **Settings UI**.
+
+## Why
+
+Some model endpoints are only reachable through a proxy while their siblings
+connect fine — for instance `opencode/muse-spark-1.2-contributor` may answer
+`403 RegionError` to direct connections that other models from the same
+provider never see. The coarse fixes don't help: process-wide proxy
+environment variables drag every request through the tunnel, and swapping a
+whole provider's `baseURL` hides the real upstream. This plugin routes
+**specific provider/model pairs** at the transport layer instead — everything
+else stays direct, and the configured endpoint is never rewritten.
+
+## Features
+
+- **Per-rule routing**: `{provider, model, proxyUrl, enabled}` — specificity: exact model > prefix `muse-*` > `*`.
+- **Purpose filter**: optional per-rule `purpose` (e.g. `compaction`) so chat goes through the proxy while background calls stay direct.
+- **credentialRef**: keep proxy passwords in the DSH credentials service instead of settings.yaml; rules reference them by name (`user:password` entries). Soft dependency — installs without it keep working.
+- **Auto probe**: newly configured proxies are connectivity-tested once (CONNECT/socks handshake, no model quota); results go to the host log.
+- **Protocols**: `http://`, `https://` (CONNECT via `undici.ProxyAgent`), `socks5://` / `socks5h://` (via optional `socks`, tunnelled by undici `Agent` + custom connect).
+- **Zero baseURL mutation** — keep the real upstream.
+- **Live**: change rules → next `llm/stream` uses them; in-flight streams unaffected.
+- **UI**: `Settings → Plugins → Model Proxy` card (also works via `~/.dsh/settings.yaml`).
+- **Provider picker**: dropdown groups user-configured providers first (derived from `llm.providers` × settings mirror, same semantics as the built-in Models page); bare directory routes follow, and "Custom…" accepts anything — hand-written yaml rules, wildcards, gateways the catalog doesn't know. Provider and model fields are dropdowns fed by the live host catalog (`llm.providers` / `llm.models`, refreshed on `llm/adapters-updated`); a "Custom…" entry keeps free text for wildcards (`muse-*`, `*`) or not-yet-installed providers.
+- **Batch & grouped management**: adding rules checks multiple models for one provider at once — one rule each, sharing proxy/purpose/credential; the list groups cards by provider with group-level apply-proxy, enable/disable-all, and delete (cross-provider grouping never affects match order).
+
+## Install
+
+### Recommended: profile-managed (bundle)
+
+The package declares a `dsh.bundle` layer, so the DSH CLI links the dependency
+**and** appends the activation row in one step:
+
+```bash
+dsh plugin --profile <name> add dsh-plugin-model-proxy
+# optional SOCKS support:
+dsh plugin --profile <name> add socks
+```
+
+Verify the composed layer without booting, then run:
+
+```bash
+dsh --profile <name> --dump-config   # shows a "# == dsh-plugin-model-proxy" layer
+dsh --profile <name>
+```
+
+Uninstall removes both the dependency and the layer:
+
+```bash
+dsh plugin --profile <name> remove dsh-plugin-model-proxy
+```
+
+Installing from GitHub (`dsh plugin --profile <name> add github:<user>/dsh-plugin-model-proxy#<sha>`)
+fetches sources; pnpm ≥10 asks you to allowlist the `prepare` build — copy the
+package key it prints into the profile's `pnpm-workspace.yaml` under
+`allowBuilds:`, then re-run the `add`. Pin a commit so later pushes cannot
+change what runs on your machine.
+
+### Manual: hand-written patch
+
+If you manage compositions by hand, install the dependency into the **profile
+directory** first (`dsh plugin --profile <name> add ./` from a checkout works;
+module resolution anchors at the profile). Then insert exactly ONE loader row:
+
+```yaml
+# ~/.dsh/cordis.patch.yml  (or a --patch overlay)
+- insert:
+    - id: model-proxy/host
+      name: dsh-plugin-model-proxy
+      config: {}
+```
+
+Patch-file rules that trip people up:
+
+- The file must parse as a **top-level YAML array** of patch entries. Comments
+  are fine; a file of only comments (no `- …` rows and no `[]`) fails to parse
+  and breaks every boot/dump that reads it.
+- The loader-entry specifier field is **`name:`** (the package name), not `module:`.
+- New rows must be nested under **`insert:`** — a bare `- id:` row means "patch an existing entry".
+- Only the **host** half is a loader entry. The browser half is discovered automatically
+  from the package's `dsh.client` declaration and served at
+  `/plugins/dsh-plugin-model-proxy/client.js`. Do NOT add a `model-proxy/client`
+  row — it would run browser code inside the Node process.
+- **Never mix this path with the profile-managed install above.** Once the
+  dependency declares `dsh.bundle.patch`, `dsh plugin add` injects the host row
+  automatically; keeping a hand-written copy in `~/.dsh/cordis.patch.yml`
+  inserts the same loader id twice and the composition collides at boot.
+
+Uninstall = remove the inserted rows + `pnpm remove dsh-plugin-model-proxy`
+from the profile.
+
+## Configure
+
+### Via UI
+
+`Settings → Plugins → Model Proxy`
+
+### Via file
+
+`~/.dsh/settings.yaml`:
+
+```yaml
+model-proxy:
+  enabled: true
+  debug: false
+  defaultProxy: ""  # fallback when no rule matches
+  rules:
+    - provider: opencode
+      model: muse-spark-1.2-contributor
+      proxyUrl: socks5://127.0.0.1:1080
+      enabled: true
+    - provider: opencode
+      model: "*"
+      proxyUrl: ""  # direct for the rest of this provider
+```
+
+`proxyUrl: ""` means **direct (exempt)**. `socks5h://` resolves DNS at the proxy.
+
+## How it works (non-invasive)
+
+1. Host registers `model-proxy` settings namespace (`installSettingsSection`, live).
+2. Wraps `globalThis.fetch` reversibly.
+3. Listens on `llm/stream` waterfall, resolves `proxyUrl` for `(provider, model)` via `AsyncLocalStorage`, then injects a `dispatcher` into the adapter's `fetch` — for proxied requests it routes through `undici.fetch` (Node's native global fetch ignores custom dispatchers), with `undici.ProxyAgent` for `http(s)` and an undici `Agent` + socks `connect` (with TLS) for `socks5/h`.
+4. Browser registers `settings.plugin.item` with key `model-proxy` — automatically paired by the Plugins tab (`served ∩ registered`).
+
+No Adapter fork, no `baseURL` rewrite. See `DESIGN.md` for full design and invasiveness analysis.
+
+## Invasiveness
+
+| Check | Result |
+|---|---|
+| Modifies `packages/*` | No |
+| Requires fork of `dsh-llm` | No |
+| Global side effect reversible | Yes (`ctx.effect` dispose restores `fetch`) |
+| Client bundle purity gate | Passes (only type-only slot import) |
+
+## Building
+
+```bash
+pnpm install
+pnpm run build
+```
+
+## Testing
+
+Fully offline (local origin + CONNECT-capable toy proxy; no real network or proxy needed):
+
+```bash
+pnpm test        # builds host + client, then runs node --test tests/
+pnpm run typecheck
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# dsh-plugin-model-proxy — bundle layer
+#
+# Declared by package.json#dsh.bundle.patch and applied automatically by
+# `dsh plugin --profile <name> add dsh-plugin-model-proxy`. Manual installs can
+# copy these rows into ~/.dsh/cordis.patch.yml or a --patch overlay.
+#
+# Only the HOST row is a loader entry (the specifier field is `name:`). The
+# browser half is discovered automatically from package.json#dsh.client and
+# served at /plugins/dsh-plugin-model-proxy/client.js — never add a second
+# `model-proxy/client` loader row, it would run browser code in the host.
+
+- insert:
+    - id: model-proxy/host
+      name: dsh-plugin-model-proxy
+      config: {}

package/lib/client/ModelProxyCard.d.ts

@@ -0,0 +1,14 @@
+import { ProviderCatalogStore } from './catalog.js';
+import type { ModelProxyController } from './controller.js';
+import { en } from './locales.js';
+type Props = {
+    controller: ModelProxyController;
+    /** Live provider/model catalog; absent or empty falls back to free text. */
+    catalog?: ProviderCatalogStore;
+    t?: (k: keyof typeof en) => string;
+};
+/** Mirrors host assertServiceable for defaultProxy so bad values never reach the wire. */
+export declare function validateDefaultProxy(defaultProxy: string): string | undefined;
+export declare function ModelProxyCard({ controller, catalog, t: tProp }: Props): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=ModelProxyCard.d.ts.map

package/lib/client/ModelProxyCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelProxyCard.d.ts","sourceRoot":"","sources":["../../src/client/ModelProxyCard.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAA+B,MAAM,iBAAiB,CAAA;AAExF,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAEjC,KAAK,KAAK,GAAG;IACX,UAAU,EAAE,oBAAoB,CAAA;IAChC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,OAAO,EAAE,KAAK,MAAM,CAAA;CACnC,CAAA;AAoKD,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAqFD,wBAAgB,cAAc,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,KAAK,+BAmetE"}

package/lib/client/catalog.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Provider/model catalog feeding the settings card dropdowns.
+ *
+ * Data sources mirror the built-in Models page and the model-selection
+ * surface:
+ * - `llm.providers` — configurable provider directory merged with live routes
+ *   (`{ providers: [{ provider, displayName, settingsNs, settingsPath,
+ *   active, declared? }] }`)
+ * - `llm.models` — advisory per-provider model catalog
+ *   (`{ groups: [{ id, name, models: [{ id, name?, … }] }], failures }`)
+ * - `settings.describe` — optional enrichment: cross-references each row's
+ *   settings address to derive `configured`, so the card can group
+ *   user-configured providers ahead of the bare directory (same semantics as
+ *   the built-in Models page).
+ *
+ * Refresh triggers mirror ui-model-selection's convergence sources:
+ * `llm/adapters-updated` (registry topology commits) and
+ * `settings/document-updated` (configuration-owned catalogs).
+ *
+ * Everything here is advisory. The card always keeps a free-text escape
+ * hatch, because proxy rules legitimately target things no catalog lists:
+ * wildcard patterns (`vendor-*`, `*`) and providers whose adapter is not
+ * installed (yet).
+ */
+/** One selectable provider row (shape of `llm.providers.providers`). */
+export type CatalogProvider = {
+    provider: string;
+    displayName: string;
+    active: boolean;
+    /** Settings namespace whose section configures this provider (absent = no settings address). */
+    settingsNs?: string;
+    /** Path from that section's root to this provider's profile object. */
+    settingsPath?: string[];
+    /** Adapter knows this route only because configuration declared it. */
+    declared?: boolean;
+    /**
+     * Mirrors ui-settings-models' derivation: the provider's settings namespace
+     * exists AND its profile object is present in the merged value. Undefined
+     * when unknown (no settings address, or settings.describe unavailable).
+     */
+    configured?: boolean;
+};
+/** One selectable model row (subset of an `llm.models` group entry). */
+export type CatalogModel = {
+    id: string;
+    name?: string;
+};
+export type CatalogSnapshot = {
+    status: 'idle' | 'loading' | 'ready' | 'unavailable';
+    providers: CatalogProvider[];
+    /** Provider id → catalog models; absent/empty means no known models. */
+    modelsByProvider: Record<string, CatalogModel[]>;
+};
+/** Structural wire face so tests can pass fakes without a transport. */
+export type CatalogApiFace = {
+    llm: {
+        providers(payload: object): Promise<unknown>;
+        models(payload: object): Promise<unknown>;
+    };
+    /**
+     * Optional settings mirror used to derive each provider's `configured`
+     * flag. Absent or failing keeps configured undefined — grouping degrades
+     * to the flat directory list.
+     */
+    settings?: {
+        describe(payload: object): Promise<unknown>;
+    };
+};
+/** Structural face of `ctx.remote` — `$on` returns its own disposer. */
+export type CatalogRemoteFace = {
+    $on(event: string, listener: (...args: never[]) => void): () => void;
+};
+type Listener = () => void;
+/**
+ * Unwrap one RPC envelope (`{ result: { ok, value | error } }`), throwing on
+ * a business rejection with its wire message.
+ */
+export declare function unwrapRpc(response: unknown): unknown;
+/**
+ * Extract selectable provider rows from an unwrapped `llm.providers` value.
+ * Malformed rows are skipped, never fatal — the dropdown degrades to whatever
+ * is parseable.
+ */
+export declare function pickProviders(value: unknown): CatalogProvider[];
+/** Deep-get along a path; undefined as soon as any hop is missing. */
+export declare function getPath(value: unknown, path: readonly string[]): unknown;
+/**
+ * Attach `configured` to provider rows, mirroring ui-settings-models'
+ * derivation: the settings namespace exists in the mirror AND either the
+ * provider configures via the whole section (`settingsPath` empty) or its
+ * profile object is present in the merged value. Rows without a settings
+ * address keep `configured` undefined (unknown, not false).
+ */
+export declare function attachConfigured(providers: CatalogProvider[], namespaces: ReadonlyArray<{
+    ns?: unknown;
+    value?: unknown;
+}>): CatalogProvider[];
+/**
+ * Group an unwrapped `llm.models` value into provider id → model rows.
+ * Failures entries are ignored (the dropdown simply offers nothing for a
+ * provider whose catalog failed host-side).
+ */
+export declare function pickModelsByProvider(value: unknown): Record<string, CatalogModel[]>;
+/**
+ * uSES-compatible store over the two catalog RPCs. Loads once on bind(),
+ * reloads on forwarded topology/settings events, and keeps the last good
+ * rows across a failed background refresh so an outage never blanks open
+ * dropdowns.
+ */
+export declare class ProviderCatalogStore {
+    private readonly api;
+    private readonly remote?;
+    private readonly listeners;
+    private snapshot;
+    private generation;
+    private unsubs;
+    private bound;
+    constructor(api: CatalogApiFace, remote?: CatalogRemoteFace | undefined);
+    /** Idempotent: start loading and subscribe to refresh events. */
+    bind(): void;
+    /** Stop listening; in-flight loads become no-ops via the generation guard. */
+    dispose(): void;
+    subscribe(listener: Listener): () => void;
+    getSnapshot(): CatalogSnapshot;
+    /**
+     * Fetch both catalogs. Each call settles independently (`allSettled`
+     * semantics via mapped thunks): a provider-catalog failure fails the whole
+     * load, while a model-catalog failure degrades to an empty model map —
+     * models are an enrichment, providers drive the primary dropdown.
+     */
+    load(): Promise<void>;
+    /**
+     * Keep last good rows across a failed refresh; the card falls back to
+     * free-text inputs only when the snapshot holds no providers at all.
+     */
+    private markUnavailable;
+    private set;
+}
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/lib/client/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/client/catalog.ts"],"names":[],"mappings":"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"}

package/lib/client/controller.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Client controller for model-proxy settings card.
+ * Binds to `model-proxy` namespace via ctx.settingsScope and exposes
+ * a small observable store for the card.
+ */
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+export type ProxyRule = {
+    /** Card key; may be absent on hand-written yaml rules until edited here. */
+    id?: string;
+    provider: string;
+    model: string;
+    proxyUrl: string;
+    enabled: boolean;
+    /** Only apply to calls with this GenerateOptions.purpose; empty = all. */
+    purpose?: string;
+    /** Credentials-service entry ("user:password") overriding proxyUrl userinfo. */
+    credentialRef?: string;
+};
+export type ModelProxyConfig = {
+    enabled: boolean;
+    rules: ProxyRule[];
+    defaultProxy: string;
+    debug: boolean;
+};
+export type ModelProxySnapshot = {
+    status: 'loading' | 'ready' | 'unavailable';
+    value?: ModelProxyConfig;
+    revision?: number;
+    writable: boolean;
+    error?: string;
+};
+type Listener = () => void;
+/**
+ * Strip unknown keys from drafted rules before persisting. The wire layer
+ * tolerates extra keys and passes them through materialization, so without
+ * this a legacy field (e.g. the removed `note`) read from the stored document
+ * would ride every save forever. Writing only known fields converges stored
+ * documents to the schema shape.
+ *
+ * Dropping is loud, not silent: every stripped key is named on the console,
+ * so a hand-written key vanishing on save is never a mystery.
+ */
+export declare function sanitizeRules(rules: ProxyRule[]): ProxyRule[];
+/** Stable-enough client-side id for rule cards (React keys / list diffs). */
+export declare function makeRuleId(): string;
+/** One "batch add" spec: shared fields + the model patterns to fan out over. */
+export type CreatorSpec = {
+    provider: string;
+    /** Model ids / wildcard patterns; one rule each. Duplicates collapse. */
+    models: string[];
+    proxyUrl: string;
+    purpose?: string;
+    credentialRef?: string;
+    enabled?: boolean;
+};
+/**
+ * Fan one creator spec out into N prefilled rules sharing provider and
+ * connection fields. Returns [] when provider or models are effectively
+ * empty — callers gate the button on the same predicate for inline counts.
+ */
+export declare function buildCreatorRules(spec: CreatorSpec): ProxyRule[];
+/**
+ * Group rules by provider for the card's grouped view: group order is first
+ * appearance, intra-group order preserved. Matching semantics only care about
+ * order WITHIN a provider (same-pass first-wins), so regrouping across
+ * providers is display-safe by construction.
+ */
+export declare function groupByProvider(rules: ProxyRule[]): Array<{
+    provider: string;
+    rules: ProxyRule[];
+}>;
+/**
+ * Fill missing rule ids so every card has a stable React key. Host-side code
+ * never relies on `id` (the schema leaves it optional), so this is purely a
+ * UI concern and does not dirty the saved document.
+ */
+export declare function ensureRuleIds(cfg: ModelProxyConfig): ModelProxyConfig;
+export declare class ModelProxyController {
+    private readonly scope;
+    private listeners;
+    private snapshot;
+    private unsub?;
+    constructor(scope: SettingsScope<ModelProxyConfig>);
+    bind(): void;
+    dispose(): void;
+    subscribe(l: Listener): () => void;
+    getSnapshot(): ModelProxySnapshot;
+    private pull;
+    private emit;
+    /**
+     * Persist the config as four fenced field writes.
+     *
+     * The scope contract exposes per-field writes only, so full atomicity would
+     * require collapsing the namespace to a single field (a breaking settings
+     * shape change). Until then we order the writes so the field most likely to
+     * be REJECTED by host validation (`rules`) goes FIRST: if it fails, nothing
+     * else has been committed and the failure aborts cleanly instead of leaving
+     * mixed old/new state. The remaining fields are booleans plus a URL that the
+     * card pre-validates with the same checks the host applies, making their
+     * rejection practically unreachable.
+     */
+    save(next: ModelProxyConfig): Promise<void>;
+    setEnabled(v: boolean): Promise<void>;
+    setDebug(v: boolean): Promise<void>;
+}
+export {};
+//# sourceMappingURL=controller.d.ts.map

package/lib/client/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/client/controller.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,MAAM,MAAM,SAAS,GAAG;IACtB,4EAA4E;IAC5E,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,aAAa,CAAA;IAC3C,KAAK,CAAC,EAAE,gBAAgB,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAA;AAK1B;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAa7D;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,CAgBhE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,CAanG;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAErE;AAED,qBAAa,oBAAoB;IAKnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJlC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,QAAQ,CAA6D;IAC7E,OAAO,CAAC,KAAK,CAAC,CAAY;gBAEG,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC;IAEnE,IAAI,IAAI,IAAI;IAKZ,OAAO,IAAI,IAAI;IAKf,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,IAAI;IAKlC,WAAW,IAAI,kBAAkB;IAIjC,OAAO,CAAC,IAAI;IAiBZ,OAAO,CAAC,IAAI;IAIZ;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3C,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/lib/client/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser half: registers `settings.plugin.item` card for `model-proxy`.
+ * Non-invasive: only depends on the declared slot via type-only import.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+export declare const inject: string[];
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAO3E,eAAO,MAAM,MAAM,UAA+D,CAAA;AAElF,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CA8C9C"}

package/lib/client/locales.d.ts

@@ -0,0 +1,106 @@
+export declare const en: {
+    readonly title: "Model Proxy";
+    readonly desc: "Route specific provider/model pairs through HTTP/HTTPS/SOCKS5 proxies. Specificity: exact model > prefix \"vendor-*\" > \"*\". Optional purpose filter targets compaction/session-title calls.";
+    readonly enabled: "Enable proxy routing";
+    readonly debug: "Debug logging (host log)";
+    readonly rules: "Rules (first match wins — exact before prefix before \"*\")";
+    readonly addRule: "Add rule";
+    readonly provider: "Provider";
+    readonly providerPlaceholder: "e.g. openai";
+    readonly model: "Model";
+    readonly modelPlaceholder: "e.g. gpt-4o-mini, vendor-* or *";
+    readonly purpose: "Purpose filter";
+    readonly purposePlaceholder: "empty = all purposes (e.g. compaction, session-title)";
+    readonly credRef: "Credential ref";
+    readonly credRefPlaceholder: "credentials entry holding user:password (optional)";
+    readonly proxyUrl: "Proxy URL";
+    readonly proxyPlaceholder: "socks5://127.0.0.1:1080 or http://127.0.0.1:7890 (empty=direct)";
+    readonly enabledShort: "On";
+    readonly delete: "Delete";
+    readonly defaultProxy: "Fallback proxy (when no rule matches)";
+    readonly defaultPlaceholder: "optional, e.g. http://127.0.0.1:7890";
+    readonly saving: "Saving…";
+    readonly save: "Save";
+    readonly saved: "Saved";
+    readonly unavailable: "Model proxy settings unavailable.";
+    readonly empty: "No rules yet — add one above. Tip: use model \"*\" for all models of a provider.";
+    readonly invalid: "Please fix highlighted fields.";
+    readonly duplicate: "Duplicate provider+model";
+    readonly reading: "Loading…";
+    readonly readOnly: "Read-only (settings provider not writable).";
+    readonly choose: "Select…";
+    readonly customOption: "Custom…";
+    readonly backToList: "Pick from the installed catalog";
+    readonly dormant: "not configured";
+    readonly groupConfigured: "Configured providers";
+    readonly groupDirectory: "Other directory routes";
+    readonly wildcardAll: "any model";
+    readonly catalogUnavailable: "Provider catalog unavailable — type values manually.";
+    readonly creatorTitle: "New rules";
+    readonly creatorModels: "Models";
+    readonly creatorPatternHint: "Or a pattern (vendor-* or *)";
+    readonly createN: "Create {n} rule(s)";
+    readonly cancel: "Cancel";
+    readonly alreadyRuled: "rule exists";
+    readonly noneCatalogued: "No catalog models — use * or a custom pattern.";
+    readonly groupApplyProxy: "proxy for all…";
+    readonly groupApply: "Apply";
+    readonly groupEnableAll: "Enable all";
+    readonly groupDisableAll: "Disable all";
+    readonly groupDelete: "Delete group";
+    readonly groupConfirmDelete: "Sure?";
+};
+export declare const zh: {
+    readonly title: "模型代理";
+    readonly desc: "按 provider/model 粒度走代理（HTTP/HTTPS/SOCKS5）。优先级：精确 model > 前缀 \"vendor-*\" > \"*\"。可选用途过滤可单独控制 compaction/session-title 等调用。";
+    readonly enabled: "启用代理路由";
+    readonly debug: "调试日志（Host 日志）";
+    readonly rules: "规则（首条命中即用 — 精确 > 前缀 > \"*\"）";
+    readonly addRule: "添加规则";
+    readonly provider: "Provider";
+    readonly providerPlaceholder: "例如 openai";
+    readonly model: "Model";
+    readonly modelPlaceholder: "例如 gpt-4o-mini、vendor-* 或 *";
+    readonly purpose: "用途过滤";
+    readonly purposePlaceholder: "留空=所有用途（如 compaction、session-title）";
+    readonly credRef: "凭据引用";
+    readonly credRefPlaceholder: "credentials 服务条目（user:password），可选";
+    readonly proxyUrl: "代理地址";
+    readonly proxyPlaceholder: "socks5://127.0.0.1:1080 或 http://127.0.0.1:7890（空=直连）";
+    readonly enabledShort: "启用";
+    readonly delete: "删除";
+    readonly defaultProxy: "兜底代理（无规则命中时）";
+    readonly defaultPlaceholder: "可选，例如 http://127.0.0.1:7890";
+    readonly saving: "保存中…";
+    readonly save: "保存";
+    readonly saved: "已保存";
+    readonly unavailable: "模型代理设置不可用。";
+    readonly empty: "暂无规则 — 点击上方添加。提示：model 用 \"*\" 表示该 provider 的所有模型。";
+    readonly invalid: "请修正标红字段。";
+    readonly duplicate: "provider+model 重复";
+    readonly reading: "加载中…";
+    readonly readOnly: "只读（settings provider 不可写）。";
+    readonly choose: "请选择…";
+    readonly customOption: "自定义…";
+    readonly backToList: "从已安装目录选择";
+    readonly dormant: "未配置";
+    readonly groupConfigured: "已配置的 Provider";
+    readonly groupDirectory: "目录中的其他路由";
+    readonly wildcardAll: "所有模型";
+    readonly catalogUnavailable: "提供方目录不可用 — 请手动输入。";
+    readonly creatorTitle: "新建规则";
+    readonly creatorModels: "勾选模型";
+    readonly creatorPatternHint: "或自定义模式（vendor-*、*）";
+    readonly createN: "创建 {n} 条规则";
+    readonly cancel: "取消";
+    readonly alreadyRuled: "已有规则";
+    readonly noneCatalogued: "该 provider 无目录模型——可用 * 或自定义模式。";
+    readonly groupApplyProxy: "整组代理地址…";
+    readonly groupApply: "应用";
+    readonly groupEnableAll: "全部启用";
+    readonly groupDisableAll: "全部停用";
+    readonly groupDelete: "删除本组";
+    readonly groupConfirmDelete: "确认？";
+};
+export type LocaleKey = keyof typeof en;
+//# sourceMappingURL=locales.d.ts.map

package/lib/client/locales.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../src/client/locales.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDL,CAAA;AAEV,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDL,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,EAAE,CAAA"}