@volter/twin-moonshot 0.1.0

package/dist/src/moonshot-stub.js

@@ -0,0 +1,222 @@
+// 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.
+/** 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) {
+    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) {
+    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.type === 'text') {
+            return String(part.text ?? '');
+        }
+        return JSON.stringify(part);
+    })
+        .join('\n');
+}
+/** Deterministic prompt-token count for a set of chat messages. */
+export function countPromptTokens(messages) {
+    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) {
+    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, model) {
+    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, model) {
+    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, model) {
+    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) {
+    return promptTokens > CACHE_HIT_THRESHOLD ? Math.floor(promptTokens * 0.25) : 0;
+}
+export function buildChatUsage(promptTokens, completionTokens, promptCacheKey) {
+    // 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) {
+    const o = t;
+    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) {
+    const d = def;
+    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) {
+    const o = tool;
+    const schema = (o?.function?.parameters ?? o?.parameters ?? o?.input_schema);
+    const props = schema && typeof schema === 'object' ? schema.properties : undefined;
+    if (!props || typeof props !== 'object')
+        return '{}';
+    const out = {};
+    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, seq, forcedName) {
+    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, model, jsonSchema) {
+    const schema = jsonSchema;
+    const props = schema?.schema?.properties ?? schema?.properties;
+    if (props && typeof props === 'object') {
+        const out = {};
+        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) {
+    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) {
+    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, limit, pro, includeContent = false) {
+    const out = [];
+    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) {
+    return {
+        url,
+        markdown: `[twin-stub] deterministic fetch of ${url} — the twin performs no real network I/O (D4).`,
+        title: `[twin-stub] ${url}`,
+    };
+}

package/dist/src/moonshot-twin.d.ts

@@ -0,0 +1,144 @@
+import { type ScenarioDecision } from '@volter/world-core';
+import { type MoonshotScenarioEngine } from './moonshot-scenario.js';
+import type { MessagesSseEvent, MoonshotChatCompletion, MoonshotMessageParam, MoonshotMessagesResponse, MoonshotResponsesResponse, SseSink } from './moonshot-types.js';
+/** The base path Moonshot's OpenAI-compatible surface hangs off. The Anthropic-compatible
+ *  surface hangs off MESSAGES_PREFIX; both are served by the same host. */
+export declare const MOONSHOT_API_PREFIX = "/v1";
+export declare const MESSAGES_PREFIX = "/anthropic/v1";
+export type MoonshotRequest = {
+    /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts the three
+     *  inference endpoints. */
+    scenarioEngine?: MoonshotScenarioEngine;
+    method: string;
+    path: string;
+    body?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** The credential the caller presents (the bearer `Authorization` header). When a request
+     *  carries an auth SURFACE (this field set, or `headers` present), the twin holds it to the
+     *  real vendor rule: a credential is required → 401 on missing/invalid. In-process trusted
+     *  calls (capability verify, connector) omit BOTH and are not auth-gated. */
+    apiKey?: string;
+    /** Lower-cased request headers the HTTP server passes through so the handler can model auth
+     *  (401), the rate-limit trigger (429), and the signature headers the /v1/signatures/verify
+     *  contract references. */
+    headers?: Record<string, string>;
+    /** When set on a streaming POST, chunks/events are written here (no sockets). */
+    sseSink?: SseSink;
+    /** When set on a streaming /anthropic/v1/messages POST, Anthropic-grammar events are written
+     *  here (event name + data; no sockets). */
+    messagesSseSink?: MessagesSseSink;
+};
+/** The handler response. `headers` (when present) are response headers the HTTP server should
+ *  set — e.g. `retry-after` + Moonshot's `x-ratelimit-*` family on a modeled 429. */
+export type MoonshotResponseEnvelope = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+type ResponseFormat = {
+    kind: 'text';
+} | {
+    kind: 'json_object';
+} | {
+    kind: 'json_schema';
+    schema: unknown;
+};
+type Thinking = {
+    type: 'enabled' | 'disabled';
+    keep?: string | null;
+};
+type ChatArgs = {
+    model: string;
+    messages: MoonshotMessageParam[];
+    tools?: unknown[];
+    n: number;
+    maxTokens?: number;
+    stop?: string[];
+    stream: boolean;
+    streamOptions?: {
+        includeUsage: boolean;
+    };
+    toolChoice?: ToolChoice;
+    responseFormat: ResponseFormat;
+    logprobs: boolean;
+    topLogprobs?: number;
+    /** kimi-k3 only: 'low' | 'high' | 'max' (default 'max'). */
+    reasoningEffort?: string;
+    /** kimi-k2.6 / kimi-k2.7-code: the `thinking` object. */
+    thinking?: Thinking;
+    promptCacheKey?: string;
+};
+export declare function buildChatCompletion(args: ChatArgs, occurredAt?: string, decision?: ScenarioDecision): MoonshotChatCompletion | MoonshotResponseEnvelope;
+/**
+ * Emit the vendor-faithful Moonshot streaming sequence into the injected sink (NO sockets, NO
+ * setTimeout). Moonshot's order: a first chunk with `delta:{role:'assistant'}`, then
+ * `delta:{content}` / `delta:{reasoning_content}` / tool_calls deltas, then a chunk carrying
+ * `finish_reason`, then — because Moonshot's ChatCompletionChunk.usage is "Object in the final
+ * chunk with usage, null in ordinary chunks" (the OpenAPI's own wording, the first-party
+ * denominator; the prose chat doc mentions the chunk under stream_options.include_usage, so the
+ * two sources disagree and the OpenAPI governs) — a FINAL chunk whose `choices:[]` and `usage`
+ * hold the whole usage object, then `data: [DONE]`. `stream_options` is ACCEPTED (validated as
+ * an object) but the tail is not gated on it. Deterministic + synchronous.
+ */
+export declare function streamChat(args: ChatArgs, sink: SseSink, occurredAt?: string, decision?: ScenarioDecision): MoonshotChatCompletion | MoonshotResponseEnvelope;
+/** The deterministic signature the twin issues on inference responses and verifies here. */
+export declare function messagesSignature(nonce: string, timestamp: number, model: string): string;
+type MessagesArgs = {
+    model: string;
+    messages: Array<{
+        role: 'user' | 'assistant';
+        content: string | Array<Record<string, unknown>>;
+    }>;
+    maxTokens: number;
+    system?: string;
+    stopSequences?: string[];
+    stream: boolean;
+    /** Anthropic's MessagesTool shape: { name, input_schema } (nested inside type:'custom'). */
+    tools?: Array<Record<string, unknown>>;
+    /** Anthropic's ToolChoice: type 'tool' names one tool (`name` REQUIRED, validated against
+     *  `tools` — the sibling pack's rule). */
+    toolChoice?: {
+        type: 'auto' | 'any' | 'tool' | 'none';
+        name?: string;
+    };
+    outputEffort?: string;
+};
+export declare function buildMessagesResponse(args: MessagesArgs, occurredAt?: string, decision?: ScenarioDecision): MoonshotMessagesResponse | MoonshotResponseEnvelope;
+/**
+ * Emit the Anthropic-compatible streaming grammar into the injected sink: message_start →
+ * ping → content_block_start(thinking) → thinking_delta → signature_delta → content_block_stop →
+ * content_block_start(text) → text_delta → content_block_stop → message_delta(stop_reason) →
+ * message_stop. No [DONE] sentinel — the stream ends after message_stop.
+ *
+ * message_start carries the EMPTY message (content: [], stop_reason: null, output_tokens small)
+ * and the blocks stream in one at a time — the real grammar (and the sibling pack's frames). A
+ * message_start carrying the COMPLETE final message made the SDK's own accumulator double every
+ * block: it pushes one block per content_block_start ON TOP of what message_start already held
+ * (the round-three BLOCKER).
+ */
+export declare function streamMessages(args: MessagesArgs, sink: MessagesSseSink, occurredAt?: string, decision?: ScenarioDecision): MoonshotMessagesResponse | MoonshotResponseEnvelope;
+type ResponsesArgs = {
+    model: string;
+    input: string | Array<Record<string, unknown>>;
+    instructions?: string;
+    maxOutputTokens?: number;
+    reasoningEffort?: string;
+    stream: boolean;
+};
+export declare function buildResponsesResponse(args: ResponsesArgs, occurredAt?: string, decision?: ScenarioDecision): MoonshotResponsesResponse | MoonshotResponseEnvelope;
+/**
+ * Emit the Responses SSE grammar into the injected sink: response.created →
+ * response.in_progress → output_item.added/done per item → response.completed. Each frame
+ * carries `event: <type>` and a monotonically increasing `sequence_number` from 0.
+ */
+export declare function streamResponses(args: ResponsesArgs, sink: MessagesSseSink, occurredAt?: string, decision?: ScenarioDecision): MoonshotResponsesResponse | MoonshotResponseEnvelope;
+export declare function handleMoonshotTwinRequest(req: MoonshotRequest): Promise<MoonshotResponseEnvelope>;
+/** A sink the Messages/Responses streaming paths write events into. `event` is the SSE event
+ *  name (Anthropic/Responses grammar); `data` the JSON payload; `done: true` ends the stream. */
+export type MessagesSseSink = (event: MessagesSseEvent) => void;
+export {};