@volter/twin-togetherai 0.1.0

package/src/togetherai-scenario.ts

@@ -0,0 +1,185 @@
+// The togetherai pack's scenario system on the kernel's ONE engine (@volter/world-core
+// scenario.ts): Together chat-completions vocabulary + the scripted-turn respond shape. THE
+// KERNEL ENGINE IS NOT RE-IMPLEMENTED HERE — this file is only the pack's adapter (features,
+// matchers, load validation) plus the realizer that turns a validated `respond` into Together's
+// own envelope.
+//
+// The handler FILE (handlers/togetherai.json in a world dir) is the only write surface; the
+// doors (`GET /twin`, `GET /twin/scenario`) are read-only. Scenario support is twin-only
+// scaffolding for eval worlds, NOT vendor surface, so it is deliberately absent from the
+// capability manifest (ADDING_A_TWIN.md §6, "Scenario scripting") and gated by
+// togetherai-scenario.test.ts.
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, lastUserText } from './togetherai-stub.ts';
+import type { TogetheraiMessageParam, TogetheraiToolCall } from './togetherai-types.ts';
+
+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';
+};
+
+const RESPOND_KEYS = new Set(['text', 'reasoning', 'toolCalls', 'finishReason', 'error']);
+const FINISH_REASONS = new Set(['stop', 'eos', 'length', 'tool_calls', 'function_call']);
+const ERROR_TYPES = new Set(['rate_limit_exceeded', 'engine_overloaded', 'internal_server_error']);
+const REASONING_EFFORTS = new Set(['low', 'medium', 'high']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+
+function lastToolResultNames(messages: TogetheraiMessageParam[]): Set<string> {
+  const names = new Set<string>();
+  const last = messages[messages.length - 1] as { role?: string; tool_call_id?: unknown } | undefined;
+  if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string') return names;
+  for (const m of messages) {
+    const am = m as { role?: string; tool_calls?: Array<{ id?: unknown; function?: { name?: unknown } }> };
+    if (am.role !== 'assistant' || !Array.isArray(am.tool_calls)) continue;
+    for (const tc of am.tool_calls) {
+      if (tc?.id === last.tool_call_id && typeof tc?.function?.name === 'string') names.add(tc.function.name);
+    }
+  }
+  return names;
+}
+
+function toolNames(tools: unknown): string[] {
+  if (!Array.isArray(tools)) return [];
+  return (tools as Array<{ function?: { name?: unknown }; name?: unknown }>).map((t) =>
+    typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null,
+  ).filter((n): n is string => n !== null);
+}
+
+export const togetheraiScenarioAdapter: PackScenarioAdapter<TogetheraiScenarioRequest> = {
+  vendor: 'togetherai',
+  features: (req): ScenarioFeatures => ({
+    model: req.model,
+    lastUserText: lastUserText(req.messages).slice(0, 300),
+    tools: toolNames(req.tools),
+    lastMessageIsToolResult: (req.messages[req.messages.length - 1] as { role?: string } | undefined)?.role === 'tool',
+    toolResultFor: [...lastToolResultNames(req.messages)],
+    reasoningEffort: req.reasoningEffort ?? 'medium',
+  }),
+  matchers: {
+    modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+    userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+    anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+    lastMessageIsToolResult: (req, cond) => typeof cond === 'boolean' && ((req.messages[req.messages.length - 1] as { role?: string } | undefined)?.role === 'tool') === cond,
+    toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+    hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+    // Together-specific: script behaviour per reasoning effort (Together's own chat param).
+    reasoningEffortEquals: (req, cond) => nonEmptyString(cond) && (req.reasoningEffort ?? 'medium') === cond,
+  },
+  text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+  validateOn: (on) => {
+    for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'] as const) {
+      if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k])) return `on.${k} is a non-empty string`;
+    }
+    if (on.lastMessageIsToolResult !== undefined && typeof on.lastMessageIsToolResult !== 'boolean') return 'on.lastMessageIsToolResult is a boolean';
+    if (on.reasoningEffortEquals !== undefined) {
+      if (typeof on.reasoningEffortEquals !== 'string' || !REASONING_EFFORTS.has(on.reasoningEffortEquals)) {
+        return `on.reasoningEffortEquals is one of ${[...REASONING_EFFORTS].join(', ')}`;
+      }
+    }
+    return null;
+  },
+  validateRespond: (respond) => {
+    if (typeof respond !== 'object' || respond === null || Array.isArray(respond)) return 'respond is an object { text?, reasoning?, toolCalls?, finishReason?, error? }';
+    const r = respond as Record<string, unknown>;
+    for (const k of Object.keys(r)) if (!RESPOND_KEYS.has(k)) return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+    if (r.error !== undefined) {
+      const e = r.error as Record<string, unknown>;
+      if (!e || typeof e !== 'object' || Array.isArray(e)) return 'respond.error is an object { type, message? }';
+      if (typeof e.type !== 'string' || !ERROR_TYPES.has(e.type)) return `respond.error.type is one of ${[...ERROR_TYPES].join(', ')}`;
+      if (e.message !== undefined && typeof e.message !== 'string') return 'respond.error.message is a string';
+      // An error handler scripts a FAILURE — mixing it with success content is a mis-typed rule.
+      for (const k of ['text', 'reasoning', 'toolCalls', 'finishReason']) if (r[k] !== undefined) return `respond.error cannot be combined with respond.${k}`;
+      return null;
+    }
+    if (r.text !== undefined && typeof r.text !== 'string') return 'respond.text is a string';
+    if (r.reasoning !== undefined && typeof r.reasoning !== 'string') return 'respond.reasoning is a string';
+    if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason))) return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+    if (r.toolCalls !== undefined) {
+      for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+        const t = tc as Record<string, unknown>;
+        if (!t || typeof t !== 'object' || Array.isArray(t)) return 'respond.toolCalls entries are objects';
+        if (typeof t.name !== 'string' || !t.name) return 'respond.toolCalls[].name is a non-empty string';
+        if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments)) return 'respond.toolCalls[].arguments is an object';
+        if (t.id !== undefined && typeof t.id !== 'string') return 'respond.toolCalls[].id is a string';
+      }
+    }
+    if (r.text === undefined && r.toolCalls === undefined) return 'respond needs text or toolCalls (or an error)';
+    return null;
+  },
+};
+
+/** 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 function loadTogetheraiScenarioDocument(path: string): ScenarioDocument {
+  let parsed: unknown;
+  try {
+    // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract
+    // R12b): the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world
+    // serves ITS OWN scenario instead of whatever happens to sit on the host disk — and the
+    // serve path stays workerd-clean. A missing document keeps the historical ENOENT wording,
+    // so the loud load-time failure reads byte-identically to the read it replaces.
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new ScenarioError(`togetherai scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, togetheraiScenarioAdapter);
+}
+
+export function createTogetheraiScenarioEngine(document?: ScenarioDocument): TogetheraiScenarioEngine {
+  return new ScenarioEngine(togetheraiScenarioAdapter, document);
+}
+
+/**
+ * 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 function realizeTogetheraiRespond(respond: TogetheraiScenarioRespond): ScriptedResult {
+  const toolCalls: TogetheraiToolCall[] = [];
+  const scripted = respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : [];
+  scripted.forEach((tc, index) => {
+    const seed = `${index}:${tc.name}:${JSON.stringify(tc.arguments)}`;
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) { h ^= seed.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+    toolCalls.push({ id: tc.id ?? `call_scripted_${(h >>> 0).toString(36)}`, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } });
+  });
+  return {
+    text: respond.text ?? (toolCalls.length ? null : ''),
+    reasoning: respond.reasoning ?? null,
+    toolCalls,
+    finishReason: respond.finishReason ?? (toolCalls.length ? 'tool_calls' : 'stop'),
+  };
+}

package/src/togetherai-server.ts

@@ -0,0 +1,199 @@
+// Together AI twin HTTP server — serve the full Together twin handler over HTTP so the real
+// `together-ai` SDK (constructed with `baseURL: http://127.0.0.1:<port>/v1`) works UNMODIFIED.
+// JSON bodies pass straight through. Writable by default; pass readOnly to reject mutations (D3).
+//
+// Streaming: when the request body has `"stream": true`, the server constructs a REAL SSE
+// response by feeding the handler an sseSink that writes each chunk in Together's
+// `data: <json>\n\n` wire format, ending with `data: [DONE]\n\n`. (The handler itself stays
+// socket-free — the sink is the only place a socket is touched, on the live HTTP path.)
+//
+// Multipart: the audio transcription/translation endpoints and POST /v1/files/upload take
+// `multipart/form-data`. The server parses the form into the handler's JSON contract so the
+// handler stays a pure JSON function.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createTogetheraiTwinFetch` and
+// the SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): SSE streaming, the multipart adaptation and the raw (non-JSON)
+// payload lane genuinely exceed the common shape — groq-server.ts is the reference.
+import { serveHttp, twinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+import { createTogetheraiScenarioEngine, type TogetheraiScenarioEngine, loadTogetheraiScenarioDocument } from './togetherai-scenario.ts';
+import { TOGETHERAI_API_PREFIX, TOGETHERAI_UPLOAD_DOOR, handleTogetheraiTwinRequest, handleTogetheraiUploadDoor } from './togetherai-twin.ts';
+import type { SseEvent } from './togetherai-types.ts';
+
+function wantsStream(body: string): boolean {
+  if (!body) return false;
+  try {
+    return (JSON.parse(body) as { stream?: unknown })?.stream === true;
+  } catch {
+    return false;
+  }
+}
+
+function encodeSse(event: SseEvent): string {
+  if (event.done) return 'data: [DONE]\n\n';
+  return `data: ${JSON.stringify(event.data)}\n\n`;
+}
+
+const STREAMABLE = new Set([`${TOGETHERAI_API_PREFIX}/chat/completions`, `${TOGETHERAI_API_PREFIX}/completions`]);
+
+async function multipartToJson(request: Request): Promise<string> {
+  try {
+    const form = await request.formData();
+    const out: Record<string, unknown> = {};
+    // Forward every scalar field generically (model, purpose, response_format, language, url, …).
+    for (const [key, value] of form.entries()) {
+      if (typeof value === 'string') {
+        // Repeated scalar fields arrive one entry at a time.
+        if (key.endsWith('[]')) {
+          const k = key.slice(0, -2);
+          const prior = out[k];
+          out[k] = Array.isArray(prior) ? [...prior, value] : [value];
+        } else {
+          out[key] = value;
+        }
+      }
+    }
+    const file = form.get('file');
+    if (file instanceof File) {
+      const content = await file.text();
+      out.file = file.name || 'upload';
+      out.filename = file.name || 'upload';
+      out.content = content;
+      out.bytes = file.size || content.length;
+    }
+    return JSON.stringify(out);
+  } catch {
+    return '{}';
+  }
+}
+
+/** Options every Together-twin HTTP surface needs, independent of who owns the socket. */
+export interface TogetheraiTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  scenarioPath?: string;
+}
+
+export function createTogetheraiTwinFetch(options: TogetheraiTwinFetchOptions): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  // Scenario scripting (togetherai-scenario.ts): a JSON scenario file — via the scenarioPath
+  // option or the TWIN_TOGETHERAI_SCENARIO env var — scripts chat completions. Loaded ONCE at
+  // startup (a malformed file fails loudly here, never silently).
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_TOGETHERAI_SCENARIO;
+  const scenarioEngine: TogetheraiScenarioEngine | undefined = scenarioPath ? createTogetheraiScenarioEngine(loadTogetheraiScenarioDocument(scenarioPath)) : undefined;
+  return async function togetheraiTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(twinManifest({
+        vendor: 'togetherai',
+        twinOf: 'Together AI API (inference at /v1; Together-native files/batches/fine-tunes)',
+        stateSentence: 'Seed files/batches/fine-tunes through the ordinary API (POST /v1/files/upload then /v1/batches) with any key. The together-ai SDK\'s files.upload() reads TOGETHER_API_BASE_URL at module load and ignores client.baseURL — point it at <twin>/v1 or it egresses to the real vendor.',
+        behaviorSentence: "Chat completions are scripted by MSW-shaped handlers in the world dir (handlers/togetherai.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageIsToolResult|reasoningEffortEquals}, respond:{text|reasoning|toolCalls, finishReason?} | {error:{type:rate_limit_exceeded|engine_overloaded|internal_server_error}}, once?, phase?}. Unmatched requests answer a labeled stub naming this door.",
+        exampleHandler: { on: { userTextIncludes: 'summarize', hasTool: 'search_docs' }, respond: { text: 'Scripted summary.' }, once: true },
+        engine: scenarioEngine as never,
+      }));
+    }
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin/scenario') {
+      return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'togetherai', handlers: [], misses: 0, recentMisses: [] });
+    }
+
+    // The SDK redirect upload flow's PUT target (twin-only scaffolding, not vendor surface).
+    if (url.pathname.replace(/\/+$/, '').startsWith(TOGETHERAI_UPLOAD_DOOR)) {
+      const res = await handleTogetheraiUploadDoor({
+        method: request.method, path: url.pathname, body: await request.text(),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        ...(options.readOnly ? { readOnly: true } : {}),
+      });
+      return new Response(JSON.stringify(res.body), { status: res.status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(res.headers ?? {}) } });
+    }
+
+    const path = url.pathname + (url.search || '');
+    const cleanPath = url.pathname.replace(/\/+$/, '');
+    const contentType = request.headers.get('content-type') ?? '';
+
+    const passHeaders: Record<string, string> = {};
+    for (const k of ['authorization', 'x-twin-force-rate-limit', 'x-twin-force-spending-limit', 'x-twin-force-engine-overloaded']) {
+      const v = request.headers.get(k);
+      if (v !== null) passHeaders[k] = v;
+    }
+
+    let body = '';
+    if (request.method !== 'GET') {
+      body = contentType.includes('multipart/form-data') ? await multipartToJson(request) : await request.text();
+    }
+
+    // Streaming POST → a real text/event-stream response built from the sink.
+    //
+    // Events are COLLECTED first, then framed. The handler is synchronous-fast, so buffering
+    // costs nothing — and it is what lets a PRE-STREAM failure (validation 400, auth 401,
+    // rate-limit 429) answer with its REAL status and the vendor's JSON error envelope. Emitting
+    // the refusal as a lone `data:` frame inside a 200 text/event-stream was a FAKE SUCCESS the
+    // in-process path could not see: `handleTogetheraiTwinRequest` returns 400 for a body with no
+    // `messages` while the wire returned 200, so every verify asserting that 400 asserted a status
+    // the socket never carried. Together rejects a bad request BEFORE opening the event stream;
+    // this twin decides every refusal before the first chunk.
+    if (!readOnly && request.method.toUpperCase() === 'POST' && STREAMABLE.has(cleanPath) && wantsStream(body)) {
+      const events: SseEvent[] = [];
+      const { status, body: out, headers: errHeaders } = await handleTogetheraiTwinRequest({
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        method: request.method, path, body, readOnly, occurredAt: worldNow(), headers: passHeaders,
+        ...(options.root !== undefined ? { root: options.root } : {}), sseSink: (e: SseEvent) => events.push(e),
+      });
+      if (status >= 400) {
+        return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(errHeaders ?? {}) } });
+      }
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const enc = new TextEncoder();
+          for (const e of events) controller.enqueue(enc.encode(encodeSse(e)));
+          controller.close();
+        },
+      });
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', 'x-request-id': 'req_twin' } });
+    }
+
+    // Defensive: a handler throw must become a vendor-shaped 500, never an escaped exception
+    // (ADDING_A_TWIN.md §8, "In-process server harnesses … contain handler errors").
+    let status: number;
+    let out: unknown;
+    let outHeaders: Record<string, string> | undefined;
+    try {
+      const res = await handleTogetheraiTwinRequest({
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        method: request.method, path, body, readOnly,
+        occurredAt: worldNow(), headers: passHeaders,
+        ...(options.root !== undefined ? { root: options.root } : {}),
+      });
+      status = res.status; out = res.body; outHeaders = res.headers;
+    } catch (err) {
+      return new Response(JSON.stringify({ error: { message: `twin handler error: ${err instanceof Error ? err.message : String(err)}`, type: 'internal_server_error' } }), {
+        status: 500, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin' },
+      });
+    }
+
+    // The SDK's redirect upload flow: the handler emits a twin-LOCAL `Location`; the real SDK
+    // fetches it with no base URL, so absolutize it against the twin's public base on the wire
+    // (twinPublicBase: the origin plus any path a served World mounts the twin under).
+    // (Done BEFORE the raw/JSON split: the 302's empty-string body is a raw payload.)
+    if (status === 302 && outHeaders?.location?.startsWith('/')) {
+      outHeaders = { ...outHeaders, location: `${twinPublicBase(request)}${outHeaders.location}` };
+    }
+
+    // Raw (non-JSON) payloads: file content downloads, `response_format:'text'` transcripts, and
+    // the TTS stub body. Each carries its own content-type from the handler.
+    if (typeof out === 'string') {
+      return new Response(out, { status, headers: { 'content-type': 'application/octet-stream', 'x-request-id': 'req_twin', ...(outHeaders ?? {}) } });
+    }
+    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(outHeaders ?? {}) } });
+  };
+}
+
+export async function createTogetheraiTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createTogetheraiTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/togetherai-stub.ts

@@ -0,0 +1,197 @@
+// THE GENERATIVE-STUB CORE — the deterministic labeled answer this twin gives where the vendor
+// runs a model.
+//
+// The twin CANNOT run the model — there are no weights here. So `POST /v1/chat/completions`
+// returns a DETERMINISTIC STUB completion that is CLEARLY a twin stub, NEVER pretending to be
+// real model output; `/v1/embeddings` returns DETERMINISTIC pseudo-vectors; and
+// `/v1/audio/speech` returns a DETERMINISTIC labeled stub body. What IS faithful is the ENTIRE
+// PROTOCOL ENVELOPE: the response shape (including Together's REQUIRED `prompt` array), the
+// streaming chunk sequence, `finish_reason:'eos'`, tool_calls, and Together's nullable usage.
+//
+// SERVE-PATH DETERMINISM (CLAUDE.md): every number below is a pure function of the request. No
+// wall clock anywhere — Together reports no timing block (that is Groq's), so there is nothing
+// to derive.
+//
+// The stub IS the twin's answer: the manifest's chat, embeddings and audio capabilities are
+// claimed on the envelope and the determinism, which is what a consumer binds to.
+
+import type { TogetheraiMessageParam, TogetheraiToolCall, TogetheraiUsage } from './togetherai-types.ts';
+
+/** Deterministic token estimate for a string: ~1 token per 4 chars (faithful order of
+ *  magnitude; deterministic so usage counts are assertable). Never zero for non-empty text. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+/** Flatten a chat message's content to its text for token counting / echo. Together's schema
+ *  types message content as `string | null` — no content-part arrays — but a number-typed
+ *  content is stringified rather than silently counted as zero. */
+export function contentToText(content: TogetheraiMessageParam['content']): string {
+  if (typeof content === 'string') return content;
+  if (content === null || content === undefined) return '';
+  return String(content);
+}
+
+/** Deterministic prompt-token count for the full set of messages. */
+export function countPromptTokens(messages: TogetheraiMessageParam[]): number {
+  let total = 0;
+  for (const m of messages) {
+    total += estimateTokens(contentToText(m.content));
+    if (m.name) total += estimateTokens(m.name);
+    for (const tc of m.tool_calls ?? []) total += estimateTokens(JSON.stringify(tc));
+  }
+  return total;
+}
+
+/** The last user turn's text — the thing the stub echoes (deterministic, clearly labeled). */
+export function lastUserText(messages: TogetheraiMessageParam[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]!.role === 'user') return contentToText(messages[i]!.content);
+  }
+  // No user turn (e.g. only system) → fall back to the last message's text.
+  return messages.length ? contentToText(messages[messages.length - 1]!.content) : '';
+}
+
+/**
+ * Build the deterministic stub ASSISTANT text. It is unmistakably a twin stub: it carries the
+ * `[twin-stub:<model>]` marker and echoes the prompt, so no caller can mistake it for real
+ * model output. Deterministic for a given prompt → assertable in tests.
+ */
+export function stubAssistantText(messages: TogetheraiMessageParam[], model: string): string {
+  const prompt = lastUserText(messages).trim();
+  const echo = prompt.length > 200 ? `${prompt.slice(0, 200)}…` : prompt;
+  return `[twin-stub:${model}] This is a deterministic stub from the Together AI twin (no model weights are run). Echoing your last message: ${echo || '(empty)'}`;
+}
+
+/**
+ * The `reasoning` string Together's reasoning models surface on the assistant message. A labeled
+ * stub, like the content — never a real chain of thought.
+ */
+export function stubReasoningText(messages: TogetheraiMessageParam[], model: string): string {
+  return `[twin-stub:${model}] deterministic stub reasoning (no model weights are run) for: ${lastUserText(messages).trim().slice(0, 120) || '(empty)'}`;
+}
+
+// ── Deterministic hashing / pseudo-vectors ──────────────────────────────────────────────
+/** A small deterministic 32-bit hash (FNV-1a) of a string. */
+export function fnv1a(text: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** A deterministic, reproducible L2-normalized pseudo-embedding vector for `text`. NOT a real
+ *  embedding — the values carry no semantic meaning; only the SHAPE and DETERMINISM are
+ *  faithful. Same text → same vector. */
+export function pseudoEmbedding(text: string, dimensions: number): number[] {
+  const dim = Math.max(1, Math.floor(dimensions));
+  let state = fnv1a(text) || 1;
+  const raw = new Array<number>(dim);
+  let norm = 0;
+  for (let i = 0; i < dim; i++) {
+    // xorshift32 PRNG seeded from the text hash → deterministic per (text, index).
+    state ^= state << 13; state >>>= 0;
+    state ^= state >> 17;
+    state ^= state << 5; state >>>= 0;
+    const v = (state / 0xffffffff) * 2 - 1;
+    raw[i] = v;
+    norm += v * v;
+  }
+  norm = Math.sqrt(norm) || 1;
+  for (let i = 0; i < dim; i++) raw[i] = raw[i]! / norm;
+  return raw;
+}
+
+/** Assemble Together's `usage` object (the three token counts, nullable per the schema). */
+export function buildUsage(promptTokens: number, completionTokens: number, extra: Partial<TogetheraiUsage> = {}): TogetheraiUsage {
+  return {
+    prompt_tokens: promptTokens,
+    completion_tokens: completionTokens,
+    total_tokens: promptTokens + completionTokens,
+    ...extra,
+  };
+}
+
+/** Extract a tool's function name from a Together/OpenAI-shaped tool
+ *  (`{ type:'function', function:{ name } }`). */
+function toolName(t: unknown): string {
+  const o = t as { function?: { name?: unknown }; name?: unknown } | undefined;
+  if (o?.function && typeof o.function.name === 'string') return o.function.name;
+  if (typeof o?.name === 'string') return o.name;
+  return 'unknown_function';
+}
+
+function placeholderForSchema(def: unknown): unknown {
+  const d = def as { type?: unknown; enum?: unknown[] } | undefined;
+  if (Array.isArray(d?.enum) && d!.enum!.length) return d!.enum![0];
+  switch (d?.type) {
+    case 'number':
+    case 'integer': return 0;
+    case 'boolean': return false;
+    case 'array': return [];
+    case 'object': return {};
+    default: return '';
+  }
+}
+
+/**
+ * Build a deterministic stub argument string for a tool. When the tool declares a JSON-schema
+ * `parameters` object, the twin synthesizes a deterministic object containing every declared
+ * property with a type-appropriate placeholder so strict callers parse it cleanly.
+ */
+export function stubToolArguments(tool: unknown): string {
+  const o = tool as { function?: { parameters?: unknown }; parameters?: unknown } | undefined;
+  const schema = (o?.function?.parameters ?? o?.parameters) as { properties?: Record<string, unknown> } | undefined;
+  const props = schema && typeof schema === 'object' ? schema.properties : undefined;
+  if (!props || typeof props !== 'object') return '{}';
+  const out: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(props)) out[key] = placeholderForSchema(def);
+  return JSON.stringify(out);
+}
+
+/**
+ * When tools/functions are provided, the stub deterministically "calls" the tool selected by
+ * `forcedName` (a named tool_choice) or the FIRST provided tool. Returns the tool_call, or null
+ * when no tools were provided.
+ */
+export function stubToolCall(tools: unknown, seq: number, forcedName?: string): TogetheraiToolCall | null {
+  if (!Array.isArray(tools) || tools.length === 0) return null;
+  const chosen = forcedName ? (tools.find((t) => toolName(t) === forcedName) ?? tools[0]) : tools[0];
+  return { id: `call_twin_${seq}`, type: 'function', function: { name: toolName(chosen), arguments: stubToolArguments(chosen) } };
+}
+
+/**
+ * Build a deterministic JSON-object stub for `response_format` json_object / json_schema.
+ * Together's `ResponseFormatJsonSchema` nests the schema under `json_schema.schema` and REQUIRES
+ * `json_schema.name` (a-z/A-Z/0-9/underscore/dash, ≤64 chars) — that requirement is modeled in
+ * the handler, not here. Always valid JSON.
+ */
+export function stubJsonObject(messages: TogetheraiMessageParam[], model: string, jsonSchema?: unknown): string {
+  const schema = jsonSchema as { schema?: { properties?: Record<string, unknown> }; properties?: Record<string, unknown> } | undefined;
+  const props = schema?.schema?.properties ?? schema?.properties;
+  if (props && typeof props === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, def] of Object.entries(props)) out[key] = placeholderForSchema(def);
+    return JSON.stringify(out);
+  }
+  return JSON.stringify({ _twin_stub: true, model, echo: lastUserText(messages).slice(0, 200) });
+}
+
+// ── Audio stub ──────────────────────────────────────────────────────────────────────────
+/**
+ * The deterministic transcript the twin returns for `/v1/audio/transcriptions` and
+ * `/…/translations`. There is no acoustic model here, so the text is a labeled stub seeded from
+ * the SUPPLIED AUDIO REFERENCE (filename or url) — same input, same transcript.
+ */
+export function stubTranscript(model: string, source: string, translate: boolean): string {
+  return `[twin-stub:${model}] deterministic ${translate ? 'translation' : 'transcription'} stub (no acoustic model is run) for audio "${source}" (${fnv1a(source).toString(36)})`;
+}
+
+/** Deterministic audio-second count for a source reference — what `duration` reports;
+ *  derived from the source hash, never a clock. */
+export function stubAudioSeconds(source: string): number {
+  return Math.round(((fnv1a(source) % 60_000) / 1000) * 100) / 100;
+}