@agenticprimitives/orchestration-openai-compat 0.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust 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,67 @@
+# @agenticprimitives/orchestration-openai-compat
+
+The **OpenAI-compatible LLM binding** for the [`@agenticprimitives/orchestration`](../orchestration) `Planner`
+and `AnswerComposer` ports — the in-repo adapter (the `chain-state` / `chain-state-viem` pattern), sibling to
+[`orchestration-anthropic`](../orchestration-anthropic). The pure orchestration core stays vendor-free; the
+chat-completions translation lives here.
+
+**Vendor-neutral.** This package names no host and no model. Groq, Ollama, OpenRouter, a self-hosted vLLM: each
+is a `baseUrl` + `model` you supply.
+
+## Install
+
+```bash
+pnpm add @agenticprimitives/orchestration-openai-compat @agenticprimitives/orchestration
+```
+
+## Quick start (Groq)
+
+```ts
+import { runIntent, type ToolSpec } from '@agenticprimitives/orchestration';
+import { createOpenAiCompatPlanner, createFetchOpenAiCompatClient } from '@agenticprimitives/orchestration-openai-compat';
+
+const tools: ToolSpec[] = [
+  { id: 'get_vault_record', description: 'Read a vault record by recordType.', inputSchema: { type: 'object', properties: { recordType: { type: 'string' } }, required: ['recordType'] } },
+  { id: 'get_pii', description: 'Read the principal’s PII (high sensitivity).' },
+];
+
+// Dependency-free client — works in a Cloudflare Worker (no SDK, no node shims). The host is YOUR choice.
+const client = createFetchOpenAiCompatClient({ apiKey: env.GROQ_API_KEY, baseUrl: 'https://api.groq.com/openai/v1' });
+const planner = createOpenAiCompatPlanner({ client, model: 'openai/gpt-oss-120b', label: 'groq' });
+
+const result = await runIntent(
+  { goal: 'show me my profile' },
+  { planner, tools, invoke: async (toolId, args) => myDelegatedMcpCall(toolId, args) },
+);
+```
+
+The model chooses **which** tool fits the goal; the chosen call still rides the task's on-chain delegation at
+the invoker (ADR-0041). The model never gains authority by being asked.
+
+## What else is here
+
+- `createOpenAiCompatComposer({ client, model })` — turns what the tools returned into a grounded sentence.
+- `createOpenAiCompatStructuredCall({ client, model })` — one forced single-tool call (a query, a selection).
+- `OpenAiCompatHttpError` — thrown on a non-OK response with `status` and, on a 429, `retryAfterSeconds`. Say
+  it to the person; never route to another vendor because of it.
+
+## `OpenAiCompatLike`
+
+Every factory takes a structural `OpenAiCompatLike` client (the minimal `chat.completions.create` surface).
+Pass either `createFetchOpenAiCompatClient({ apiKey, baseUrl })` or the official `new OpenAI({ apiKey, baseURL })`
+— it satisfies the same shape. This keeps the adapter unit-testable with a fake and avoids a hard SDK dependency.
+
+## Wire notes
+
+- Tool `arguments` arrive as a JSON **string**; the adapter parses them. Unparseable → `planner_failed`.
+- `tool_choice: 'required'` is a request; a prose-only reply is `no_plan`.
+- The client is non-streaming. Fine for planning / answering budgets; a very long generation may hit an
+  intermediary timeout until streaming lands.
+
+## Boundaries
+
+Imports only `@agenticprimitives/orchestration` (+ `types`). See `spec.md` + `capability.manifest.json`.
+
+## License
+
+MIT

package/dist/composer.d.ts

@@ -0,0 +1,16 @@
+import type { AnswerComposer } from '@agenticprimitives/orchestration';
+import type { OpenAiCompatLike } from './types.js';
+export interface OpenAiCompatComposerOpts {
+    client: OpenAiCompatLike;
+    /** The answering model, as the host names it. REQUIRED. */
+    model: string;
+    maxTokens?: number;
+    /** Extra guidance appended after the contract above (e.g. an org's voice). Never replaces it. */
+    systemPrompt?: string;
+    /** Cap on the observation JSON handed to the model, in characters. */
+    maxEvidenceChars?: number;
+    /** Names the consumer in errors. Default `openai-compat`. */
+    label?: string;
+}
+export declare function createOpenAiCompatComposer(opts: OpenAiCompatComposerOpts): AnswerComposer;
+//# sourceMappingURL=composer.d.ts.map

package/dist/composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../src/composer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,kCAAkC,CAAC;AAErF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAsBnD,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,gBAAgB,CAAC;IACzB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,cAAc,CAoCzF"}

package/dist/composer.js

@@ -0,0 +1,66 @@
+import { fitEvidence } from '@agenticprimitives/orchestration';
+const SYSTEM = [
+    'You put an agent\'s findings into plain words for the person who asked.',
+    '',
+    'You are given the question and the RESULTS the agent\'s tools returned. Answer ONLY from those results.',
+    'Every name, number, address and relationship you state must appear in them.',
+    '',
+    'If the results are empty or do not cover the question, say WHAT WAS LOOKED FOR and that it matched',
+    'nothing — "nothing matched a name search for X" — and stop. Never restate an empty lookup as a fact',
+    'about the world ("X does not exist"): you know how the search went, not what exists.',
+    'And never fill a gap with something plausible: an invented agent is worse than no answer.',
+    '',
+    'Be brief and concrete. Lead with the answer. Prefer a short list to a paragraph when the results are a',
+    'list. Do not describe the tools you used, do not mention JSON or queries, and do not offer to do more.',
+    '',
+    'ANSWER THE QUESTION THAT WAS ASKED, FIRST. If it asks for one fact (a balance, a count, a name), the',
+    'first sentence is that fact, in the unit the results display (never a raw base-unit figure). If the',
+    'results do not contain the asked fact, say so in one sentence and stop — do not summarise other data',
+    'in its place, and do not compute what the results do not state.',
+].join('\n');
+const stringify = (v) => {
+    try {
+        return JSON.stringify(v, (_k, x) => (typeof x === 'bigint' ? x.toString() : x));
+    }
+    catch {
+        return String(v);
+    }
+};
+export function createOpenAiCompatComposer(opts) {
+    const model = opts.model;
+    const label = opts.label ?? 'openai-compat';
+    if (!model)
+        throw new Error(`${label} composer: model is required — this adapter names no vendor default`);
+    const maxTokens = opts.maxTokens ?? 700;
+    const cap = opts.maxEvidenceChars ?? 24_000;
+    return {
+        evidenceBudget: cap,
+        async compose({ intent, observations, corrections, evidence }) {
+            // Only what SUCCEEDED is evidence (a failed step is not a fact about the world), FITTED to the budget —
+            // by the caller when it hands `evidence` (the drops are then on its trace), else here. Never sliced:
+            // a body that does not fit is replaced by its summary and said so (spec 391).
+            const items = evidence ?? fitEvidence(observations, cap).items;
+            const body = stringify(items);
+            const res = await opts.client.chat.completions.create({
+                model, max_tokens: maxTokens,
+                messages: [
+                    { role: 'system', content: opts.systemPrompt ? `${SYSTEM}\n\n${opts.systemPrompt}` : SYSTEM },
+                    {
+                        role: 'user',
+                        content: `Question: ${intent.goal}\n\nResults:\n${body}${corrections?.length
+                            // The governor's own words, verbatim: it states what was claimed and what the evidence
+                            // supports, which is exactly the instruction a recompose needs.
+                            ? `\n\nYour previous answer overstated the results. Corrections that MUST be honoured:\n${corrections.map((c) => `- ${c}`).join('\n')}`
+                            : ''}`,
+                    },
+                ],
+            });
+            const text = (res.choices?.[0]?.message?.content ?? '').trim();
+            // No text is not an answer. Say nothing rather than something: the caller renders the raw result.
+            if (!text)
+                throw new Error('the composer returned no text');
+            return text;
+        },
+    };
+}
+//# sourceMappingURL=composer.js.map

package/dist/composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.js","sourceRoot":"","sources":["../src/composer.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAG/D,MAAM,MAAM,GAAG;IACb,yEAAyE;IACzE,EAAE;IACF,yGAAyG;IACzG,6EAA6E;IAC7E,EAAE;IACF,oGAAoG;IACpG,qGAAqG;IACrG,sFAAsF;IACtF,2FAA2F;IAC3F,EAAE;IACF,wGAAwG;IACxG,wGAAwG;IACxG,EAAE;IACF,sGAAsG;IACtG,qGAAqG;IACrG,sGAAsG;IACtG,iEAAiE;CAClE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAeb,MAAM,SAAS,GAAG,CAAC,CAAU,EAAU,EAAE;IACvC,IAAI,CAAC;QAAC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAAC,CAAC;AACtH,CAAC,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,IAA8B;IACvE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,eAAe,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,qEAAqE,CAAC,CAAC;IAC3G,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,gBAAgB,IAAI,MAAM,CAAC;IAC5C,OAAO;QACL,cAAc,EAAE,GAAG;QACnB,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAgB;YACzE,wGAAwG;YACxG,qGAAqG;YACrG,8EAA8E;YAC9E,MAAM,KAAK,GAAG,QAAQ,IAAI,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC;YAC/D,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;YAC9B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;gBACpD,KAAK,EAAE,UAAU,EAAE,SAAS;gBAC5B,QAAQ,EAAE;oBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE;oBAC7F;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE,aAAa,MAAM,CAAC,IAAI,iBAAiB,IAAI,GACpD,WAAW,EAAE,MAAM;4BACjB,uFAAuF;4BACvF,gEAAgE;4BAChE,CAAC,CAAC,wFAAwF,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;4BACvI,CAAC,CAAC,EACN,EAAE;qBACH;iBACF;aACF,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC/D,kGAAkG;YAClG,IAAI,CAAC,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAC5D,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/fetch-client.d.ts

@@ -0,0 +1,42 @@
+import type { OpenAiCompatLike } from './types.js';
+export interface FetchOpenAiCompatOpts {
+    /** The API key. Never log this; the app reads it from a Worker secret. */
+    apiKey: string;
+    /** The OpenAI-compatible API base, e.g. `https://api.groq.com/openai/v1`. REQUIRED — this adapter names no vendor. */
+    baseUrl: string;
+    /** Injectable fetch (for tests / non-global-fetch runtimes). Default the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Send the SAME request once more when a reasoning model answered `tool_use_failed` (it reasoned and called no tool). Default true. */
+    retryOnNoToolCall?: boolean;
+    /** Extra request headers (a host's project or organization header, say). Never the auth header. */
+    extraHeaders?: Record<string, string>;
+    /**
+     * WHICH NAME THIS HOST WANTS FOR THE COMPLETION BOUND. `max_tokens` is what most compatible hosts accept
+     * and stays the default; OpenAI's own reasoning families REFUSE it ("Unsupported parameter: 'max_tokens'
+     * is not supported with this model") rather than ignoring it, and want `max_completion_tokens`. The
+     * consumer names the host, so the consumer names the field — this package still names no vendor. The
+     * client sends exactly one of the two, never both.
+     */
+    tokenLimitParam?: 'max_tokens' | 'max_completion_tokens';
+    /**
+     * On a 429 whose `retry-after` is at most this many seconds, wait that long and send the SAME request once
+     * more. A metered host (Groq's free plan: tokens per minute) answers the second ask in a minute with "try
+     * again in 6s", and failing the whole turn for six seconds is worse than a six-second turn. This is the
+     * bounded retry of one call ADR-0013 permits — never a different request, never another vendor — and a
+     * longer wait, or a second 429, surfaces as the error it is. `0` disables it. Default 30.
+     */
+    waitOn429UpToSeconds?: number;
+    /** Injectable sleep (tests). */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** A non-OK HTTP response, with what a caller needs to SAY about it: the status and, on a 429, how long the
+ *  host asked us to wait. Surfaces as-is — never a cue to route to another vendor (ADR-0013). */
+export declare class OpenAiCompatHttpError extends Error {
+    readonly status: number;
+    readonly retryAfterSeconds: number | undefined;
+    readonly detail: string;
+    constructor(status: number, detail: string, retryAfterSeconds?: number);
+}
+/** Build a minimal `OpenAiCompatLike` client backed by `fetch`. */
+export declare function createFetchOpenAiCompatClient(opts: FetchOpenAiCompatOpts): OpenAiCompatLike;
+//# sourceMappingURL=fetch-client.d.ts.map

package/dist/fetch-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-client.d.ts","sourceRoot":"","sources":["../src/fetch-client.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAA4D,MAAM,YAAY,CAAC;AAE7G,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,sHAAsH;IACtH,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,wIAAwI;IACxI,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mGAAmG;IACnG,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,YAAY,GAAG,uBAAuB,CAAC;IACzD;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;iGACiG;AACjG,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM;CASvE;AAWD,mEAAmE;AACnE,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,qBAAqB,GAAG,gBAAgB,CAkD3F"}

package/dist/fetch-client.js

@@ -0,0 +1,79 @@
+/** A non-OK HTTP response, with what a caller needs to SAY about it: the status and, on a 429, how long the
+ *  host asked us to wait. Surfaces as-is — never a cue to route to another vendor (ADR-0013). */
+export class OpenAiCompatHttpError extends Error {
+    status;
+    retryAfterSeconds;
+    detail;
+    constructor(status, detail, retryAfterSeconds) {
+        super(`openai-compat chat.completions.create failed (HTTP ${status}${retryAfterSeconds !== undefined ? `, retry after ${retryAfterSeconds}s` : ''})${detail ? `: ${detail}` : ''}`);
+        this.name = 'OpenAiCompatHttpError';
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.detail = detail;
+    }
+}
+function retryAfterOf(resp) {
+    const raw = resp.headers.get('retry-after');
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0)
+        return n;
+    const at = Date.parse(raw);
+    return Number.isFinite(at) ? Math.max(0, Math.round((at - Date.now()) / 1000)) : undefined;
+}
+/** Build a minimal `OpenAiCompatLike` client backed by `fetch`. */
+export function createFetchOpenAiCompatClient(opts) {
+    const base = (opts.baseUrl ?? '').trim().replace(/\/+$/, '');
+    if (!base)
+        throw new Error('createFetchOpenAiCompatClient: baseUrl is required — this adapter names no vendor; the consumer supplies the host');
+    const f = opts.fetchImpl ?? fetch;
+    return {
+        chat: {
+            completions: {
+                async create(params) {
+                    // One bound, under the name this host wants (see `tokenLimitParam`).
+                    const body = opts.tokenLimitParam === 'max_completion_tokens'
+                        ? { ...params, max_completion_tokens: params.max_tokens, max_tokens: undefined }
+                        : params;
+                    const send = () => f(`${base}/chat/completions`, {
+                        method: 'POST',
+                        headers: {
+                            'content-type': 'application/json',
+                            authorization: `Bearer ${opts.apiKey}`,
+                            ...(opts.extraHeaders ?? {}),
+                        },
+                        body: JSON.stringify(body),
+                    });
+                    const waitUpTo = opts.waitOn429UpToSeconds ?? 30;
+                    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+                    let resp = await send();
+                    if (resp.status === 429 && waitUpTo > 0) {
+                        const after = retryAfterOf(resp);
+                        if (after !== undefined && after <= waitUpTo) {
+                            await resp.text().catch(() => '');
+                            await sleep(Math.ceil(after * 1000) + 250);
+                            resp = await send();
+                        }
+                    }
+                    if (!resp.ok) {
+                        let detail = await resp.text().catch(() => '');
+                        // A REASONING MODEL THAT REASONED AND CALLED NO TOOL (Groq's gpt-oss under `tool_choice: 'required'`
+                        // answers HTTP 400 `tool_use_failed`, seen live 2026-09-10 on a request identical to one that had
+                        // planned fine minutes before). The same request once more is the one bounded retry ADR-0013 permits:
+                        // same body, same host, no different prompt and no other vendor. A second refusal is the answer.
+                        if (resp.status === 400 && /"code"\s*:\s*"tool_use_failed"/.test(detail) && (opts.retryOnNoToolCall ?? true)) {
+                            resp = await send();
+                            if (resp.ok)
+                                return (await resp.json());
+                            detail = await resp.text().catch(() => '');
+                        }
+                        throw new OpenAiCompatHttpError(resp.status, detail.slice(0, 2_000), retryAfterOf(resp));
+                    }
+                    return (await resp.json());
+                },
+            },
+        },
+    };
+}
+//# sourceMappingURL=fetch-client.js.map

package/dist/fetch-client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { PACKAGE_NAME, PACKAGE_STATUS, SPEC_REF } from './types.js';
+export type { OpenAiCompatLike, OpenAiCompatChatCreateParams, OpenAiCompatChatCompletion, OpenAiCompatChatMessage, OpenAiCompatToolDef, OpenAiCompatToolChoice, OpenAiCompatToolCall, } from './types.js';
+export { createOpenAiCompatPlanner, parseToolArguments } from './planner.js';
+export type { OpenAiCompatPlannerOpts } from './planner.js';
+export { createFetchOpenAiCompatClient, OpenAiCompatHttpError } from './fetch-client.js';
+export type { FetchOpenAiCompatOpts } from './fetch-client.js';
+export { createOpenAiCompatComposer } from './composer.js';
+export type { OpenAiCompatComposerOpts } from './composer.js';
+export { createOpenAiCompatStructuredCall } from './structured-call.js';
+export type { OpenAiCompatStructuredCallOpts, StructuredToolCallInput } from './structured-call.js';
+//# 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":"AAKA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EACV,gBAAgB,EAChB,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC7E,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzF,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAG9D,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC;AACxE,YAAY,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// @agenticprimitives/orchestration-openai-compat — public API. The OpenAI-compatible LLM binding for the
+// orchestration `Planner` / `AnswerComposer` ports (the in-repo adapter, chain-state-viem pattern; spec 377).
+// Vendor-neutral: the consumer supplies `baseUrl` + `model` (Groq, Ollama, OpenRouter, …). Authority is never
+// here — a chosen tool's call still rides the task delegation at the invoker (ADR-0041).
+export { PACKAGE_NAME, PACKAGE_STATUS, SPEC_REF } from './types.js';
+export { createOpenAiCompatPlanner, parseToolArguments } from './planner.js';
+export { createFetchOpenAiCompatClient, OpenAiCompatHttpError } from './fetch-client.js';
+// Spec 350 §3.7 — the answering half: what the tools returned, in plain words, grounded in them.
+export { createOpenAiCompatComposer } from './composer.js';
+// Spec 358 W1 — the one forced single-tool call the semantic context plane makes.
+export { createOpenAiCompatStructuredCall } from './structured-call.js';
+//# 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,yGAAyG;AACzG,8GAA8G;AAC9G,8GAA8G;AAC9G,yFAAyF;AAEzF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAWpE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG7E,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAGzF,iGAAiG;AACjG,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAG3D,kFAAkF;AAClF,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/planner.d.ts

@@ -0,0 +1,32 @@
+import { type Planner } from '@agenticprimitives/orchestration';
+import type { OpenAiCompatLike } from './types.js';
+export interface OpenAiCompatPlannerOpts {
+    /** The structural client (real `openai` SDK client OR `createFetchOpenAiCompatClient`). */
+    client: OpenAiCompatLike;
+    /** Planning model, as the host names it (`llama-3.3-70b-versatile`, `openai/gpt-oss-120b`, …). REQUIRED. */
+    model: string;
+    /** Max tokens for the planning turn. Default 1024. */
+    maxTokens?: number;
+    /** Reasoning effort for a reasoning model (`reasoning_effort` on the wire). Planning is one tool choice:
+     *  live, gpt-oss-120b thought for 30s at the host's default and then called NO tool ("tool_use_failed",
+     *  an empty generation) — the thinking had consumed the completion. `low` is the planner's setting. */
+    reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
+    /** Override the system prompt (the default constrains the model to the tool-selection job). */
+    systemPrompt?: string;
+    /** Names the consumer in rationales and errors — `groq`, `ollama`. Default `openai-compat`. */
+    label?: string;
+}
+/**
+ * Parse a tool call's `arguments`. On this wire they are a JSON STRING, and a string that does not parse to an
+ * object is not "no arguments" — it is a generation that went wrong, and it fails loudly (`planner_failed`)
+ * rather than yielding a plausible step with empty args. Empty / whitespace IS no arguments.
+ */
+export declare function parseToolArguments(raw: string | undefined, where: string): Record<string, unknown>;
+/**
+ * Create a `Planner` backed by chat-completions tool calling. Fail-closed: if the model returns no tool call
+ * (prose only, despite `tool_choice: 'required'`), the planner throws `OrchestrationError('no_plan')` — the
+ * loop surfaces it as a failed run. One or more tool calls become the plan steps (in order). The loop's
+ * `assertKnownTools` is the backstop if the model ever names a tool outside the provided set.
+ */
+export declare function createOpenAiCompatPlanner(opts: OpenAiCompatPlannerOpts): Planner;
+//# sourceMappingURL=planner.d.ts.map

package/dist/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../src/planner.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,OAAO,EAMb,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAuB,MAAM,YAAY,CAAC;AAExE,MAAM,WAAW,uBAAuB;IACtC,2FAA2F;IAC3F,MAAM,EAAE,gBAAgB,CAAC;IACzB,4GAA4G;IAC5G,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;2GAEuG;IACvG,eAAe,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxD,+FAA+F;IAC/F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAalG;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAkChF"}

package/dist/planner.js

@@ -0,0 +1,94 @@
+// createOpenAiCompatPlanner — implements the orchestration `Planner` port via chat-completions tool calling.
+// Present the goal + the agent's exposed tools to the model; read back the chosen tool + args as a `Plan`.
+// Authority is NOT here — the chosen tool's call still rides the task delegation at the invoker (ADR-0041).
+// The model only decides WHICH tool; it never gains authority by being asked.
+import { OrchestrationError, toolNameMap, planStepFromToolArgs, } from '@agenticprimitives/orchestration';
+const DEFAULT_SYSTEM = 'You are the planning component of an agent. Choose the single tool that best satisfies the user\'s goal, ' +
+    'and provide its arguments. You may ONLY use the provided tools. Do not answer in prose — select a tool.';
+/** Map an orchestration `ToolSpec` to a chat-completions tool definition (object-root schema by default). */
+function toWireTool(t, wireName) {
+    return {
+        type: 'function',
+        function: {
+            name: wireName,
+            description: t.description,
+            parameters: t.inputSchema ?? { type: 'object', properties: {}, additionalProperties: true },
+        },
+    };
+}
+/** Build the user turn: the goal, plus any prior failed observations so a re-plan can choose differently. */
+function buildUserMessage(input) {
+    const lines = [`Goal: ${input.intent.goal}`];
+    if (input.intent.constraints)
+        lines.push(`Constraints: ${JSON.stringify(input.intent.constraints)}`);
+    if (input.intent.context)
+        lines.push(`Context: ${JSON.stringify(input.intent.context)}`);
+    const failed = (input.observations ?? []).filter((o) => !o.ok);
+    if (failed.length) {
+        lines.push('Previous attempts failed — choose a different approach:');
+        for (const o of failed)
+            lines.push(`- ${o.step.toolId} failed: ${o.error ?? 'unknown error'}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Parse a tool call's `arguments`. On this wire they are a JSON STRING, and a string that does not parse to an
+ * object is not "no arguments" — it is a generation that went wrong, and it fails loudly (`planner_failed`)
+ * rather than yielding a plausible step with empty args. Empty / whitespace IS no arguments.
+ */
+export function parseToolArguments(raw, where) {
+    const s = (raw ?? '').trim();
+    if (!s)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(s);
+    }
+    catch (e) {
+        throw new OrchestrationError('planner_failed', `${where} returned tool arguments that are not valid JSON (${e instanceof Error ? e.message : String(e)})`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new OrchestrationError('planner_failed', `${where} returned tool arguments that are not a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * Create a `Planner` backed by chat-completions tool calling. Fail-closed: if the model returns no tool call
+ * (prose only, despite `tool_choice: 'required'`), the planner throws `OrchestrationError('no_plan')` — the
+ * loop surfaces it as a failed run. One or more tool calls become the plan steps (in order). The loop's
+ * `assertKnownTools` is the backstop if the model ever names a tool outside the provided set.
+ */
+export function createOpenAiCompatPlanner(opts) {
+    const model = opts.model;
+    const label = opts.label ?? 'openai-compat';
+    if (!model)
+        throw new Error(`${label} planner: model is required — this adapter names no vendor default`);
+    return {
+        async plan(input) {
+            const names = toolNameMap(input.tools);
+            const res = await opts.client.chat.completions.create({
+                model,
+                max_tokens: opts.maxTokens ?? 1024,
+                messages: [
+                    { role: 'system', content: opts.systemPrompt ?? DEFAULT_SYSTEM },
+                    { role: 'user', content: buildUserMessage(input) },
+                ],
+                tools: input.tools.map((t) => toWireTool(t, names.toWire.get(t.id))),
+                tool_choice: 'required', // force a tool selection (no prose-only answer) — a request, not a guarantee
+                ...(opts.reasoningEffort ? { reasoning_effort: opts.reasoningEffort } : {}),
+            });
+            const calls = res.choices?.[0]?.message?.tool_calls ?? [];
+            const steps = calls
+                .filter((c) => c && c.type === 'function' && typeof c.function?.name === 'string')
+                // Map the API name BACK to the tool id. A name we did not issue is a hallucinated tool: kept as-is so
+                // the loop's unknown-tool gate refuses it (fail-closed), never mapped to a nearest id. The plan-shape
+                // convention (`$ref`, `$forEach`, `$after`, `$when`) rides inside the args; the core lifts it.
+                .map((c) => planStepFromToolArgs(names.fromWire.get(c.function.name) ?? c.function.name, parseToolArguments(c.function.arguments, `${label}(${model})`)));
+            if (steps.length === 0) {
+                throw new OrchestrationError('no_plan', `the model (${label}(${model})) selected no tool for the goal`);
+            }
+            return { steps, rationale: `${label}(${model})` };
+        },
+    };
+}
+//# sourceMappingURL=planner.js.map

package/dist/planner.js.map

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

package/dist/structured-call.d.ts

@@ -0,0 +1,37 @@
+import type { OpenAiCompatLike } from './types.js';
+export interface StructuredToolCallInput {
+    system: string;
+    messages: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    /** The one tool the model MUST call. `input_schema` is the Anthropic-shaped name the port uses; on this
+     *  wire it becomes `function.parameters`. */
+    tool: {
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    };
+    maxTokens?: number;
+}
+export interface OpenAiCompatStructuredCallOpts {
+    client: OpenAiCompatLike;
+    /** The model, as the host names it. REQUIRED. */
+    model: string;
+    /** Names the consumer in errors. Default `openai-compat`. */
+    label?: string;
+    /** Reasoning effort for a reasoning model. The bound below covers reasoning AND the tool call together,
+     *  so a host default of `medium` can spend the whole bound thinking and call nothing — which surfaces as
+     *  "answered in prose", a confusing way to say "ran out of room". Omitted ⇒ the host's default. */
+    reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
+    /** The completion bound when a call names none. Default 1500. */
+    maxTokens?: number;
+}
+/**
+ * Build the forced call. STRICTER than a permissive reading on purpose: a response with no tool call, or a
+ * call to a different tool, is an error — the caller offered exactly one tool and asked for exactly that one,
+ * so anything else is the model declining, and a declined structured call must not read as `{}` (an empty
+ * query, an empty selection) downstream.
+ */
+export declare function createOpenAiCompatStructuredCall(opts: OpenAiCompatStructuredCallOpts): (input: StructuredToolCallInput) => Promise<Record<string, unknown>>;
+//# sourceMappingURL=structured-call.d.ts.map

package/dist/structured-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-call.d.ts","sourceRoot":"","sources":["../src/structured-call.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE;iDAC6C;IAC7C,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,gBAAgB,CAAC;IACzB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;uGAEmG;IACnG,eAAe,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxD,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,8BAA8B,GACnC,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqBtE"}

package/dist/structured-call.js

@@ -0,0 +1,43 @@
+// THE FORCED SINGLE-TOOL CALL — the one structured model call the semantic context plane makes (spec 358 W1:
+// a SPARQL query over a projected schema, a record selection over a vault's inventory). System + question
+// in, ONE tool's arguments out, and the arguments are the entire result.
+//
+// NOT A PLANNER. This never chooses tools, never sees the run, never loops. It is a grounded translator: the
+// caller supplies everything the model may know, and validation of what comes back happens at the endpoint
+// that executes it — never here.
+//
+// The return type is STRUCTURALLY the `StructuredCall` port in `@agenticprimitives/context`; this package
+// does not import that package (an adapter depends on the core it binds, nothing else).
+import { OrchestrationError, wireNameFor } from '@agenticprimitives/orchestration';
+import { parseToolArguments } from './planner.js';
+/**
+ * Build the forced call. STRICTER than a permissive reading on purpose: a response with no tool call, or a
+ * call to a different tool, is an error — the caller offered exactly one tool and asked for exactly that one,
+ * so anything else is the model declining, and a declined structured call must not read as `{}` (an empty
+ * query, an empty selection) downstream.
+ */
+export function createOpenAiCompatStructuredCall(opts) {
+    const model = opts.model;
+    const label = opts.label ?? 'openai-compat';
+    if (!model)
+        throw new Error(`${label} structured call: model is required — this adapter names no vendor default`);
+    return async ({ system, messages, tool, maxTokens }) => {
+        const wire = wireNameFor(tool.name);
+        const res = await opts.client.chat.completions.create({
+            model,
+            max_tokens: maxTokens ?? opts.maxTokens ?? 1500,
+            messages: [{ role: 'system', content: system }, ...messages],
+            tools: [{ type: 'function', function: { name: wire, description: tool.description, parameters: tool.input_schema } }],
+            tool_choice: { type: 'function', function: { name: wire } },
+            ...(opts.reasoningEffort ? { reasoning_effort: opts.reasoningEffort } : {}),
+        });
+        const call = (res.choices?.[0]?.message?.tool_calls ?? []).find((c) => c && c.type === 'function');
+        if (!call)
+            throw new OrchestrationError('planner_failed', `${label}(${model}) answered in prose instead of calling "${tool.name}"`);
+        if (call.function.name !== wire) {
+            throw new OrchestrationError('planner_failed', `${label}(${model}) called "${call.function.name}" when only "${tool.name}" was offered`);
+        }
+        return parseToolArguments(call.function.arguments, `${label}(${model})`);
+    };
+}
+//# sourceMappingURL=structured-call.js.map

package/dist/structured-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-call.js","sourceRoot":"","sources":["../src/structured-call.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAC7G,0GAA0G;AAC1G,yEAAyE;AACzE,EAAE;AACF,6GAA6G;AAC7G,2GAA2G;AAC3G,iCAAiC;AACjC,EAAE;AACF,0GAA0G;AAC1G,wFAAwF;AACxF,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAyBlD;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAC9C,IAAoC;IAEpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,eAAe,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,4EAA4E,CAAC,CAAC;IAClH,OAAO,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE;QACrD,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;YACpD,KAAK;YACL,UAAU,EAAE,SAAS,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;YAC/C,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,QAAQ,CAAC;YAC5D,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YACrH,WAAW,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC3D,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;QACnG,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,kBAAkB,CAAC,gBAAgB,EAAE,GAAG,KAAK,IAAI,KAAK,2CAA2C,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACpI,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAChC,MAAM,IAAI,kBAAkB,CAAC,gBAAgB,EAAE,GAAG,KAAK,IAAI,KAAK,aAAa,IAAI,CAAC,QAAQ,CAAC,IAAI,gBAAgB,IAAI,CAAC,IAAI,eAAe,CAAC,CAAC;QAC3I,CAAC;QACD,OAAO,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export declare const PACKAGE_NAME: "@agenticprimitives/orchestration-openai-compat";
+export declare const PACKAGE_STATUS: "w1-adapter";
+export declare const SPEC_REF: "packages/orchestration-openai-compat/spec.md";
+/** One tool definition on the chat-completions wire: the planner maps each `ToolSpec` to this. */
+export interface OpenAiCompatToolDef {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        /** JSON Schema for the tool arguments (object root). */
+        parameters: Record<string, unknown>;
+    };
+}
+/** The `tool_choice` modes we use. `'required'` forces a call (the planner); the object form forces ONE tool
+ *  (the structured call). A request, not a guarantee — `no_plan` stays the backstop. */
+export type OpenAiCompatToolChoice = 'none' | 'auto' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+export interface OpenAiCompatChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/** The chat-completions request subset we send. `max_tokens` is the widely-accepted name; hosts that prefer
+ *  `max_completion_tokens` accept it as the deprecated alias. */
+export interface OpenAiCompatChatCreateParams {
+    model: string;
+    max_tokens: number;
+    /** The same bound under the name the newer OpenAI models REQUIRE (`max_tokens` is refused outright by the
+     *  reasoning families, not ignored). The adapter never sets both: a consumer picks the name its host wants
+     *  with `tokenLimitParam`, and the client renames the one field on the way out. */
+    max_completion_tokens?: number;
+    messages: OpenAiCompatChatMessage[];
+    tools?: OpenAiCompatToolDef[];
+    tool_choice?: OpenAiCompatToolChoice;
+    temperature?: number;
+    /** OpenAI's reasoning knob, honoured by the reasoning models on compatible hosts (Groq's gpt-oss, qwen). A
+     *  reasoning model spends COMPLETION tokens thinking before it calls a tool; for a turn whose whole job is
+     *  one tool choice, `low` keeps the thinking from eating the budget and the clock. Omitted ⇒ host default. */
+    reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
+}
+/** One tool call in a response. NOTE: `arguments` is a JSON STRING on this wire — the adapter parses it. */
+export interface OpenAiCompatToolCall {
+    id?: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** The chat-completions response subset we read. */
+export interface OpenAiCompatChatCompletion {
+    choices: Array<{
+        message: {
+            role?: string;
+            content: string | null;
+            tool_calls?: OpenAiCompatToolCall[];
+        };
+        finish_reason?: string | null;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    };
+}
+/** The structural client the adapter needs — satisfied by `new OpenAI()` OR `createFetchOpenAiCompatClient`. */
+export interface OpenAiCompatLike {
+    chat: {
+        completions: {
+            create(params: OpenAiCompatChatCreateParams): Promise<OpenAiCompatChatCompletion>;
+        };
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,YAAY,EAAG,gDAAyD,CAAC;AACtF,eAAO,MAAM,cAAc,EAAG,YAAqB,CAAC;AACpD,eAAO,MAAM,QAAQ,EAAG,8CAAuD,CAAC;AAEhF,kGAAkG;AAClG,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,wDAAwD;QACxD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED;wFACwF;AACxF,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAErH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;iEACiE;AACjE,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB;;uFAEmF;IACnF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IACpC,KAAK,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;kHAE8G;IAC9G,gBAAgB,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC1D;AAED,4GAA4G;AAC5G,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,KAAK,CAAC;QACb,OAAO,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAA;SAAE,CAAC;QACxF,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC,CAAC;IACH,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF;AAED,gHAAgH;AAChH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE;QACJ,WAAW,EAAE;YACX,MAAM,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;SACnF,CAAC;KACH,CAAC;CACH"}

package/dist/types.js

@@ -0,0 +1,14 @@
+// @agenticprimitives/orchestration-openai-compat — the OpenAI-compatible LLM binding for the orchestration
+// Planner / AnswerComposer ports (spec 377).
+//
+// This is the in-repo ADAPTER (the chain-state / chain-state-viem pattern), sibling to `orchestration-anthropic`:
+// the pure `orchestration` core stays vendor-free; the chat-completions protocol translation lives HERE. It
+// is VENDOR-NEUTRAL by construction — it names no host and no model. Groq, Ollama, OpenRouter, a self-hosted
+// vLLM: each is a `baseUrl` + `model` the CONSUMER supplies. We define a STRUCTURAL `OpenAiCompatLike` client
+// rather than depending on the `openai` SDK, so (a) the planner is unit-testable with a fake, (b) a consumer
+// can pass the real SDK client (it satisfies the shape) OR our dependency-free fetch client, and (c) this
+// package needs no heavy runtime dep. The SDK remains the reference, not a build dependency.
+export const PACKAGE_NAME = '@agenticprimitives/orchestration-openai-compat';
+export const PACKAGE_STATUS = 'w1-adapter';
+export const SPEC_REF = 'packages/orchestration-openai-compat/spec.md';
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,6CAA6C;AAC7C,EAAE;AACF,kHAAkH;AAClH,4GAA4G;AAC5G,6GAA6G;AAC7G,8GAA8G;AAC9G,6GAA6G;AAC7G,0GAA0G;AAC1G,6FAA6F;AAE7F,MAAM,CAAC,MAAM,YAAY,GAAG,gDAAyD,CAAC;AACtF,MAAM,CAAC,MAAM,cAAc,GAAG,YAAqB,CAAC;AACpD,MAAM,CAAC,MAAM,QAAQ,GAAG,8CAAuD,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@agenticprimitives/orchestration-openai-compat",
+  "version": "0.0.0-alpha.1",
+  "description": "OpenAI-compatible chat-completions binding for the @agenticprimitives/orchestration Planner / AnswerComposer ports (the in-repo adapter, chain-state-viem pattern). Vendor-neutral: the consumer supplies baseUrl + model (Groq, Ollama, OpenRouter, …). createOpenAiCompatPlanner turns a goal + exposed tools into a plan via tool calling, plus a composer, a forced single-tool structured call, and a dependency-free fetch client (Cloudflare-Worker friendly). The pure orchestration core stays vendor-free; authority is never here.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/orchestration-openai-compat"
+  },
+  "homepage": "https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/orchestration-openai-compat",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "spec.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@agenticprimitives/orchestration": "0.0.0-alpha.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8",
+    "@agenticprimitives/orchestration": "0.0.0-alpha.1"
+  },
+  "keywords": [
+    "agentic",
+    "primitives",
+    "orchestration",
+    "planner",
+    "openai-compatible",
+    "groq",
+    "llm-adapter"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

package/spec.md

@@ -0,0 +1,66 @@
+# orchestration-openai-compat — the OpenAI-compatible LLM binding
+
+**Status:** w1-adapter. **Doctrine:** [ADR-0044](../../docs/architecture/decisions/0044-a2a-is-the-agentic-orchestration-layer.md)
++ [spec 377](../../specs/377-a-second-model-behind-the-same-port.md). **Core:** [`@agenticprimitives/orchestration`](../orchestration/spec.md).
+**Sibling:** [`orchestration-anthropic`](../orchestration-anthropic/spec.md).
+
+## 1. Why
+
+The doctrine: orchestration is a Ring-0 primitive, but ONLY the concrete LLM-framework binding lives in a
+dedicated in-repo adapter behind the port (the `chain-state` + `chain-state-viem` pattern — the core stays
+pure; the vendor specifics are exiled to the adapter). This package is that adapter for every host that speaks
+the OpenAI chat-completions wire. It names NO host and NO model: Groq, Ollama, OpenRouter, a self-hosted vLLM
+are each a `baseUrl` + `model` the consumer supplies. That is the difference from the Anthropic sibling, which
+binds one vendor and may default its model.
+
+## 2. The binding
+
+- **`createOpenAiCompatPlanner({ client, model, maxTokens?, systemPrompt?, label? })`** implements the core's
+  `Planner` port. It maps each exposed `ToolSpec` to a `{ type: 'function', function: { name, description,
+  parameters } }` tool, sends a system message + the goal (plus any prior failed observations, so a re-plan
+  chooses differently) with `tool_choice: 'required'`, and turns `choices[0].message.tool_calls` into `Plan`
+  steps. No tool call → `OrchestrationError('no_plan')` (fail-closed; `required` is a request, not a guarantee).
+- **Arguments are a JSON string** on this wire. Empty → `{}`. Unparseable or not an object →
+  `OrchestrationError('planner_failed')` — never a plausible step with silently empty args.
+- **The plan-shape convention is the core's.** `toolNameMap` (dotted ids → API-safe names, collisions refused)
+  and `planStepFromToolArgs` (`$ref` / `$forEach` / `$after` / `$when` lifted from the args) are imported from
+  `@agenticprimitives/orchestration`; a hallucinated tool name is kept verbatim so the loop's `assertKnownTools`
+  refuses it. The model decides *which* tool; it never gains *authority*.
+- **`createOpenAiCompatComposer({ client, model, … })`** implements `AnswerComposer` with the SAME grounding
+  contract as the Anthropic composer: only successful observations are evidence; empty text throws.
+- **`createOpenAiCompatStructuredCall({ client, model, label? })`** is the forced single-tool call the semantic
+  context plane uses (spec 358 W1). Structurally the `StructuredCall` port in `@agenticprimitives/context`,
+  which this package does not import. Stricter than a permissive reading: no call, a different tool, or bad
+  JSON all throw — a declined structured call must not read as `{}` downstream.
+
+## 3. The structural client (`OpenAiCompatLike`)
+
+We DEFINE the minimal `chat.completions.create` request/response shapes rather than importing `openai`:
+the planner is unit-testable with a fake; a consumer may pass the real SDK client OR
+`createFetchOpenAiCompatClient({ apiKey, baseUrl, fetchImpl?, extraHeaders? })` — dependency-free, Worker-safe,
+POST `${baseUrl}/chat/completions` with `Authorization: Bearer`. `baseUrl` is REQUIRED. A non-OK response is
+`OpenAiCompatHttpError { status, retryAfterSeconds?, detail }`, so a rate limit can be SAID, never rerouted.
+
+Non-streaming. The Anthropic client streams because a long blocking generation was killed by an intermediary
+at ~156s (HTTP 524); the turns this adapter serves first are 1024 / 700 tokens on a fast host. Streaming is a
+follow-up, and a consumer running a 16k-token work turn through this client should expect that story to repeat
+until it lands.
+
+## 4. Runtime activation
+
+The app decides. demo-a2a (spec 377 §3) lists providers in `ORCHESTRATION_LLM` (`anthropic,groq`), reads
+`GROQ_API_KEY` from a Worker secret and `ORCHESTRATION_GROQ_MODEL` / `ORCHESTRATION_GROQ_BASE_URL` with app-level
+defaults, and constructs this adapter with `label: 'groq'`. A provider that is listed and not credentialed is a
+thrown configuration error, never a fallback (ADR-0013).
+
+## 5. Boundaries
+
+Imports `@agenticprimitives/orchestration` (+ `types`). Forbidden: `a2a`, `mcp-runtime`, `mcp-protocol`,
+`delegation`, `service-agent`, `orchestration-anthropic`, `context`, `openai`, `@anthropic-ai/sdk`, `langchain`.
+Authority, the loop, and the model live elsewhere.
+
+## 6. Out of scope
+
+Streaming; multi-turn tool-result message threads (the loop re-plans with observation summaries); host-specific
+extensions (`reasoning` fields, `response_format: json_schema`, `parallel_tool_calls`); any vendor's default
+model or host.