@volter/twin-togetherai 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,147 @@
+# @volter/twin-togetherai
+
+A local, faithful **Together AI API** twin your real `together-ai` SDK talks to unmodified — point
+the client at the twin's `baseURL` and `chat.completions.create`, streaming, `models`, `files`,
+`batches`, `fine-tunes`, `embeddings`, `rerank`, the image endpoints and the audio endpoints 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
+import Together from 'together-ai';
+import { createTogetheraiTwinServer } from '@volter/twin-togetherai';
+
+const { port } = createTogetheraiTwinServer({});
+// together-ai's baseURL is the API ROOT; it appends `/v1/…` (or `/v2/…` for videos) itself.
+const client = new Together({ apiKey: 'twin-key', baseURL: `http://127.0.0.1:${port}/v1` });
+const res = await client.chat.completions.create({
+  model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+  messages: [{ role: 'user', content: 'hello' }],
+});
+// res.choices[0].message.content starts with "[twin-stub:…]" — a deterministic stub, clearly labeled.
+// res.usage carries the three token counts; res.prompt is Together's REQUIRED prompt array.
+```
+
+## `files.upload()` needs `TOGETHER_API_BASE_URL` — the one documented exception
+
+The SDK's custom upload (`client.files.upload(path, purpose)`) is NOT an ordinary SDK call:
+`together-ai` reads **`TOGETHER_API_BASE_URL` at module load and ignores the client's
+`baseURL`** (`lib/upload.js:12`, together-ai@0.53.0 — it then POSTs
+`${baseURL}/files?…` itself to drive its 302-redirect flow). Unset, that var defaults to
+`https://api.together.xyz/v1`, so `files.upload()` **egresses to the real Together API with the
+caller's key** even when the client points at the twin. Before the first `import 'together-ai'`
+(the read happens at module load):
+
+```sh
+TOGETHER_API_BASE_URL=http://127.0.0.1:<port>/v1
+```
+
+Every other SDK call rides `baseURL` (or the injector's `api.together.ai` interception — a world
+wired through `TOGETHER_TWIN_URL` gets `TOGETHER_API_BASE_URL=<twin>/v1` injected from this pack's
+descriptor automatically) and needs nothing else. The integration suite pins the same var for the
+same reason (`togetherai-sdk.integration.test.ts`).
+
+## Together is not OpenAI — the differences this twin models
+
+Together exposes an *OpenAI-compatible* inference surface, and treating "compatible" as "identical"
+is how a Together twin gets built wrong. The load-bearing differences, each grounded in
+[`together-ai@0.53.0`](https://www.npmjs.com/package/together-ai) (Stainless-generated from
+Together's own OpenAPI), Together's published spec (141 paths / 156 operations) and Together's
+docs, read 2026-09-16:
+
+| | Together | OpenAI |
+|---|---|---|
+| base URL | **`https://api.together.ai/v1/…`** (`TOGETHER_BASE_URL`) | `https://api.openai.com/v1/…` |
+| error envelope | `{ error: { message, type, param, code } }` — `message`+`type` required, `param`/`code` nullable | same shape |
+| `n` | **1..128** — an OpenAI-compatible freedom | no 128 cap |
+| `logprobs` | an **integer 0..20** (not a boolean) | boolean |
+| context overflow | **403** ("context length exceeded"), with `context_length_exceeded_behavior: truncate\|error` | 400 |
+| spending limit | **402** — monthly spending limit reached | — |
+| overload | **503** `engine_overloaded` | — |
+| rate limit | 429 with types `dynamic_request_limited`/`dynamic_token_limited` + `x-ratelimit-reset`; success responses carry NO rate-limit headers | `x-ratelimit-*` on every response |
+| finish reasons | adds **`eos`** | `stop`/`length`/`tool_calls`/`function_call` |
+| chat response | **`prompt: []` REQUIRED** on the schema; usage is **nullable** | no `prompt` array |
+| streaming | **every chunk carries `usage` + `warnings`** | usage only in an opt-in tail chunk |
+| assistant message | has **`reasoning`** / `reasoning_content`; has **no `refusal`** | has `refusal` |
+| files | purposes **`fine-tune`/`eval`/`batch-api`**, capital-F `Processed`/`FileType`, `processing_status` pipeline; upload is a **302-redirect flow** in the SDK or multipart `/files/upload` | `batch`/`fine-tune`/`assistants` purposes |
+| batches | **201 `BatchJobWithWarning {job}`**, list answers a **bare array**, errors are a bare string, UPPER-CASE statuses, endpoints `chat/completions` + audio | 200 batch object, `{object:'list',data}`, `cancelling` statuses |
+| fine-tunes | `/v1/fine-tunes` (NOT OpenAI's `/v1/fine_tuning/jobs`), 9-state lowercase enum, delete answers `{message}` (not `{id, deleted}`) | different path + shape |
+| model ids | slash-namespaced (`meta-llama/Llama-3.3-70B-Instruct-Turbo`) | flat |
+
+The twin serves **only** `/v1/…` (the inference half). The v2 management half (endpoints,
+deployments, compute, rl, videos, evaluation, queue, tci) is real Together surface this pack does
+not serve — it 404s like any other unmodeled path, never a fake success. Assistants/Threads,
+`moderations`, OpenAI's `responses` API and OpenAI's batch/file/fine-tuning shapes do not exist at
+Together, so the twin refuses them too.
+
+## The generative-stub design (be honest)
+
+The twin **cannot run the model** — there are no weights here. So `POST /v1/chat/completions`
+returns a **deterministic STUB completion** that is unmistakably a twin stub (it carries a
+`[twin-stub:<model>]` marker and echoes your prompt), `POST /v1/embeddings` returns **deterministic
+pseudo-vectors** (L2-normalized, seeded from the input hash, at each model's documented
+dimensionality), `POST /v1/rerank` returns **deterministic pseudo-scores**, and the audio/image
+endpoints return **deterministic labeled stubs**. They **never** pretend to be real model output.
+
+What **is** faithful is the **entire protocol envelope**:
+
+- chat response shape — `{ id, object:'chat.completion', created, model, choices:[{index, message, finish_reason}], prompt:[], usage }`
+- **streaming** via SSE — real `data: {…chat.completion.chunk with choices[].delta…}` chunks ending with `data: [DONE]` (role chunk → reasoning/content/tool_call deltas → finish_reason chunk → the empty-choices usage tail; **every chunk carries Together's `usage` + `warnings`**; driven through an injected sink — no real sockets in the handler)
+- **tool / function calling** — `tool_calls` + `finish_reason:'tool_calls'`, `tool_choice` (`none`/`auto`/`required`/named), `parallel_tool_calls`, and the deprecated `functions` array answering the deprecated `function_call` shape
+- **reasoning** — `reasoning_effort` `low`/`medium`/`high` surfaces the `reasoning` field on the assistant message
+- **structured outputs** — `response_format` `json_object` / `json_schema` (Together REQUIRES `json_schema.name`, ≤64 chars `[a-zA-Z0-9_-]` — enforced)
+- `n` (1..128), `max_tokens`, `stop`, `seed`, `echo` (the REQUIRED `prompt` array), integer `logprobs` (0..20), `compliance:'hipaa'`; the OpenAI fields Together accepts-but-ignores (`service_tier`, `store`, `metadata`, `prediction`) change nothing; **deterministic usage**
+- Stub honesty: the deterministic completion is ONE continuation regardless of `n` (every choice repeats it); `stop` sequences are honored deterministically — the text is cut at the earliest occurrence of any stop string (the envelope validates and echoes them).
+
+The genuinely **stateful + static** surface is real, not a stub:
+
+- `GET /v1/models` (+ `/models/:id`) — static catalog answering a **bare array** of `ModelInfo` with Together's `type`/`display_name`/`context_length`
+- `GET /v1/whoami` — static identity for the presented key
+- **Files** — `POST /v1/files/upload` (the spec's create) + `GET/DELETE /v1/files{,/:id,/content}` (+ the SDK's **302-redirect flow** with `x-together-file-id`), kernel-backed, Together's closed purpose/type sets, `processing_status` on fine-tune files
+- **Batches** — `POST/GET /v1/batches` (+ cancel → `CANCELLED`), 201 `BatchJobWithWarning`, bare-array list, closed 3-endpoint set. The asynchronous `VALIDATING→IN_PROGRESS→COMPLETED` progression is a filed `todo`, not modeled: doing it on a read made a GET write to the log (breaking the read-only contract) and minted an action with no vendor endpoint to push it to.
+- **Fine-tunes** — `POST/GET/DELETE /v1/fine-tunes` (+ cancel, events, checkpoints, estimate-price, preview, models/limits), purpose-checked training files; delete answers `{message}` and estimate-price the SDK's `estimation_available` union
+
+Vendor-shaped errors throughout: `400` / `401` / `402` / `403` / `404` / `405` (read-only guard) /
+`429` / `503`. Every envelope carries the required `message` + `type` and only keys Together's
+`ErrorData` declares.
+
+## Rate budget (live calls)
+
+`liveTogetheraiExecute` — the ONE place this pack issues a real `api.together.xyz` request — routes
+every call through the kernel's fail-closed `RateBudget`. Together publishes NO fixed request limit
+(dynamic, per organization per model), so the declaration pins the kernel's fallback ceiling
+(60 units / 60s, defaultWeight 2 = 30 calls/min) and buys resolution DOWNWARD: inference endpoints
+cost 6, so at most 10 land in a window. A 429's `x-ratelimit-reset` becomes a persisted cooldown.
+There is no option to disable the guard.
+
+## Scenario scripting (twin-only)
+
+Chat completions can be scripted by MSW-shaped handlers in a world dir's `handlers/togetherai.json`,
+run by the ONE kernel scenario engine with this pack's adapter:
+
+```json
+{ "handlers": [
+  { "on": { "userTextIncludes": "refund", "hasTool": "create_job" },
+    "respond": { "toolCalls": { "name": "create_job", "arguments": { "title": "Refund order" } } }, "once": true },
+  { "on": { "reasoningEffortEquals": "high" }, "respond": { "error": { "type": "engine_overloaded" } } }
+] }
+```
+
+Load it with `--scenario FILE` / `createTogetheraiTwinServer({ scenarioPath })` /
+`TWIN_TOGETHERAI_SCENARIO`. The read doors `GET /twin` and `GET /twin/scenario` explain and inspect
+it. A malformed file throws **at load**, never a silent fall-back. Scenario support is twin-only
+scaffolding for eval worlds, not vendor surface, so it is deliberately **not** in the capability
+manifest.
+
+## CLI
+
+```sh
+world-togetherai serve [--port N] [--root DIR] [--read-only] [--scenario FILE]
+world-togetherai conformance [--root DIR]
+```
+
+## Coverage
+
+The capability manifest (`togetherai-capabilities.ts`) is authored against Together's published
+OpenAPI spec — 141 paths / 156 operations — with every entry `done` (with a runnable verify) or
+`todo`. The v2 management half is filed honestly as `todo` at `niche` tier. Run
+`world-togetherai conformance` for the offline protocol checks.

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-togetherai CLI: serve the Together API twin or run conformance. Together is an API-first
+// vendor — app.together.ai is a console, not where the work happens
+// (docs/contributing/architecture.md C1b) — so this pack ships no mirror.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createTogetheraiTwinServer } from "./togetherai-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 createTogetheraiTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+    process.stdout.write(`togetherai twin (Together API at /v1; model output is a deterministic stub)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} 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 { checkTogetheraiConformance } = await import("./togetherai-conformance.js");
+    const report = await checkTogetheraiConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-togetherai serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+export { handleTogetheraiTwinRequest, streamChat, buildChatCompletion, TOGETHERAI_API_PREFIX, TOGETHERAI_UPLOAD_DOOR, handleTogetheraiUploadDoor } from './togetherai-twin.js';
+export type { TogetheraiRequest, TogetheraiResponseEnvelope } from './togetherai-twin.js';
+export { createTogetheraiTwinFetch, createTogetheraiTwinServer, type TogetheraiTwinFetchOptions } from './togetherai-server.js';
+export { TOGETHERAI_MODELS, findModel, SPEECH_MODELS, EMBEDDING_MODELS, EMBEDDING_DIMENSIONS, RERANK_MODELS } from './togetherai-models.js';
+export { buildUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText, pseudoEmbedding, stubAssistantText, stubAudioSeconds, stubJsonObject, stubReasoningText, stubToolArguments, stubToolCall, stubTranscript, } from './togetherai-stub.js';
+export type { TogetheraiAssistantMessage, TogetheraiBatch, TogetheraiBatchEndpoint, TogetheraiBatchStatus, TogetheraiChatCompletion, TogetheraiChoice, TogetheraiEmbedding, TogetheraiEmbeddingResponse, TogetheraiError, TogetheraiFile, TogetheraiFilePurpose, TogetheraiFileType, TogetheraiFinishReason, TogetheraiMessageParam, TogetheraiModel, TogetheraiRerankResponse, TogetheraiToolCall, TogetheraiUsage, SseEvent, SseSink, } from './togetherai-types.js';
+export { createTogetheraiScenarioEngine, togetheraiScenarioAdapter, loadTogetheraiScenarioDocument, realizeTogetheraiRespond } from './togetherai-scenario.js';
+export type { TogetheraiScenarioEngine, TogetheraiScenarioRequest, TogetheraiScenarioRespond, ScenarioToolCall, ScriptedResult } from './togetherai-scenario.js';
+export { fullSyncTogetherai, externalIdFor, togetheraiRequestForAction, liveTogetheraiExecute, mapBatch, mapFile, mapModel, pullTogetheraiState, pushTogetheraiAction, pushPendingTogetheraiActions, syncTogetheraiFromReal, unpushableReason, } from './togetherai-connector.js';
+export type { TogetheraiExecute, LiveTogetheraiOptions } from './togetherai-connector.js';
+export { TOGETHERAI_BUDGET_CEILING, TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S, TOGETHERAI_BUDGET_WINDOW_MS, TOGETHERAI_CALL_WEIGHTS, TOGETHERAI_RATE_BUDGET, TogetheraiBudget, TogetheraiBudgetError, togetheraiBudgetPath, togetheraiCallWeight, } from './togetherai-budget.js';
+export type { TogetheraiBudgetErrorKind, TogetheraiBudgetOptions, TogetheraiBudgetReservation, TogetheraiBudgetSnapshot } from './togetherai-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,79 @@
+// @volter/twin-togetherai — the Together AI twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. The Together API: a vendor-faithful protocol envelope (chat
+// completions/streaming/tool_calls with Together's REQUIRED `prompt` array and per-chunk
+// usage/warnings, `eos` finish reasons, Together's OWN status table — 402 spending limit, 403
+// context length, 503 engine overloaded), a static models catalog, deterministic embeddings/
+// rerank/image/audio stubs, and STATEFUL files + batches + fine-tunes — over an event/action log.
+// (Together is an API-first vendor: app.together.ai is a console, not where the work happens, so
+// this pack ships no mirror.)
+//
+// THE DETERMINISTIC STUB IS THE ANSWER: the twin runs no model, so POST /v1/chat/completions
+// returns a DETERMINISTIC STUB completion (clearly labeled), /v1/embeddings returns DETERMINISTIC
+// pseudo-vectors, and the audio endpoints return DETERMINISTIC labeled stubs — never pretending to
+// be real inference. Everything around them — the wire protocol — is faithful. (Conformance +
+// capability tooling live in @volter/world-tooling, a dev dependency — NOT re-exported here, per
+// E2.)
+export { handleTogetheraiTwinRequest, streamChat, buildChatCompletion, TOGETHERAI_API_PREFIX, TOGETHERAI_UPLOAD_DOOR, handleTogetheraiUploadDoor } from "./togetherai-twin.js";
+export { createTogetheraiTwinFetch, createTogetheraiTwinServer } from "./togetherai-server.js";
+export { TOGETHERAI_MODELS, findModel, SPEECH_MODELS, EMBEDDING_MODELS, EMBEDDING_DIMENSIONS, RERANK_MODELS } from "./togetherai-models.js";
+export { buildUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText, pseudoEmbedding, stubAssistantText, stubAudioSeconds, stubJsonObject, stubReasoningText, stubToolArguments, stubToolCall, stubTranscript, } from "./togetherai-stub.js";
+export { createTogetheraiScenarioEngine, togetheraiScenarioAdapter, loadTogetheraiScenarioDocument, realizeTogetheraiRespond } from "./togetherai-scenario.js";
+export { fullSyncTogetherai, externalIdFor, togetheraiRequestForAction, liveTogetheraiExecute, mapBatch, mapFile, mapModel, pullTogetheraiState, pushTogetheraiAction, pushPendingTogetheraiActions, syncTogetheraiFromReal, unpushableReason, } from "./togetherai-connector.js";
+// The client-side rate budget — the fail-closed backstop `liveTogetheraiExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Together's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `TogetheraiBudgetError` by type; there is deliberately no export that disables the guard.
+export { TOGETHERAI_BUDGET_CEILING, TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S, TOGETHERAI_BUDGET_WINDOW_MS, TOGETHERAI_CALL_WEIGHTS, TOGETHERAI_RATE_BUDGET, TogetheraiBudget, TogetheraiBudgetError, togetheraiBudgetPath, togetheraiCallWeight, } from "./togetherai-budget.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { TOGETHERAI_RATE_BUDGET as RATE_BUDGET } from "./togetherai-budget.js";
+import { performTogetheraiAction, syncTogetheraiFromRemote } from "./togetherai-connector.js";
+export const pack = {
+    vendor: 'togetherai',
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+    // the real state system: perform one entry against Together, refresh the root from it.
+    protocol: '2',
+    stateSystem: { perform: performTogetheraiAction, refresh: syncTogetheraiFromRemote },
+    // the round trip: a file create — the one thing this API mints an id for and keeps, a fresh id
+    // each time, so it repeats cleanly on a branch (the spec's own create door, POST
+    // /v1/files/upload; Together's purposes are a CLOSED set: fine-tune | eval | batch-api)
+    roundTrip: { method: 'POST', path: '/v1/files/upload', body: { purpose: 'batch-api', file_name: 'round-trip.jsonl', content: '' }, headers: { authorization: 'Bearer rt' } },
+    // The SAME object togetherai-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'generative',
+    bin: 'world-togetherai',
+    // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+    resourcesUnreachable: {
+        'model': 'the vendor catalog',
+    },
+    resources: ['file', 'batch', 'finetune', 'model'],
+    specSource: 'Together API — enumerated from Together\'s own published OpenAPI spec (api.together.xyz/openapi.json, captured to test-fixtures/togetherai-openapi.yaml: 141 paths / 156 operations — the /v1 inference half AND the v2 management half, of which this pack models the inference half) + together-ai@0.53.0 (Stainless-generated from Together\'s spec: the model unions, the SDK-only 302-redirect upload flow, whoami, the TOGETHER_BASE_URL/TOGETHER_API_KEY/TOGETHER_PROJECT_ID env contract) + docs.together.ai/{error-codes,serverless/rate-limits,inference/openai-compatibility} (all read 2026-09-16). Envelope-faithful; model output, embedding values, rerank scores, images and audio are labeled deterministic stubs.',
+    description: 'Together AI API twin — faithful protocol envelope (chat completions/streaming/tool_calls, Together\'s prompt array and eos finish reasons, Together\'s own 402/403/503 status table), models, stateful files/batches/fine-tunes (both upload flows, incl. the SDK\'s 302 redirect), embeddings/rerank/images/audio; generative output is a labeled stub.',
+    // ADOPTION (adding-a-twin.md §3): how an app repo betrays that it talks to Together. Declared
+    // HERE, not in world-runtime's central SDK_TWINS/ENV_STEM_VENDORS maps — declaring in both
+    // throws. `together-ai` is Together's own official client (npm).
+    adoption: {
+        sdks: ['together-ai'], envStems: ['TOGETHER'],
+    },
+    // INTERCEPTION: the host the official client addresses by default
+    // (together-ai@0.53.0 client.js: TOGETHER_BASE_URL defaults to https://api.together.ai/v1).
+    hosts: [{ host: 'api.together.ai' }],
+    // App-read endpoint templates RIDE ALONGSIDE the injector (the PLANETSCALE_DATABASE_URL
+    // precedent, init.ts wiringFor): `together-ai`'s custom `files.upload()` reads
+    // `TOGETHER_API_BASE_URL` at MODULE LOAD and IGNORES the client's `baseURL`
+    // (lib/upload.js:12 — it then POSTs `${baseURL}/files?…` itself), so interception of
+    // api.together.ai does NOT cover it: unset, `files.upload()` egresses to the real
+    // https://api.together.xyz with the caller's key. The template points that var at the twin's
+    // `/v1` (the SDK POSTs `/files?…` onto it directly), so the one flow the injector cannot reach
+    // is wired too, while ordinary SDK traffic still rides the injector.
+    endpointEnv: {
+        name: 'TOGETHER_TWIN_URL',
+        templates: { TOGETHER_API_BASE_URL: '${url}/v1' },
+        note: 'the injector covers api.together.ai, but together-ai\'s files.upload() reads TOGETHER_API_BASE_URL at module load and ignores client.baseURL (lib/upload.js:12) — the template points it at the twin\'s /v1 so the SDK upload flow does not egress to the real vendor.',
+    },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);

package/dist/src/togetherai-budget.d.ts

@@ -0,0 +1,52 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const TOGETHERAI_BUDGET_WINDOW_MS = 60000;
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback, because Together publishes no scalar that would
+ * justify more. See the header.
+ */
+export declare const TOGETHERAI_BUDGET_CEILING = 60;
+/** Seconds. A `x-ratelimit-reset` above this means the key is throttled hard — fail loudly, don't sleep. */
+export declare const TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export declare const TOGETHERAI_CALL_WEIGHTS: {
+    /** `/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/rerank`,
+     *  `/v1/images/generations`, `/v1/audio/*` — token-metered, where Together's DYNAMIC token
+     *  budget (`dynamic_token_limited`) rather than its request budget is usually what binds. */
+    readonly inference: 6;
+    /** Everything else: files, batches, models, whoami, fine-tunes, endpoints. */
+    readonly other: 2;
+};
+/** THE PACK'S DECLARATION — pure data, the only Together-specific thing in the whole budget. */
+export declare const TOGETHERAI_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Together. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export declare function togetheraiCallWeight(method: string, path: string): number;
+/** Where Together's ledger lives. Token-keyed and cwd-independent by default (Together's limits
+ *  are per ORGANIZATION, i.e. per key, so a cwd-scoped ledger would hand the same key a fresh
+ *  allowance in every checkout, worktree and CI matrix leg); pass `root` for world-scoped
+ *  accounting. */
+export declare function togetheraiBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options for Together's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type TogetheraiBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * Together's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof TogetheraiBudget` in `liveTogetheraiExecute`
+ * means "a budget that accounts against TOGETHER's ledger under TOGETHER's ceiling".
+ */
+export declare class TogetheraiBudget extends RateBudget {
+    constructor(opts?: TogetheraiBudgetOptions);
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as TogetheraiBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as TogetheraiBudgetErrorKind } from '@volter/world-core';
+export type TogetheraiBudgetReservation = RateBudgetReservation;
+export type TogetheraiBudgetSnapshot = RateBudgetSnapshot;