@sigrun/provider-openai 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-08
+
+### Added
+
+- Initial release: OpenAI chat models through pi-ai, scoped settings, and a configurable API base URL.
+- The decision provider kind: one provider per configured model over `POST /v1/decisions`.
+- The embedding provider kind: every configured model over `POST /v1/embeddings`, split by input count and by an estimated token budget, with a per-model `local` report derived from `baseUrl`'s host.
+- One shared readiness tracker across the three kinds.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+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

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @sigrun/provider-openai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sigrun extension package for OpenAI-compatible providers. Version 0.1.0
+contributes three provider kinds under the provider id `openai`: pi-ai's OpenAI
+chat catalog through the Responses API (classifier models kept out of the chat
+catalog), decision providers over `POST /v1/decisions`, and embedding providers
+over `POST /v1/embeddings`.
+
+## Install
+
+Add `@sigrun/provider-openai` to the sigrun packages and extensions lists in
+`settings.json`, then restart sigrun.
+
+## Credential
+
+The provider id is `openai`. Core resolves `auth.json["openai"].apiKey` first,
+then the ambient `OPENAI_API_KEY`; the key is per id, so one credential serves
+every kind. Chat authentication uses pi-ai's normal credential resolution and
+applies the configured base URL to each request. Decisions and embeddings
+receive the resolved key per call; both work without one against a custom
+`baseUrl` that does not need it (a local endpoint, for example).
+
+Readiness is reported per kind: `not_configured` when no call has presented a
+credential yet AND `baseUrl` points at `api.openai.com`, otherwise `ready`
+until a call fails (then `degraded`, with the error, until a success). The
+tracker cannot read `auth.json`, so a keyed install pointed at the public API
+reports `not_configured` until its first call — display only, and the first
+successful call clears it.
+
+## Settings
+
+Scoped settings live in `settings/provider-openai.json`. Every setting is read
+when the extension loads; restart sigrun after editing it.
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `baseUrl` | `https://api.openai.com/v1` | OpenAI-compatible API root |
+| `chat.enabled` | `true` | Contribute OpenAI chat models |
+| `decisions.enabled` | `true` | Contribute the decision provider |
+| `decisions.models` | `["gpt-6-luna"]` | Decision model ids |
+| `embeddings.enabled` | `true` | Contribute the embedding provider |
+| `embeddings.models` | `[{id: "text-embedding-3-small", dimensions: 1536}, {id: "text-embedding-3-large", dimensions: 3072}]` | Embedding model ids and vector dimensions |
+| `embeddings.maxBatch` | `2048` | Maximum inputs per embedding request |
+
+Unknown or malformed settings warn and fall back per key. The default `baseUrl`
+is passed through unchanged; do not add or remove a trailing slash when using
+pi-ai's OpenAI subscription-auth behavior.
+
+## Provider kinds
+
+- **Chat:** pi-ai's OpenAI Responses provider, model catalog included.
+- **Decisions:** one provider per configured model, posted to
+  `POST <baseUrl>/decisions`.
+- **Embeddings:** one provider with every configured model. Each request is
+  split so it holds at most `embeddings.maxBatch` inputs and stays within the
+  endpoint's per-request token ceiling (estimated at four characters per
+  token); vectors return in input order. Each model reports `local` when
+  `baseUrl`'s host is loopback or a private address (`127.0.0.0/8`, `::1`,
+  `localhost`, `10/8`, `172.16/12`, `192.168/16`, `fc00::/7`), so a local
+  embedding server can serve `confidentiality: "local-only"` calls once the
+  admin lists the model in core's `embeddings.localModels`.
+
+Readiness is one tracker per kind, fed by the calls themselves: `ready` on a
+custom `baseUrl`, and `not_configured` on the default public endpoint until a
+call presents a credential (the tracker cannot read `auth.json`, so this is a
+display-only gap the first successful call closes); a failed call reports
+`degraded` with the error until a success clears it.
+
+## Development
+
+```sh
+npm install
+npm test          # manifest check + vitest
+npm run typecheck
+npm run build     # emits dist/ (committed)
+```
+
+Tests are hermetic and use synthetic credentials and hosts. No real API key or
+network access is required.

package/dist/chat.d.ts

@@ -0,0 +1,13 @@
+import type { ProviderContribution } from "@sigrun/sigrun/extension";
+/**
+ * pi-ai's OpenAI provider with a chat-only catalog and a per-request base URL.
+ *
+ * The contribution carries the plugin's shared readiness tracker, fed by
+ * the auth resolution pi-ai performs before every request: a resolved
+ * apiKey is the plugin's only evidence that a credential exists (it cannot
+ * read `auth.json`). Chat requests themselves fail inside pi-ai's stream,
+ * which this plugin never observes, so chat readiness reports
+ * `not_configured` until the first authenticated request and stays `ready`
+ * afterwards — the same display-only limitation every kind shares.
+ */
+export declare function createOpenAIChat(baseUrl: string): ProviderContribution;

package/dist/chat.js

@@ -0,0 +1,42 @@
+import { isModelType } from "@earendil-works/pi-ai/models";
+import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { createOpenAIReadiness } from "./readiness.js";
+/**
+ * pi-ai's OpenAI provider with a chat-only catalog and a per-request base URL.
+ *
+ * The contribution carries the plugin's shared readiness tracker, fed by
+ * the auth resolution pi-ai performs before every request: a resolved
+ * apiKey is the plugin's only evidence that a credential exists (it cannot
+ * read `auth.json`). Chat requests themselves fail inside pi-ai's stream,
+ * which this plugin never observes, so chat readiness reports
+ * `not_configured` until the first authenticated request and stays `ready`
+ * afterwards — the same display-only limitation every kind shares.
+ */
+export function createOpenAIChat(baseUrl) {
+    const readiness = createOpenAIReadiness(baseUrl);
+    const base = openaiProvider();
+    const models = (base.getAllModels?.() ?? base.getModels()).filter((model) => !isModelType(model, "classifier"));
+    const provider = {
+        ...base,
+        auth: {
+            ...base.auth,
+            ...(base.auth.apiKey === undefined ? {} : {
+                apiKey: {
+                    ...base.auth.apiKey,
+                    resolve: async (input) => {
+                        const resolved = await base.auth.apiKey.resolve(input);
+                        if (resolved !== undefined && typeof resolved.auth?.apiKey === "string") {
+                            readiness.noteCredential(resolved.auth.apiKey);
+                        }
+                        return resolved === undefined
+                            ? undefined
+                            : { ...resolved, auth: { ...resolved.auth, baseUrl } };
+                    },
+                },
+            }),
+        },
+        getModels: () => models.filter((model) => isModelType(model, "chat")),
+        getAllModels: () => models,
+    };
+    return { provider, readiness: () => readiness.readiness() };
+}

package/dist/decisions.d.ts

@@ -0,0 +1,11 @@
+import type { DecisionProviderContribution } from "@sigrun/sigrun/extension";
+type DecisionModels = readonly string[];
+/**
+ * The decision-provider contribution. Readiness is `not_configured` when the
+ * last call carried no credential and the endpoint is OpenAI's own host (a
+ * keyless custom endpoint stays ready); a failed call marks the tracker
+ * `degraded` until a success. `evaluate` throws for transport and answer
+ * failures; core maps a throw to `failed`.
+ */
+export declare function createOpenAIDecisions(baseUrl: string, models: DecisionModels, warn?: (message: string) => void): DecisionProviderContribution;
+export {};

package/dist/decisions.js

@@ -0,0 +1,199 @@
+/**
+ * The OpenAI Decisions API as a sigrun decision provider. pi-ai's own
+ * `classify` drops the per-level probabilities of score answers and
+ * never throws, so this module builds the request body itself, posts it
+ * with pi-ai's transport (`postClassifierRequest` — retries and bearer auth;
+ * usage and answers are parsed locally), and parses the raw answers. The predicate-instructions
+ * wording mirrors pi-ai's openai-decisions client.
+ */
+import { postClassifierRequest } from "@earendil-works/pi-ai/api/classifier-shared";
+import { isModelType } from "@earendil-works/pi-ai/models";
+import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { createOpenAIReadiness } from "./readiness.js";
+const LABEL = "OpenAI Decisions";
+/** Cloudflare in front of api.openai.com answers 504 on very large inputs; retrying hits it again. */
+const NO_RETRY_STATUSES = [504];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/** One classifier catalog entry per configured model, with the settings baseUrl laid over it. */
+function classifierModels(baseUrl, models, warn) {
+    const base = openaiProvider();
+    const catalog = (base.getAllModels?.() ?? base.getModels()).filter((model) => isModelType(model, "classifier") && model.api === "openai-decisions");
+    const byId = new Map(catalog.map((model) => [model.id, model]));
+    const usable = [];
+    for (const id of models) {
+        if (byId.has(id)) {
+            usable.push(id);
+        }
+        else {
+            warn(`provider-openai: no OpenAI Decisions classifier catalog entry for "${id}"; dropping it`);
+        }
+    }
+    const ids = usable.length > 0 ? usable : catalog.map((model) => model.id);
+    if (usable.length === 0) {
+        warn("provider-openai: settings.decisions.models named no usable classifier model; using the default");
+    }
+    const result = new Map();
+    for (const id of ids) {
+        // postClassifierRequest posts to an explicit URL built like pi-ai's classify:
+        // new URL("decisions", `${baseUrl without trailing slashes}/`).
+        result.set(id, { ...byId.get(id), baseUrl });
+    }
+    return result;
+}
+function predicateInstructions(name, question) {
+    const instructions = question.instructions === undefined ? name : text(question.instructions);
+    const meanings = [
+        question.criteria?.true !== undefined && question.criteria.true !== null
+            ? `True means: ${text(question.criteria.true)}`
+            : "",
+        question.criteria?.false !== undefined && question.criteria.false !== null
+            ? `False means: ${text(question.criteria.false)}`
+            : "",
+    ].filter(Boolean);
+    return meanings.length > 0 ? `${instructions}\n\n${meanings.join("\n")}` : instructions;
+}
+function wireQuestion(name, question) {
+    const instructions = question.instructions === undefined ? name : text(question.instructions);
+    if (question.type === "choice") {
+        return {
+            type: "choice",
+            name,
+            instructions,
+            choices: Object.entries(question.criteria).map(([value, description]) => description === null || description === undefined
+                ? { value }
+                : { value, description: text(description) }),
+        };
+    }
+    if (question.type === "score") {
+        return {
+            type: "score",
+            name,
+            instructions,
+            levels: question.criteria.map((label) => ({ label: text(label) })),
+        };
+    }
+    return { type: "predicate", name, instructions: predicateInstructions(name, question) };
+}
+function requiredNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${LABEL} returned an invalid ${field}`);
+    }
+    return value;
+}
+function probabilities(value, key, id) {
+    if (!Array.isArray(value))
+        throw new Error(`${LABEL} returned invalid probabilities for ${id}`);
+    return Object.fromEntries(value.map((entry) => {
+        if (!isRecord(entry) || typeof entry[key] !== "string") {
+            throw new Error(`${LABEL} returned invalid probabilities for ${id}`);
+        }
+        const name = entry[key];
+        return [name, requiredNumber(entry.probability, `probability for ${id}.${name}`)];
+    }));
+}
+function parseAnswer(id, question, answer) {
+    if (answer.type === "refusal")
+        throw new Error(`openai refused question ${id}`);
+    if (question.type === "choice") {
+        if (answer.type !== "choice" || typeof answer.choice !== "string") {
+            throw new Error(`${LABEL} did not return a choice answer for ${id}`);
+        }
+        return {
+            type: "choice",
+            choice: answer.choice,
+            confidence: requiredNumber(answer.confidence, `confidence for ${id}`),
+            probabilities: probabilities(answer.probabilities, "value", id),
+        };
+    }
+    if (question.type === "score") {
+        if (answer.type !== "score") {
+            throw new Error(`${LABEL} did not return a score answer for ${id}`);
+        }
+        return {
+            type: "score",
+            score: requiredNumber(answer.score, `score for ${id}`),
+            confidence: requiredNumber(answer.confidence, `confidence for ${id}`),
+            probabilities: probabilities(answer.probabilities, "label", id),
+        };
+    }
+    if (answer.type !== "predicate") {
+        throw new Error(`${LABEL} did not return a predicate answer for ${id}`);
+    }
+    return { type: "noul", noul: requiredNumber(answer.probability, `probability for ${id}`) };
+}
+function parseAnswers(body, request, model) {
+    if (!isRecord(body) || !Array.isArray(body.answers)) {
+        throw new Error(`${LABEL} returned an unexpected response`);
+    }
+    const byName = new Map();
+    for (const answer of body.answers) {
+        if (isRecord(answer) && typeof answer.name === "string")
+            byName.set(answer.name, answer);
+    }
+    const answers = {};
+    for (const [id, question] of Object.entries(request.questions)) {
+        const answer = byName.get(id);
+        if (answer === undefined)
+            throw new Error(`${LABEL} did not return an answer for ${id}`);
+        answers[id] = parseAnswer(id, question, answer);
+    }
+    const usage = isRecord(body.usage) ? body.usage : undefined;
+    return {
+        answers,
+        model: typeof body.model === "string" ? body.model : model.id,
+        usage: usage === undefined
+            ? undefined
+            : {
+                input_tokens: typeof usage.input_tokens === "number" ? usage.input_tokens : null,
+                output_tokens: typeof usage.output_tokens === "number" ? usage.output_tokens : null,
+            },
+    };
+}
+/**
+ * The decision-provider contribution. Readiness is `not_configured` when the
+ * last call carried no credential and the endpoint is OpenAI's own host (a
+ * keyless custom endpoint stays ready); a failed call marks the tracker
+ * `degraded` until a success. `evaluate` throws for transport and answer
+ * failures; core maps a throw to `failed`.
+ */
+export function createOpenAIDecisions(baseUrl, models, warn = () => { }) {
+    const catalog = classifierModels(baseUrl, models, warn);
+    // The shared three-state tracker (spec §3): every kind reports readiness
+    // the same way, including the display-only gap before the first call.
+    const readiness = createOpenAIReadiness(baseUrl);
+    return {
+        id: "openai",
+        label: "OpenAI",
+        credentialEnv: "OPENAI_API_KEY",
+        models: [...catalog.keys()].map((id) => ({ id })),
+        readiness: () => readiness.readiness(),
+        async evaluate(request, ctx) {
+            const model = catalog.get(ctx.model);
+            if (model === undefined)
+                throw new Error(`${LABEL} has no model "${ctx.model}"`);
+            readiness.noteCredential(ctx.credential);
+            if (readiness.publicEndpoint && ctx.credential === undefined) {
+                throw new Error("OpenAI Decisions: no API key (auth.json openai or OPENAI_API_KEY)");
+            }
+            try {
+                const body = await postClassifierRequest(LABEL, new URL("decisions", `${model.baseUrl.replace(/\/+$/u, "")}/`), model, {
+                    model: model.id,
+                    input: typeof request.state === "string" ? request.state : JSON.stringify(request.state),
+                    questions: Object.entries(request.questions).map(([id, question]) => wireQuestion(id, question)),
+                }, { apiKey: ctx.credential ?? "", signal: ctx.signal }, NO_RETRY_STATUSES);
+                const answers = parseAnswers(body, request, model);
+                readiness.noteSuccess();
+                return answers;
+            }
+            catch (error) {
+                readiness.noteFailure(error instanceof Error ? error.message : String(error));
+                throw error;
+            }
+        },
+    };
+}

package/dist/embeddings.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The OpenAI Embeddings API as a sigrun embedding provider (spec §3).
+ *
+ * One provider request becomes one or more `POST <baseUrl>/embeddings`
+ * calls: core splits by the model's `maxBatch` (input count), and this
+ * module splits again by the endpoint's per-request TOKEN ceiling, which is
+ * estimated at four characters per token — the same rough ratio OpenAI
+ * documents. Both limits apply to every HTTP request.
+ *
+ * Vectors come back in input order: the wire carries an `index` per entry
+ * and nothing guarantees the array order, so the response is re-sorted by
+ * it (a missing/duplicate/out-of-range index is a malformed response, not a
+ * guessing game).
+ *
+ * Failure messages never carry the credential or the input text: a non-2xx
+ * body is truncated to a short snippet with both scrubbed out.
+ */
+import type { EmbeddingProviderContribution } from "@sigrun/sigrun/extension";
+import type { OpenAIEmbeddingModelSettings } from "./settings.js";
+/** The endpoint's per-request token ceiling, in ESTIMATED tokens. */
+export declare const EMBEDDING_REQUEST_TOKEN_BUDGET = 300000;
+/**
+ * Whether `hostname` is loopback or a private address — the provider's own
+ * view of where a model runs (`EmbeddingModelInfo.local`). `hostname` comes
+ * from `new URL(baseUrl).hostname`, so an IPv6 literal keeps its brackets.
+ * An IPv4-mapped IPv6 literal is judged by the address it maps.
+ */
+export declare function isLocalHost(hostname: string): boolean;
+/**
+ * The embedding-provider contribution. `models` come from the scoped
+ * settings; `local` is this provider's own view of the endpoint (a host
+ * that is not a loopback or private address is never local, however the
+ * admin lists it). `embed` throws for transport, response and configuration
+ * failures; core maps a throw to `failed`.
+ */
+export declare function createOpenAIEmbeddings(baseUrl: string, models: readonly OpenAIEmbeddingModelSettings[], maxBatch: number): EmbeddingProviderContribution;

package/dist/embeddings.js

@@ -0,0 +1,237 @@
+import { createOpenAIReadiness } from "./readiness.js";
+/**
+ * The message prefix for every error this module raises. Deliberately the
+ * plugin's own name rather than the vendor's: these strings reach operators
+ * through core's failure result and this provider's readiness detail, and a
+ * plugin-named prefix is unambiguous there.
+ */
+const PREFIX = "provider-openai embeddings";
+/** The endpoint's per-request token ceiling, in ESTIMATED tokens. */
+export const EMBEDDING_REQUEST_TOKEN_BUDGET = 300_000;
+/**
+ * The estimation ratio: four characters per token. An empty string counts as
+ * one token (the endpoint bills a minimum), so a batch of empty inputs still
+ * advances the budget instead of looking free.
+ */
+const CHARS_PER_TOKEN = 4;
+/** How much of a failing response body reaches the error message. */
+const BODY_SNIPPET_CHARS = 200;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function octets(address) {
+    const parts = address.split(".");
+    if (parts.length !== 4)
+        return undefined;
+    const parsed = parts.map((part) => (/^\d{1,3}$/u.test(part) ? Number(part) : Number.NaN));
+    if (parsed.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255))
+        return undefined;
+    return parsed;
+}
+/** The dotted-quad classes: loopback 127/8, private 10/8, 172.16/12, 192.168/16. */
+function isLocalIPv4(address) {
+    const parsed = octets(address);
+    if (parsed === undefined)
+        return false;
+    const first = parsed[0] ?? Number.NaN;
+    const second = parsed[1] ?? Number.NaN;
+    if (first === 127)
+        return true;
+    if (first === 10)
+        return true;
+    if (first === 172 && second >= 16 && second <= 31)
+        return true;
+    return first === 192 && second === 168;
+}
+/** The IPv6 classes: loopback `::1` and unique-local `fc00::/7`. */
+function isLocalIPv6(address) {
+    const lower = address.toLowerCase();
+    if (lower === "::1")
+        return true;
+    const first = lower.split(":")[0] ?? "";
+    if (!/^[0-9a-f]{1,4}$/u.test(first))
+        return false;
+    return (Number.parseInt(first, 16) & 0xfe00) === 0xfc00;
+}
+/**
+ * Whether `hostname` is loopback or a private address — the provider's own
+ * view of where a model runs (`EmbeddingModelInfo.local`). `hostname` comes
+ * from `new URL(baseUrl).hostname`, so an IPv6 literal keeps its brackets.
+ * An IPv4-mapped IPv6 literal is judged by the address it maps.
+ */
+export function isLocalHost(hostname) {
+    const host = hostname.trim().toLowerCase().replace(/^\[/u, "").replace(/\]$/u, "");
+    if (host === "")
+        return false;
+    if (host === "localhost")
+        return true;
+    const dotted = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/u.exec(host);
+    if (dotted !== null)
+        return isLocalIPv4(dotted[1]);
+    const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/u.exec(host);
+    if (mapped !== null) {
+        const high = Number.parseInt(mapped[1], 16);
+        const low = Number.parseInt(mapped[2], 16);
+        return isLocalIPv4([high >> 8, high & 0xff, low >> 8, low & 0xff].join("."));
+    }
+    if (host.includes(":"))
+        return isLocalIPv6(host);
+    return isLocalIPv4(host);
+}
+/**
+ * Whether a thrown value is a caller cancellation rather than a provider
+ * failure. Node's `fetch` rejects with a `DOMException` named `AbortError`;
+ * the abort flag covers an implementation that rejects some other way after
+ * the signal fired. A cancellation says nothing about the endpoint's health,
+ * so it must not degrade readiness.
+ */
+function isAbort(error, signal) {
+    if (signal.aborted)
+        return true;
+    return (typeof error === "object" &&
+        error !== null &&
+        error.name === "AbortError");
+}
+/** The provider's estimated token count for one input text (never below 1). */
+function estimateTokens(text) {
+    return Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));
+}
+/**
+ * Split this provider request's inputs into per-HTTP-request batches: each
+ * batch holds at most `maxBatch` inputs AND stays within `budget` estimated
+ * tokens. An input that exceeds the budget on its own is sent alone — the
+ * estimate is a heuristic and the endpoint, not the estimate, has the final
+ * say on a single input.
+ */
+function splitInputs(input, maxBatch, budget) {
+    const batches = [];
+    let batch = [];
+    let tokens = 0;
+    for (const text of input) {
+        const estimate = estimateTokens(text);
+        if (batch.length > 0 && (batch.length >= maxBatch || tokens + estimate > budget)) {
+            batches.push(batch);
+            batch = [];
+            tokens = 0;
+        }
+        batch.push(text);
+        tokens += estimate;
+    }
+    if (batch.length > 0)
+        batches.push(batch);
+    return batches;
+}
+/**
+ * The error text for a failing response: the status plus a short snippet,
+ * with the credential AND the submitted inputs scrubbed out (the message
+ * reaches both core's failure result and this provider's readiness detail,
+ * and neither may carry either).
+ */
+function failureMessage(status, body, credential, input) {
+    let message = body.replace(/\s+/gu, " ").trim();
+    for (const sensitive of [credential, ...input]) {
+        if (sensitive !== undefined && sensitive !== "")
+            message = message.replaceAll(sensitive, "[redacted]");
+    }
+    const snippet = message.slice(0, BODY_SNIPPET_CHARS);
+    return `${PREFIX} returned ${status}${snippet === "" ? "" : `: ${snippet}`}`;
+}
+/**
+ * The embeddings of one response body, in `index` order. A body whose entry
+ * count, indexes or vector shape do not match the inputs is malformed.
+ */
+function parseVectors(payload, expected) {
+    if (!isRecord(payload) || !Array.isArray(payload.data)) {
+        throw new Error(`${PREFIX} returned an unexpected response`);
+    }
+    if (payload.data.length !== expected) {
+        throw new Error(`${PREFIX} returned ${payload.data.length} vectors for ${expected} inputs`);
+    }
+    const vectors = new Array(expected);
+    for (const [position, entry] of payload.data.entries()) {
+        if (!isRecord(entry) || !Array.isArray(entry.embedding)) {
+            throw new Error(`${PREFIX} returned an entry without an embedding`);
+        }
+        const index = entry.index === undefined ? position : entry.index;
+        if (typeof index !== "number" ||
+            !Number.isInteger(index) ||
+            index < 0 ||
+            index >= expected ||
+            vectors[index] !== undefined) {
+            throw new Error(`${PREFIX} returned an out-of-range or duplicate index`);
+        }
+        const vector = entry.embedding;
+        if (vector.some((element) => typeof element !== "number")) {
+            throw new Error(`${PREFIX} returned a non-numeric embedding element`);
+        }
+        vectors[index] = vector;
+    }
+    return vectors;
+}
+/**
+ * The embedding-provider contribution. `models` come from the scoped
+ * settings; `local` is this provider's own view of the endpoint (a host
+ * that is not a loopback or private address is never local, however the
+ * admin lists it). `embed` throws for transport, response and configuration
+ * failures; core maps a throw to `failed`.
+ */
+export function createOpenAIEmbeddings(baseUrl, models, maxBatch) {
+    const readiness = createOpenAIReadiness(baseUrl);
+    const local = isLocalHost(new URL(baseUrl).hostname);
+    const catalog = models.map((model) => ({
+        id: model.id,
+        dimensions: model.dimensions,
+        maxBatch,
+        local,
+    }));
+    const endpoint = new URL("embeddings", `${baseUrl.replace(/\/+$/u, "")}/`);
+    return {
+        id: "openai",
+        // The Providers-page display name, shared with the other two kinds.
+        label: "OpenAI",
+        credentialEnv: "OPENAI_API_KEY",
+        models: catalog,
+        readiness: () => readiness.readiness(),
+        async embed(request, ctx) {
+            readiness.noteCredential(ctx.credential);
+            if (readiness.publicEndpoint && ctx.credential === undefined) {
+                // Core only reaches here when readiness said so; keep a direct
+                // caller from sending a placeholder key to the public API.
+                throw new Error(`${PREFIX}: no API key (auth.json openai or OPENAI_API_KEY)`);
+            }
+            try {
+                const vectors = [];
+                for (const batch of splitInputs(request.input, maxBatch, EMBEDDING_REQUEST_TOKEN_BUDGET)) {
+                    const response = await fetch(endpoint, {
+                        method: "POST",
+                        headers: {
+                            "content-type": "application/json",
+                            ...(ctx.credential === undefined ? {} : { authorization: `Bearer ${ctx.credential}` }),
+                        },
+                        body: JSON.stringify({ model: request.model, input: batch }),
+                        signal: ctx.signal,
+                    });
+                    if (!response.ok) {
+                        const body = await response.text().catch(() => "");
+                        throw new Error(failureMessage(response.status, body, ctx.credential, batch));
+                    }
+                    const payload = await response.json().catch(() => undefined);
+                    if (payload === undefined)
+                        throw new Error(`${PREFIX} returned an unreadable response`);
+                    vectors.push(...parseVectors(payload, batch.length));
+                }
+                readiness.noteSuccess();
+                return { vectors };
+            }
+            catch (error) {
+                // A caller abort is a cancellation, not a failure: the tracker keeps
+                // reporting the provider's real health. Core maps its own deadline
+                // abort to `timeout`, which likewise says nothing about the endpoint.
+                if (!isAbort(error, ctx.signal)) {
+                    readiness.noteFailure(error instanceof Error ? error.message : String(error));
+                }
+                throw error;
+            }
+        },
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,8 @@
+/** Structural slice of sigrun's seam host consumed by this provider. */
+export interface OpenAIProviderHost {
+    readonly stores: {
+        readonly settings: {
+            get(): Promise<Record<string, unknown>>;
+        };
+    };
+}

package/dist/host.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/** @sigrun/provider-openai — provider-only OpenAI chat, decision and embedding contributions. */
+import type { DecisionProviderContribution, EmbeddingProviderContribution, ProviderContribution } from "@sigrun/sigrun/extension";
+import type { OpenAIProviderHost } from "./host.js";
+export { createOpenAIChat } from "./chat.js";
+export { createOpenAIDecisions } from "./decisions.js";
+export { createOpenAIEmbeddings, EMBEDDING_REQUEST_TOKEN_BUDGET, isLocalHost, } from "./embeddings.js";
+export { createOpenAIReadiness } from "./readiness.js";
+export type { OpenAIReadiness } from "./readiness.js";
+export type { OpenAIProviderHost } from "./host.js";
+export { DEFAULT_DECISION_MODELS, DEFAULT_EMBEDDING_MAX_BATCH, DEFAULT_EMBEDDING_MODELS, DEFAULT_OPENAI_BASE_URL, parseSettings, } from "./settings.js";
+export type { OpenAIEmbeddingModelSettings, OpenAIProviderSettings } from "./settings.js";
+export interface OpenAIProviderResult {
+    readonly name: "provider-openai";
+    readonly providers: readonly ProviderContribution[];
+    readonly decisionProviders?: readonly DecisionProviderContribution[];
+    readonly embeddingProviders?: readonly EmbeddingProviderContribution[];
+}
+/** Arity 1: sigrun supplies the scoped host; settings are read once at load. */
+export default function createOpenAIProvider(host: OpenAIProviderHost): Promise<OpenAIProviderResult>;

package/dist/index.js

@@ -0,0 +1,26 @@
+import { createOpenAIChat } from "./chat.js";
+import { createOpenAIDecisions } from "./decisions.js";
+import { createOpenAIEmbeddings } from "./embeddings.js";
+import { parseSettings } from "./settings.js";
+export { createOpenAIChat } from "./chat.js";
+export { createOpenAIDecisions } from "./decisions.js";
+export { createOpenAIEmbeddings, EMBEDDING_REQUEST_TOKEN_BUDGET, isLocalHost, } from "./embeddings.js";
+export { createOpenAIReadiness } from "./readiness.js";
+export { DEFAULT_DECISION_MODELS, DEFAULT_EMBEDDING_MAX_BATCH, DEFAULT_EMBEDDING_MODELS, DEFAULT_OPENAI_BASE_URL, parseSettings, } from "./settings.js";
+/** Arity 1: sigrun supplies the scoped host; settings are read once at load. */
+export default async function createOpenAIProvider(host) {
+    const warn = (message) => console.warn(message);
+    const settings = parseSettings(await host.stores.settings.get(), warn);
+    return {
+        name: "provider-openai",
+        providers: settings.chat.enabled ? [createOpenAIChat(settings.baseUrl)] : [],
+        ...(settings.decisions.enabled
+            ? { decisionProviders: [createOpenAIDecisions(settings.baseUrl, settings.decisions.models, warn)] }
+            : {}),
+        ...(settings.embeddings.enabled
+            ? {
+                embeddingProviders: [createOpenAIEmbeddings(settings.baseUrl, settings.embeddings.models, settings.embeddings.maxBatch)],
+            }
+            : {}),
+    };
+}

package/dist/readiness.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The one readiness tracker this plugin's provider kinds share (spec §3):
+ * `not_configured` when no credential has been seen AND `baseUrl`'s host is
+ * the vendor's own public API, otherwise `ready` until a call fails; a
+ * failed call leaves it `degraded` with the error text until a success
+ * clears it.
+ *
+ * A tracker CANNOT read `auth.json` — core owns credentials and hands them
+ * over per call — so "a credential exists" is learned only from a call that
+ * carried one. The visible consequence is display-only: before the first
+ * call, a keyed install pointed at the default base URL reports
+ * `not_configured`. That limitation is deliberate and shared by every kind;
+ * it is also why the rule keys on the endpoint as well, so a keyless custom
+ * endpoint (a local embedding server, say) starts `ready` instead of
+ * waiting for a call that may never carry a key.
+ */
+import type { ProviderReadiness } from "@sigrun/sigrun/extension";
+export interface OpenAIReadiness {
+    /** True when `baseUrl`'s host is the vendor's public API. */
+    readonly publicEndpoint: boolean;
+    /** The contribution's `readiness` tracker (a pure synchronous read). */
+    readiness(): ProviderReadiness;
+    /** Record the credential a call carried (absent/empty teaches nothing). */
+    noteCredential(credential: string | undefined): void;
+    /** Record a successful call: clears a previous failure. */
+    noteSuccess(): void;
+    /** Record a failed call; `message` becomes the degraded detail. */
+    noteFailure(message: string): void;
+}
+/** One tracker instance per provider kind, over the kind's resolved baseUrl. */
+export declare function createOpenAIReadiness(baseUrl: string): OpenAIReadiness;

package/dist/readiness.js

@@ -0,0 +1,28 @@
+/** The vendor's public API host: keyless use there is impossible. */
+const PUBLIC_HOST = "api.openai.com";
+/** One tracker instance per provider kind, over the kind's resolved baseUrl. */
+export function createOpenAIReadiness(baseUrl) {
+    const publicEndpoint = new URL(baseUrl).hostname === PUBLIC_HOST;
+    let configured = !publicEndpoint;
+    let failure;
+    return {
+        publicEndpoint,
+        readiness() {
+            if (!configured)
+                return { status: "not_configured" };
+            if (failure !== undefined)
+                return { status: "degraded", detail: failure };
+            return { status: "ready" };
+        },
+        noteCredential(credential) {
+            if (credential !== undefined && credential !== "")
+                configured = true;
+        },
+        noteSuccess() {
+            failure = undefined;
+        },
+        noteFailure(message) {
+            failure = message;
+        },
+    };
+}

package/dist/settings.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scoped settings for settings/provider-openai.json. Invalid or unknown keys
+ * warn and fall back per key; malformed settings never quarantine the plugin.
+ */
+export declare const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+export declare const DEFAULT_DECISION_MODELS: readonly ["gpt-6-luna"];
+export declare const DEFAULT_EMBEDDING_MODELS: readonly [{
+    readonly id: "text-embedding-3-small";
+    readonly dimensions: 1536;
+}, {
+    readonly id: "text-embedding-3-large";
+    readonly dimensions: 3072;
+}];
+export declare const DEFAULT_EMBEDDING_MAX_BATCH = 2048;
+export interface OpenAIEmbeddingModelSettings {
+    readonly id: string;
+    readonly dimensions: number;
+}
+export interface OpenAIProviderSettings {
+    readonly baseUrl: string;
+    readonly chat: {
+        readonly enabled: boolean;
+    };
+    readonly decisions: {
+        readonly enabled: boolean;
+        readonly models: readonly string[];
+    };
+    readonly embeddings: {
+        readonly enabled: boolean;
+        readonly models: readonly OpenAIEmbeddingModelSettings[];
+        readonly maxBatch: number;
+    };
+}
+type Warn = (message: string) => void;
+/** Parse one scoped settings snapshot without reading storage or the environment. */
+export declare function parseSettings(raw: Record<string, unknown>, warn: Warn): OpenAIProviderSettings;
+export {};

package/dist/settings.js

@@ -0,0 +1,138 @@
+/**
+ * Scoped settings for settings/provider-openai.json. Invalid or unknown keys
+ * warn and fall back per key; malformed settings never quarantine the plugin.
+ */
+export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+export const DEFAULT_DECISION_MODELS = ["gpt-6-luna"];
+export const DEFAULT_EMBEDDING_MODELS = [
+    { id: "text-embedding-3-small", dimensions: 1536 },
+    { id: "text-embedding-3-large", dimensions: 3072 },
+];
+export const DEFAULT_EMBEDDING_MAX_BATCH = 2048;
+function section(raw, key, warn) {
+    const value = raw[key];
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn(`provider-openai: settings.${key} must be an object; using the default`);
+        return {};
+    }
+    return value;
+}
+function unknownKeys(raw, known, path, warn) {
+    for (const key of Object.keys(raw)) {
+        if (!known.includes(key)) {
+            warn(`provider-openai: unknown ${path} key "${key}"; ignoring`);
+        }
+    }
+}
+function boolean(raw, key, path, warn) {
+    const value = raw[key];
+    if (value === undefined)
+        return true;
+    if (typeof value !== "boolean") {
+        warn(`provider-openai: settings.${path}.${key} must be a boolean; using the default`);
+        return true;
+    }
+    return value;
+}
+function decisionModels(raw, warn) {
+    if (raw.models === undefined)
+        return [...DEFAULT_DECISION_MODELS];
+    if (!Array.isArray(raw.models)) {
+        warn("provider-openai: settings.decisions.models must be an array; using the default");
+        return [...DEFAULT_DECISION_MODELS];
+    }
+    const models = raw.models.filter((model) => typeof model === "string" && model.trim().length > 0).map((model) => model.trim());
+    if (models.length !== raw.models.length) {
+        warn("provider-openai: settings.decisions.models dropped entries that were not non-empty strings");
+    }
+    const deduped = [...new Set(models)];
+    if (deduped.length !== models.length) {
+        warn("provider-openai: settings.decisions.models dropped duplicate entries");
+    }
+    if (deduped.length === 0) {
+        warn("provider-openai: settings.decisions.models left no usable entry; using the default");
+        return [...DEFAULT_DECISION_MODELS];
+    }
+    return deduped;
+}
+function embeddingModels(raw, warn) {
+    if (raw.models === undefined)
+        return DEFAULT_EMBEDDING_MODELS.map((model) => ({ ...model }));
+    if (!Array.isArray(raw.models)) {
+        warn("provider-openai: settings.embeddings.models must be an array; using the default");
+        return DEFAULT_EMBEDDING_MODELS.map((model) => ({ ...model }));
+    }
+    const models = [];
+    let dropped = false;
+    for (const entry of raw.models) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            dropped = true;
+            continue;
+        }
+        const value = entry;
+        unknownKeys(value, ["id", "dimensions"], "settings.embeddings.models entry", warn);
+        if (typeof value.id !== "string" || value.id.trim().length === 0 ||
+            typeof value.dimensions !== "number" || !Number.isInteger(value.dimensions) || value.dimensions <= 0) {
+            dropped = true;
+            continue;
+        }
+        models.push({ id: value.id.trim(), dimensions: value.dimensions });
+    }
+    if (dropped) {
+        warn("provider-openai: settings.embeddings.models dropped entries without a non-empty id and positive integer dimensions");
+    }
+    if (models.length === 0) {
+        warn("provider-openai: settings.embeddings.models left no usable entry; using the default");
+        return DEFAULT_EMBEDDING_MODELS.map((model) => ({ ...model }));
+    }
+    return models;
+}
+/** Parse one scoped settings snapshot without reading storage or the environment. */
+export function parseSettings(raw, warn) {
+    unknownKeys(raw, ["baseUrl", "chat", "decisions", "embeddings"], "settings", warn);
+    let baseUrl = DEFAULT_OPENAI_BASE_URL;
+    if (raw.baseUrl !== undefined) {
+        if (typeof raw.baseUrl === "string" && raw.baseUrl.length > 0) {
+            try {
+                new URL(raw.baseUrl);
+                baseUrl = raw.baseUrl;
+            }
+            catch {
+                warn("provider-openai: settings.baseUrl is not a valid URL; using the default");
+            }
+        }
+        else {
+            warn("provider-openai: settings.baseUrl must be a non-empty string; using the default");
+        }
+    }
+    const chat = section(raw, "chat", warn);
+    unknownKeys(chat, ["enabled"], "settings.chat", warn);
+    const decisions = section(raw, "decisions", warn);
+    unknownKeys(decisions, ["enabled", "models"], "settings.decisions", warn);
+    const embeddings = section(raw, "embeddings", warn);
+    unknownKeys(embeddings, ["enabled", "models", "maxBatch"], "settings.embeddings", warn);
+    let maxBatch = DEFAULT_EMBEDDING_MAX_BATCH;
+    if (embeddings.maxBatch !== undefined) {
+        if (typeof embeddings.maxBatch === "number" && Number.isInteger(embeddings.maxBatch) && embeddings.maxBatch > 0) {
+            maxBatch = embeddings.maxBatch;
+        }
+        else {
+            warn("provider-openai: settings.embeddings.maxBatch must be a positive integer; using the default");
+        }
+    }
+    return {
+        baseUrl,
+        chat: { enabled: boolean(chat, "enabled", "chat", warn) },
+        decisions: {
+            enabled: boolean(decisions, "enabled", "decisions", warn),
+            models: decisionModels(decisions, warn),
+        },
+        embeddings: {
+            enabled: boolean(embeddings, "enabled", "embeddings", warn),
+            models: embeddingModels(embeddings, warn),
+            maxBatch,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,53 @@
 {
-  "name": "@sigrun/provider-openai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sigrun/provider-openai",
+	"version": "0.1.0",
+	"description": "Sigrun provider plugin: OpenAI chat, decisions, and embeddings",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"test": "node scripts/check-manifest.mjs --expect-name @sigrun/provider-openai && vitest run",
+		"typecheck": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepare": "npm run build"
+	},
+	"dependencies": {},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "1.5.0",
+		"@earendil-works/pi-durable": "1.5.0",
+		"@sigrun/sigrun": "file:../sigrun",
+		"@types/node": "^26.6.4",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "github",
+		"url": "git+https://github.com/sigrun-ai/sigrun-provider-openai.git"
+	},
+	"bugs": {
+		"url": "https://github.com/sigrun-ai/sigrun-provider-openai/issues"
+	},
+	"homepage": "https://github.com/sigrun-ai/sigrun-provider-openai#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-durable": "*"
+	}
+}