@instruktlabs/kiln 1.0.0 → 1.2.0

package/lib/asset-widget-uri.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The MCP App resource the asset viewer is served under.
+ *
+ * Shared by the tool registry, which stamps it into `kiln_present`'s `_meta`,
+ * and by the protocol core, which answers `resources/read` for it before the
+ * engine has loaded. Neither of those may import the other, so the literal
+ * lives here on its own.
+ */
+export declare const KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v5.html";

package/lib/asset-widget-uri.js

@@ -0,0 +1,9 @@
+/**
+ * The MCP App resource the asset viewer is served under.
+ *
+ * Shared by the tool registry, which stamps it into `kiln_present`'s `_meta`,
+ * and by the protocol core, which answers `resources/read` for it before the
+ * engine has loaded. Neither of those may import the other, so the literal
+ * lives here on its own.
+ */
+export const KILN_ASSET_WIDGET_URI = 'ui://kiln/asset-v5.html';

package/lib/cli-render-mode.js

@@ -39,12 +39,19 @@ export function makeLazyRenderPort(start, token, sourceFingerprint, initialUrl)
         catch (error) {
             if (execution?.signal?.aborted || error.name === 'TimeoutError')
                 throw error;
-            if ((await readRenderServiceHealth(url, {
+            // A different capture may already have replaced this failed connection.
+            // Its healthy socket must not make us rethrow a late error from the old one.
+            if (resolving !== pending)
+                return (await resolve()).port(req, execution);
+            const health = await readRenderServiceHealth(url, {
                 token,
                 signal: execution?.signal,
-            })).kind !== 'absent')
-                throw error;
+            });
             execution?.signal?.throwIfAborted();
+            if (resolving !== pending)
+                return (await resolve()).port(req, execution);
+            if (health.kind !== 'absent')
+                throw error;
             // Concurrent captures can all observe the old socket disappearing. Only
             // the first retires its connection; the others share the replacement.
             if (resolving === pending)

package/lib/discovery/index.d.ts

@@ -6,4 +6,4 @@ export type { DiscoveryRequest } from "./query-schema.js";
 export { createDiscoveryService } from "./service.js";
 export type { DiscoveryIndex, DiscoveryResponse } from "./service.js";
 /** Share one immutable catalog/index per process; host capabilities stay live. */
-export declare function createDiscovery(capabilities?: () => Promise<unknown>, notes?: () => Promise<string[]>): (input: unknown) => Promise<import("./service.js").DiscoveryResponse>;
+export declare function createDiscovery(capabilities?: () => Promise<unknown>, notes?: () => Promise<string[]>, capabilitiesCall?: string): (input: unknown) => Promise<import("./service.js").DiscoveryResponse>;

package/lib/discovery/index.js

@@ -11,10 +11,10 @@ let snapshot;
 export function createDiscovery(capabilities = async () => ({
     host: 'No host capability provider was supplied.',
     discovery: { mode: 'lexical', offline: true, requiresModel: false },
-}), notes = async () => []) {
+}), notes = async () => [], capabilitiesCall = 'capabilities:true') {
     snapshot ??= (() => {
         const entries = listDiscoveryEntries();
         return { entries, index: createLexicalDiscoveryIndex(entries) };
     })();
-    return createDiscoveryService(snapshot.entries, snapshot.index, capabilities, REMOVED_AUTHORING_HELPERS, notes);
+    return createDiscoveryService(snapshot.entries, snapshot.index, capabilities, REMOVED_AUTHORING_HELPERS, notes, capabilitiesCall);
 }

package/lib/discovery/portable.d.ts

@@ -0,0 +1,9 @@
+/** Search a host-supplied catalog without importing Node's catalog construction. */
+export { createDiscoveryService } from "./service.js";
+export type { DiscoveryIndex, DiscoveryResponse, DiscoverySearchEvidence } from "./service.js";
+export { createLexicalDiscoveryIndex, DISCOVERY_INDEX_VERSION } from "./lexical-index.js";
+export { discoveryEntrySchema, parseCatalog } from "./catalog-schema.js";
+export type { DiscoveryEntry, OperationContract } from "./catalog-schema.js";
+export { discoveryInputSchema, parseDiscoveryRequest } from "./query-schema.js";
+export type { DiscoveryRequest } from "./query-schema.js";
+export { REMOVED_AUTHORING_HELPERS } from "../geometry-catalog.js";

package/lib/discovery/portable.js

@@ -0,0 +1,6 @@
+/** Search a host-supplied catalog without importing Node's catalog construction. */
+export { createDiscoveryService } from "./service.js";
+export { createLexicalDiscoveryIndex, DISCOVERY_INDEX_VERSION } from "./lexical-index.js";
+export { discoveryEntrySchema, parseCatalog } from "./catalog-schema.js";
+export { discoveryInputSchema, parseDiscoveryRequest } from "./query-schema.js";
+export { REMOVED_AUTHORING_HELPERS } from "../geometry-catalog.js";

package/lib/discovery/service.d.ts

@@ -53,5 +53,7 @@ export interface DiscoveryResponse {
 }
 export declare function createDiscoveryService(source: unknown, index: DiscoveryIndex, capabilities: () => Promise<unknown>, retirements?: Readonly<Record<string, string>>, 
 /** Host notes for the overview, such as the project an omitted `projectId` selects. */
-notes?: () => Promise<string[]>): (input: unknown) => Promise<DiscoveryResponse>;
+notes?: () => Promise<string[]>, 
+/** Host-selected capability entrypoint, never a model-provided instruction. */
+capabilitiesCall?: string): (input: unknown) => Promise<DiscoveryResponse>;
 export {};

package/lib/discovery/service.js

@@ -7,7 +7,9 @@ const DETAIL_RESULT_BUDGET = 15_000;
 const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 export function createDiscoveryService(source, index, capabilities, retirements = {}, 
 /** Host notes for the overview, such as the project an omitted `projectId` selects. */
-notes = async () => []) {
+notes = async () => [], 
+/** Host-selected capability entrypoint, never a model-provided instruction. */
+capabilitiesCall = 'capabilities:true') {
     const entries = parseCatalog(source);
     const byId = new Map(entries.map((entry) => [entry.id, entry]));
     const byName = new Map(entries.filter((entry) => entry.kind !== 'recipe').map((entry) => [entry.name, entry]));
@@ -34,7 +36,7 @@ notes = async () => []) {
             'Parts auto-add to opts.parent; do not wrap createPart in parent.add. Part rotation uses degrees.',
             'Custom THREE.BufferGeometry and ordinary JavaScript functions remain available. Recipes offer guidance and never restrict modeling.',
             'Send source once and reuse programRef for reads, edits, inspection and rendering. Review geometry, materials and destination constraints separately.',
-            'Search for the operation you need in ordinary language, then fetch exact contracts with ids. Use capabilities:true for the current host.',
+            `Search for the operation you need in ordinary language, then fetch exact contracts with ids. Use ${capabilitiesCall} for the current host.`,
         ],
     };
     const error = (mode, code, message) => ({

package/lib/engine-identity.d.ts

@@ -26,7 +26,7 @@
  * `src/__tests__/package-contents.test.ts` fails if it disagrees with the manifest
  * or with any plugin manifest, which is what keeps the literal honest.
  */
-export declare const ENGINE_VERSION = "1.0.0";
+export declare const ENGINE_VERSION = "1.2.0";
 /**
  * Where this engine was loaded from, as a `file://` URL of the package root.
  *

package/lib/engine-identity.js

@@ -26,7 +26,7 @@
  * `src/__tests__/package-contents.test.ts` fails if it disagrees with the manifest
  * or with any plugin manifest, which is what keeps the literal honest.
  */
-export const ENGINE_VERSION = '1.0.0';
+export const ENGINE_VERSION = '1.2.0';
 /**
  * Where this engine was loaded from, as a `file://` URL of the package root.
  *

package/lib/evaluator/isolation.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readlinkSync } from 'node:fs';
 import { posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isolatedWorkerUrls } from "./worker-urls.js";
@@ -9,6 +9,7 @@ const DEFAULT_BWRAP_PATH = '/usr/local/bin/bwrap';
 const DEFAULT_SETPRIV_PATH = '/usr/bin/setpriv';
 const DEFAULT_PRLIMIT_PATH = '/usr/bin/prlimit';
 const DEFAULT_NODE_PATH = '/usr/local/bin/node';
+const ENV_PATH = '/usr/bin/env';
 const READINESS_VERSION = 'kiln.evaluator.isolation-readiness.v1';
 const TRANSPORT_VERSION = 'kiln.evaluator.isolation-transport.v1';
 const TRANSPORT_STDOUT_MARKER = 'kiln-evaluator-transport-boot-v1\n';
@@ -99,7 +100,7 @@ function isolatedEvaluatorLaunchWithLoader(workerPath, host = {}, loader = 'tsx'
     const setprivPath = requiredAbsolutePath(host.setprivPath ?? DEFAULT_SETPRIV_PATH);
     const prlimitPath = requiredAbsolutePath(host.prlimitPath ?? DEFAULT_PRLIMIT_PATH);
     const nodePath = requiredAbsolutePath(host.nodePath ?? DEFAULT_NODE_PATH);
-    for (const executable of [bwrapPath, setprivPath, prlimitPath, nodePath]) {
+    for (const executable of [bwrapPath, setprivPath, prlimitPath, nodePath, ENV_PATH]) {
         if (!pathExists(executable))
             isolationUnavailable();
     }
@@ -136,11 +137,19 @@ function isolatedEvaluatorLaunchWithLoader(workerPath, host = {}, loader = 'tsx'
     for (const mount of runtimeMounts(runtimeRoot, pathExists)) {
         bwrapArgs.push('--ro-bind', mount, mount);
     }
-    const nodeArgs = [nodePath, '--max-old-space-size=512', '--disable-proto=throw'];
+    // Remove the legacy mutation accessor. Throw mode breaks the Khronos
+    // validator's feature detection before any GLB can be validated.
+    const nodeArgs = [nodePath, '--max-old-space-size=512', '--disable-proto=delete'];
     if (loader === 'tsx')
         nodeArgs.push('--import', 'tsx');
     nodeArgs.push(resolvedWorkerPath);
-    bwrapArgs.push('--chdir', runtimeRoot, '--preserve-fds', '1', '--', prlimitPath, '--cpu=65:65', '--as=6442450944:6442450944', '--fsize=100663296:100663296', '--nofile=64:64', '--nproc=64:64', '--', ...nodeArgs);
+    bwrapArgs.push('--chdir', runtimeRoot, 
+    // Bubblewrap passes inherited fds to the command. The spawn caller supplies
+    // only stdio and the fd3 protocol pipe; no descriptor-preservation flag exists.
+    '--', prlimitPath, '--cpu=65:65', '--as=6442450944:6442450944', '--fsize=100663296:100663296', '--nofile=64:64', '--nproc=64:64', '--', 
+    // Bubblewrap adds PWD after --clearenv. Clear the final worker environment
+    // again instead of weakening the exact two-variable readiness invariant.
+    ENV_PATH, '-i', 'NODE_ENV=production', 'NO_COLOR=1', ...nodeArgs);
     return {
         command: setprivPath,
         args: [
@@ -342,7 +351,9 @@ async function runIsolationProbe(launch) {
 }
 /** Fail-closed boot/readiness proof. Package presence alone is not accepted. */
 export async function assertIsolatedEvaluatorReady(host = {}) {
-    if (typeof process.getuid !== 'function' || process.getuid() === 0) {
+    if (typeof process.getuid !== 'function' ||
+        process.getuid() === 0 ||
+        process.geteuid?.() !== process.getuid()) {
         throw new EvaluatorIsolationReadinessError('invariant-namespace');
     }
     const workers = isolatedWorkerUrls(import.meta.url);
@@ -353,6 +364,9 @@ export async function assertIsolatedEvaluatorReady(host = {}) {
     try {
         transportLaunch = isolatedEvaluatorLaunchWithLoader(transportPath, host, 'module');
         probeLaunch = isolatedEvaluatorLaunch(probePath, host);
+        // Trusted parent evidence is passed as bounded probe arguments, never
+        // through the source worker's environment or generated-source protocol.
+        probeLaunch.args.push('--kiln-host-uid', String(process.getuid()), '--kiln-host-userns', readlinkSync('/proc/self/ns/user'));
     }
     catch {
         throw new EvaluatorIsolationReadinessError('wrapper-launch');

package/lib/evaluator/probe-invariants.d.ts

@@ -1,2 +1,13 @@
+export interface ProbeHostIdentity {
+    uid: number;
+    userNamespace: string;
+}
+export declare function parseProbeHostIdentity(argv: readonly string[]): ProbeHostIdentity | undefined;
+export declare function processUserNamespaceIsIsolated(current: {
+    uid: number;
+    effectiveUid: number;
+    userNamespace?: string;
+    uidMap?: string;
+}, host: ProbeHostIdentity | undefined): boolean;
 /** Require every capability set exposed by /proc to be present and empty. */
 export declare function processCapabilitiesAreEmpty(status: string | undefined): boolean;

package/lib/evaluator/probe-invariants.js

@@ -1,4 +1,40 @@
 const CAPABILITY_STATUS_FIELDS = ['CapInh', 'CapPrm', 'CapEff', 'CapBnd', 'CapAmb'];
+const namespacePattern = /^user:\[[0-9]{1,20}\](?![\s\S])/;
+const nonRootUid = (uid) => Number.isSafeInteger(uid) && uid > 0 && uid < 0xffff_ffff;
+export function parseProbeHostIdentity(argv) {
+    if (argv.length !== 4 ||
+        argv[0] !== '--kiln-host-uid' ||
+        argv[2] !== '--kiln-host-userns' ||
+        !argv[1] ||
+        !/^[1-9][0-9]{0,9}(?![\s\S])/.test(argv[1]) ||
+        !argv[3] ||
+        !namespacePattern.test(argv[3]))
+        return undefined;
+    const uid = Number(argv[1]);
+    return nonRootUid(uid) ? { uid, userNamespace: argv[3] } : undefined;
+}
+export function processUserNamespaceIsIsolated(current, host) {
+    if (!host ||
+        !nonRootUid(host.uid) ||
+        !namespacePattern.test(host.userNamespace) ||
+        current.uid !== host.uid ||
+        current.effectiveUid !== host.uid ||
+        typeof current.userNamespace !== 'string' ||
+        !namespacePattern.test(current.userNamespace) ||
+        current.userNamespace === host.userNamespace ||
+        typeof current.uidMap !== 'string' ||
+        current.uidMap.length > 256)
+        return false;
+    const map = /^\s*([0-9]{1,10})\s+([0-9]{1,10})\s+([0-9]{1,10})\s*$/.exec(current.uidMap);
+    if (!map)
+        return false;
+    const [, inside, outside, count] = map.map(Number);
+    // --disable-userns creates a second user namespace. With --dev, that maps
+    // our non-root UID to UID 0 in Bubblewrap's intermediate namespace, not host
+    // root. Require a different namespace, the exact unprivileged caller identity
+    // and a single-ID map; never accept an initial-namespace or broad mapping.
+    return inside === host.uid && count === 1 && (outside === 0 || outside === host.uid);
+}
 /** Require every capability set exposed by /proc to be present and empty. */
 export function processCapabilitiesAreEmpty(status) {
     if (typeof status !== 'string')

package/lib/evaluator/probe-worker.js

@@ -1,9 +1,9 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, readlink, writeFile } from 'node:fs/promises';
 import { connect } from 'node:net';
 import { networkInterfaces } from 'node:os';
 import { validate } from "../validation.js";
 import { writeFileSync } from 'node:fs';
-import { processCapabilitiesAreEmpty } from "./probe-invariants.js";
+import { parseProbeHostIdentity, processCapabilitiesAreEmpty, processUserNamespaceIsIsolated, } from "./probe-invariants.js";
 const VERSION = 'kiln.evaluator.isolation-readiness.v1';
 async function deniedRead(path) {
     try {
@@ -85,12 +85,15 @@ function groupedFailure(failedChecks) {
     return 'invariant-generated-policy';
 }
 function generatedDenials() {
+    if (Object.hasOwn(Object.prototype, '__proto__'))
+        return false;
     const prelude = "const meta = { name: 'probe' }; function build(){ return createRoot('probe'); }";
     const probes = [
         `const leak = process.env; ${prelude}`,
         `const leak = fetch('http://169.254.169.254/'); ${prelude}`,
         `const leak = globalThis.process.mainModule.require('fs'); ${prelude}`,
         `const leak = globalThis.process.mainModule.require('child_process'); ${prelude}`,
+        `const leak = ({}).constructor.constructor('return process')(); ${prelude}`,
     ];
     return probes.every((source) => !validate(source).valid);
 }
@@ -98,11 +101,20 @@ async function main() {
     const status = await optionalRead('/proc/self/status');
     const uidMap = await optionalRead('/proc/self/uid_map');
     const envKeys = Object.keys(process.env).sort();
-    const outsideUid = Number(uidMap?.trim().split(/\s+/)[1]);
+    const userNamespace = await readlink('/proc/self/ns/user').catch(() => undefined);
+    const hostIdentity = parseProbeHostIdentity(process.argv.slice(2));
     const interfaceMap = isolationInterfaces();
     const interfaces = interfaceMap ? Object.values(interfaceMap).flat().filter(Boolean) : undefined;
     const checks = [
-        ['user-namespace', Number.isInteger(outsideUid) && outsideUid > 0],
+        [
+            'user-namespace',
+            processUserNamespaceIsIsolated({
+                uid: process.getuid?.() ?? -1,
+                effectiveUid: process.geteuid?.() ?? -1,
+                uidMap,
+                userNamespace,
+            }, hostIdentity),
+        ],
         ['no-new-privileges', typeof status === 'string' && /^NoNewPrivs:\s+1$/m.test(status)],
         ['capabilities-empty', processCapabilitiesAreEmpty(status)],
         ['environment-exact', envKeys.join(',') === 'NODE_ENV,NO_COLOR'],

package/lib/loopback.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hostnames that name this machine's loopback interface, spelled as `URL.hostname`
+ * reports them. The local viewer answers these Host names, and loopback HTTP is the
+ * only plain-HTTP download location hosts accept.
+ */
+export declare const LOOPBACK_HOSTNAMES: readonly string[];

package/lib/loopback.js

@@ -0,0 +1,6 @@
+/**
+ * Hostnames that name this machine's loopback interface, spelled as `URL.hostname`
+ * reports them. The local viewer answers these Host names, and loopback HTTP is the
+ * only plain-HTTP download location hosts accept.
+ */
+export const LOOPBACK_HOSTNAMES = ['127.0.0.1', 'localhost', '[::1]'];

package/lib/mcp-core.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The protocol half of the Kiln MCP server, shared by the thin stdio entry
+ * (`src/mcp-server.ts`) and the in-process server the tests build
+ * (`createKilnMcpServer` in `src/mcp-engine.ts`): identity, instructions,
+ * the request handlers over a tool manifest, cache hints and the stdin guard.
+ *
+ * Nothing here imports the engine. That is the whole point: the entry bundles
+ * this module with a generated manifest and loads `mcp-engine` on the first
+ * call that needs it, so the handshake, `server/discover` and the tool list
+ * are answered in the time it takes Node to load the protocol library, not
+ * the time it takes to load three, zod, sharp and the registry. Codex gives
+ * an optional server one second before it goes on without its tools.
+ *
+ * The handlers are written on the low-level `Server` rather than `McpServer`
+ * because the advertised definitions must be exact bytes from the manifest
+ * (stable across processes, no library-side schema conversion at startup)
+ * and because the capabilities must say only what Kiln does: the list of
+ * tools and resources is fixed for a build, so no `listChanged` is
+ * advertised and none is acknowledged on `subscriptions/listen`.
+ */
+import { Server, type Transport } from '@modelcontextprotocol/server';
+import { type ServeStdioOptions, type StdioServerHandle } from '@modelcontextprotocol/server/stdio';
+import type { AssetLink } from "./assets-resources.js";
+/** Server identity reported in the handshake and stamped into every 2026-07-28 result. */
+export declare const MCP_SERVER_NAME = "kiln";
+export declare const MCP_SERVER_VERSION = "1.2.0";
+/**
+ * The spec's optional `instructions` field, returned by `initialize` and
+ * `server/discover`.
+ *
+ * This is the only orientation channel that survives every install shape. A
+ * user who configures the server by hand and opens an empty folder has no
+ * AGENTS.md, no CLAUDE.md and no registered skills -- but the skills do ship
+ * beside the server, so the useful thing to say is that they exist and where.
+ *
+ * At most 700 characters, with the essentials inside the first 512 (v1 contract
+ * rule 5): the text rides on every session start in every client, and the
+ * harnesses that cut it cut from the end. It names no absolute path, so the
+ * same bytes serve every installation.
+ */
+export declare const MCP_SERVER_INSTRUCTIONS = "Kiln turns JavaScript you write into GLB assets and returns rendered views. Work by reference: send a program once to kiln_validate or kiln_render, keep the returned programRef exactly, and use it for every later render, inspect, kiln_source and kiln_edit call; never resend a program to change part of it. Call kiln_discover first for helper contracts, with capabilities:true for the host's runtime, project and camera facts. Read viewFidelity before judging materials: a CPU view shows shape, not material; GPU views need the render service in render-service/. Agent Skills for authoring, refining, QA and scenes ship in skills/ beside this server's dist/; read the matching SKILL.md first.";
+export declare const MCP_OPERATION_INSTRUCTIONS = "Kiln turns authored JavaScript into editable GLB assets and rendered views. Send source once to kiln_validate or kiln_render, then preserve the exact programRef for later reads, edits and renders. Use kiln_discover for helper contracts and full input shapes; use kiln_capabilities for host configuration and limits. Read viewFidelity before judging materials: CPU geometry views are not material evidence. Search saved assets with kiln_assets_search; reopen exact source with kiln_assets_restore. Browse materials with kiln_material_search and create with kiln_material_create. Save only when requested. Pin collection, asset and revision IDs for reuse and export.";
+/** One MCP content block. Mirrors the SDK's `CallToolResult['content']` element. */
+export type KilnContentBlock = AssetLink | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+};
+/**
+ * The structurally-typed subset of the SDK's `CallToolResult` Kiln produces.
+ *
+ * Declared locally rather than imported so `runTool` stays usable by callers
+ * that are not holding an SDK type (the parity test drives it directly).
+ *
+ * A type alias, not an interface, and that is load-bearing: the SDK's
+ * `CallToolResult` carries an index signature for protocol passthrough fields,
+ * and TypeScript grants an implicit index signature to type aliases but not to
+ * interfaces.
+ */
+export type KilnToolResult = {
+    content: KilnContentBlock[];
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+};
+/** One `resources/read` content entry: text for source and JSON, base64 for everything else. */
+export type KilnResourceContents = {
+    uri: string;
+    mimeType: string;
+    _meta?: Record<string, unknown>;
+} & ({
+    text: string;
+} | {
+    blob: string;
+});
+/** A tool definition exactly as `tools/list` advertises it. */
+export interface KilnMcpManifestTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        [key: string]: unknown;
+    };
+    annotations?: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+    _meta?: Record<string, unknown>;
+    outputSchema?: {
+        [key: string]: unknown;
+    };
+}
+/** A fixed resource exactly as `resources/list` advertises it. */
+export interface KilnMcpManifestResource {
+    uri: string;
+    name: string;
+    mimeType: string;
+    description: string;
+    _meta?: Record<string, unknown>;
+}
+/** A resource template exactly as `resources/templates/list` advertises it. */
+export interface KilnMcpManifestTemplate {
+    name: string;
+    uriTemplate: string;
+    description: string;
+}
+/**
+ * Everything a client can learn without calling a tool. Generated from the
+ * registry by `scripts/generate-mcp-manifest.ts` into
+ * `src/generated/mcp-manifest.json`, which the entry bundles; a test proves
+ * the committed file equals what the registry builds.
+ */
+export interface KilnMcpManifest {
+    kind: 'kiln.mcp-manifest.v1';
+    tools: KilnMcpManifestTool[];
+    resources: KilnMcpManifestResource[];
+    resourceTemplates: KilnMcpManifestTemplate[];
+}
+/** What the engine supplies once loaded: the calls that need it. */
+export interface KilnMcpHost {
+    callTool(name: string, args: Record<string, unknown>, request: {
+        signal: AbortSignal;
+    }): Promise<KilnToolResult>;
+    readResource(uri: string): Promise<KilnResourceContents>;
+}
+/** Presentation hints for the asset viewer app, hidden from the language model. */
+export declare const KILN_WIDGET_META: Record<string, unknown>;
+export declare const KILN_WIDGET_RESOURCE: KilnMcpManifestResource;
+export declare const KILN_RESOURCE_TEMPLATES: {
+    readonly assetFile: {
+        readonly name: 'asset-file';
+        readonly uriTemplate: 'kiln://assets/{collection}/{asset}/{revision}/{file}';
+        readonly description: 'Saved GLB/source/preview/manifest/bundle, or derived runtime GLB and metadata sidecar.';
+    };
+    readonly projectPackage: {
+        readonly name: 'project-package';
+        readonly uriTemplate: 'kiln://projects/{project}/{revision}/{profile}';
+        readonly description: 'Exact editable project bundle or runtime derivative ZIP.';
+    };
+};
+/**
+ * Definitions, templates and the viewer page are fixed for a build, and a new
+ * build restarts the process, so a client may hold them for a day. Asset and
+ * project files are a user's own data: never shared, and re-read on demand.
+ */
+export declare const DEFINITION_TTL_MS = 86400000;
+/** Only what Kiln does: no `listChanged`, because the lists never change within a build. */
+export declare function kilnServerCapabilities(): {
+    tools: {};
+    resources: {};
+    extensions: {
+        "io.modelcontextprotocol/ui": {
+            mimeTypes: string[];
+        };
+    };
+};
+export interface KilnServerOptions {
+    manifest: KilnMcpManifest;
+    /**
+     * Supplies the engine on first use. The entry loads `mcp-engine` here; the
+     * in-process server resolves immediately. A rejection is reported as a tool
+     * result naming the next step, and the next call tries again.
+     */
+    host: () => Promise<KilnMcpHost>;
+    /** Runs once, after the first `tools/list` has been answered on this instance. */
+    afterFirstToolList?: () => void;
+    /** The viewer page served for the widget resource; defaults to the packaged `dist/viewer/chat.html`. */
+    widgetHtml?: () => Promise<string>;
+    instructions?: string;
+}
+/**
+ * Rule 9 of the v1 contract: a diagnostic names the cause and the next call
+ * and carries no absolute local path. Raw filesystem errors do carry one, so
+ * the loading diagnostics pass through here before they reach a tool result.
+ */
+export declare function withoutLocalPaths(text: string): string;
+export declare function errorMessage(error: unknown): string;
+/** Build the server over a manifest; every call that needs the engine goes through `host()`. */
+export declare function createKilnServer(options: KilnServerOptions): Server;
+/** Options the MCP executable accepts on its command line. */
+export interface KilnMcpArguments {
+    requirementsFile?: string;
+}
+/**
+ * Only explicit host startup configuration can supply a standalone session's
+ * policy. Parsed before the engine, because a wrong command line is the host's
+ * mistake and the only honest answer is an exit with the message.
+ */
+export declare function parseMcpArguments(argv: readonly string[]): KilnMcpArguments;
+/**
+ * Refuses a request that belongs to neither era: no per-request protocol
+ * version (so not a 2026-07-28 request) and no `initialize` before it (so not a
+ * 2025 session either). Under 2026-07-28 a request missing a required `_meta`
+ * field is malformed and answered -32602; under 2025-11-25 nothing but a ping
+ * may precede the handshake. The library would otherwise pin the connection to
+ * a 2025 instance and serve it, which hides a broken client.
+ */
+export declare function guardedStdioTransport(inner?: Transport): Transport;
+/**
+ * Serve over this process's stdio, both eras: a 2025 client opens with
+ * `initialize`, a 2026-07-28 client with `server/discover` or any request
+ * carrying the per-request envelope. The library owns the era decision; Kiln
+ * adds the pre-handshake guard above.
+ */
+export declare function serveKilnStdio(options: KilnServerOptions, stdio?: Pick<ServeStdioOptions, 'onerror'>): StdioServerHandle;