@stratusagent/provider-openai 0.11.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stratus Labs
+
+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,74 @@
+# @stratusagent/provider-openai
+
+The OpenAI-compatible chat-completions provider, as a **plugin**. It
+registers a provider named `openai-compatible` through the plugin seam
+([19](../../docs/roadmap/19-registration-seams.md)), and a soul selects it
+the way it selects a built-in:
+
+```markdown
+---
+id: ava
+provider: openai-compatible
+model: llama3
+credentials: [openai.apiKey]
+---
+```
+
+## Install and enable
+
+```bash
+npm install @stratusagent/provider-openai
+```
+
+```jsonc
+// ~/.stratus/config.json — a trusted config only
+{
+  "plugins": {
+    "@stratusagent/provider-openai": {
+      "enabled": true,
+      "baseUrl": "http://127.0.0.1:11434/v1",   // any chat-completions endpoint; omit for api.openai.com
+      "model": "llama3"                          // the default when a soul names none
+    }
+  }
+}
+```
+
+Then store the key it uses, as a **named credential** — the agent's own
+entry, or one the fleet shares — and list it in each soul's `credentials:`:
+
+```bash
+stratus credential set openai.apiKey                # shared by every agent that lists it
+stratus credential set openai.apiKey --agent ava    # ava's own account
+```
+
+## Settings
+
+| Key | What it sets |
+| --- | --- |
+| `baseUrl` | The endpoint. Default: the OpenAI API |
+| `model` | The model when a soul or config names none. A run with neither is refused, naming both places |
+| `headers` | Extra request headers, name to value |
+| `vision` | Whether the model takes images. Default `true`; `false` for a text-only model |
+| `requestTimeoutMs` | Upper bound on one request. Default five minutes; `0` disables |
+
+## How this differs from `provider: openai`
+
+Same adapter — `createOpenAICompatibleProvider` from
+`@stratusagent/providers`, unchanged — arriving the way a third party's
+provider would, which is why it exists:
+
+- **The key is a per-agent credential, resolved on every request.**
+  `openai.apiKey` goes through the manifest-bound resolver for the agent
+  the request is for: its own entry first, then the shared one. Two agents
+  on one installed plugin can bill to two accounts, a rotated key takes
+  effect on the next turn, and an agent whose soul does not list the name
+  cannot use it. Nothing here reads `process.env`.
+- **The endpoint is the plugin's setting**, not a stored sign-in's binding.
+  The built-in `openai` selection keeps its stored sign-in, its
+  endpoint-bound key, and `STRATUS_API_KEY`; none of that reaches this
+  plugin, and none of it is needed here.
+- **It works as a fallback target**: `fallbackProvider: openai-compatible`
+  with a `fallbackModel` fails over to it under the same rules as a
+  built-in.
+
+Diagnostics show it as `plugin:openai-compatible`.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import type { JsonObject, Plugin } from '@stratusagent/core';
+/**
+ * The name a soul selects this provider by. Not `openai`: that name is the
+ * built-in adapter with its stored sign-in and endpoint binding, and a
+ * plugin may not shadow a built-in — the host refuses the manifest.
+ */
+export declare const OPENAI_COMPATIBLE_PROVIDER_NAME = "openai-compatible";
+/** The credential this plugin resolves, per calling agent — declared in the manifest. */
+export declare const OPENAI_API_KEY_CREDENTIAL = "openai.apiKey";
+export interface OpenAiProviderPluginOptions {
+    /** Test injection: the transport the adapter sends on. */
+    fetch?: typeof fetch;
+}
+/**
+ * The OpenAI-compatible adapter, reached through the provider seam.
+ *
+ * The adapter is `@stratusagent/providers`' `createOpenAICompatibleProvider`
+ * unchanged; what this package adds is the two things a plugin provider
+ * gets that a built-in does not. Its settings — the endpoint, a default
+ * model, extra headers — come from its own config block. And its key comes
+ * through the manifest-bound credential resolver, **per calling agent**:
+ * `openai.apiKey` is a named credential the soul allowlists, resolved on
+ * every request from the agent the request is for, so two agents on one
+ * installed plugin can bill to two accounts, and a rotated key needs no
+ * restart. The adapter takes a fixed key, so one is built per (selection,
+ * key) and kept — never one per turn.
+ *
+ * Nothing here reads `process.env`, and the built-in `openai` selection —
+ * the stored sign-in, the endpoint binding, `STRATUS_API_KEY` — is
+ * untouched: this is the same adapter arriving the way a third party's
+ * would, which is the point of building it.
+ */
+export declare const createOpenAiProviderPlugin: (config?: JsonObject, options?: OpenAiProviderPluginOptions) => Plugin;
+/** The loader's entry point. See docs/architecture/plugins.md. */
+export declare const createPlugin: (config: JsonObject) => Plugin;
+//# 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,KAAK,EAEV,UAAU,EAEV,MAAM,EAGP,MAAM,oBAAoB,CAAC;AAG5B;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,sBAAsB,CAAC;AAEnE,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD,MAAM,WAAW,2BAA2B;IAC1C,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAiBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAQ,UAAe,EACvB,UAAS,2BAAgC,KACxC,MA6EF,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,YAAY,GAAI,QAAQ,UAAU,KAAG,MAA4C,CAAC"}

package/dist/index.js

@@ -0,0 +1,111 @@
+import { createOpenAICompatibleProvider } from '@stratusagent/providers';
+/**
+ * The name a soul selects this provider by. Not `openai`: that name is the
+ * built-in adapter with its stored sign-in and endpoint binding, and a
+ * plugin may not shadow a built-in — the host refuses the manifest.
+ */
+export const OPENAI_COMPATIBLE_PROVIDER_NAME = 'openai-compatible';
+/** The credential this plugin resolves, per calling agent — declared in the manifest. */
+export const OPENAI_API_KEY_CREDENTIAL = 'openai.apiKey';
+const readString = (value) => (typeof value === 'string' && value.length > 0 ? value : undefined);
+const readHeaders = (value) => {
+    const headers = {};
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return headers;
+    }
+    for (const [name, entry] of Object.entries(value)) {
+        if (typeof entry === 'string') {
+            headers[name] = entry;
+        }
+    }
+    return headers;
+};
+/**
+ * The OpenAI-compatible adapter, reached through the provider seam.
+ *
+ * The adapter is `@stratusagent/providers`' `createOpenAICompatibleProvider`
+ * unchanged; what this package adds is the two things a plugin provider
+ * gets that a built-in does not. Its settings — the endpoint, a default
+ * model, extra headers — come from its own config block. And its key comes
+ * through the manifest-bound credential resolver, **per calling agent**:
+ * `openai.apiKey` is a named credential the soul allowlists, resolved on
+ * every request from the agent the request is for, so two agents on one
+ * installed plugin can bill to two accounts, and a rotated key needs no
+ * restart. The adapter takes a fixed key, so one is built per (selection,
+ * key) and kept — never one per turn.
+ *
+ * Nothing here reads `process.env`, and the built-in `openai` selection —
+ * the stored sign-in, the endpoint binding, `STRATUS_API_KEY` — is
+ * untouched: this is the same adapter arriving the way a third party's
+ * would, which is the point of building it.
+ */
+export const createOpenAiProviderPlugin = (config = {}, options = {}) => {
+    const baseUrl = readString(config.baseUrl);
+    const configuredModel = readString(config.model);
+    const headers = readHeaders(config.headers);
+    const vision = typeof config.vision === 'boolean' ? config.vision : undefined;
+    const requestTimeoutMs = typeof config.requestTimeoutMs === 'number' ? config.requestTimeoutMs : undefined;
+    return {
+        name: 'provider-openai',
+        setup(context) {
+            if (!context.providers) {
+                throw new Error(`This host hands plugins no provider handle, so @stratusagent/provider-openai cannot register ${OPENAI_COMPATIBLE_PROVIDER_NAME}.`);
+            }
+            const credentials = context.credentials;
+            context.providers.register({
+                name: OPENAI_COMPATIBLE_PROVIDER_NAME,
+                // The chat-completions adapter answers in one response; nothing
+                // reaches `onDelta`, so a host must not arm a stall watchdog over it.
+                streams: false,
+                create(selection) {
+                    const model = selection.model ?? configuredModel;
+                    if (model === undefined) {
+                        throw new Error(`No model for provider ${OPENAI_COMPATIBLE_PROVIDER_NAME}: set model: in the soul, or model in plugins["@stratusagent/provider-openai"].`);
+                    }
+                    // One adapter per key this selection has been asked to use. A
+                    // fleet of agents on one account shares one; an agent on its own
+                    // account gets its own; a rotated key gets a fresh one.
+                    const adapters = new Map();
+                    const adapterFor = (apiKey) => {
+                        let adapter = adapters.get(apiKey);
+                        if (!adapter) {
+                            adapter = createOpenAICompatibleProvider({
+                                model,
+                                apiKey,
+                                name: OPENAI_COMPATIBLE_PROVIDER_NAME,
+                                headers,
+                                ...(baseUrl !== undefined ? { baseUrl } : {}),
+                                ...(selection.systemPrompt !== undefined ? { systemPrompt: selection.systemPrompt } : {}),
+                                ...(vision !== undefined ? { vision } : {}),
+                                ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
+                                ...(options.fetch !== undefined ? { fetch: options.fetch } : {}),
+                            });
+                            adapters.set(apiKey, adapter);
+                        }
+                        return adapter;
+                    };
+                    return {
+                        name: OPENAI_COMPATIBLE_PROVIDER_NAME,
+                        async generate(request) {
+                            if (!credentials) {
+                                throw new Error(`This host hands plugins no credential resolver, so ${OPENAI_COMPATIBLE_PROVIDER_NAME} cannot reach ${OPENAI_API_KEY_CREDENTIAL} for agent ${request.session.agent.id}.`);
+                            }
+                            // The calling agent's key, every request — its own entry,
+                            // then the fleet's shared one — and refused, naming the
+                            // remedy, rather than read from the environment.
+                            const apiKey = await credentials.resolve(request.session.agent, OPENAI_API_KEY_CREDENTIAL);
+                            if (apiKey === undefined) {
+                                throw new Error(`No ${OPENAI_API_KEY_CREDENTIAL} credential resolves for agent ${request.session.agent.id}. `
+                                    + `Store one with \`stratus credential set ${OPENAI_API_KEY_CREDENTIAL}\` (or per agent with --agent), and list it in the soul's credentials:.`);
+                            }
+                            return adapterFor(apiKey).generate(request);
+                        },
+                    };
+                },
+            });
+        },
+    };
+};
+/** The loader's entry point. See docs/architecture/plugins.md. */
+export const createPlugin = (config) => createOpenAiProviderPlugin(config);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@stratusagent/provider-openai",
+  "version": "0.11.4",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.13 <23 || >=23.4"
+  },
+  "dependencies": {
+    "@stratusagent/core": "0.11.4",
+    "@stratusagent/providers": "0.11.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3",
+    "@stratusagent/plugins": "0.11.4",
+    "@stratusagent/state": "0.11.4"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stratuslabs/agent.git",
+    "directory": "packages/provider-openai"
+  },
+  "description": "The OpenAI-compatible chat-completions provider as a Stratus plugin: registers `openai-compatible`, selectable by a soul, credentialed per agent through the plugin seam",
+  "keywords": [
+    "stratus",
+    "agent",
+    "ai",
+    "llm",
+    "stratus-plugin",
+    "openai",
+    "provider"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "stratus": {
+    "pluginVersion": 1,
+    "contributes": {
+      "providers": [
+        {
+          "name": "openai-compatible"
+        }
+      ]
+    },
+    "credentials": [
+      "openai.apiKey"
+    ],
+    "config": {
+      "type": "object",
+      "properties": {
+        "baseUrl": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "headers": {
+          "type": "object"
+        },
+        "vision": {
+          "type": "boolean"
+        },
+        "requestTimeoutMs": {
+          "type": "integer"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit --project tsconfig.test.json",
+    "test": "node --test --experimental-strip-types"
+  }
+}