@volter/twin-moonshot 0.1.0

package/src/moonshot-scenario.ts

@@ -0,0 +1,194 @@
+// The moonshot pack's scenario system on the kernel's ONE engine (@volter/world-core
+// scenario.ts): Moonshot 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 Moonshot's
+// own envelope shapes.
+//
+// The handler FILE (handlers/moonshot.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: the manifest's `moonshot.scenario.*` entries verify THIS
+// scaffolding (filed under their own `scenario` area, section-commented "NOT vendor surface"),
+// and the behavior is gated by moonshot-scenario.test.ts.
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, fnv1a, lastUserText } from './moonshot-stub.ts';
+import type { MoonshotMessageParam, MoonshotToolCall } from './moonshot-types.ts';
+
+export type MoonshotScenarioRequest = {
+  model: string;
+  messages: MoonshotMessageParam[];
+  tools?: unknown;
+  /** Moonshot-specific: the k2.6/k2.7-code `thinking` object. Scriptable because thinking mode
+   *  decides whether `reasoning_content` appears on the response. */
+  thinking?: { type?: string; keep?: string | null };
+};
+export type MoonshotScenarioEngine = ScenarioEngine<MoonshotScenarioRequest>;
+
+export type ScenarioToolCall = { name: string; arguments: Record<string, unknown>; id?: string };
+
+/**
+ * What a moonshot handler may script. `reasoning` is Moonshot-specific (the `reasoning_content`
+ * field on the assistant message, and the thinking block on the Messages surface); `error`
+ * scripts one of Moonshot's own documented failure envelopes rather than a success.
+ */
+export type MoonshotScenarioRespond = {
+  text?: string;
+  reasoning?: string;
+  toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+  finishReason?: 'stop' | 'length' | 'tool_calls';
+  /** A scripted vendor failure: Moonshot's documented error types (platform.kimi.ai/docs/api/errors). */
+  error?: { type: 'rate_limit_reached_error' | 'server_unavailable' | 'server_error'; message?: string };
+};
+
+export type ScriptedResult = {
+  text: string | null;
+  reasoning: string | null;
+  toolCalls: MoonshotToolCall[];
+  finishReason: 'stop' | 'length' | 'tool_calls';
+};
+
+const RESPOND_KEYS = new Set(['text', 'reasoning', 'toolCalls', 'finishReason', 'error']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls']);
+const ERROR_TYPES = new Set(['rate_limit_reached_error', 'server_unavailable', 'server_error']);
+const THINKING_TYPES = new Set(['enabled', 'disabled']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+
+function lastToolResultNames(messages: MoonshotMessageParam[]): 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 moonshotScenarioAdapter: PackScenarioAdapter<MoonshotScenarioRequest> = {
+  vendor: 'moonshot',
+  // R15 — a status fault in THIS vendor's envelope: the same {error:{message,type}} bodies
+  // moonshot-twin.ts serves for its own refusals (its 429 is `type: 'rate_limit_reached_error'`,
+  // its outage is `server_unavailable`). The Messages surface re-wears the body in the Anthropic
+  // envelope at its own route; the fault result carries the Moonshot shape.
+  renderFault: (f) => ({
+    body: f.status === 429
+      ? { error: { message: f.message ?? 'Request rate limit reached: 3 requests per minute (Tier 0). Please retry after 20 seconds.', type: 'rate_limit_reached_error' } }
+      : f.status >= 500
+        ? { error: { message: f.message ?? 'The server is overloaded or not ready to handle the request. Please try again later.', type: f.status === 503 ? 'server_unavailable' : 'server_error' } }
+        : { error: { message: f.message ?? 'The request was refused by a scripted fault.', type: 'invalid_request_error' } },
+  }),
+  features: (req): ScenarioFeatures => ({
+    model: req.model,
+    lastUserText: lastUserText(req.messages as MoonshotMessageParam[]).slice(0, 300),
+    tools: toolNames(req.tools),
+    lastMessageIsToolResult: (req.messages[req.messages.length - 1] as { role?: string } | undefined)?.role === 'tool',
+    toolResultFor: [...lastToolResultNames(req.messages)],
+    thinkingType: req.thinking?.type ?? 'enabled',
+  }),
+  matchers: {
+    modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+    userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages as MoonshotMessageParam[]).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),
+    // Moonshot-specific: script behaviour per thinking mode (kimi-k2.6 accepts 'disabled';
+    // kimi-k2.7-code does not).
+    thinkingTypeEquals: (req, cond) => nonEmptyString(cond) && (req.thinking?.type ?? 'enabled') === 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.thinkingTypeEquals !== undefined) {
+      if (typeof on.thinkingTypeEquals !== 'string' || !THINKING_TYPES.has(on.thinkingTypeEquals)) {
+        return `on.thinkingTypeEquals is one of ${[...THINKING_TYPES].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 loadMoonshotScenarioDocument(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(`moonshot scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, moonshotScenarioAdapter);
+}
+
+export function createMoonshotScenarioEngine(document?: ScenarioDocument): MoonshotScenarioEngine {
+  return new ScenarioEngine(moonshotScenarioAdapter, document);
+}
+
+/**
+ * Turn a validated `respond` into the pack's own faithful assistant turn.
+ *
+ * Determinism (CLAUDE.md): the tool-call id is derived from the scripted call's own content and
+ * its position in the handler — never a module-level counter, which would make two identical
+ * scripted requests answer differently after a restart.
+ */
+export function realizeMoonshotRespond(respond: MoonshotScenarioRespond): ScriptedResult {
+  const toolCalls: MoonshotToolCall[] = [];
+  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)}`;
+    toolCalls.push({ id: tc.id ?? `call_scripted_${fnv1a(seed).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/moonshot-server.ts

@@ -0,0 +1,220 @@
+// Moonshot twin HTTP server — serve the full Moonshot twin handler over HTTP so the REAL clients
+// work UNMODIFIED: the standard `openai` SDK with `baseURL: 'http://127.0.0.1:<port>/v1'`, the
+// `anthropic` SDK with `baseURL: 'http://127.0.0.1:<port>/anthropic'`, and plain HTTP callers.
+// There is no vendor SDK to configure — Moonshot's documented integration path IS these clients
+// with a swapped base URL (platform.kimi.ai/docs/overview, read 2026-09-16).
+//
+// Streaming: when a chat/responses/messages request body has `"stream": true`, the server
+// constructs a REAL SSE response by feeding the handler an injected sink — OpenAI grammar writes
+// `data: <json>\n\n` frames ending with `data: [DONE]\n\n`; the Anthropic-compatible Messages
+// surface and the Responses surface write `event: <name>\ndata: <json>\n\n` frames (Anthropic's
+// grammar has no [DONE] sentinel; the stream ends after `message_stop` / `response.completed`).
+//
+// Multipart: POST /v1/files takes `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 `createMoonshotTwinFetch` and the
+// SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): three SSE grammars plus the multipart adaptation genuinely
+// exceed the common shape — openai-server.ts is the reference for that lane.
+import { serveHttp, twinManifest, worldNow } from '@volter/world-core';
+import {
+  handleMoonshotTwinRequest,
+  MESSAGES_PREFIX,
+  MOONSHOT_API_PREFIX,
+  type MessagesSseSink,
+} from './moonshot-twin.ts';
+import { createMoonshotScenarioEngine, loadMoonshotScenarioDocument, type MoonshotScenarioEngine } from './moonshot-scenario.ts';
+import type { MessagesSseEvent, SseEvent, SseSink } from './moonshot-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`;
+}
+
+/** Named-event framing (Anthropic Messages / Responses grammar): `event: <name>\ndata: <json>`. */
+function encodeNamedSse(event: MessagesSseEvent): string {
+  if (event.done) return '\n';
+  const name = event.event ?? 'message';
+  return `event: ${name}\ndata: ${JSON.stringify(event.data)}\n\n`;
+}
+
+// The three streaming POST endpoints, each with its own wire grammar.
+const OPENAI_STREAMABLE = new Set([`${MOONSHOT_API_PREFIX}/chat/completions`]);
+const NAMED_STREAMABLE = new Set([`${MESSAGES_PREFIX}/messages`, `${MOONSHOT_API_PREFIX}/responses`]);
+
+async function multipartToJson(request: Request): Promise<string> {
+  try {
+    const form = await request.formData();
+    const out: Record<string, unknown> = {};
+    // Forward every scalar field generically: `purpose` and `filename` on Moonshot's Files API.
+    for (const [key, value] of form.entries()) {
+      if (typeof value === 'string') {
+        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)) {
+      // The vendor's Upload File REQUIRES the file body (§9 round two, F3): a form without one
+      // reaches createFile marked, and the handler refuses it rather than minting an empty
+      // 'ready' file. (form.get returns the FIRST 'file' part when several are sent; the
+      // vendor's form has one.)
+      out._multipart_missing_file = true;
+    }
+    if (file instanceof File) {
+      const bytes = new Uint8Array(await file.arrayBuffer());
+      out.file = file.name || 'upload';
+      out.filename = file.name || 'upload';
+      // The handler's JSON contract carries content as a STRING, so binary uploads travel
+      // base64-encoded WITH the `binary_content: true` marker; the file row stores the marker
+      // and the /content route decodes before serving (the twin imports nothing from the
+      // server — the marker is the contract). Encoding was a §9-round-one finding: the adapter
+      // used to store the base64 TEXT itself, so a real multipart client got base64 back from
+      // GET /content while `bytes` counted the raw length.
+      out.content = Buffer.from(bytes).toString('base64');
+      out.binary_content = true;
+      out.media_type = file.type || '';
+      out.bytes = bytes.length;
+    }
+    return JSON.stringify(out);
+  } catch {
+    return '{}';
+  }
+}
+
+/** Options every Moonshot-twin HTTP surface needs, independent of who owns the socket. */
+export interface MoonshotTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  scenarioPath?: string;
+}
+
+export function createMoonshotTwinFetch(options: MoonshotTwinFetchOptions): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  // Scenario scripting (moonshot-scenario.ts): a JSON scenario file — via the scenarioPath option
+  // or the TWIN_MOONSHOT_SCENARIO env var — scripts the three inference endpoints. Loaded ONCE at
+  // startup (a malformed file fails loudly here, never silently).
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_MOONSHOT_SCENARIO;
+  const scenarioEngine: MoonshotScenarioEngine | undefined = scenarioPath ? createMoonshotScenarioEngine(loadMoonshotScenarioDocument(scenarioPath)) : undefined;
+  return async function moonshotTwinFetch(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: 'moonshot',
+        twinOf: 'Moonshot (Kimi) Platform API — OpenAI-compatible under /v1, Anthropic-compatible under /anthropic/v1; Moonshot ships no SDK of its own, its documented clients are the standard openai/anthropic SDKs with a swapped base URL',
+        stateSentence: 'Seed files through the ordinary API (POST /v1/files, multipart) with any key; files, batches and the account balance are stateful, everything else is deterministic.',
+        behaviorSentence: "The three inference endpoints are scripted by MSW-shaped handlers in the world dir (handlers/moonshot.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageIsToolResult|thinkingTypeEquals}, respond:{text|reasoning|toolCalls, finishReason?} | {error:{type:rate_limit_reached_error|server_unavailable|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: 'moonshot', handlers: [], misses: 0, recentMisses: [] });
+    }
+
+    const path = url.pathname + (url.search || '');
+    // Collapse REPEATED slashes as well as the trailing one, exactly as `routeMoonshot` does when
+    // it builds `seg` (and as the budget's split does for its anchored rules) — the two
+    // normalizations must agree or `POST //v1/chat/completions` with `stream: true` reaches the
+    // streaming ROUTE but misses the STREAMABLE set and is answered with a unary JSON body to a
+    // client reading text/event-stream (the groq pack's §9 round-two finding).
+    const cleanPath = url.pathname.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+    const contentType = request.headers.get('content-type') ?? '';
+
+    const passHeaders: Record<string, string> = {};
+    // `x-api-key` + `anthropic-version`: the /anthropic surface's documented client is the
+    // UNMODIFIED `@anthropic-ai/sdk`, which authenticates with x-api-key (never a bearer) and
+    // sends anthropic-version on every call — not forwarding them made the whole surface
+    // 401-dead for exactly the client Moonshot documents.
+    for (const k of ['authorization', 'x-api-key', 'anthropic-version', 'x-msh-request-nonce', 'x-twin-force-rate-limit', 'x-twin-force-server-unavailable']) {
+      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 (a 400 for a bad body, an auth
+    // 401, a 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: Moonshot rejects a bad request BEFORE opening the event stream.
+    const isStreamable = !readOnly && request.method.toUpperCase() === 'POST'
+      && (OPENAI_STREAMABLE.has(cleanPath) || NAMED_STREAMABLE.has(cleanPath))
+      && wantsStream(body);
+    if (isStreamable) {
+      const named = NAMED_STREAMABLE.has(cleanPath);
+      const events: Array<SseEvent | MessagesSseEvent> = [];
+      const sink: SseSink = (e) => events.push(e);
+      const namedSink: MessagesSseSink = (e) => events.push(e);
+      const { status, body: out, headers: errHeaders } = await handleMoonshotTwinRequest({
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        method: request.method, path, body, readOnly, occurredAt: worldNow(), headers: passHeaders,
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        sseSink: named ? undefined : sink,
+        messagesSseSink: named ? namedSink : undefined,
+      });
+      const resHeaders: Record<string, string> = { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive', ...(errHeaders ?? {}) };
+      if (status !== 200) {
+        // A pre-stream failure answers its REAL status + the vendor's JSON envelope.
+        return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(errHeaders ?? {}) } });
+      }
+      const frames = events.map((e) => ('event' in (e as MessagesSseEvent) && (e as MessagesSseEvent).event !== undefined ? encodeNamedSse(e as MessagesSseEvent) : encodeSse(e as SseEvent))).join('');
+      // The Msh-Request-* signature headers are minted IN THE HANDLER (one signer for every
+      // surface — see handleMoonshotTwinRequest) and arrive here through `errHeaders`, which
+      // resHeaders already spreads.
+      return new Response(frames, { status: 200, headers: resHeaders });
+    }
+
+    // Unary path.
+    const { status, body: out, headers: errHeaders } = await handleMoonshotTwinRequest({
+      ...(scenarioEngine ? { scenarioEngine } : {}),
+      method: request.method, path, body, readOnly, occurredAt: worldNow(), headers: passHeaders,
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    });
+    // The file-content route returns raw bytes; everything else is JSON. The handler's
+    // `x-twin-content-binary` response header (§9 round two, F1) says how to turn the body
+    // STRING into bytes: binary content is latin1-carried (every byte value intact, converted
+    // back here — a plain `new Response(string)` would re-encode as UTF-8 and mangle every
+    // byte ≥ 0x80); text content is the string itself, written UTF-8 so a non-ASCII text file
+    // round-trips byte for byte.
+    const isRawContent = request.method === 'GET' && /\/v1\/files\/[^/]+\/content$/.test(cleanPath);
+    if (isRawContent && status === 200) {
+      const binary = errHeaders?.['x-twin-content-binary'] === '1';
+      const bytes = binary ? Buffer.from(String(out), 'latin1') : Buffer.from(String(out), 'utf8');
+      const headers = { ...errHeaders };
+      delete headers['x-twin-content-binary'];
+      return new Response(bytes, { status, headers: { 'content-type': 'application/octet-stream', ...headers } });
+    }
+    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(errHeaders ?? {}) } });
+  };
+}
+
+export async function createMoonshotTwinServer(options: MoonshotTwinFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createMoonshotTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/moonshot-stub.ts

@@ -0,0 +1,230 @@
+// 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`,
+// `POST /v1/responses` and `POST /anthropic/v1/messages` return DETERMINISTIC STUB completions
+// clearly labeled `[twin-stub:<model>]` — they NEVER pretend to be real model output. What IS
+// faithful is the ENTIRE PROTOCOL ENVELOPE: the response shapes of all three protocols, the
+// streaming chunk/event sequences, tool_calls / tool_use blocks, finish_reason / stop_reason,
+// `reasoning_content` / thinking blocks, and Moonshot's cache-split `usage` objects.
+//
+// SERVE-PATH DETERMINISM (CLAUDE.md): every number below is a pure function of the request. The
+// cache split in the usage object is DERIVED from the token counts by a fixed rule (Moonshot
+// documents that a cache hit requires >256 prompt tokens), never from a wall clock — a replay is
+// byte-identical.
+//
+// The stub IS the twin's answer: the manifest's chat/responses/messages capabilities are claimed
+// on the envelope and the determinism, which is what a consumer binds to.
+
+import type { MoonshotMessageParam, MoonshotToolCall } from './moonshot-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 (string OR content-part array) to its text for token
+ *  counting / echo. Non-text parts contribute their JSON length so the count is deterministic
+ *  and reflects payload size. */
+export function contentToText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (content === null || content === undefined) return '';
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((part) => {
+      if (part && typeof part === 'object' && (part as { type?: string }).type === 'text') {
+        return String((part as { text?: unknown }).text ?? '');
+      }
+      return JSON.stringify(part);
+    })
+    .join('\n');
+}
+
+/** Deterministic prompt-token count for a set of chat messages. */
+export function countPromptTokens(messages: MoonshotMessageParam[]): 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: MoonshotMessageParam[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]!.role === 'user') return contentToText(messages[i]!.content);
+  }
+  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: MoonshotMessageParam[], 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 Moonshot twin (no model weights are run). Echoing your last message: ${echo || '(empty)'}`;
+}
+
+/**
+ * The `reasoning_content` string a thinking-mode model returns (kimi-k3 always; k2.6/k2.7-code
+ * when thinking is enabled). A labeled stub, like the content — never a real chain of thought.
+ */
+export function stubReasoningContent(messages: MoonshotMessageParam[], model: string): string {
+  return `[twin-stub:${model}] deterministic stub reasoning (no model weights are run) for: ${lastUserText(messages).trim().slice(0, 120) || '(empty)'}`;
+}
+
+/** A deterministic stub signature for a Messages `thinking` block (the vendor asks callers to
+ *  pass it back unchanged; the twin's is a deterministic label). */
+export function stubSignature(messages: MoonshotMessageParam[], model: string): string {
+  return `sig_twin_${fnv1a(`${model}:${lastUserText(messages)}`).toString(36)}`;
+}
+
+// ── Usage assembly ──────────────────────────────────────────────────────────────────────
+/**
+ * Moonshot's automatic context caching: a hit requires MORE THAN 256 prompt tokens
+ * (platform.kimi.ai/docs/guides/context-caching — automatic caching, read 2026-09-16). The twin
+ * derives the cached share deterministically from the token count: at or below the threshold the
+ * cache is cold (0); above it a fixed 25% of the prompt is served from cache. That fraction is a
+ * judgement call, not a vendor figure — what IS vendor-shaped is the FIELD (cached_tokens in
+ * chat usage; cached_tokens / cache_write_tokens in Responses usage) and the threshold rule.
+ */
+export const CACHE_HIT_THRESHOLD = 256;
+
+export function stubCachedTokens(promptTokens: number): number {
+  return promptTokens > CACHE_HIT_THRESHOLD ? Math.floor(promptTokens * 0.25) : 0;
+}
+
+export function buildChatUsage(promptTokens: number, completionTokens: number, promptCacheKey?: string): {
+  prompt_tokens: number; completion_tokens: number; total_tokens: number; cached_tokens: number;
+} {
+  // The cache split is LOAD-BEARING on the key: Moonshot's context caching is keyed by
+  // `prompt_cache_key` (platform.kimi.ai/docs/guides/context-caching) — a request WITHOUT one has
+  // no cache namespace to hit, so `cached_tokens` is 0 however long the prompt is. With a key the
+  // threshold/fraction rule applies. (The threshold itself stays in stubCachedTokens.)
+  const cached = promptCacheKey !== undefined ? stubCachedTokens(promptTokens) : 0;
+  return {
+    prompt_tokens: promptTokens,
+    completion_tokens: completionTokens,
+    total_tokens: promptTokens + completionTokens,
+    cached_tokens: cached,
+  };
+}
+
+// ── Tool calls ──────────────────────────────────────────────────────────────────────────
+/** Extract a tool's function name from an 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 (schema-typed placeholders). Reads the
+ *  OpenAI shape (`function.parameters`), the bare `parameters`, AND the Anthropic Messages shape
+ *  (`input_schema`) — the Messages surface stubs its tool_use input through the same helper. */
+export function stubToolArguments(tool: unknown): string {
+  const o = tool as { function?: { parameters?: unknown }; parameters?: unknown; input_schema?: unknown } | undefined;
+  const schema = (o?.function?.parameters ?? o?.parameters ?? o?.input_schema) 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 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): MoonshotToolCall | 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. */
+export function stubJsonObject(messages: MoonshotMessageParam[], 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) });
+}
+
+// ── Deterministic hashing / pseudo-content ──────────────────────────────────────────────
+/** 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 id suffix from a request (so ids are stable + assertable). */
+export function stableSuffix(...parts: unknown[]): string {
+  return fnv1a(parts.map((p) => JSON.stringify(p) ?? String(p)).join('|')).toString(36);
+}
+
+/**
+ * A deterministic stub web-search result set for POST /v1/tools/search{,_pro} and the Responses
+ * web_search tool. The twin cannot reach the web (D4 — no real network), so the results are a
+ * labeled, deterministic echo of the query: same query → same results.
+ */
+export function stubSearchResults(textQuery: string, limit: number, pro: boolean, includeContent = false): Array<Record<string, unknown>> {
+  const out: Array<Record<string, unknown>> = [];
+  for (let i = 0; i < limit; i++) {
+    const base = {
+      authority: 'twin',
+      date: '2026-01-01',
+      icon: '',
+      mime: 'text/html',
+      site_name: 'twin-stub',
+      snippet: `[twin-stub] deterministic search result ${i + 1}/${limit} for: ${textQuery}`,
+      title: `[twin-stub] result ${i + 1} for: ${textQuery}`,
+      url: `https://twin-stub.invalid/search?q=${encodeURIComponent(textQuery)}&i=${i}`,
+    };
+    if (pro) {
+      out.push({ ...base, chunks: [{ text: `[twin-stub] chunk for: ${textQuery}`, score: 0.5 }] });
+    } else {
+      // `include_content: true` SERVES the content (the option's documented meaning): a labeled
+      // deterministic page stub, like tools/fetch's. Default (false) is the vendor's bare shape.
+      out.push({ ...base, text: includeContent ? `[twin-stub] content for: ${textQuery} (result ${i + 1}) — the twin performs no real network I/O (D4).` : '' });
+    }
+  }
+  return out;
+}
+
+/** A deterministic stub markdown page for POST /v1/tools/fetch. */
+export function stubFetchedMarkdown(url: string): { url: string; markdown: string; title: string } {
+  return {
+    url,
+    markdown: `[twin-stub] deterministic fetch of ${url} — the twin performs no real network I/O (D4).`,
+    title: `[twin-stub] ${url}`,
+  };
+}