@volter/twin-openai 0.1.1 → 2.0.0

package/README.md

@@ -3,7 +3,7 @@
 A local, faithful **OpenAI API** twin your real `openai` SDK talks to unmodified — point the
 SDK at the twin's `baseURL` and `chat.completions.create`, streaming, the Responses API,
 `embeddings`, `models`, `moderations`, `files`, `batches`, fine-tuning jobs, and vector stores
-all work. Built on the shared `@volter/twin` kernel (durable event/action log + projection);
+all work. Built on the shared `@volter/world-core` kernel; see [the model](../../../docs/concepts/the-model.md) for storage and branching;
 no parallel side store.
 
 ```ts
@@ -27,6 +27,19 @@ stub (it carries a `[twin-stub:<model>]` marker and echoes your prompt), and `PO
 returns **deterministic pseudo-vectors** (seeded from the input hash). They **never** pretend to
 be real model output / real embedding values.
 
+Responses uses the same file-authored scenario handlers as Chat Completions, including text,
+function calls, faults, and labeled misses. Stored input items retain their vendor structure;
+scenario matching uses a separate messages projection. `previous_response_id` carries the
+accumulated input and output items forward once, including tool call identities. Top-level
+`instructions` apply only to the current request. This follows OpenAI's
+[conversation-state model](https://developers.openai.com/api/docs/guides/conversation-state)
+and [function-calling loop](https://developers.openai.com/api/docs/guides/function-calling).
+
+Background requests retain the scenario decision selected at creation; the first poll completes
+that decision without matching handlers again. Stored response identities are allocated from
+the kernel's current state under its atomic write lock, so repeated requests cannot overwrite
+one another.
+
 What **is** faithful is the **entire protocol envelope**:
 
 - chat response shape — `{ id:'chatcmpl-…', object:'chat.completion', created, model, choices:[{index, message:{role:'assistant', content}, finish_reason}], usage:{prompt_tokens, completion_tokens, total_tokens}, system_fingerprint }`
@@ -58,15 +71,15 @@ world-openai conformance [--root DIR]                            # offline envel
 ```
 
 (OpenAI is an API-first vendor with no meaningful product UI worth mirroring — see
-ARCHITECTURE.md C1b — so this pack ships **no mirror**.)
+../../../docs/contributing/architecture.md C1b — so this pack ships **no mirror**.)
 
-## Connector (pull / push)
+## Observation and execution
 
-`syncOpenAIFromReal` pulls real files / batches / fine-tuning jobs / vector stores into the
-twin; `pushPendingOpenAIActions` pushes pending local writes (create / cancel / delete) to the
-real API and confirms them. All vendor I/O is over an **injected client**
-(`liveOpenAIExecute(apiKey)` live; a fake in tests) — the pack holds no key and imports no SDK
-at runtime.
+`syncOpenAIFromReal` observes files, batches, fine-tuning jobs and vector stores through an injected client.
+The kernel invokes `performOpenAIAction` for supported real-system writes and owns landing and
+receipts. The package adapter owns vendor request/response semantics; it does not run a second
+pending-action deployment loop. See the [deployment guide](../../../docs/guides/deploy-from-a-shared-world.md)
+for the World workflow and the capability manifest for supported operations.
 
 ## Coverage
 
@@ -115,8 +128,7 @@ deterministically. Run `bun scripts/twin-capabilities.ts openai` for the live nu
 - **Errors / protocol** — 404, `invalid_request_error` envelope, read-only 405 guard, modeled
   auth (`401` on a missing/invalid credential when a request carries an auth surface; trusted
   in-process + real-SDK calls pass), rate-limit `429` (deterministic opt-in trigger header →
-  vendor envelope + `Retry-After` + `x-ratelimit-*`), `Idempotency-Key` dedup (re-issue replays
-  the same response/id; a new key → a new result), cursor pagination (`after`/`limit` +
+  vendor envelope + `Retry-After` + `x-ratelimit-*`), cursor pagination (`after`/`limit` +
   `has_more`/`first_id`/`last_id`)
 - **Connector** — read surface, pull+map (offline), push+confirm (offline), unsupported-op fails,
   full bi-directional sync (push-then-pull, idempotent)
@@ -128,24 +140,15 @@ deterministically. Run `bun scripts/twin-capabilities.ts openai` for the live nu
 - **Background responses** — `background:true` → queued status + poll + cancel
 - **Fine-tuning** — job pause / resume
 - **Webhooks** — event signature verification (signing-secret HMAC)
+- **Image URLs that resolve** — serve deterministic placeholder bytes at the URLs the twin
+  returns (today they point at the dead `twin.invalid` host)
+- **Binary file content** — persist and return arbitrary bytes, not only supplied text
+- **Responses built-in tools** — web_search / file_search / computer_use / code_interpreter with a
+  deterministic, labeled twin-stub result, exactly as chat stubs generation
+- **Realtime API** — the websocket session protocol with deterministic labeled stub events
 
-### Out of scope (the honest carve-outs)
-- **`openai.chat.inference`** — *real model inference (generation from model weights).* The twin
-  returns a deterministic stub; the protocol envelope is faithful.
-- **`openai.embeddings.real_vectors`** — *real embedding values.* The twin returns deterministic
-  pseudo-vectors; the shape/dimensions/determinism are faithful.
-- **`openai.images.real_pixels`** — *real generated image bytes.* The response shape is faithful;
-  the URL is a placeholder.
-- **`openai.files.real_bytes`** — *arbitrary binary blob storage.* Metadata + supplied text
-  content are faithful; the twin is not a binary object store.
-- **`openai.responses.tools`** — *hosted built-in tools (web_search / computer_use /
-  code_interpreter).* These require live model + infrastructure side effects that cannot be
-  reproduced offline without fabricating output; user-defined function tools ARE modeled.
-- **`openai.audio.realtime`** — *Realtime API (WebSocket sessions).* A live bidirectional audio
-  socket to a running speech model — both the transport and the inference are irreproducible in
-  the offline, HTTP `verify()` harness.
-
-Everything else is covered by default and is either done or planned.
+Every capability is done or todo. The labeled stub completion and the deterministic pseudo-vector are
+the twin's answer, not a shortfall from a "real" one; every capability is done or todo.
 
 ## Rate budget — the fail-closed backstop on live calls
 
@@ -160,9 +163,9 @@ validated by *method identity*, so a subclass or a `Proxy` that replaces `checkB
 
 The declared numbers: **60 weighted units / 60s at weight 2 = 30 calls/minute — exactly the kernel's austere fallback**, because OpenAI publishes *no* scalar per-key request limit (limits are per org/project, per model, per tier, and live only on the account's limits page). The one documented scalar that can bind this pack is Vector Store ingestion at 300 requests/minute per store. The declaration therefore buys **resolution, not headroom**: inference paths cost 5, vector-store ingestion 4, and nothing is cheaper than the fallback would price it.
 
-The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/twin` →
-`control-plane/src/rateBudget.ts`); what lives here in [`src/openai-budget.ts`](src/openai-budget.ts) is this vendor's
+The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/world-core` →
+`packages/world-core/src/rateBudget.ts`); what lives here in [`src/openai-budget.ts`](src/openai-budget.ts) is this vendor's
 **declaration** (window, ceiling, per-endpoint weights, and a `reason` citing the limits above) plus
 the vendor-bound `OpenAIBudget`. The rule is ratified as
-[ARCHITECTURE.md](../../../ARCHITECTURE.md) **D8**, and the kernel module's header documents what the
+[../../../docs/contributing/architecture.md](../../../docs/contributing/architecture.md) **D8**, and the kernel module's header documents what the
 guard does *not* guarantee — read that before trusting it.

package/defaults/handlers.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "[twin-demo] Starter handlers, copied visibly into your world dir by init — yours to edit or delete. Ordered first-match; GET /twin on the twin explains the grammar; GET /twin/scenario lists these with match/miss counts.",
+  "handlers": [
+    {
+      "$comment": "[twin-demo] A narrow smoke beat: prove scripting works end-to-end, then write your own.",
+      "on": { "userTextIncludes": "twin-demo ping" },
+      "respond": { "text": "twin-demo pong — scripted by handlers/openai.json. Edit that file to script your own beats." }
+    }
+  ]
+}

package/dist/defaults/handlers.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "[twin-demo] Starter handlers, copied visibly into your world dir by init — yours to edit or delete. Ordered first-match; GET /twin on the twin explains the grammar; GET /twin/scenario lists these with match/miss counts.",
+  "handlers": [
+    {
+      "$comment": "[twin-demo] A narrow smoke beat: prove scripting works end-to-end, then write your own.",
+      "on": { "userTextIncludes": "twin-demo ping" },
+      "respond": { "text": "twin-demo pong — scripted by handlers/openai.json. Edit that file to script your own beats." }
+    }
+  ]
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './index.js';

package/dist/src/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-openai CLI: serve the OpenAI API twin or run conformance. OpenAI is an API-first
+// vendor with no meaningful product UI worth mirroring (docs/contributing/architecture.md C1b), so this pack
+// ships no mirror.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import "./index.js"; // the pack registers itself on load (protocol 2)
+import { createOpenAITwinServer } from "./openai-server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted completions (JSON file)
+if (cmd === 'serve') {
+    const s = await createOpenAITwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+    process.stdout.write(`openai twin (chat/responses/embeddings output is a deterministic stub)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    // dev-only; lazy so the bin runs without @volter/world-tooling
+    const { checkOpenAIConformance } = await import("./openai-conformance.js");
+    const report = await checkOpenAIConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-openai serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}