@crvouga/mockingbird-service-openai 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-openai
+
+## 0.1.0 (2026-10-05)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-openai discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-openai/`; no repository checkout is needed to discover the mock's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Scripted chat/tool calls, SSE, embeddings, models, files and uploads**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Official documentation and local SDK oracle**.
+- Repository command: `bun run parity:service -- openai`.
+- Evidence model: Live billed inference is disabled by repository policy. The package parity runner exits 2; tests verify official SDKs locally.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `openai`.

package/README.md

@@ -0,0 +1,193 @@
+# @crvouga/mockingbird-service-openai
+
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+A **wip**, portable, entirely local OpenAI mock for Chat Completions, function tool loops,
+Chat SSE streams, embeddings, models, files and staged uploads. Verified with unmodified
+**openai 7.27.0**, **@ai-sdk/openai 4.0.83** and **ai 7.0.127** over Node HTTP.
+It makes no inference calls and requires no vendor account or billed API key.
+
+## Install
+
+```sh
+bun add @crvouga/mockingbird-service-openai
+```
+
+## Usage
+
+```ts
+import { createRuntime, DEFAULT_TOKEN } from "@crvouga/mockingbird-service-openai"
+
+const mock = createRuntime({
+  scripts: [{
+    kind: "chat",
+    message: { role: "assistant", content: "Fixture answer" },
+    usage: { prompt_tokens: 12, completion_tokens: 3, cached_tokens: 8 },
+  }],
+})
+const response = await mock.fetch(new Request("http://mock.local/v1/chat/completions", {
+  method: "POST",
+  headers: { authorization: `Bearer ${DEFAULT_TOKEN}`, "content-type": "application/json" },
+  body: JSON.stringify({ model: "fixture-chat", messages: [{ role: "user", content: "Fixture question" }] }),
+}))
+console.log(await response.json())
+```
+
+For this optional SDK example, also install `@ai-sdk/openai@4.0.83` and `ai@7.0.127`.
+Use the explicit `.chat()` provider: the provider's default model uses the Responses API.
+
+```js
+import { createOpenAI } from "@ai-sdk/openai"
+import { generateText } from "ai"
+import { createServer } from "@crvouga/mockingbird-service-openai/server"
+import { DEFAULT_TOKEN } from "@crvouga/mockingbird-service-openai"
+
+const server = await createServer({
+  scripts: [{ kind: "chat", message: { role: "assistant", content: "Fixture answer" } }],
+})
+try {
+  const provider = createOpenAI({ baseURL: `${server.url}/v1`, apiKey: DEFAULT_TOKEN })
+  console.log((await generateText({ model: provider.chat("fixture-chat"), prompt: "Fixture", maxRetries: 0 })).text)
+} finally {
+  await server.close()
+}
+```
+
+`openai` also accepts `baseURL: server.url + "/v1"` and the fixture `apiKey`.
+The CLI is `mockingbird-openai serve --port 8813`. `createServer()` defaults to an ephemeral port.
+
+## Routes and persisted behavior
+
+| Endpoint | Behavior |
+| --- | --- |
+| `POST /v1/chat/completions` | Scripted assistant JSON or Chat SSE; tools, finish reasons and exact usage |
+| `GET /v1/chat/completions` | Stored completions only, model filter, `after`, `limit`, `order` |
+| `GET` / `DELETE /v1/chat/completions/{completion_id}` | Retrieve/delete a `store: true` completion |
+| `POST /v1/embeddings` | Exact scripted vectors, string or token inputs, float/base64 encoding and dimensions |
+| `GET /v1/models` / `GET /v1/models/{model}` | Configured synthetic model fixtures |
+| `POST` / `GET /v1/files` | Multipart file creation; metadata listing with purpose, order, after and limit |
+| `GET` / `DELETE /v1/files/{file_id}` | Metadata read and deletion |
+| `GET /v1/files/{file_id}/content` | Exact binary bytes |
+| `POST /v1/uploads` | Create a pending staged Upload, expires after one hour |
+| `POST /v1/uploads/{upload_id}/parts` | Multipart `data`, pending parts remain unpublished |
+| `POST /v1/uploads/{upload_id}/complete` | Ordered `part_ids`; exact declared byte count and optional MD5 check |
+| `POST /v1/uploads/{upload_id}/cancel` | Cancel a pending Upload |
+
+`DEFAULT_TOKEN` is `fixture-openai-token`; `tokens: [{ token, models?: string[] }]` configures
+synthetic bearer credentials and optional model access. Invalid/missing credentials return 401,
+model-scope denial 403, unknown model/resource 404, malformed requests 400, with
+`{ error: { message, type, param, code } }` and `x-request-id`. Default models are `fixture-chat`
+and `fixture-embedding` (three dimensions). `models` accepts `{ id, kind: "chat" | "embedding",
+dimensions?, created?, owned_by? }`. No model name implies real inference or vendor availability.
+
+Script selection consumes the first unconsumed script matching its kind and optional
+`match: { model?, lastRole?, contentIncludes?, toolCallId? }`. Unmatched scripts stay queued.
+`ChatScript` has `kind: "chat"`, `message: { role: "assistant", content: string | null,
+tool_calls?, refusal? }`, optional `finish_reason`, `usage`, `chunk_size` and `stream_delay_ms`.
+Function calls use `{ id?, type: "function", function: { name, arguments: string } }`;
+arguments must be valid JSON **strings**. Missing IDs are generated once and persist. Assistant
+null content is preserved with tools/refusal; a `role: "tool"` reply must refer to an earlier
+assistant call ID. Finish reasons are `stop`, `tool_calls`, `length`, `content_filter`.
+`EmbeddingScript` has `kind: "embedding"`, `vectors: number[][]`, optional match and usage.
+
+Exact usage is `{ prompt_tokens, completion_tokens?, cached_tokens? }` (nonnegative integers,
+cached at most prompt). Chat replies include total tokens and `prompt_tokens_details.cached_tokens`.
+Without a script, the local default is `Fixture response`; embeddings use deterministic hash
+vectors. Default token estimates count UTF-8 bytes divided by four, rounded up, with a minimum
+of one. These defaults are synthetic policies; supply usage/vectors for precise consumer tests.
+They do not approximate semantic inference or claim tokenizer parity.
+
+SSE emits `chat.completion.chunk` JSON with indexed content/tool argument deltas, a final
+finish reason, and `[DONE]`. `stream_options.include_usage: true` adds a final empty-choices
+usage chunk; earlier chunks carry null usage. `chunk_size` counts Unicode characters;
+`stream_delay_ms` delays frame delivery for cancellation tests. Aborting/canceling closes the
+stream and clears its pending timer; a begun completion remains a created resource.
+
+Only `store: true` completions are available through vendor reads. Chat ordering defaults to
+ascending creation time. Its local page bounds are default 20, maximum 100. File ordering defaults locally to descending
+creation time, limit/max 10,000; callers can set order explicitly. Stable insertion order breaks
+creation-time ties. `after` is the last resource ID; all pages expose `first_id`, `last_id`,
+`has_more`. Repeating `prompt_cache_key`, headers or request IDs does not deduplicate creations:
+the documented Chat contract does not promise mutation idempotency. Upload completion only
+accepts pending uploads; completed/cancelled/expired uploads reject further mutation.
+
+File multipart bodies use `purpose` and `file`. Supported purposes are `assistants`, `batch`,
+`fine-tune`, `vision`, `user_data`; staged Uploads use the first four. Batch files expire after
+30 days. Optional `expires_after[anchor]=created_at` and `expires_after[seconds]` accept
+3,600–2,592,000 seconds. Staged Upload completion creates the file atomically in caller part
+order, verifies byte count/checksum, and never publishes partial data. `maxFileBytes` defaults
+to 20 MiB and bounds files/uploads/parts locally; it is not a production quota.
+
+All records use SQLite Collections and IdSequence; lifecycle timestamps/expiry use the shared
+clock. Each namespace receives constructor `scripts`, `models`, `files` fixtures; reset restores
+them. Files accept `{ id?, filename, purpose, bytes: string | number[], expires_at? }`.
+Use `x-mockingbird-namespace`, `/__admin/ns/{namespace}/v1/...`, or shared credential registration
+for SDKs. Timeline branches/checkpoints reuse the shared runtime and keep their state isolated.
+
+## Controls, failures and privacy
+
+`DEFAULT_ADMIN_KEY` is `fixture-openai-admin`. Admin data routes require
+`x-mockingbird-admin-key`; configure a nonempty `adminKey` to replace it. A custom `adminPrefix`
+relocates all controls and the namespace path carrier. Shared clock, fault, reset, journal,
+state, credential, metrics and Timeline routes remain available.
+
+| Control | Purpose |
+| --- | --- |
+| `POST /__admin/scripts` | Strictly validate and queue one exact Chat/embedding script |
+| `GET /__admin/scripts` | IDs, kinds and consumption state only |
+| `POST /__admin/raw-faults` | Explicit raw `{ body: string, status?, content_type?, model? }`; allows malformed vendor data |
+| `GET /__admin/request-metadata` | Model, counts/roles, byte length, hashes and response/script IDs |
+| `POST /__admin/request-assertions` | `{ fingerprints: string[] }`, compare ordered SHA-256 request hashes |
+| `GET /__admin/stream-metadata` | Open/closed/aborted stream status and chunk counts |
+| `GET /__admin/upload-metadata` | Pending/completed/cancelled/expired Upload metadata |
+
+Normal scripts reject unknown fields and malformed response shapes atomically. Raw-fault controls
+are the sole escape hatch. `fingerprint(body)` computes the exact JSON-serialization SHA-256 hash
+for request assertions; property order matters. No incoming prompts/tool results are retained.
+Scripts, replies, file/part bytes and raw fault bodies are AES-GCM encrypted in SQLite with a
+private runtime key and logical namespace binding. Generic state snapshots show ciphertext and
+metadata, never plaintext bodies or keys. Vendor resource reads decrypt the requested output.
+The shared request journal/logs contain metadata only; API keys are never logged.
+
+Presets fire once: `rate_limited` (429, Retry-After and retry-after-ms), `server_error` (500),
+`service_unavailable` (503), `network_reset`, `invalid_json`, `malformed_stream`, `content_refusal`,
+`slow_response` (50 ms before dispatch). Canned errors/drop do not consume scripts.
+The reported raw client retries only network errors, 429 and 5xx. Official OpenAI SDK additionally
+retries 408/409 by its own policy; configure `maxRetries` when asserting attempts. Transport
+latency uses wall time, while resource lifecycle uses the mock clock.
+
+## API
+
+Root exports `OpenAIAPI`, `createRuntime`, `document`, `supportedOperationIds`, `DEFAULT_MODELS`,
+`DEFAULT_TOKEN`, `DEFAULT_ADMIN_KEY`, `OPENAI_NAMESPACE`, `OPENAI_PRESETS`, `fingerprint`,
+`validateScript`, `createVaultKey`, `vendorError`, and exported fixture/script/options/runtime types.
+The API exposes `fetch`, `reset`, `ensureSeeded`, `queue`, `queueRaw`, `seedFile`, `state`, `app`,
+`sqlite`. Node `./server` exports `createServer`, `DEFAULT_PORT`, `serveTarget` and server types.
+Optional `vaultKey` is caller-supplied private key material, never persisted in state.
+
+## Oracle and verification
+
+The contract follows official [Chat creation](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create),
+[function calling](https://developers.openai.com/api/docs/guides/function-calling),
+[stored Chat listing](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/list),
+[embeddings](https://developers.openai.com/api/reference/resources/embeddings/methods/create),
+[models](https://developers.openai.com/api/reference/resources/models/methods/list),
+[files](https://developers.openai.com/api/reference/resources/files/methods/create),
+[file listing](https://developers.openai.com/api/reference/resources/files/methods/list),
+[Uploads](https://developers.openai.com/api/reference/resources/uploads/methods/create),
+[completion](https://developers.openai.com/api/reference/resources/uploads/methods/complete), and
+[errors](https://developers.openai.com/api/docs/guides/error-codes).
+
+`bun test` verifies unmodified SDKs over Node HTTP, the reported nonstream tool loop with exact
+retry counts, SSE/abort handling, exact bytes and staged atomicity, namespaces/reset/Timeline,
+privacy, pagination, every preset, every enabled JSON operation via independent-instance walks,
+and a deliberately divergent instance. Multipart/binary operations have served acceptance tests.
+`bun run parity` exits 2: repository policy prohibits billed inference. No live OpenAI result is
+claimed; official documentation and local SDK execution are the oracle evidence.
+
+## Deliberately not modelled
+
+Responses API, realtime/audio/image/batch/fine-tuning APIs, built-in hosted tools, multimodal
+content interpretation, real inference/tokenization, account billing, production quotas,
+production opaque IDs/cursor encodings and undocumented request-ID deduplication. This package
+never calls OpenAI. Encrypted persistence is private runtime state, not a production key vault.

package/SUPPORT.md

@@ -0,0 +1,26 @@
+# Local scripted OpenAI API — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **16**
+- supported by the mock: **16**
+- parity enabled: **13**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `ListChatCompletions` | `GET /v1/chat/completions` | ✅ supported | ✅ |  |
+| `CreateChatCompletion` | `POST /v1/chat/completions` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetChatCompletion` | `GET /v1/chat/completions/{completion_id}` | ✅ supported | ✅ |  |
+| `DeleteChatCompletion` | `DELETE /v1/chat/completions/{completion_id}` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `CreateEmbeddings` | `POST /v1/embeddings` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `ListModels` | `GET /v1/models` | ✅ supported | ✅ |  |
+| `GetModel` | `GET /v1/models/{model}` | ✅ supported | ✅ |  |
+| `ListFiles` | `GET /v1/files` | ✅ supported | ✅ |  |
+| `CreateFile` | `POST /v1/files` | ✅ supported | ❌ disabled | Multipart/binary byte shapes are verified by served SDK and acceptance tests. |
+| `GetFile` | `GET /v1/files/{file_id}` | ✅ supported | ✅ |  |
+| `DeleteFile` | `DELETE /v1/files/{file_id}` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `DownloadFile` | `GET /v1/files/{file_id}/content` | ✅ supported | ❌ disabled | Multipart/binary byte shapes are verified by served SDK and acceptance tests. |
+| `CreateUpload` | `POST /v1/uploads` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `CreateUploadPart` | `POST /v1/uploads/{upload_id}/parts` | ✅ supported | ❌ disabled | Multipart/binary byte shapes are verified by served SDK and acceptance tests. |
+| `CompleteUpload` | `POST /v1/uploads/{upload_id}/complete` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `CancelUpload` | `POST /v1/uploads/{upload_id}/cancel` | ✅ supported | ⚠️ unsafe (opt-in) |  |