@volter/twin-moonshot 0.1.0

package/dist/src/moonshot-scenario.js

@@ -0,0 +1,175 @@
+// 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, ScenarioError, ScenarioEngine } from '@volter/world-core';
+import { contentToText, fnv1a, lastUserText } from "./moonshot-stub.js";
+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) => typeof cond === 'string' && cond.length > 0;
+function lastToolResultNames(messages) {
+    const names = new Set();
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string')
+        return names;
+    for (const m of messages) {
+        const am = m;
+        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) {
+    if (!Array.isArray(tools))
+        return [];
+    return tools.map((t) => typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null).filter((n) => n !== null);
+}
+export const moonshotScenarioAdapter = {
+    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) => ({
+        model: req.model,
+        lastUserText: lastUserText(req.messages).slice(0, 300),
+        tools: toolNames(req.tools),
+        lastMessageIsToolResult: req.messages[req.messages.length - 1]?.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).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]?.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']) {
+            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;
+        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;
+            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;
+                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) {
+    let parsed;
+    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) {
+    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) {
+    const toolCalls = [];
+    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/dist/src/moonshot-server.d.ts

@@ -0,0 +1,13 @@
+/** Options every Moonshot-twin HTTP surface needs, independent of who owns the socket. */
+export interface MoonshotTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}
+export declare function createMoonshotTwinFetch(options: MoonshotTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createMoonshotTwinServer(options?: MoonshotTwinFetchOptions & {
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/moonshot-server.js

@@ -0,0 +1,202 @@
+// 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, } from "./moonshot-twin.js";
+import { createMoonshotScenarioEngine, loadMoonshotScenarioDocument } from "./moonshot-scenario.js";
+function wantsStream(body) {
+    if (!body)
+        return false;
+    try {
+        return JSON.parse(body)?.stream === true;
+    }
+    catch {
+        return false;
+    }
+}
+function encodeSse(event) {
+    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) {
+    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) {
+    try {
+        const form = await request.formData();
+        const out = {};
+        // 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 '{}';
+    }
+}
+export function createMoonshotTwinFetch(options) {
+    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 = scenarioPath ? createMoonshotScenarioEngine(loadMoonshotScenarioDocument(scenarioPath)) : undefined;
+    return async function moonshotTwinFetch(request) {
+        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,
+            }));
+        }
+        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 = {};
+        // `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 = [];
+            const sink = (e) => events.push(e);
+            const namedSink = (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 = { '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 && e.event !== undefined ? encodeNamedSse(e) : encodeSse(e))).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 = {}) {
+    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/dist/src/moonshot-stub.d.ts

@@ -0,0 +1,70 @@
+import type { MoonshotMessageParam, MoonshotToolCall } from './moonshot-types.js';
+/** 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 declare function estimateTokens(text: string): number;
+/** 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 declare function contentToText(content: unknown): string;
+/** Deterministic prompt-token count for a set of chat messages. */
+export declare function countPromptTokens(messages: MoonshotMessageParam[]): number;
+/** The last user turn's text — the thing the stub echoes (deterministic, clearly labeled). */
+export declare function lastUserText(messages: MoonshotMessageParam[]): string;
+/**
+ * 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 declare function stubAssistantText(messages: MoonshotMessageParam[], model: string): string;
+/**
+ * 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 declare function stubReasoningContent(messages: MoonshotMessageParam[], model: string): string;
+/** 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 declare function stubSignature(messages: MoonshotMessageParam[], model: string): string;
+/**
+ * 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 declare const CACHE_HIT_THRESHOLD = 256;
+export declare function stubCachedTokens(promptTokens: number): number;
+export declare function buildChatUsage(promptTokens: number, completionTokens: number, promptCacheKey?: string): {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cached_tokens: number;
+};
+/** 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 declare function stubToolArguments(tool: unknown): string;
+/**
+ * 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 declare function stubToolCall(tools: unknown, seq: number, forcedName?: string): MoonshotToolCall | null;
+/** Build a deterministic JSON-object stub for `response_format` json_object / json_schema. */
+export declare function stubJsonObject(messages: MoonshotMessageParam[], model: string, jsonSchema?: unknown): string;
+/** A small deterministic 32-bit hash (FNV-1a) of a string. */
+export declare function fnv1a(text: string): number;
+/** A deterministic id suffix from a request (so ids are stable + assertable). */
+export declare function stableSuffix(...parts: unknown[]): string;
+/**
+ * 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 declare function stubSearchResults(textQuery: string, limit: number, pro: boolean, includeContent?: boolean): Array<Record<string, unknown>>;
+/** A deterministic stub markdown page for POST /v1/tools/fetch. */
+export declare function stubFetchedMarkdown(url: string): {
+    url: string;
+    markdown: string;
+    title: string;
+};