@instruktlabs/kiln 1.0.0 → 1.1.0

package/skills/kiln-setup-workspace/references/renderer-setup.md

@@ -0,0 +1,11 @@
+# Local renderer setup
+
+Setup asks for render mode `auto`: textured or metallic scenes use a compatible GPU service, starting one lazily when available. Ordinary untextured scenes with zero metalness and no advanced material extensions use CPU views, even with a GPU available. CPU views support silhouette, proportion and contact review, but cannot confirm PBR appearance. Use CLI `--render gpu` when material review is required, including roughness on nonmetallic surfaces.
+
+The renderer code is included with Kiln; its native GPU dependency is optional at the Kiln package root. For material-dependent tasks, check `node kiln.mjs service status` before starting the authoring session. If dependencies are missing or incompatible, reinstall the official Kiln package with optional dependencies enabled. npm 11 may print an `install-scripts` warning for the optional `webgpu` package; its postinstall only clears the macOS download quarantine from the prebuilt Dawn binary the package ships, so Windows and Linux need nothing and the warning is not an install failure. Read `runtime` from `.kiln/workspace.json` to identify the installation. A source checkout uses `bun install --frozen-lockfile` at that root. Setup checks dependency resolution without loading native code; ready dependencies alone do not prove the device can render.
+
+Once dependencies are available, local CLI/MCP auto mode starts a managed service lazily for a view that needs PBR shading. Compatible clients share it; it survives the initiating session and exits after five minutes without admitted uploads, queued jobs or active renders. From the installation root, `node --import ./render-service/src/register-hooks.mjs render-service/src/server.mjs` starts a manual service that remains running while idle. It binds loopback; widening `HOST` requires `RENDER_SERVICE_TOKEN`.
+
+`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. After dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
+
+A `KILN_RENDER_PORT_URL` whose origin is exactly the shared local socket (`http://127.0.0.1:8000` by default) takes the local route: it starts on demand and restarts after an idle exit. For rendering on another device, configure the MCP server process's `KILN_RENDER_PORT_URL` and, when needed, `KILN_RENDER_TOKEN` through the chosen harness. CLI accepts `--render-port URL` and reads `KILN_RENDER_TOKEN`. Start a compatible Kiln renderer on that device; its wider bind requires `RENDER_SERVICE_TOKEN` unless an authenticated proxy is explicitly configured. Manage the remote service on its own device. Verify the selected route with capabilities and require an actual `viewFidelity` receipt for material evidence.

package/src/cli-render-mode.ts

@@ -71,16 +71,16 @@ export function makeLazyRenderPort(
       return await port(req, execution);
     } catch (error) {
       if (execution?.signal?.aborted || (error as Error).name === 'TimeoutError') throw error;
-      if (
-        (
-          await readRenderServiceHealth(url, {
-            token,
-            signal: execution?.signal,
-          })
-        ).kind !== 'absent'
-      )
-        throw error;
+      // 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,
+      });
       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) resolving = undefined;

package/src/cli.ts

@@ -82,11 +82,11 @@ EXPORT ENVIRONMENT
   KILN_INDEX_POLICY      indexed (default) | asBuilt (requires optimization off)
 
 EXAMPLES
-  kiln render examples/crate.kiln.js --out crate.glb --views sheet.png
+  kiln render my-asset.kiln.js --out asset.glb --views sheet.png
   kiln generate "a weathered wooden crate" --out crate.glb --views sheet.png
-  kiln render examples/crate.kiln.js --render cpu --views sheet.png
+  kiln render my-asset.kiln.js --render cpu --views sheet.png
   kiln render p_RETURNED_HANDLE --capture cameras.json --views chosen.png
-  kiln render examples/crate.kiln.js --views sheet.png --backdrop light
+  kiln render my-asset.kiln.js --views sheet.png --backdrop light
 `;
 
 interface Args extends WorkspaceSelection {

package/src/discovery/portable.ts

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

package/src/engine-identity.ts

@@ -27,7 +27,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.1.0';
 
 /**
  * Where this engine was loaded from, as a `file://` URL of the package root.

package/src/evaluator/isolation.ts

@@ -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';
@@ -17,6 +17,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';
@@ -159,7 +160,7 @@ function isolatedEvaluatorLaunchWithLoader(
   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();
   }
   const resolvedWorkerPath = workerInsideRuntime(workerPath, runtimeRoot);
@@ -195,14 +196,16 @@ function isolatedEvaluatorLaunchWithLoader(
   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',
+    // 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',
@@ -211,6 +214,12 @@ function isolatedEvaluatorLaunchWithLoader(
     '--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,
   );
 
@@ -435,7 +444,11 @@ async function runIsolationProbe(
 export async function assertIsolatedEvaluatorReady(
   host: IsolatedEvaluatorHost = {},
 ): Promise<EvaluatorIsolationReadiness> {
-  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);
@@ -446,6 +459,14 @@ export async function assertIsolatedEvaluatorReady(
   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/src/evaluator/probe-invariants.ts

@@ -1,5 +1,55 @@
 const CAPABILITY_STATUS_FIELDS = ['CapInh', 'CapPrm', 'CapEff', 'CapBnd', 'CapAmb'] as const;
 
+export interface ProbeHostIdentity {
+  uid: number;
+  userNamespace: string;
+}
+
+const namespacePattern = /^user:\[[0-9]{1,20}\](?![\s\S])/;
+const nonRootUid = (uid: number) => Number.isSafeInteger(uid) && uid > 0 && uid < 0xffff_ffff;
+
+export function parseProbeHostIdentity(argv: readonly string[]): ProbeHostIdentity | undefined {
+  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: { uid: number; effectiveUid: number; userNamespace?: string; uidMap?: string },
+  host: ProbeHostIdentity | undefined,
+): boolean {
+  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: string | undefined): boolean {
   if (typeof status !== 'string') return false;

package/src/evaluator/probe-worker.ts

@@ -1,9 +1,13 @@
-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';
 import { writeFileSync } from 'node:fs';
-import { processCapabilitiesAreEmpty } from './probe-invariants';
+import {
+  parseProbeHostIdentity,
+  processCapabilitiesAreEmpty,
+  processUserNamespaceIsIsolated,
+} from './probe-invariants';
 
 const VERSION = 'kiln.evaluator.isolation-readiness.v1';
 type ProbeFailure =
@@ -105,12 +109,14 @@ function groupedFailure(failedChecks: readonly string[]): ProbeFailure {
 }
 
 function generatedDenials(): boolean {
+  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);
 }
@@ -119,11 +125,23 @@ async function main(): Promise<void> {
   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: Array<[string, boolean]> = [
-    ['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/src/mcp.ts

@@ -0,0 +1,5 @@
+/** Node embedding API. The stdio executable retains its separate lazy entry. */
+export { createKilnMcpServer, createKilnToolHost, kilnMcpToolDefs } from './mcp-engine';
+export type { KilnMcpCompatibilityOptions, KilnToolResult } from './mcp-engine';
+export type { KilnMcpHost, KilnContentBlock, KilnResourceContents } from './mcp-core';
+export type { KilnToolContext, KilnToolDef } from './tools/registry';

package/src/render-service-host.ts

@@ -264,7 +264,7 @@ export async function startLocalRenderService(
       // A failed spawn has no such race; absent/unknown never count as success.
       if (spawnError || (exitedAt !== undefined && Date.now() - exitedAt >= 1500))
         throw new Error(
-          `render service exited during startup${spawnError ? `: ${spawnError.message}` : ''}${stderr.trim() ? `: ${stderr.trim().split('\n').slice(-3).join(' ')}` : windowsLaunch ? '; launch the renderer manually to inspect native-driver errors' : ''}`,
+          `render service exited during startup${spawnError ? `: ${spawnError.message}` : ''}${stderr.trim() ? `: ${stderr.trim()}` : windowsLaunch ? '; launch the renderer manually to inspect native-driver errors' : ''}`,
         );
       await new Promise((done) => setTimeout(done, 250));
     }