@volter/twin-moonshot 0.1.0

package/dist/src/moonshot-connector.js

@@ -0,0 +1,416 @@
+// Moonshot CONNECTOR — the live-vendor pull/push path that gives the Moonshot twin the full
+// "git for SaaS" lifecycle (pull real state → mirror; push local writes → real).
+//
+// PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+// the real state system.
+//   REFRESH (real → twin): fetch the real Models / Files / Batches / Balance, map them to
+//                          observed resources, and fold them onto the root's log through the
+//                          kernel's `observeResources` (content-addressed entries, so re-pulling
+//                          identical state appends nothing).
+//   PERFORM (twin → real): the HEAD calls `performMoonshotAction` per deployable entry; the
+//                          vendor's minted id comes back as the `externalId` the kernel adopts.
+//
+// The vendor I/O is an INJECTED executor (B3 auth boundary): the kernel + this pack hold NO
+// Moonshot key and import NO SDK at runtime. Tests pass a fake executor; live runs pass
+// `liveMoonshotExecute(apiKey)`. Same code path either way — fully exercisable offline.
+import { assertBudgetGuardIntact, confirmAction, deployableEntries, observeResources, resolveSubjectId } from '@volter/world-core';
+import { MoonshotBudget, MoonshotBudgetError, moonshotCallWeight } from "./moonshot-budget.js";
+const SERVICE = 'moonshot';
+/**
+ * A live executor against the real Moonshot REST API (the user's own API key). Sends the required
+ * `Authorization: Bearer` header. Never imported by the pack's own serve path — only constructed
+ * by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.moonshot.ai` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `MoonshotBudgetError` instead of returning
+ * when the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `retry-after` / 429 / `x-ratelimit-remaining: 0` signal becomes a persisted cooldown that makes
+ * every later call fail fast WITHOUT touching Moonshot. There is deliberately no OPTION to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client.
+ * What that does NOT claim is immunity from a caller who WANTS one: a fresh `budgetOptions.path`
+ * per construction, or an injected clock, restores the allowance, because the same seam tests
+ * need cannot be denied to a determined caller in the same process. See `moonshot-budget.ts` and
+ * the kernel header for the limits of the guarantee.
+ */
+export function liveMoonshotExecute(apiKey, base = 'https://api.moonshot.ai', opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    // ONE expression decides which budget is used, so there is no second, weaker test that could
+    // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+    // must be an UNMODIFIED MoonshotBudget — a duck-typed stand-in, a SUBCLASS overriding
+    // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+    // would otherwise hand back a client with no ceiling. The default ledger is keyed by a hash of
+    // THIS key: Moonshot limits per account, so a cwd-scoped ledger would hand the same key a
+    // fresh allowance per checkout/worktree/CI leg.
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, MoonshotBudget, 'liveMoonshotExecute')
+        : new MoonshotBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, body) => {
+        // A path this pack never modelled is refused BEFORE the budget is even charged: an executor
+        // that will happily issue any URL is how a careless script reaches an unpriced endpoint.
+        if (!path.startsWith('/v1/') && !path.startsWith('/anthropic/v1/')) {
+            throw new Error(`moonshot: refusing to call an unmodeled path "${path}" — Moonshot serves /v1 and /anthropic/v1`);
+        }
+        const headers = { authorization: `Bearer ${apiKey}` };
+        const init = { method, headers };
+        if (method === 'POST') {
+            headers['content-type'] = 'application/json';
+            init.body = JSON.stringify(body ?? {});
+        }
+        const weight = moonshotCallWeight(method, path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(`${base}${path}`, init);
+        const resHeaders = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        const parsed = (await res.json());
+        // Settles the reservation and, on a back-off signal, arms the cooldown.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer Moonshot ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof MoonshotBudgetError) || !res.ok)
+                throw error;
+        }
+        return parsed;
+    };
+}
+function listOf(res) {
+    return Array.isArray(res.data) ? res.data : [];
+}
+/**
+ * A REFUSED pull is NOT an empty account. Moonshot answers failures with its documented
+ * `{ error: { message, type } }` envelope, so a status check alone is not enough — throw on the
+ * envelope rather than folding an empty list over real observed state.
+ */
+function throwIfError(res, ctx) {
+    if (res.error)
+        throw new Error(`moonshot ${ctx} failed: ${res.error.message ?? res.error.type ?? 'unknown error'}`);
+}
+// ── PULL ────────────────────────────────────────────────────────────────────
+/** Map a real-Moonshot model object → a twin sync resource. */
+export function mapModel(m) {
+    return {
+        type: 'model',
+        id: String(m.id),
+        fields: {
+            object: 'model',
+            created: m.created ?? null,
+            owned_by: m.owned_by ?? null,
+        },
+    };
+}
+/** Map a real-Moonshot File object → a twin sync resource. */
+export function mapFile(f) {
+    return {
+        type: 'file',
+        id: String(f.id),
+        fields: {
+            object: 'file',
+            bytes: f.bytes ?? 0,
+            created_at: f.created_at ?? null,
+            filename: f.filename ?? null,
+            purpose: f.purpose ?? null,
+            status: f.status ?? null,
+        },
+    };
+}
+/** Map a real-Moonshot Batch object → a twin sync resource. */
+export function mapBatch(b) {
+    const counts = (b.request_counts && typeof b.request_counts === 'object') ? b.request_counts : {};
+    return {
+        type: 'batch',
+        id: String(b.id),
+        fields: {
+            object: 'batch',
+            endpoint: b.endpoint ?? null,
+            input_file_id: b.input_file_id ?? null,
+            completion_window: b.completion_window ?? null,
+            status: b.status ?? null,
+            output_file_id: b.output_file_id ?? null,
+            created_at: b.created_at ?? null,
+            completed_at: b.completed_at ?? null,
+            request_counts: counts,
+        },
+    };
+}
+/** Map the real-Moonshot balance → the twin's 'balance' resource (id 'me'). */
+export function mapBalance(b) {
+    const d = (b.data && typeof b.data === 'object') ? b.data : {};
+    return {
+        type: 'balance',
+        id: 'me',
+        fields: {
+            available_balance: d.available_balance ?? null,
+            voucher_balance: d.voucher_balance ?? null,
+            cash_balance: d.cash_balance ?? null,
+        },
+    };
+}
+const COLLECTIONS = [
+    { path: '/v1/models', map: mapModel },
+    { path: '/v1/files', map: mapFile },
+    { path: '/v1/batches', map: mapBatch },
+];
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export async function pullMoonshotState(execute) {
+    const out = [];
+    for (const c of COLLECTIONS) {
+        const res = await execute('GET', c.path);
+        throwIfError(res, `pull ${c.path}`);
+        for (const item of listOf(res))
+            out.push(c.map(item));
+    }
+    // The balance is its own envelope ({code, data:{…}, scode, status}) — no `data` list.
+    const bal = await execute('GET', '/v1/users/me/balance');
+    throwIfError(bal, 'pull /v1/users/me/balance');
+    out.push(mapBalance(bal));
+    return out;
+}
+/**
+ * Pull from real Moonshot and fold into the twin (mirror seeding). Observation entries are
+ * content-addressed, so a re-pull of identical state appends nothing.
+ *
+ * `occurredAt` has NO pinned default on purpose: the kernel hashes an observed event over
+ * (occurredAt + post-state), so under a fixed poll time a vendor value that REVERTS across polls
+ * collides with its own earlier observation and the fold reports a phantom delta while the
+ * projection keeps the stale value (ADDING_A_TWIN.md §6). Callers pass a moving timestamp.
+ */
+export async function syncMoonshotFromReal(execute, opts) {
+    const resources = await pullMoonshotState(execute);
+    const result = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+    });
+    return { observed: result.observed, deltasAppended: result.appended };
+}
+// ── PUSH ────────────────────────────────────────────────────────────────────
+// The twin operations this connector knows how to push to real Moonshot. Anything not here must
+// FAIL LOUDLY rather than be silently dropped — pushing an unrecognized op risks hitting the
+// wrong endpoint or no-op'ing a real change.
+const PUSHABLE_VERBS = new Set(['create', 'cancel', 'delete']);
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+function assertPushable(op) {
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    if (!PUSHABLE_VERBS.has(verb)) {
+        throw new Error(`moonshot push: unsupported operation '${op}' — refusing to silently drop a local write`);
+    }
+    const why = UNPUSHABLE[op];
+    if (why)
+        throw new Error(`moonshot push: cannot push '${op}' — ${why}`);
+}
+/** Why this action cannot be pushed, or null if it can. Pure — no vendor call on its path. */
+export function unpushableReason(op) {
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    if (!PUSHABLE_VERBS.has(verb))
+        return `unsupported operation '${op}'`;
+    return UNPUSHABLE[op] ?? null;
+}
+// Map a subject type → its REST collection path.
+const COLLECTION_PATH = {
+    file: '/v1/files',
+    batch: '/v1/batches',
+};
+/**
+ * Pushes this connector must REFUSE rather than fake, keyed `"<type>.<verb>"`.
+ *
+ * `file.create` is the case: real Moonshot's `POST /v1/files` is multipart/form-data carrying
+ * the actual file body, while this executor sends JSON. Pushing `{purpose, filename}` as JSON
+ * would 400 at the vendor, and the twin stores no binary content to upload anyway. Refusing
+ * loudly is the honest answer; the gap is filed as `moonshot.connector.push_file_create`.
+ */
+const UNPUSHABLE = {
+    'file.create': "real Moonshot's POST /v1/files is multipart/form-data with the file body; this JSON executor cannot express it, and the twin stores no real bytes to send",
+};
+/**
+ * The twin's LOCALLY-MINTED id namespace (`file_twin_1`, `batch_twin_3` — see `nextId` in
+ * moonshot-twin.ts). A subject still bearing one has no counterpart in the real account.
+ */
+const LOCAL_ID = /_twin_\d+$/;
+/**
+ * Resolve the id the VENDOR knows this subject by.
+ *
+ * The kernel records the vendor's minted id at landing time (`vendorSubjectId` → the landed copy
+ * carries the vendor's id, `aliasOf` the local one), and `resolveSubjectId` answers it — so a
+ * later delete/cancel addresses the vendor by THAT. A locally-minted subject with no recorded
+ * alias is refused rather than guessed at — addressing the real account by the twin's own mint
+ * would DELETE or CANCEL a resource the vendor never had.
+ */
+export function externalIdFor(subjectType, subjectId, root) {
+    if (!LOCAL_ID.test(subjectId))
+        return subjectId; // already a vendor id (e.g. observed by a pull)
+    const resolved = resolveSubjectId(SERVICE, subjectType, subjectId, root);
+    return resolved !== subjectId ? resolved : null;
+}
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real Moonshot REST
+ * surface:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export function moonshotRequestForAction(action, 
+/** The id the VENDOR knows this subject by. Required for anything but a create — see
+ *  `externalIdFor`; passing the twin's own mint would address a resource the vendor never had. */
+externalId) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    const collection = COLLECTION_PATH[action.subject.type];
+    if (!collection)
+        throw new Error(`moonshot push: no REST collection for subject type '${action.subject.type}'`);
+    if (verb === 'create')
+        return { method: 'POST', path: collection };
+    const vendorId = externalId ?? action.subject.id;
+    if (LOCAL_ID.test(vendorId)) {
+        throw new Error(`moonshot push: refusing to address the real account by the twin's own id '${vendorId}' — no vendor id was ever recorded for this subject`);
+    }
+    if (verb === 'cancel')
+        return { method: 'POST', path: `${collection}/${vendorId}/cancel` };
+    if (verb === 'delete')
+        return { method: 'DELETE', path: `${collection}/${vendorId}` };
+    // assertPushable rejects anything else, so this is only reached for the pushable verbs above.
+    return { method: 'POST', path: collection };
+}
+/**
+ * Push ONE pending action to REAL Moonshot via the injected executor. Returns the real external
+ * id (the object id from the response; for a create that's a freshly minted id, otherwise it
+ * echoes the subject). WRITES TO THE REAL ACCOUNT.
+ */
+export async function pushMoonshotAction(execute, action, opts = {}) {
+    assertPushable(action.operation ?? `${action.subject.type}.update`);
+    const { method, path } = moonshotRequestForAction(action, opts.externalId);
+    const verb = (action.operation ?? '').includes('.') ? action.operation.slice(action.operation.indexOf('.') + 1) : '';
+    const payload = verb === 'create' ? createPayload(action) : undefined;
+    const res = await execute(method, path, payload);
+    throwIfError(res, `push ${action.subject.type}`);
+    const id = res.id;
+    return { externalId: typeof id === 'string' && id ? id : action.subject.id };
+}
+function createPayload(action) {
+    const f = (action.fields ?? {});
+    switch (action.subject.type) {
+        case 'batch':
+            return { input_file_id: f.input_file_id, endpoint: f.endpoint, completion_window: f.completion_window, ...(f.metadata ? { metadata: f.metadata } : {}) };
+        default:
+            return {};
+    }
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's: the same Moonshot call, carried by the head. The
+ *  credential never enters this file — the kernel's executor applies it to the authorization
+ *  header before this sees the request. */
+export function moonshotExecuteOver(execute) {
+    return async (method, path, body) => {
+        const res = await execute({
+            method, path,
+            headers: { accept: 'application/json', authorization: 'Bearer twin', ...(method === 'POST' ? { 'content-type': 'application/json' } : {}) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (res.body === '')
+            return {};
+        try {
+            return JSON.parse(res.body);
+        }
+        catch {
+            return { error: { type: 'server_error', message: res.body.slice(0, 200) } };
+        }
+    };
+}
+/** The refresh adapter: pull the account's models / files / batches / balance through the executor. */
+export async function syncMoonshotFromRemote(execute, opts = {}) {
+    return syncMoonshotFromReal(moonshotExecuteOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? new Date().toISOString(),
+    });
+}
+/**
+ * The PERFORM adapter: one deployable entry crosses to Moonshot, or settles with the reason it
+ * never could. `file.create` is unpushable-BY-DESIGN (the real endpoint is multipart with the
+ * file body; this executor sends JSON) — it settles without crossing rather than throwing, so it
+ * cannot wedge every later batch action behind it. A locally-minted subject with no vendor alias
+ * THROWS (the head records the failure): addressing the real account by the twin's own mint would
+ * delete or cancel a resource the vendor never had.
+ */
+export async function performMoonshotAction(execute, action, ctx) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const why = unpushableReason(op);
+    if (why)
+        return { externalId: action.subject.id, data: { performed: false, reason: why } };
+    const vendorId = ctx.resolve(action.subject.type, action.subject.id);
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    if (verb !== 'create' && LOCAL_ID.test(vendorId)) {
+        throw new Error(`moonshot push: refusing to address the real account by the twin's own id '${vendorId}' — no vendor id was ever recorded for this subject`);
+    }
+    const { externalId } = await pushMoonshotAction(moonshotExecuteOver(execute), { operation: op, subject: action.subject, fields: action.fields ?? {} }, ...(verb !== 'create' ? [{ externalId: vendorId }] : []));
+    return { externalId };
+}
+/**
+ * Push the twin's PENDING local actions to real Moonshot and CONFIRM each. Idempotency: a
+ * confirmed action is no longer deployable, so a re-push enacts NOTHING.
+ *
+ * Every action this pack records is SINGLE-RESOURCE (one file, one batch), so confirming with
+ * `fields` alone is correct — see ADDING_A_TWIN.md §5 on compound actions, which this pack has
+ * none of. If a compound write is ever added here, it must ride its extra resources in
+ * `additionalObservations` or the push will silently delete them.
+ */
+export async function pushPendingMoonshotActions(execute, opts) {
+    const confirmed = [];
+    const externalIds = {};
+    const refused = [];
+    for (const action of deployableEntries(SERVICE, opts.root)) {
+        const op = action.operation ?? `${action.subject.type}.update`;
+        // An action this connector cannot faithfully push is SKIPPED AND REPORTED, never confirmed
+        // and never silently dropped: it stays deployable, and it is named in `refused` so a caller
+        // can see it. Throwing instead meant ONE unpushable action — e.g. the local file create,
+        // whose real endpoint is multipart — aborted the whole sweep and took every unrelated
+        // pending write down with it.
+        const why = unpushableReason(op);
+        if (why) {
+            refused.push({ actionId: action.id, operation: op, reason: why });
+            continue;
+        }
+        const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+        // Anything but a create must address the vendor by the id the vendor issued. A locally-minted
+        // subject with none recorded is REFUSED, never guessed.
+        let external;
+        if (verb !== 'create') {
+            const resolved = externalIdFor(action.subject.type, action.subject.id, opts.root);
+            if (resolved === null) {
+                refused.push({ actionId: action.id, operation: op, reason: `no vendor id recorded for ${action.subject.type} '${action.subject.id}' — it was never pushed to the real account, so there is nothing there to ${verb}` });
+                continue;
+            }
+            external = resolved;
+        }
+        const { externalId } = await pushMoonshotAction(execute, action, ...(external !== undefined ? [{ externalId: external }] : []));
+        // The kernel records the vendor's id as the subject ALIAS (the landed copy carries the
+        // vendor's id, aliasOf the local one), so a later delete/cancel resolves through
+        // `resolveSubjectId` — no `_external_id` field to read back.
+        confirmAction({
+            service: SERVICE, actionId: action.id, subject: action.subject,
+            fields: action.fields ?? {},
+            occurredAt: opts.occurredAt, vendorSubjectId: externalId, receipt: { status: 'deployed' },
+            ...(opts.root !== undefined ? { root: opts.root } : {}),
+        });
+        confirmed.push(action.id);
+        externalIds[action.id] = externalId;
+    }
+    return { pushed: confirmed.length, confirmed, externalIds, refused };
+}
+// ── FULL bi-directional sync ─────────────────────────────────────────────────
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every deployable local entry to
+ * real Moonshot and confirm it, then (2) PULL all modeled collections back and fold them onto
+ * the root's log. Pushing first means the pull observes the twin's own writes as confirmed
+ * external state (no double-count). Re-running with nothing deployable and identical real state
+ * is a no-op.
+ */
+export async function fullSyncMoonshot(execute, opts) {
+    const push = await pushPendingMoonshotActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+    const resources = await pullMoonshotState(execute);
+    const pull = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+    });
+    return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.appended, collections: COLLECTIONS.length + 1, refused: push.refused };
+}

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

@@ -0,0 +1,36 @@
+export type MoonshotModel = {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+    /** The OpenAPI request schema's enum for this id — which endpoints accept it. */
+    supports: {
+        /** POST /v1/chat/completions (all four). */
+        chat: boolean;
+        /** POST /v1/responses — kimi-k3 only ("This endpoint currently supports kimi-k3"). */
+        responses: boolean;
+        /** POST /anthropic/v1/messages — kimi-k3 only (MessagesRequest['model'] enum). */
+        messages: boolean;
+        /** POST /v1/batches — only kimi-k2.7-code(-highspeed) and kimi-k2.6, NOT kimi-k3. */
+        batch: boolean;
+        /** Vision (image_url parts in chat messages). kimi-k3 and kimi-k2.6 are vision models. */
+        vision: boolean;
+    };
+    context_length: number;
+    /** Max output tokens. kimi-k3: default 131072, up to 1048576 (ChatRequestCommon
+     *  max_completion_tokens description). The k2.6/k2.7-code models share the 256k window. */
+    max_completion_tokens: number;
+};
+export declare const MOONSHOT_MODELS: MoonshotModel[];
+/** Resolve a model by id, or undefined if the twin doesn't model it. */
+export declare function findModel(id: string): MoonshotModel | undefined;
+/** The ids that accept a batch job's chat/completions requests. */
+export declare const BATCH_MODELS: Set<string>;
+/** kimi-k3's `reasoning_effort` — a CLOSED documented set (KimiK3ChatRequest). */
+export declare const REASONING_EFFORTS: readonly ["low", "high", "max"];
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+/** kimi-k2.6 `thinking.type` — enabled and disabled are BOTH supported. */
+export declare const K26_THINKING_TYPES: readonly ["enabled", "disabled"];
+/** kimi-k2.7-code `thinking.type` — ONLY 'enabled'; 'disabled' returns an error (OpenAPI:
+ *  "Unlike kimi-k2.6, `\"disabled\"` is NOT supported — passing it returns an error."). */
+export declare const K27_THINKING_TYPES: readonly ["enabled"];

package/dist/src/moonshot-models.js

@@ -0,0 +1,37 @@
+const K3_CTX = 1_048_576;
+const K2_CTX = 262_144;
+export const MOONSHOT_MODELS = [
+    {
+        id: 'kimi-k3', object: 'model', created: 1_760_000_000, owned_by: 'moonshot',
+        supports: { chat: true, responses: true, messages: true, batch: false, vision: true },
+        context_length: K3_CTX, max_completion_tokens: 1_048_576,
+    },
+    {
+        id: 'kimi-k2.7-code', object: 'model', created: 1_760_000_001, owned_by: 'moonshot',
+        supports: { chat: true, responses: false, messages: false, batch: true, vision: false },
+        context_length: K2_CTX, max_completion_tokens: K2_CTX,
+    },
+    {
+        id: 'kimi-k2.7-code-highspeed', object: 'model', created: 1_760_000_002, owned_by: 'moonshot',
+        supports: { chat: true, responses: false, messages: false, batch: true, vision: false },
+        context_length: K2_CTX, max_completion_tokens: K2_CTX,
+    },
+    {
+        id: 'kimi-k2.6', object: 'model', created: 1_760_000_003, owned_by: 'moonshot',
+        supports: { chat: true, responses: false, messages: false, batch: true, vision: true },
+        context_length: K2_CTX, max_completion_tokens: K2_CTX,
+    },
+];
+/** Resolve a model by id, or undefined if the twin doesn't model it. */
+export function findModel(id) {
+    return MOONSHOT_MODELS.find((m) => m.id === id);
+}
+/** The ids that accept a batch job's chat/completions requests. */
+export const BATCH_MODELS = new Set(MOONSHOT_MODELS.filter((m) => m.supports.batch).map((m) => m.id));
+/** kimi-k3's `reasoning_effort` — a CLOSED documented set (KimiK3ChatRequest). */
+export const REASONING_EFFORTS = ['low', 'high', 'max'];
+/** kimi-k2.6 `thinking.type` — enabled and disabled are BOTH supported. */
+export const K26_THINKING_TYPES = ['enabled', 'disabled'];
+/** kimi-k2.7-code `thinking.type` — ONLY 'enabled'; 'disabled' returns an error (OpenAPI:
+ *  "Unlike kimi-k2.6, `\"disabled\"` is NOT supported — passing it returns an error."). */
+export const K27_THINKING_TYPES = ['enabled'];

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

@@ -0,0 +1,54 @@
+import { type PackScenarioAdapter, type ScenarioDocument, ScenarioEngine } from '@volter/world-core';
+import type { MoonshotMessageParam, MoonshotToolCall } from './moonshot-types.js';
+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';
+};
+export declare const moonshotScenarioAdapter: PackScenarioAdapter<MoonshotScenarioRequest>;
+/** Load + STRICTLY validate a scenario document. A malformed file throws at load with what is
+ *  wrong — never a silent ignore-and-stub (a mis-typed rule falling back is a fake success). */
+export declare function loadMoonshotScenarioDocument(path: string): ScenarioDocument;
+export declare function createMoonshotScenarioEngine(document?: ScenarioDocument): MoonshotScenarioEngine;
+/**
+ * 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 declare function realizeMoonshotRespond(respond: MoonshotScenarioRespond): ScriptedResult;