@volter/twin-togetherai 0.1.0

package/dist/src/togetherai-connector.js

@@ -0,0 +1,457 @@
+// Together AI CONNECTOR — the live-vendor pull/push path that gives the Together twin the full
+// "git for SaaS" lifecycle (pull real state → mirror; push local writes → real).
+//
+// PULL  (real → twin):  fetch the real Models / Files / Batches, map them to SyncResource[], and
+//                       fold into the event log via observeResources (shadow-diff dedup, so
+//                       re-pulling identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action (create / cancel / delete), call the real
+//                       Together REST API and confirmAction on success.
+//
+// The vendor I/O is an INJECTED executor (B3 auth boundary): the kernel + this pack hold NO
+// Together key and import NO SDK at runtime. Tests pass a fake executor; live runs pass
+// `liveTogetheraiExecute(apiKey)`. Same code path either way — fully exercisable offline.
+import { assertBudgetGuardIntact, confirmAction, observeResources, pendingActions, projectResources } from '@volter/world-core';
+import { TogetheraiBudget, TogetheraiBudgetError, togetheraiCallWeight } from "./togetherai-budget.js";
+const SERVICE = 'togetherai';
+/**
+ * A live executor against the real Together REST API (the user's own API key). Sends the required
+ * `Authorization: Bearer` header. Never imported by the pack's own serve path — only constructed
+ * by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.together.xyz` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `TogetheraiBudgetError` instead of returning
+ * when the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `x-ratelimit-reset` / 429 signal becomes a persisted cooldown that makes every later call fail
+ * fast WITHOUT touching Together. There is deliberately no OPTION to disable the guard, and no
+ * value a caller can pass for `budget` that yields an unguarded client. What that does NOT claim
+ * is immunity from a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an
+ * injected clock, restores the allowance, because the same seam tests need cannot be denied to a
+ * determined caller in the same process. See `togetherai-budget.ts` and the kernel header for the
+ * limits of the guarantee.
+ */
+export function liveTogetheraiExecute(apiKey, base = 'https://api.together.xyz', opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    // ONE expression decides which budget is used, so there is no second, weaker test that could
+    // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+    // must be an UNMODIFIED TogetheraiBudget — a duck-typed stand-in, a SUBCLASS overriding
+    // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+    // would otherwise hand back a client with no ceiling. The default ledger is keyed by a hash of
+    // THIS key: Together limits per organization, so a cwd-scoped ledger would hand the same key a
+    // fresh allowance per checkout/worktree/CI leg.
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, TogetheraiBudget, 'liveTogetheraiExecute')
+        : new TogetheraiBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, body) => {
+        // A path this pack never modelled is refused BEFORE the budget is even charged: an executor
+        // that will happily issue any URL is how a careless script reaches an unpriced endpoint.
+        if (!path.startsWith('/v1/')) {
+            throw new Error(`togetherai: refusing to call an unmodeled path "${path}" — Together's API is served under /v1/`);
+        }
+        const headers = { authorization: `Bearer ${apiKey}` };
+        const init = { method, headers };
+        if (method === 'POST') {
+            headers['content-type'] = 'application/json';
+            init.body = JSON.stringify(body ?? {});
+        }
+        const weight = togetheraiCallWeight(method, path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(`${base}${path}`, init);
+        const resHeaders = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        const parsed = (await res.json());
+        // Settles the reservation and, on a back-off signal, arms the cooldown.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer Together AI ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof TogetheraiBudgetError) || !res.ok)
+                throw error;
+        }
+        return parsed;
+    };
+}
+function listOf(res) {
+    // Together's list endpoints are split: /v1/models and /v1/batches answer a BARE ARRAY, while
+    // /v1/files answers `{ data: [...] }`. Accept both shapes here — the mapper only runs on items.
+    if (Array.isArray(res))
+        return res;
+    const o = res;
+    return Array.isArray(o?.data) ? o.data : [];
+}
+/**
+ * A REFUSED pull is NOT an empty account. Together answers failures with its documented
+ * `{ error: { message, type } }` envelope, so a status check alone is not enough — throw on the
+ * envelope rather than folding an empty list over real observed state.
+ */
+function throwIfError(res, ctx) {
+    if (res.error)
+        throw new Error(`togetherai ${ctx} failed: ${res.error.message ?? res.error.type ?? 'unknown error'}`);
+}
+// ── PULL ────────────────────────────────────────────────────────────────────
+/** Map a real-Together ModelInfo object → a twin sync resource. */
+export function mapModel(m) {
+    return {
+        type: 'model',
+        id: String(m.id),
+        fields: {
+            object: 'model',
+            created: m.created ?? null,
+            type: m.type ?? null,
+            display_name: m.display_name ?? null,
+            context_length: m.context_length ?? null,
+        },
+    };
+}
+/** Map a real-Together FileResponse object → a twin sync resource. */
+export function mapFile(f) {
+    return {
+        type: 'file',
+        id: String(f.id),
+        fields: {
+            object: 'file',
+            bytes: f.bytes ?? 0,
+            created_at: f.created_at ?? null,
+            filename: f.filename ?? null,
+            purpose: f.purpose ?? null,
+            Processed: f.Processed === undefined ? null : Boolean(f.Processed),
+            FileType: f.FileType ?? null,
+            ...(f.processing_status !== undefined ? { processing_status: f.processing_status ?? null } : {}),
+        },
+    };
+}
+/** Map a real-Together BatchJob object → a twin sync resource. */
+export function mapBatch(b) {
+    return {
+        type: 'batch',
+        id: String(b.id),
+        fields: {
+            object: 'batch',
+            endpoint: b.endpoint ?? null,
+            input_file_id: b.input_file_id ?? null,
+            status: b.status ?? null,
+            created_at: b.created_at ?? null,
+            completed_at: b.completed_at ?? null,
+            output_file_id: b.output_file_id ?? null,
+            error_file_id: b.error_file_id ?? null,
+            error: b.error ?? null,
+            progress: b.progress ?? null,
+        },
+    };
+}
+const COLLECTIONS = [
+    { path: '/v1/models', map: mapModel },
+    { path: '/v1/files', map: mapFile },
+    { path: '/v1/batches', map: mapBatch },
+];
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export async function pullTogetheraiState(execute) {
+    const out = [];
+    for (const c of COLLECTIONS) {
+        const res = await execute('GET', c.path);
+        throwIfError(res, `pull ${c.path}`);
+        for (const item of listOf(res))
+            out.push(c.map(item));
+    }
+    return out;
+}
+/** One fold onto the head: protocol 2's observe, one batch, one instant. Shadow-diff makes a
+ *  re-pull of identical state a no-op (appended 0). */
+function fold(resources, opts) {
+    return observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+    });
+}
+/**
+ * Pull from real Together and fold into the twin (mirror seeding).
+ *
+ * `occurredAt` has NO pinned default on purpose: the kernel hashes an observed event over
+ * (occurredAt + post-state), so under a fixed poll time a vendor value that REVERTS across polls
+ * collides with its own earlier observation and the fold reports a phantom delta while the
+ * projection keeps the stale value (ADDING_A_TWIN.md §6). Callers pass a moving timestamp.
+ */
+export async function syncTogetheraiFromReal(execute, opts) {
+    const resources = await pullTogetheraiState(execute);
+    const result = fold(resources, opts);
+    return { observed: result.observed, deltasAppended: result.appended };
+}
+// ── PUSH ────────────────────────────────────────────────────────────────────
+// The twin operations this connector knows how to push to real Together. Anything not here must
+// FAIL LOUDLY rather than be silently dropped — pushing an unrecognized op risks hitting the
+// wrong endpoint or no-op'ing a real change.
+const PUSHABLE_VERBS = new Set(['create', 'cancel', 'delete']);
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+function assertPushable(op) {
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    if (!PUSHABLE_VERBS.has(verb)) {
+        throw new Error(`togetherai push: unsupported operation '${op}' — refusing to silently drop a local write`);
+    }
+    const why = UNPUSHABLE[op];
+    if (why)
+        throw new Error(`togetherai push: cannot push '${op}' — ${why}`);
+}
+/** Why this action cannot be pushed, or null if it can. Pure — no vendor call on its path. */
+export function unpushableReason(op) {
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    if (!PUSHABLE_VERBS.has(verb))
+        return `unsupported operation '${op}'`;
+    return UNPUSHABLE[op] ?? null;
+}
+// Map a subject type → its REST collection path. `finetune` is pushable too (§9 round two,
+// R2-D1): the real surface is POST /v1/fine-tunes, POST /v1/fine-tunes/{id}/cancel and DELETE
+// /v1/fine-tunes/{id} (together-ai@0.53.0 fine-tuning.mjs:53) — a plain-Error for it aborted the
+// whole push sweep and took every unrelated pending write (and the pull half) down with it.
+const COLLECTION_PATH = {
+    file: '/v1/files',
+    batch: '/v1/batches',
+    finetune: '/v1/fine-tunes',
+};
+/**
+ * Pushes this connector must REFUSE rather than fake, keyed `"<type>.<verb>"`.
+ *
+ * `file.create` is the case: real Together's file upload is NOT a JSON create — the together-ai
+ * SDK's own flow is a urlencoded POST that must answer **302** with a `Location` upload URL +
+ * `x-together-file-id` header, then a PUT of the raw bytes, then a confirm
+ * (`together-ai@0.53.0 lib/upload.js`); the spec's `POST /v1/files/upload` is multipart. This
+ * JSON executor can express NEITHER, and the twin stores no real bytes to send. Pushing
+ * `{purpose, filename}` as JSON would 400 at the vendor. Refusing loudly is the honest answer;
+ * the gap is filed as `togetherai.connector.push_file_create`. (The groq pack's §9 round one,
+ * finding 6 — the same shape of gap.)
+ */
+const UNPUSHABLE = {
+    'file.create': "real Together's file upload is the SDK's 302-redirect flow (urlencoded POST → Location + x-together-file-id → PUT bytes) or the spec's multipart POST /v1/files/upload; this JSON executor cannot express either, and the twin stores no real bytes to send",
+};
+/**
+ * The twin's LOCALLY-MINTED id namespace (`file_twin_1`, `batch_twin_3` — see `nextId` in
+ * togetherai-twin.ts). A subject still bearing one has no counterpart in the real account.
+ */
+const LOCAL_ID = /_twin_\d+$/;
+/**
+ * Resolve the id the VENDOR knows this subject by.
+ *
+ * §9 ROUND TWO, BLOCKER (transcribed from the groq pack): a request builder that addresses the
+ * vendor straight from `action.subject.id` uses the twin's OWN mint for anything created locally.
+ * So a create's real id is written into the resource as `_external_id` at confirm time, and every
+ * later delete/cancel addresses the vendor by THAT. A locally-minted subject with no recorded
+ * external id is refused rather than guessed at.
+ */
+export function externalIdFor(subjectType, subjectId, root) {
+    if (!LOCAL_ID.test(subjectId))
+        return subjectId; // already a vendor id (e.g. observed by a pull)
+    const row = projectResources(SERVICE, root).find((r) => r.type === subjectType && r.id === subjectId);
+    const ext = row?._external_id;
+    return typeof ext === 'string' && ext ? ext : null;
+}
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real Together REST
+ * surface:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export function togetheraiRequestForAction(action, 
+/** The id the VENDOR knows this subject by. Required for anything but a create — see
+ *  `externalIdFor`; passing the twin's own mint would address a resource the vendor never had. */
+externalId) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    const collection = COLLECTION_PATH[action.subject.type];
+    if (!collection)
+        throw new Error(`togetherai push: no REST collection for subject type '${action.subject.type}'`);
+    if (verb === 'create')
+        return { method: 'POST', path: collection };
+    const vendorId = externalId ?? action.subject.id;
+    if (LOCAL_ID.test(vendorId)) {
+        throw new PushRefusalError(`refusing to address the real account by the twin's own id '${vendorId}' — no vendor id was ever recorded for this subject`);
+    }
+    if (verb === 'cancel')
+        return { method: 'POST', path: `${collection}/${vendorId}/cancel` };
+    if (verb === 'delete')
+        return { method: 'DELETE', path: `${collection}/${vendorId}` };
+    // assertPushable rejects anything else, so this is only reached for the pushable verbs above.
+    return { method: 'POST', path: collection };
+}
+/** A push that must not go to the vendor (an unresolvable reference, a local id offered as a
+ *  vendor id). In the SWEEP it is caught and reported as a refusal — one bad action never aborts
+ *  the rest (the groq pack's §9 round one, finding 5); in PERFORM the head catches the throw and
+ *  records a failed receipt, which is exactly the entry-level answer a deploy wants. */
+export class PushRefusalError extends Error {
+}
+/**
+ * Push ONE pending action to REAL Together via the injected executor. Returns the real external
+ * id (the object id from the response; for a create that's a freshly minted id, otherwise it
+ * echoes the subject). WRITES TO THE REAL ACCOUNT.
+ */
+export async function pushTogetheraiAction(execute, action, opts = {}) {
+    assertPushable(action.operation ?? `${action.subject.type}.update`);
+    const { method, path } = togetheraiRequestForAction(action, opts.externalId);
+    const verb = (action.operation ?? '').includes('.') ? action.operation.slice(action.operation.indexOf('.') + 1) : '';
+    const built = verb === 'create' ? createPayload(action, opts.root) : undefined;
+    if (built && 'unresolvable' in built) {
+        throw new PushRefusalError(`cannot push '${action.operation ?? `${action.subject.type}.create`}' — ${built.unresolvable}`);
+    }
+    const res = await execute(method, path, built);
+    throwIfError(res, `push ${action.subject.type}`);
+    const id = res.id;
+    // A batch create answers 201 with `{ job: {...} }` (BatchJobWithWarning) — the id lives nested.
+    const jobId = res.job?.id;
+    const externalId = typeof id === 'string' && id ? id : typeof jobId === 'string' && jobId ? jobId : action.subject.id;
+    return { externalId };
+}
+function createPayload(action, root) {
+    const f = (action.fields ?? {});
+    switch (action.subject.type) {
+        case 'batch': {
+            // The batch's input_file_id names a FILE by its twin id. `file.create` is unpushable (the
+            // 302-redirect upload is not expressible in JSON), so the referenced file can only exist at
+            // the vendor if it was observed there by a pull — resolve it through externalIdFor, and
+            // refuse rather than send the twin's own mint (the vendor would 404 an id it never issued).
+            const raw = typeof f.input_file_id === 'string' ? f.input_file_id : '';
+            if (!raw)
+                return { unresolvable: 'batch.create has no input_file_id' };
+            const resolved = externalIdFor('file', raw, root);
+            if (resolved === null)
+                return { unresolvable: `input_file_id '${raw}' is the twin's own id and no vendor id was ever recorded for it (file uploads are not pushable) — refusing to send an id the vendor never issued` };
+            return { input_file_id: resolved, endpoint: f.endpoint, ...(f.completion_window ? { completion_window: f.completion_window } : {}) };
+        }
+        case 'finetune': {
+            // Same rule for the fine-tune's training/validation files: the vendor only knows ids it
+            // issued (or that a pull observed).
+            const out = {};
+            if (typeof f.model === 'string')
+                out.model = f.model;
+            const training = typeof f.training_file === 'string' ? externalIdFor('file', f.training_file, root) : null;
+            if (training === null)
+                return { unresolvable: `training_file '${String(f.training_file)}' has no vendor id (file uploads are not pushable) — refusing to send an id the vendor never issued` };
+            out.training_file = training;
+            if (typeof f.validation_file === 'string' && f.validation_file) {
+                const validation = externalIdFor('file', f.validation_file, root);
+                if (validation === null)
+                    return { unresolvable: `validation_file '${f.validation_file}' has no vendor id (file uploads are not pushable) — refusing to send an id the vendor never issued` };
+                out.validation_file = validation;
+            }
+            if (typeof f.n_epochs === 'number')
+                out.n_epochs = f.n_epochs;
+            return out;
+        }
+        default:
+            return {};
+    }
+}
+/**
+ * Push the twin's PENDING local actions to real Together and CONFIRM each. Idempotency: a
+ * confirmed action is no longer pending, so a re-push enacts NOTHING.
+ *
+ * Every action this pack records is SINGLE-RESOURCE (one file, one batch), so confirming with
+ * `fields` alone is correct — see ADDING_A_TWIN.md §5 on compound actions, which this pack has
+ * none of. If a compound write is ever added here, it must ride its extra resources in
+ * `additionalObservations` or the push will silently delete them.
+ */
+export async function pushPendingTogetheraiActions(execute, opts) {
+    const confirmed = [];
+    const externalIds = {};
+    const refused = [];
+    for (const action of pendingActions(SERVICE, opts.root)) {
+        const op = action.operation ?? `${action.subject.type}.update`;
+        // An action this connector cannot faithfully push is SKIPPED AND REPORTED, never confirmed
+        // and never silently dropped: it stays pending, and it is named in `refused` so a caller can
+        // see it. Throwing instead meant ONE unpushable action — e.g. the local file create, whose
+        // real upload is the SDK's redirect flow — aborted the whole sweep and took every unrelated
+        // pending write down with it (the groq pack's §9 round one, finding 5).
+        const why = unpushableReason(op);
+        if (why) {
+            refused.push({ actionId: action.id, operation: op, reason: why });
+            continue;
+        }
+        const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+        // Anything but a create must address the vendor by the id the vendor issued. A locally-minted
+        // subject with none recorded is REFUSED, never guessed (§9 round two, blocker).
+        let external;
+        if (verb !== 'create') {
+            const resolved = externalIdFor(action.subject.type, action.subject.id, opts.root);
+            if (resolved === null) {
+                refused.push({ actionId: action.id, operation: op, reason: `no vendor id recorded for ${action.subject.type} '${action.subject.id}' — it was never pushed to the real account, so there is nothing there to ${verb}` });
+                continue;
+            }
+            external = resolved;
+        }
+        let externalId;
+        try {
+            externalId = (await pushTogetheraiAction(execute, action, { ...(external !== undefined ? { externalId: external } : {}), ...(opts.root !== undefined ? { root: opts.root } : {}) })).externalId;
+        }
+        catch (err) {
+            if (err instanceof PushRefusalError) {
+                refused.push({ actionId: action.id, operation: op, reason: err.message });
+                continue;
+            }
+            throw err;
+        }
+        // Record the id the vendor issued ON the resource, so a later delete/cancel can address it.
+        confirmAction({
+            service: SERVICE, actionId: action.id, subject: action.subject,
+            fields: { ...(action.fields ?? {}), ...(verb === 'create' ? { _external_id: externalId } : {}) },
+            occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}),
+        });
+        confirmed.push(action.id);
+        externalIds[action.id] = externalId;
+    }
+    return { pushed: confirmed.length, confirmed, externalIds, refused };
+}
+// ── FULL bi-directional sync ─────────────────────────────────────────────────
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to real
+ * Together and confirm it, then (2) PULL all modeled collections back and fold them into the event
+ * log. Pushing first means the pull observes the twin's own writes as confirmed external state (no
+ * double-count). Re-running with no pending writes and identical real state is a no-op.
+ */
+export async function fullSyncTogetherai(execute, opts) {
+    const push = await pushPendingTogetheraiActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+    const resources = await pullTogetheraiState(execute);
+    const pull = fold(resources, opts);
+    return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.appended, collections: COLLECTIONS.length, refused: push.refused };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's: the same Together call, carried by the head. */
+export function togetheraiExecuteOver(execute) {
+    return async (method, path, body) => {
+        const res = await execute({
+            method, path,
+            headers: { accept: 'application/json', authorization: 'Bearer twin', ...(body ? { 'content-type': 'application/json' } : {}) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (res.body === '')
+            return {};
+        try {
+            return JSON.parse(res.body);
+        }
+        catch {
+            return { error: { message: `togetherai answered ${res.status} with a body that is not JSON`, type: 'internal_server_error' } };
+        }
+    };
+}
+/** The refresh adapter: pull the account's models/files/batches through the executor and fold. */
+export async function syncTogetheraiFromRemote(execute, opts = {}) {
+    return syncTogetheraiFromReal(togetheraiExecuteOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? new Date().toISOString(),
+    });
+}
+/** The perform adapter: one entry crosses to Together, or settles with the reason it never could.
+ *  Account-shaped writes (batches, files, fine-tunes) cross through `pushTogetheraiAction`; the
+ *  stub-only subjects (a chat completion, its record) are the twin's own record of a call already
+ *  answered — nothing at Together to write. */
+export async function performTogetheraiAction(execute, action, ctx) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const STUB_TYPES = new Set(['chat_completion', 'embedding', 'rerank', 'image', 'speech', 'transcription']);
+    if (STUB_TYPES.has(action.subject.type) || unpushableReason(op) !== null) {
+        return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record or is not expressible in JSON (see unpushableReason) — nothing at Together to write` } };
+    }
+    // the head's resolver has already swapped declared references to vendor ids (docs/contributing/architecture.md
+    // #alias-aware-lookup-at-the-request-boundary); the root lets createPayload resolve an input_file_id recorded earlier in the same root
+    const { externalId } = await pushTogetheraiAction(togetheraiExecuteOver(execute), action, { ...(ctx.root !== undefined ? { root: ctx.root } : {}) });
+    return { externalId };
+}

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

@@ -0,0 +1,19 @@
+import type { TogetheraiModel } from './togetherai-types.js';
+/** The production-tier catalog slice. `created` values are deterministic constants (the twin
+ *  has no clock on its serve path); they are stable so a client can assert them. */
+export declare const TOGETHERAI_MODELS: TogetheraiModel[];
+/** Resolve a model object by id, or undefined if the twin doesn't model it. */
+export declare function findModel(id: string): TogetheraiModel | undefined;
+/**
+ * The models the twin's AUDIO endpoints accept, by family. Together rejects a chat model on
+ * `/v1/audio/speech` (and vice versa), so the twin has to know which is which to reproduce that
+ * 400 — the alternative (accepting anything) is the fake-success the bar forbids. Sourced from
+ * together-ai's own per-endpoint model unions.
+ */
+export declare const SPEECH_MODELS: Set<string>;
+/** together-ai `EmbeddingCreateParams['model']`: the four-model union. */
+export declare const EMBEDDING_MODELS: Set<string>;
+/** Embedding dimensionality per model (the vendors' published vector sizes). */
+export declare const EMBEDDING_DIMENSIONS: Record<string, number>;
+/** together-ai `RerankCreateParams['model']`'s enum. */
+export declare const RERANK_MODELS: Set<string>;

package/dist/src/togetherai-models.js

@@ -0,0 +1,49 @@
+const model = (id, type, displayName, contextLength, created) => ({
+    id, object: 'model', created, type, display_name: displayName, organization: id.split('/')[0] ?? 'together', context_length: contextLength,
+});
+/** The production-tier catalog slice. `created` values are deterministic constants (the twin
+ *  has no clock on its serve path); they are stable so a client can assert them. */
+export const TOGETHERAI_MODELS = [
+    // Chat models — the exact ids together-ai's ChatCompletionCreateParams union + docs examples.
+    model('meta-llama/Llama-3.3-70B-Instruct-Turbo', 'chat', 'Llama 3.3 70B Instruct Turbo', 131_072, 1_733_447_754),
+    model('meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo', 'chat', 'Meta Llama 3.1 8B Instruct Turbo', 131_072, 1_721_827_200),
+    model('mistralai/Mixtral-8x7B-Instruct-v0.1', 'chat', 'Mixtral 8x7B Instruct v0.1', 32_768, 1_699_344_000),
+    model('Qwen/Qwen2.5-7B-Instruct-Turbo', 'chat', 'Qwen2.5 7B Instruct Turbo', 32_768, 1_727_126_400),
+    model('deepseek-ai/DeepSeek-V3', 'chat', 'DeepSeek V3', 131_072, 1_734_364_800),
+    // Embedding models — together-ai's EmbeddingCreateParams union (a CLOSED set in the SDK).
+    model('WhereIsAI/UAE-Large-V1', 'embedding', 'UAE Large V1', 512, 1_700_000_000),
+    model('BAAI/bge-large-en-v1.5', 'embedding', 'BGE Large English v1.5', 512, 1_690_000_000),
+    model('BAAI/bge-base-en-v1.5', 'embedding', 'BGE Base English v1.5', 512, 1_690_000_001),
+    model('togethercomputer/m2-bert-80M-8k-retrieval', 'embedding', 'M2-BERT 80M 8k Retrieval', 8_192, 1_690_000_002),
+    // Rerank — together-ai's RerankCreateParams enum (a CLOSED set in the SDK).
+    model('Salesforce/Llama-Rank-v1', 'rerank', 'Llama Rank V1', 8_192, 1_715_000_000),
+    // Image — together-ai's image union examples.
+    model('black-forest-labs/FLUX.1-schnell', 'image', 'FLUX.1 [schnell]', 0, 1_715_000_001),
+    model('black-forest-labs/FLUX.1.1-pro', 'image', 'FLUX.1.1 [pro]', 0, 1_730_000_000),
+    // Speech — together-ai's AudioSpeechRequest union (a CLOSED set in the SDK).
+    model('cartesia/sonic', 'language', 'Cartesia Sonic', 0, 1_735_000_000),
+    model('hexgrad/Kokoro-82M', 'language', 'Kokoro 82M', 0, 1_735_000_001),
+    model('canopylabs/orpheus-3b-0.1-ft', 'language', 'Orpheus 3B', 0, 1_735_000_002),
+];
+/** Resolve a model object by id, or undefined if the twin doesn't model it. */
+export function findModel(id) {
+    return TOGETHERAI_MODELS.find((m) => m.id === id);
+}
+/**
+ * The models the twin's AUDIO endpoints accept, by family. Together rejects a chat model on
+ * `/v1/audio/speech` (and vice versa), so the twin has to know which is which to reproduce that
+ * 400 — the alternative (accepting anything) is the fake-success the bar forbids. Sourced from
+ * together-ai's own per-endpoint model unions.
+ */
+export const SPEECH_MODELS = new Set(['cartesia/sonic', 'hexgrad/Kokoro-82M', 'canopylabs/orpheus-3b-0.1-ft']);
+/** together-ai `EmbeddingCreateParams['model']`: the four-model union. */
+export const EMBEDDING_MODELS = new Set(['WhereIsAI/UAE-Large-V1', 'BAAI/bge-large-en-v1.5', 'BAAI/bge-base-en-v1.5', 'togethercomputer/m2-bert-80M-8k-retrieval']);
+/** Embedding dimensionality per model (the vendors' published vector sizes). */
+export const EMBEDDING_DIMENSIONS = {
+    'WhereIsAI/UAE-Large-V1': 1024,
+    'BAAI/bge-large-en-v1.5': 1024,
+    'BAAI/bge-base-en-v1.5': 768,
+    'togethercomputer/m2-bert-80M-8k-retrieval': 768,
+};
+/** together-ai `RerankCreateParams['model']`'s enum. */
+export const RERANK_MODELS = new Set(['Salesforce/Llama-Rank-v1']);

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

@@ -0,0 +1,52 @@
+import { type PackScenarioAdapter, type ScenarioDocument, ScenarioEngine } from '@volter/world-core';
+import type { TogetheraiMessageParam, TogetheraiToolCall } from './togetherai-types.js';
+export type TogetheraiScenarioRequest = {
+    model: string;
+    messages: TogetheraiMessageParam[];
+    tools?: unknown;
+    /** Together-specific: `reasoning_effort` ('low' | 'medium' | 'high') is scriptable because it
+     *  is one of Together's own documented chat params. */
+    reasoningEffort?: string;
+};
+export type TogetheraiScenarioEngine = ScenarioEngine<TogetheraiScenarioRequest>;
+export type ScenarioToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+    id?: string;
+};
+/**
+ * What a togetherai handler may script. `reasoning` is Together-specific (the `reasoning` /
+ * `reasoning_content` fields on the assistant message); `error` scripts one of Together's own
+ * documented failure envelopes rather than a success.
+ */
+export type TogetheraiScenarioRespond = {
+    text?: string;
+    reasoning?: string;
+    toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+    /** Together's `FinishReason` — including Together's own `eos`. */
+    finishReason?: 'stop' | 'eos' | 'length' | 'tool_calls' | 'function_call';
+    /** A scripted vendor failure: Together's documented error statuses/types. */
+    error?: {
+        type: 'rate_limit_exceeded' | 'engine_overloaded' | 'internal_server_error';
+        message?: string;
+    };
+};
+export type ScriptedResult = {
+    text: string | null;
+    reasoning: string | null;
+    toolCalls: TogetheraiToolCall[];
+    finishReason: 'stop' | 'eos' | 'length' | 'tool_calls' | 'function_call';
+};
+export declare const togetheraiScenarioAdapter: PackScenarioAdapter<TogetheraiScenarioRequest>;
+/** Load + STRICTLY validate a scenario document. A malformed file throws at load with what is
+ *  wrong — never a silent ignore-and-stub (a mis-typed rule falling back is a fake success). */
+export declare function loadTogetheraiScenarioDocument(path: string): ScenarioDocument;
+export declare function createTogetheraiScenarioEngine(document?: ScenarioDocument): TogetheraiScenarioEngine;
+/**
+ * Turn a validated `respond` into the pack's own faithful assistant turn.
+ *
+ * The tool-call id is derived from the scripted call's own content and its position in the
+ * handler (the groq pack's §9 round-two lesson: a module-level counter made two identical
+ * scripted requests answer differently after a restart — a serve-path determinism violation).
+ */
+export declare function realizeTogetheraiRespond(respond: TogetheraiScenarioRespond): ScriptedResult;