@moxxy/plugin-provider-local 0.21.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+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/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { type ModelDescriptor } from '@moxxy/sdk';
+/**
+ * Default endpoint: Ollama's OpenAI-compatible server. Override with the
+ * `LOCAL_MODEL_BASE_URL` env var (or `provider.config.baseURL`) to point at LM
+ * Studio (`http://localhost:1234/v1`), llama.cpp, vLLM, or a remote box.
+ */
+export declare const DEFAULT_LOCAL_BASE_URL = "http://localhost:11434/v1";
+/**
+ * A small catalog of popular local models as sensible defaults. Local model ids
+ * vary by whatever the user has pulled, so this is intentionally short — an
+ * unlisted id (e.g. `mistral-small`, `phi4`, a custom tag) still works, since
+ * the id is passed straight through to the local server. The catalog only seeds
+ * the `/model` picker and gives context-window budgets a starting point.
+ *
+ * `supportsTools` is optimistic only for ids that reliably do OpenAI
+ * tool-calling (llama3.3 / qwen). Reasoning/experimental builds (deepseek-r1,
+ * gpt-oss) and many quantized pulls don't, so they default conservative rather
+ * than advertising a capability the backend ignores or 400s on. Confirm per
+ * pulled model.
+ */
+export declare const localModels: ReadonlyArray<ModelDescriptor>;
+/**
+ * Test-only: clear the once-per-host warning memo so a suite can assert
+ * deterministic warn counts independent of which other tests ran first. Not part
+ * of the runtime API — the memo is process-lifetime and never reset in prod.
+ * @internal
+ */
+export declare function __resetRemoteWarningsForTests(): void;
+/**
+ * Local models via any OpenAI-compatible server (Ollama, LM Studio, llama.cpp,
+ * vLLM). Reuses the shared {@link defineOpenAICompatProvider} pointed at a
+ * localhost base URL, with the `local` slug forced on. `validate: false` and a
+ * placeholder API key: local servers don't authenticate, so the credential path
+ * supplies a placeholder (see `resolveProviderCredentials` in the CLI),
+ * activation never prompts, and we never probe a possibly-offline box.
+ *
+ * Env-var resolution is duplicated by design: in the CLI flow
+ * `resolveProviderCredentials` pre-resolves `apiKey`/`baseURL` into the config
+ * (so the env reads below are unreachable there), but non-CLI callers
+ * (desktop / provider-admin direct `createClient`) don't — these `resolve*`
+ * functions are the authoritative readers for them, with identical precedence.
+ */
+export declare const localProviderDef: import("@moxxy/sdk").ProviderDef;
+export declare const localPlugin: import("@moxxy/sdk").Plugin;
+export default localPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAM5E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,8BAA8B,CAAC;AAkBlE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,eAAe,CAMtD,CAAC;AAmBF;;;;;GAKG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAoDD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,kCAa3B,CAAC;AAEH,eAAO,MAAM,WAAW,6BAItB,CAAC;AAEH,eAAe,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,150 @@
+import { definePlugin, MoxxyError } from '@moxxy/sdk';
+import { defineOpenAICompatProvider, } from '@moxxy/plugin-provider-openai';
+/**
+ * Default endpoint: Ollama's OpenAI-compatible server. Override with the
+ * `LOCAL_MODEL_BASE_URL` env var (or `provider.config.baseURL`) to point at LM
+ * Studio (`http://localhost:1234/v1`), llama.cpp, vLLM, or a remote box.
+ */
+export const DEFAULT_LOCAL_BASE_URL = 'http://localhost:11434/v1';
+const LOCAL_DEFAULT_MODEL = 'llama3.3';
+/**
+ * Local servers don't authenticate, but the OpenAI SDK requires a non-empty
+ * key. Use a harmless placeholder unless one is explicitly provided.
+ */
+const LOCAL_PLACEHOLDER_KEY = 'local';
+/**
+ * Conservative context-window floor for the seed catalog. Stock Ollama defaults
+ * to `num_ctx` 2k–4k and other servers vary widely; the value here only seeds
+ * the compaction/elision budget. Over-claiming (e.g. 131k) means the budget
+ * guard never fires and the backend silently truncates the prompt once the real
+ * window is exceeded — under-claiming degrades gracefully, so floor it. Raise it
+ * via `provider.config.defaultModel`/a pinned descriptor when `num_ctx` is known.
+ */
+const LOCAL_CONTEXT_FLOOR = 8_192;
+/**
+ * A small catalog of popular local models as sensible defaults. Local model ids
+ * vary by whatever the user has pulled, so this is intentionally short — an
+ * unlisted id (e.g. `mistral-small`, `phi4`, a custom tag) still works, since
+ * the id is passed straight through to the local server. The catalog only seeds
+ * the `/model` picker and gives context-window budgets a starting point.
+ *
+ * `supportsTools` is optimistic only for ids that reliably do OpenAI
+ * tool-calling (llama3.3 / qwen). Reasoning/experimental builds (deepseek-r1,
+ * gpt-oss) and many quantized pulls don't, so they default conservative rather
+ * than advertising a capability the backend ignores or 400s on. Confirm per
+ * pulled model.
+ */
+export const localModels = [
+    { id: 'llama3.3', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: true, supportsStreaming: true },
+    { id: 'qwen3', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: true, supportsStreaming: true },
+    { id: 'qwen2.5-coder', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: true, supportsStreaming: true },
+    { id: 'deepseek-r1', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: false, supportsStreaming: true },
+    { id: 'gpt-oss', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: false, supportsStreaming: true },
+];
+/** Hosts that keep traffic on the local machine — no data egress. */
+function isLoopbackHost(hostname) {
+    const h = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (h === 'localhost' || h === '::1' || h === '0.0.0.0' || h === '::')
+        return true;
+    if (h.endsWith('.localhost'))
+        return true;
+    // IPv4 loopback block 127.0.0.0/8.
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+// Warn at most once per distinct non-loopback host. Bounded so a pathological
+// caller that cycles base URLs can't grow this without limit; once the bound is
+// reached, further never-before-seen hosts are silently suppressed (rather than
+// re-warning on every call) — 64 distinct remote endpoints is already
+// pathological, and unbounded log spam is its own failure mode.
+const warnedRemoteHosts = new Set();
+const MAX_WARNED_HOSTS = 64;
+/**
+ * Test-only: clear the once-per-host warning memo so a suite can assert
+ * deterministic warn counts independent of which other tests ran first. Not part
+ * of the runtime API — the memo is process-lifetime and never reset in prod.
+ * @internal
+ */
+export function __resetRemoteWarningsForTests() {
+    warnedRemoteHosts.clear();
+}
+/**
+ * Resolve and validate the base URL the prompt (which can carry session context,
+ * file contents, and shown secrets) will be POSTed to. Precedence matches the
+ * prior behaviour: `provider.config.baseURL` → `LOCAL_MODEL_BASE_URL` env →
+ * Ollama default. Because this provider is branded `local` and runs with
+ * `validate: false` (no setup probe), a mistaken/poisoned URL would otherwise
+ * silently redirect ALL traffic (and the placeholder credential) to an
+ * arbitrary endpoint over an arbitrary scheme. So: reject anything that isn't
+ * parseable http/https, and surface a one-time warning when the resolved host
+ * leaves the local machine so egress is visible (remote boxes are explicitly
+ * supported, hence a warning rather than a hard block).
+ */
+function resolveLocalBaseURL(cfg) {
+    const raw = cfg.baseURL ?? process.env.LOCAL_MODEL_BASE_URL ?? DEFAULT_LOCAL_BASE_URL;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch (cause) {
+        throw new MoxxyError({
+            code: 'CONFIG_INVALID',
+            message: `local provider baseURL is not a valid URL: ${raw}`,
+            hint: 'Set provider.config.baseURL or LOCAL_MODEL_BASE_URL to e.g. http://localhost:11434/v1',
+            context: { provider: 'local' },
+            cause,
+        });
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new MoxxyError({
+            code: 'CONFIG_INVALID',
+            message: `local provider baseURL must use http or https, got ${url.protocol}//`,
+            hint: 'Set provider.config.baseURL or LOCAL_MODEL_BASE_URL to an http(s) endpoint.',
+            context: { provider: 'local', url: raw },
+        });
+    }
+    if (!isLoopbackHost(url.hostname) &&
+        !warnedRemoteHosts.has(url.hostname) &&
+        warnedRemoteHosts.size < MAX_WARNED_HOSTS) {
+        // Only warn for hosts we can record, so the once-per-host guarantee holds
+        // even past the cap (an unrecorded host would otherwise re-warn every call).
+        warnedRemoteHosts.add(url.hostname);
+        console.warn(`[local] sending prompts to a non-local endpoint (${url.host}). ` +
+            'Conversation context, file contents and shown secrets are POSTed there.');
+    }
+    return raw;
+}
+/**
+ * Local models via any OpenAI-compatible server (Ollama, LM Studio, llama.cpp,
+ * vLLM). Reuses the shared {@link defineOpenAICompatProvider} pointed at a
+ * localhost base URL, with the `local` slug forced on. `validate: false` and a
+ * placeholder API key: local servers don't authenticate, so the credential path
+ * supplies a placeholder (see `resolveProviderCredentials` in the CLI),
+ * activation never prompts, and we never probe a possibly-offline box.
+ *
+ * Env-var resolution is duplicated by design: in the CLI flow
+ * `resolveProviderCredentials` pre-resolves `apiKey`/`baseURL` into the config
+ * (so the env reads below are unreachable there), but non-CLI callers
+ * (desktop / provider-admin direct `createClient`) don't — these `resolve*`
+ * functions are the authoritative readers for them, with identical precedence.
+ */
+export const localProviderDef = defineOpenAICompatProvider({
+    name: 'local',
+    baseURL: DEFAULT_LOCAL_BASE_URL,
+    defaultModel: LOCAL_DEFAULT_MODEL,
+    models: localModels,
+    validate: false,
+    resolveApiKey: (cfg) => cfg.apiKey ?? process.env.LOCAL_API_KEY ?? LOCAL_PLACEHOLDER_KEY,
+    resolveBaseURL: resolveLocalBaseURL,
+    auth: {
+        kind: 'apiKey',
+        envVar: 'LOCAL_API_KEY',
+        hint: 'optional — local servers need no key; set LOCAL_MODEL_BASE_URL for a non-Ollama endpoint',
+    },
+});
+export const localPlugin = definePlugin({
+    name: '@moxxy/plugin-provider-local',
+    version: '0.0.0',
+    providers: [localProviderDef],
+});
+export default localPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAwB,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,0BAA0B,GAE3B,MAAM,+BAA+B,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,2BAA2B,CAAC;AAClE,MAAM,mBAAmB,GAAG,UAAU,CAAC;AACvC;;;GAGG;AACH,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAElC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmC;IACzD,EAAE,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,mBAAmB,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;IACpG,EAAE,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;IACjG,EAAE,EAAE,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;IACzG,EAAE,EAAE,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE;IACxG,EAAE,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE;CACrG,CAAC;AAEF,qEAAqE;AACrE,SAAS,cAAc,CAAC,QAAgB;IACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnF,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,mCAAmC;IACnC,OAAO,kCAAkC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,sEAAsE;AACtE,gEAAgE;AAChE,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;AAC5C,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B;IAC3C,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,mBAAmB,CAAC,GAAuB;IAClD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,sBAAsB,CAAC;IACtF,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,8CAA8C,GAAG,EAAE;YAC5D,IAAI,EAAE,uFAAuF;YAC7F,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE;YAC9B,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,sDAAsD,GAAG,CAAC,QAAQ,IAAI;YAC/E,IAAI,EAAE,6EAA6E;YACnF,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE;SACzC,CAAC,CAAC;IACL,CAAC;IACD,IACE,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC7B,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC;QACpC,iBAAiB,CAAC,IAAI,GAAG,gBAAgB,EACzC,CAAC;QACD,0EAA0E;QAC1E,6EAA6E;QAC7E,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CACV,oDAAoD,GAAG,CAAC,IAAI,KAAK;YAC/D,yEAAyE,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;IACzD,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,sBAAsB;IAC/B,YAAY,EAAE,mBAAmB;IACjC,MAAM,EAAE,WAAW;IACnB,QAAQ,EAAE,KAAK;IACf,aAAa,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,qBAAqB;IACxF,cAAc,EAAE,mBAAmB;IACnC,IAAI,EAAE;QACJ,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,eAAe;QACvB,IAAI,EAAE,0FAA0F;KACjG;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;IACtC,IAAI,EAAE,8BAA8B;IACpC,OAAO,EAAE,OAAO;IAChB,SAAS,EAAE,CAAC,gBAAgB,CAAC;CAC9B,CAAC,CAAC;AAEH,eAAe,WAAW,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@moxxy/plugin-provider-local",
+  "version": "0.21.1",
+  "description": "Local-model LLMProvider plugin for moxxy. Talks to any OpenAI-compatible local server (Ollama, LM Studio, llama.cpp, vLLM) — no API key required.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "provider",
+    "ollama",
+    "local",
+    "llm"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-provider-local"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "provider"
+    }
+  },
+  "dependencies": {
+    "@moxxy/plugin-provider-openai": "0.21.1",
+    "@moxxy/sdk": "0.21.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.0",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { MoxxyError } from '@moxxy/sdk';
+import {
+  localPlugin,
+  localProviderDef,
+  localModels,
+  DEFAULT_LOCAL_BASE_URL,
+  __resetRemoteWarningsForTests,
+} from './index.js';
+
+describe('@moxxy/plugin-provider-local', () => {
+  it('registers the local provider', () => {
+    expect(localPlugin.providers?.map((p) => p.name)).toEqual(['local']);
+  });
+
+  it('has no validateKey (local servers do not authenticate)', () => {
+    expect(localProviderDef.validateKey).toBeUndefined();
+  });
+
+  it('activates with no key — createClient supplies a placeholder and the Ollama base URL', () => {
+    const client = localProviderDef.createClient({});
+    expect(client.name).toBe('local');
+    expect(client.models).toEqual(localModels);
+    expect(DEFAULT_LOCAL_BASE_URL).toBe('http://localhost:11434/v1');
+  });
+
+  it('passes through unlisted local model ids (catalog is only a default set)', () => {
+    // The catalog is short on purpose; the provider streams any model id the
+    // local server knows. Sanity-check the seed catalog is non-empty.
+    expect(localModels.length).toBeGreaterThan(0);
+    expect(localModels.every((m) => m.supportsStreaming)).toBe(true);
+  });
+
+  it('seeds a conservative context window (never over-claims the server window)', () => {
+    // Over-claiming defeats the compaction/elision budget; under-claiming is the
+    // safe direction. Stock Ollama num_ctx is 2k–4k, so the seed must stay small.
+    expect(localModels.every((m) => m.contextWindow <= 8_192)).toBe(true);
+    expect(localModels.every((m) => m.contextWindow > 0)).toBe(true);
+  });
+
+  describe('baseURL validation (SSRF / data-egress guard)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    beforeEach(() => {
+      warn.mockClear();
+      __resetRemoteWarningsForTests();
+      delete process.env.LOCAL_MODEL_BASE_URL;
+    });
+    afterEach(() => {
+      delete process.env.LOCAL_MODEL_BASE_URL;
+    });
+
+    it('rejects an unparseable baseURL with a structured MoxxyError', () => {
+      expect(() => localProviderDef.createClient({ baseURL: 'not a url' })).toThrow(MoxxyError);
+      try {
+        localProviderDef.createClient({ baseURL: '::::' });
+      } catch (err) {
+        expect(MoxxyError.isMoxxyError(err)).toBe(true);
+        expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+      }
+    });
+
+    it.each(['file:///etc/passwd', 'gopher://evil/', 'ftp://host/x', 'data:text/plain,x'])(
+      'rejects a non-http(s) scheme (%s) instead of handing it to the SDK',
+      (bad) => {
+        let thrown: unknown;
+        try {
+          localProviderDef.createClient({ baseURL: bad });
+        } catch (err) {
+          thrown = err;
+        }
+        expect(MoxxyError.isMoxxyError(thrown)).toBe(true);
+        expect((thrown as MoxxyError).code).toBe('CONFIG_INVALID');
+      },
+    );
+
+    it('does not warn for a loopback endpoint (the local happy path)', () => {
+      localProviderDef.createClient({ baseURL: 'http://127.0.0.1:11434/v1' });
+      localProviderDef.createClient({ baseURL: 'http://localhost:1234/v1' });
+      localProviderDef.createClient({ baseURL: 'http://[::1]:11434/v1' });
+      localProviderDef.createClient({ baseURL: 'http://dev.localhost/v1' });
+      localProviderDef.createClient({ baseURL: 'http://127.5.5.5/v1' });
+      expect(warn).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      'http://localhost.evil.com/v1',
+      'http://127.0.0.1.evil.com/v1',
+      'http://[fe80::1]/v1',
+      'http://192.168.1.50:11434/v1',
+    ])('warns for a remote host that merely looks loopback-ish (%s)', (baseURL) => {
+      // The dangerous direction is mis-classifying a REMOTE host as loopback and
+      // silently suppressing the egress warning. These must all warn.
+      localProviderDef.createClient({ baseURL });
+      expect(warn).toHaveBeenCalled();
+    });
+
+    it('warns once per distinct non-loopback host so data egress is visible', () => {
+      localProviderDef.createClient({ baseURL: 'https://remote.example.com/v1' });
+      localProviderDef.createClient({ baseURL: 'https://remote.example.com/v2' });
+      expect(warn).toHaveBeenCalledTimes(1);
+      localProviderDef.createClient({ baseURL: 'http://other.example.org:8080/v1' });
+      expect(warn).toHaveBeenCalledTimes(2);
+    });
+
+    it('never re-warns for an already-seen host, even past the bound (no unbounded log spam)', () => {
+      // Cycle many distinct remote hosts so the warn cap is reached, then replay
+      // the exact same hosts. The worst case the bound protects against is a
+      // caller cycling base URLs: hosts beyond the cap must NOT re-warn on every
+      // call. So the second pass over the identical hosts must emit zero warns.
+      const hosts = Array.from({ length: 80 }, (_, i) => `https://spam-${i}.example.net/v1`);
+      for (const baseURL of hosts) localProviderDef.createClient({ baseURL });
+      const afterFirstPass = warn.mock.calls.length;
+      warn.mockClear();
+      for (const baseURL of hosts) localProviderDef.createClient({ baseURL });
+      expect(warn).not.toHaveBeenCalled();
+      // First pass is itself bounded: at most one warn per distinct host.
+      expect(afterFirstPass).toBeLessThanOrEqual(hosts.length);
+    });
+
+    it('honours the LOCAL_MODEL_BASE_URL env fallback for non-CLI callers', () => {
+      process.env.LOCAL_MODEL_BASE_URL = 'http://localhost:11434/v1';
+      expect(() => localProviderDef.createClient({})).not.toThrow();
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,163 @@
+import { definePlugin, MoxxyError, type ModelDescriptor } from '@moxxy/sdk';
+import {
+  defineOpenAICompatProvider,
+  type OpenAICompatConfig,
+} from '@moxxy/plugin-provider-openai';
+
+/**
+ * Default endpoint: Ollama's OpenAI-compatible server. Override with the
+ * `LOCAL_MODEL_BASE_URL` env var (or `provider.config.baseURL`) to point at LM
+ * Studio (`http://localhost:1234/v1`), llama.cpp, vLLM, or a remote box.
+ */
+export const DEFAULT_LOCAL_BASE_URL = 'http://localhost:11434/v1';
+const LOCAL_DEFAULT_MODEL = 'llama3.3';
+/**
+ * Local servers don't authenticate, but the OpenAI SDK requires a non-empty
+ * key. Use a harmless placeholder unless one is explicitly provided.
+ */
+const LOCAL_PLACEHOLDER_KEY = 'local';
+
+/**
+ * Conservative context-window floor for the seed catalog. Stock Ollama defaults
+ * to `num_ctx` 2k–4k and other servers vary widely; the value here only seeds
+ * the compaction/elision budget. Over-claiming (e.g. 131k) means the budget
+ * guard never fires and the backend silently truncates the prompt once the real
+ * window is exceeded — under-claiming degrades gracefully, so floor it. Raise it
+ * via `provider.config.defaultModel`/a pinned descriptor when `num_ctx` is known.
+ */
+const LOCAL_CONTEXT_FLOOR = 8_192;
+
+/**
+ * A small catalog of popular local models as sensible defaults. Local model ids
+ * vary by whatever the user has pulled, so this is intentionally short — an
+ * unlisted id (e.g. `mistral-small`, `phi4`, a custom tag) still works, since
+ * the id is passed straight through to the local server. The catalog only seeds
+ * the `/model` picker and gives context-window budgets a starting point.
+ *
+ * `supportsTools` is optimistic only for ids that reliably do OpenAI
+ * tool-calling (llama3.3 / qwen). Reasoning/experimental builds (deepseek-r1,
+ * gpt-oss) and many quantized pulls don't, so they default conservative rather
+ * than advertising a capability the backend ignores or 400s on. Confirm per
+ * pulled model.
+ */
+export const localModels: ReadonlyArray<ModelDescriptor> = [
+  { id: 'llama3.3', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: true, supportsStreaming: true },
+  { id: 'qwen3', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: true, supportsStreaming: true },
+  { id: 'qwen2.5-coder', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: true, supportsStreaming: true },
+  { id: 'deepseek-r1', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: false, supportsStreaming: true },
+  { id: 'gpt-oss', contextWindow: LOCAL_CONTEXT_FLOOR, supportsTools: false, supportsStreaming: true },
+];
+
+/** Hosts that keep traffic on the local machine — no data egress. */
+function isLoopbackHost(hostname: string): boolean {
+  const h = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  if (h === 'localhost' || h === '::1' || h === '0.0.0.0' || h === '::') return true;
+  if (h.endsWith('.localhost')) return true;
+  // IPv4 loopback block 127.0.0.0/8.
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+
+// Warn at most once per distinct non-loopback host. Bounded so a pathological
+// caller that cycles base URLs can't grow this without limit; once the bound is
+// reached, further never-before-seen hosts are silently suppressed (rather than
+// re-warning on every call) — 64 distinct remote endpoints is already
+// pathological, and unbounded log spam is its own failure mode.
+const warnedRemoteHosts = new Set<string>();
+const MAX_WARNED_HOSTS = 64;
+
+/**
+ * Test-only: clear the once-per-host warning memo so a suite can assert
+ * deterministic warn counts independent of which other tests ran first. Not part
+ * of the runtime API — the memo is process-lifetime and never reset in prod.
+ * @internal
+ */
+export function __resetRemoteWarningsForTests(): void {
+  warnedRemoteHosts.clear();
+}
+
+/**
+ * Resolve and validate the base URL the prompt (which can carry session context,
+ * file contents, and shown secrets) will be POSTed to. Precedence matches the
+ * prior behaviour: `provider.config.baseURL` → `LOCAL_MODEL_BASE_URL` env →
+ * Ollama default. Because this provider is branded `local` and runs with
+ * `validate: false` (no setup probe), a mistaken/poisoned URL would otherwise
+ * silently redirect ALL traffic (and the placeholder credential) to an
+ * arbitrary endpoint over an arbitrary scheme. So: reject anything that isn't
+ * parseable http/https, and surface a one-time warning when the resolved host
+ * leaves the local machine so egress is visible (remote boxes are explicitly
+ * supported, hence a warning rather than a hard block).
+ */
+function resolveLocalBaseURL(cfg: OpenAICompatConfig): string {
+  const raw = cfg.baseURL ?? process.env.LOCAL_MODEL_BASE_URL ?? DEFAULT_LOCAL_BASE_URL;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch (cause) {
+    throw new MoxxyError({
+      code: 'CONFIG_INVALID',
+      message: `local provider baseURL is not a valid URL: ${raw}`,
+      hint: 'Set provider.config.baseURL or LOCAL_MODEL_BASE_URL to e.g. http://localhost:11434/v1',
+      context: { provider: 'local' },
+      cause,
+    });
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new MoxxyError({
+      code: 'CONFIG_INVALID',
+      message: `local provider baseURL must use http or https, got ${url.protocol}//`,
+      hint: 'Set provider.config.baseURL or LOCAL_MODEL_BASE_URL to an http(s) endpoint.',
+      context: { provider: 'local', url: raw },
+    });
+  }
+  if (
+    !isLoopbackHost(url.hostname) &&
+    !warnedRemoteHosts.has(url.hostname) &&
+    warnedRemoteHosts.size < MAX_WARNED_HOSTS
+  ) {
+    // Only warn for hosts we can record, so the once-per-host guarantee holds
+    // even past the cap (an unrecorded host would otherwise re-warn every call).
+    warnedRemoteHosts.add(url.hostname);
+    console.warn(
+      `[local] sending prompts to a non-local endpoint (${url.host}). ` +
+        'Conversation context, file contents and shown secrets are POSTed there.',
+    );
+  }
+  return raw;
+}
+
+/**
+ * Local models via any OpenAI-compatible server (Ollama, LM Studio, llama.cpp,
+ * vLLM). Reuses the shared {@link defineOpenAICompatProvider} pointed at a
+ * localhost base URL, with the `local` slug forced on. `validate: false` and a
+ * placeholder API key: local servers don't authenticate, so the credential path
+ * supplies a placeholder (see `resolveProviderCredentials` in the CLI),
+ * activation never prompts, and we never probe a possibly-offline box.
+ *
+ * Env-var resolution is duplicated by design: in the CLI flow
+ * `resolveProviderCredentials` pre-resolves `apiKey`/`baseURL` into the config
+ * (so the env reads below are unreachable there), but non-CLI callers
+ * (desktop / provider-admin direct `createClient`) don't — these `resolve*`
+ * functions are the authoritative readers for them, with identical precedence.
+ */
+export const localProviderDef = defineOpenAICompatProvider({
+  name: 'local',
+  baseURL: DEFAULT_LOCAL_BASE_URL,
+  defaultModel: LOCAL_DEFAULT_MODEL,
+  models: localModels,
+  validate: false,
+  resolveApiKey: (cfg) => cfg.apiKey ?? process.env.LOCAL_API_KEY ?? LOCAL_PLACEHOLDER_KEY,
+  resolveBaseURL: resolveLocalBaseURL,
+  auth: {
+    kind: 'apiKey',
+    envVar: 'LOCAL_API_KEY',
+    hint: 'optional — local servers need no key; set LOCAL_MODEL_BASE_URL for a non-Ollama endpoint',
+  },
+});
+
+export const localPlugin = definePlugin({
+  name: '@moxxy/plugin-provider-local',
+  version: '0.0.0',
+  providers: [localProviderDef],
+});
+
+export default localPlugin;