@volter/twin-ai-gateway 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,176 @@
+# @volter/twin-ai-gateway
+
+A local, faithful **Vercel AI Gateway** twin (`https://ai-gateway.vercel.sh`) your real SDK
+talks to unmodified, over BOTH of the gateway's wire protocols:
+
+- **`createGateway` (the `ai` package / `@ai-sdk/gateway`)** — the AI SDK's native gateway
+  provider, which speaks the **AI SDK gateway protocol at `/v3/ai`** (`POST /language-model`
+  with `ai-language-model-*` headers, `GET /config`). This is how a backend that does
+  `createGateway({ apiKey })` + `creator/model` slugs actually reaches the gateway.
+- **`createOpenAI` (AI SDK) or the `openai` client** — the gateway's **OpenAI-compatible
+  `/v1` endpoint** (`/v1/chat/completions`, `/v1/embeddings`, `/v1/models`, …).
+
+Point either at the twin's `baseURL` with `creator/model` slugs (`anthropic/claude-sonnet-4.6`,
+`openai/gpt-5.2`, `xai/grok-4-1`, …) and chat completions, streaming, tool calls, structured
+outputs, reasoning, provider routing metadata, embeddings, models, credits, generation lookup,
+and spend reports all work. Built on the shared `@volter/world-core` kernel (durable event/action log
++ projection); no parallel side store — both protocols fold into the SAME generation log, so
+credits/reports/lookup agree no matter which surface a consumer speaks.
+
+```ts
+import { createGateway, generateText } from 'ai';
+import { createAiGatewayTwinServer } from '@volter/twin-ai-gateway';
+
+const { port } = createAiGatewayTwinServer({});
+// The AI SDK's native gateway provider, unmodified (the shape a real backend uses):
+const gateway = createGateway({ apiKey: 'test-key', baseURL: `http://127.0.0.1:${port}/v3/ai` });
+const { text } = await generateText({
+  model: gateway('anthropic/claude-sonnet-4.6'),
+  prompt: 'hello',
+});
+// text starts with "[twin-stub:ai-gateway:…]" — a deterministic stub, clearly labeled.
+
+// The OpenAI-compatible surface works identically:
+//   createOpenAI({ apiKey, baseURL: `http://127.0.0.1:${port}/v1` }).chat('anthropic/claude-sonnet-4.6')
+```
+
+## The generative-stub design (be honest)
+
+The twin **cannot run models or broker real providers** — there are no weights and no upstream
+here. `POST /v1/chat/completions` returns a **deterministic STUB completion** that is
+unmistakably a twin stub (a `[twin-stub:ai-gateway:<model>]` marker echoing your prompt), tool
+calls return **schema-conformant synthesized arguments** (so an unmodified SDK's own argument
+validation passes), and `POST /v1/embeddings` returns **deterministic, L2-normalized
+pseudo-vectors** (default dimension 1536, matching the real `openai/text-embedding-3-small`;
+`dimensions` overrides). They never pretend to be real model output.
+
+What **is** faithful is the **entire protocol envelope**, per Vercel's docs:
+
+- chat response shape — `{ id:'gen_…', object:'chat.completion', created, model, choices, usage }`
+  with a **unique `gen_` generation id per generation** (seeded with a per-root monotonic
+  sequence: identical repeated requests each get their own id and record, while a fresh root
+  replays byte-identically) and **`providerMetadata.gateway`** (`routing` with
+  `originalModelId/resolvedProvider/fallbacksAvailable/planningReasoning/modelAttempts/...`,
+  decimal-string `cost`/`marketCost`, `generationId`); `n` (OpenAI-spec passthrough — Vercel's
+  own parameter list doesn't enumerate it) produces multiple indexed choices, each the SAME
+  deterministic stub (a real provider would sample distinct ones)
+- **streaming** via SSE — `chat.completion.chunk` deltas ending with `data: [DONE]`; the
+  generation id rides on the first chunk (documented for pre-completion capture); reasoning
+  streams as `delta.reasoning`; the final chunk carries `finish_reason` + usage; with `n>1`
+  EVERY billed choice index streams (each reconstructs its full content), matching the unary
+  body's choices
+- **the AI SDK gateway protocol (`/v3/ai`)** — the wire protocol `createGateway` actually
+  speaks, derived from the shipped `@ai-sdk/gateway` SDK (there is no separately published
+  spec): `POST /v3/ai/language-model` consumes the raw LanguageModelV3 call options with the
+  model id in the `ai-language-model-id` header (+ `ai-language-model-specification-version`,
+  `ai-language-model-streaming`) and returns the LanguageModelV3 result — ordered content
+  parts, `finishReason: { unified, raw }`, nested usage, `providerMetadata.gateway` — or an
+  SSE stream of LanguageModelV3 stream parts (`response-metadata` → `text-delta`s /
+  `tool-input-*` + `tool-call` → `finish`); `GET /v3/ai/config` serves the model config
+  document `getAvailableModels()` consumes; unknown models fail with the `model_not_found`
+  envelope the SDK maps to its typed `GatewayModelNotFoundError`. V3 calls are a TRANSLATION
+  onto the same chat machinery, so generation records/credits/reports are one surface across
+  both protocols
+- **tools** — `tool_calls` + `finish_reason:'tool_calls'`, `tool_choice`
+  (`none`/`auto`/`required`/named), streaming tool-call deltas
+- **structured outputs** — OpenAI `json_schema` and `json_object` formats + the gateway's
+  legacy `{ type:'json' }` format, synthesized to conform to the supplied schema
+- **reasoning** — `reasoning.{enabled,effort,max_tokens,exclude}` (effort and max_tokens are
+  mutually exclusive, as documented), `message.reasoning` + normalized `reasoning_details`
+  (anthropic `reasoning.text`+signature; openai `reasoning.summary`+`reasoning.encrypted`),
+  `usage.completion_tokens_details.reasoning_tokens`
+- **provider routing** — `providerOptions.gateway.{order,only,sort,models,byok,caching}` + the
+  top-level `provider`/`models` shorthands (conflicting shorthand values fail, as documented);
+  `only` with no available provider fails naming the allowed providers; `sort` reports
+  `routing.sort` metadata (option/executionOrder/metrics) over **deterministic** per-provider
+  metrics — a twin simulation of the gateway's live telemetry
+- **error envelope** — `{ error: { message, type, param, code } }` (400 validation with `param`,
+  404 `model_not_found`, 405 in read-only mode, 404 for unmodeled operations — never fake
+  success; a failed *streaming* request gets its real 4xx JSON on the wire, never a 200 SSE
+  stream wrapping an error)
+- **BYOK accounting per the docs** — a request routed over request-scoped BYOK credentials
+  records `total_cost` 0.00 (the provider bills the tokens; gateway credits are untouched) and
+  carries the market price as `upstream_inference_cost`/`marketCost`
+
+The genuinely **stateful** surface is real accounting over the kernel's generation log, not a
+hardcoded stub: every chat completion — and every **embeddings** call, which the real gateway
+bills too (`providerMetadata.gateway.generationId` on the embeddings response points at its
+record) — appends a generation record; `GET /v1/generation?id=…`
+serves it (cost/latency/token/BYOK fields per the REST API Reference); `GET /v1/credits` folds
+`balance`/`total_used` from recorded spend; `GET /v1/report` serves the documented Custom
+Reporting `results` rows (grouping field `day`/`hour`/`model`/`provider`/`credential_type` +
+`total_cost`/`market_cost`/`surcharge_cost`/`gateway_cost`/token counts/`request_count`) with
+the documented query validation and model/provider/credential_type filters; attribution-keyed
+groupings and filters (user/tag/api_key_name/ZDR) resolve to empty result sets because the twin
+records no request attribution yet (an open todo, not a fabrication). `GET /v1/models`,
+`GET /v1/models/{creator}/{model}`, and `GET /v1/models/{id}/endpoints` serve a deterministic
+local catalog in the documented shapes (including per-provider endpoint pricing/uptime/latency
+fields — deterministic simulations of live telemetry).
+
+## Scenario scripting (test scaffolding, not vendor surface)
+
+Per the anthropic-pack convention, a JSON scenario file can script the exact assistant turns a
+flow under test needs, while the envelope stays vendor-faithful:
+
+```ts
+createAiGatewayTwinServer({ scenarioPath: './scenario.json' });
+// or: TWIN_AI_GATEWAY_SCENARIO=./scenario.json | world-ai-gateway serve --scenario ./scenario.json
+```
+
+Rules match on model / nth call / user text / available tools / tool-result turns and respond
+with text, reasoning, and/or tool calls (verbatim argument payloads; streamed faithfully).
+Malformed scenarios fail startup loudly. Scenario scripting is deliberately **excluded from the
+capability manifest** — counting twin-only scaffolding as vendor coverage would be padding.
+
+## Observation and execution
+
+`syncAiGatewayFromReal` observes the model catalog and account credits through an injected
+client. The kernel's adapter is `performAiGatewayAction`; inspect its supported operations
+before enabling real execution. Simulated generations are deterministic. Observation of
+catalog or credit data does not itself replay inference or spend model credits.
+See the [shared model](../../../docs/concepts/the-model.md) for the execution boundary.
+
+## Coverage
+
+The capability manifest (`ai-gateway-capabilities.ts`) enumerates the **real AI Gateway
+surface** (authored top-down from Vercel's AI Gateway docs: the OpenAI-compatible family, the
+Responses/Anthropic-Messages/OpenResponses compatibility APIs, the REST API Reference, provider
+options/filtering/sorting, usage & billing, authentication & BYOK — plus the AI SDK gateway
+protocol at `/v3/ai`, derived from the shipped `@ai-sdk/gateway` SDK) as the honest
+denominator; `verify()` proves each `done` against the local twin, offline + deterministically.
+Run `bun scripts/twin-capabilities.ts ai-gateway` for the live numbers. Coverage is partial and
+honest: the Responses API, Anthropic Messages API, OpenResponses, web search, image/video
+generation, tiered pricing, provider timeouts, bearer-auth enforcement (core todo — the twin
+currently fakes auth), reporting attribution (`providerOptions.gateway.{user,tags}` / the
+`ai-reporting-*` headers), a deterministic 429 rate-limit envelope, report attribution
+groupings, and the `/v3/ai` sub-surfaces the twin does not model yet
+(`/v3/ai/embedding-model`, `/v3/ai/image-model`, `/v3/ai/video-model`, provider-executed
+gateway tools) are open `todo`s, not silent gaps — unmodeled `/v3/ai/*` operations 404 with the
+vendor error envelope rather than faking success. The exact live status code for the
+"no allowed providers available" failure is not documented; the twin uses `400` with a
+`no_available_providers` code and a message naming the allowed providers (the documented
+behavior is "fails with an error indicating the allowed providers").
+
+**Out of scope** (each genuinely impossible for a local twin, with reasons in the manifest):
+
+- `ai-gateway.chat.real_inference` — real model inference / live provider brokering.
+- `ai-gateway.billing.real_settlement` — real credit purchase/settlement, provider billing, and
+  live telemetry values (a deterministic twin-armed 429 rate-limit envelope is NOT carved out —
+  it is the open `ai-gateway.limits.rate_limit_429` todo).
+- `ai-gateway.auth.oidc` — Vercel-hosted OIDC token issuance/verification.
+
+### No UI mirror
+
+The AI Gateway is a vendor whose **product is the API**: integrators call it from code, and the
+Vercel dashboard is incidental tooling for keys, spend monitoring, and logs rather than where
+the work happens. Per [../../../docs/contributing/adding-a-twin.md](../../../docs/contributing/adding-a-twin.md) ("Does this
+vendor get a mirror?") and [../../../docs/contributing/architecture.md](../../../docs/contributing/architecture.md) C1b, this pack ships
+**no React mirror and no UI capabilities** — omit rather than fabricate a dashboard. Coverage
+is API + connector.
+
+## CLI
+
+```
+world-ai-gateway serve       [--port N] [--root DIR] [--read-only] [--scenario FILE]
+world-ai-gateway conformance [--root DIR]
+```

package/dist/src/ai-gateway-capabilities.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const AI_GATEWAY_CAPABILITIES: CapabilitySpec[];
+export { AI_GATEWAY_CAPABILITIES as 'AI-GATEWAY_CAPABILITIES' };
+export declare function aiGatewayCapabilities(): Promise<CapabilityReport>;