@instruktlabs/kiln 1.0.0 → 1.2.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/index.ts

@@ -21,6 +21,7 @@ export function createDiscovery(
     discovery: { mode: 'lexical', offline: true, requiresModel: false },
   }),
   notes: () => Promise<string[]> = async () => [],
+  capabilitiesCall = 'capabilities:true',
 ) {
   snapshot ??= (() => {
     const entries = listDiscoveryEntries();
@@ -32,5 +33,6 @@ export function createDiscovery(
     capabilities,
     REMOVED_AUTHORING_HELPERS,
     notes,
+    capabilitiesCall,
   );
 }

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/discovery/service.ts

@@ -63,6 +63,8 @@ export function createDiscoveryService(
   retirements: Readonly<Record<string, string>> = {},
   /** Host notes for the overview, such as the project an omitted `projectId` selects. */
   notes: () => Promise<string[]> = async () => [],
+  /** Host-selected capability entrypoint, never a model-provided instruction. */
+  capabilitiesCall = 'capabilities:true',
 ): (input: unknown) => Promise<DiscoveryResponse> {
   const entries = parseCatalog(source);
   const byId = new Map(entries.map((entry) => [entry.id, entry]));
@@ -94,7 +96,7 @@ export function createDiscoveryService(
       '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 = (

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.2.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-core.ts

@@ -65,6 +65,9 @@ export const MCP_SERVER_VERSION = ENGINE_VERSION;
 export 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 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

package/src/mcp-engine.ts

@@ -26,6 +26,7 @@ import {
   type KilnResourceContents,
   type KilnToolResult,
   withoutLocalPaths,
+  MCP_OPERATION_INSTRUCTIONS,
 } from './mcp-core';
 import { buildMcpManifest } from './mcp-manifest';
 import { localProgramStore } from './program-store-node';
@@ -33,6 +34,7 @@ import { validateRequirementsBinding } from './requirements-context';
 import { describeInputError, schemaFields } from './tools/actions';
 import {
   createKilnProgramToolRegistry,
+  createKilnOperationToolRegistry,
   type KilnToolContext,
   type KilnToolDef,
 } from './tools/registry';
@@ -42,6 +44,8 @@ export type { KilnToolResult } from './mcp-core';
 
 /** Optional wire features whose support is not negotiated by core MCP. */
 export type KilnMcpCompatibilityOptions = {
+  /** Opt-in domain operation presentation generated from the shared registry. */
+  toolPresentation?: 'grouped' | 'operations';
   /**
    * Add core `resource_link` blocks for saved artifact files.
    *
@@ -160,7 +164,10 @@ export function createKilnToolHost(
       };
     },
   };
-  const defs = kilnMcpToolDefs(requestContext);
+  const defs =
+    options.toolPresentation === 'operations'
+      ? createKilnOperationToolRegistry(requestContext)
+      : kilnMcpToolDefs(requestContext);
   const byName = new Map(defs.map((def) => [def.name, def] as const));
   return {
     defs,
@@ -259,6 +266,9 @@ export function createKilnMcpServer(
 ): Server {
   const host = createKilnToolHost(context, options);
   return createKilnServer({
+    ...(options.toolPresentation === 'operations'
+      ? { instructions: MCP_OPERATION_INSTRUCTIONS }
+      : {}),
     manifest: buildMcpManifest(host.defs, context),
     host: async () => host,
   });

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));
     }

package/src/tools/discovery.ts

@@ -11,10 +11,14 @@ import { resolveGltfExporter } from '../community-exporter';
 import { approvedTextureCatalogV1 } from '../material-resources';
 
 /** Shared native tool definition; all transports use the same Discovery service. */
-export function createKilnDiscoveryDef(context: KilnToolContext): KilnToolDef {
+export function createKilnDiscoveryDef(
+  context: KilnToolContext,
+  presentation: 'grouped' | 'operations' = 'grouped',
+): KilnToolDef {
   const run = createDiscovery(
-    () => currentCapabilities(context),
+    () => currentCapabilities(context, presentation),
     async () => projectNotes(context),
+    presentation === 'operations' ? 'kiln_capabilities({})' : 'capabilities:true',
   );
   return {
     name: 'kiln_discover',
@@ -48,7 +52,10 @@ function projectNotes(context: KilnToolContext): string[] {
     : [];
 }
 
-async function currentCapabilities(context: KilnToolContext) {
+async function currentCapabilities(
+  context: KilnToolContext,
+  presentation: 'grouped' | 'operations',
+) {
   const externalEvaluator =
     Boolean(context.evaluatorPort) || context.evaluatorProfile === 'evaluator-required';
   const approvedTextures = context.approvedTextureResources
@@ -102,12 +109,15 @@ async function currentCapabilities(context: KilnToolContext) {
     // you -- so the workspace guide's "do not substitute it silently" had
     // nothing to check against. Compare with `runtime` in .kiln/workspace.json.
     engine: engineIdentity(),
-    project: {
-      configured: configuredProject(context),
-      select:
-        'projectId per call; omitted uses the configured project, null selects standalone work',
-      read: 'kiln_project { action: "get", projectId } returns the brief, design, inventory and material pins',
-    },
+    project:
+      presentation === 'operations' && !context.projectStore
+        ? { available: false }
+        : {
+            configured: configuredProject(context),
+            select:
+              'projectId per call; omitted uses the configured project, null selects standalone work',
+            read: 'kiln_project { action: "get", projectId } returns the brief, design, inventory and material pins',
+          },
     renderer,
     execution:
       context.localExecution ??
@@ -128,7 +138,7 @@ async function currentCapabilities(context: KilnToolContext) {
       available: Boolean(context.assetLibrary),
       collections: context.assetLibrary?.collections() ?? [],
       save: 'kiln_save persists exact GLB, source and provenance; draft renders do not populate collections',
-      resume: 'kiln_assets action=restore imports a saved revision into the current program store',
+      resume: `${presentation === 'operations' ? 'kiln_assets_restore' : 'kiln_assets action=restore'} imports a saved revision into the current program store`,
       downloads: 'kiln_export returns GLB/source/ZIP resource links; client presentation varies',
       viewer:
         'kiln_present opens a saved revision in supporting chat clients with 3D viewing and downloads; kiln view opens a local collection or standalone GLB/ZIP',

package/src/tools/materials.ts

@@ -14,6 +14,7 @@ import { createMaterialRecordV1, decodeMaterialLibraryPayload } from '../materia
 import { createMaterialPresetDraft, listMaterialPresets } from '../material-presets';
 import { nestedRecordDescription, requireActionFields } from './actions';
 import type { KilnToolDef } from './registry';
+import type { KilnActionContract } from './operation-contract';
 
 const MATERIAL_ACTIONS = [
   'presets',
@@ -24,13 +25,43 @@ const MATERIAL_ACTIONS = [
   'import',
 ] as const;
 type MaterialAction = (typeof MATERIAL_ACTIONS)[number];
-const REQUIREMENTS: Record<MaterialAction, Parameters<typeof requireActionFields>[3]> = {
-  presets: { required: [] },
-  'create-preset': { required: ['presetId', 'seed', 'creator', 'license'] },
-  list: { required: [] },
-  get: { required: ['materialId'] },
-  'create-procedural': { required: ['draft'], shapes: { draft: 'shape:material-draft' } },
-  import: { required: ['payload'], shapes: { payload: 'shape:material-import' } },
+const MATERIAL_CONTRACT: Record<MaterialAction, KilnActionContract> = {
+  presets: {
+    fields: ['tag'],
+    required: [],
+    description: 'List shipped material recipes, optionally filtered by tag.',
+  },
+  'create-preset': {
+    fields: ['presetId', 'seed', 'creator', 'license', 'size', 'materialId'],
+    required: ['presetId', 'seed', 'creator', 'license'],
+    description:
+      'Create an immutable material from a shipped preset with explicit seed, creator and license.',
+  },
+  list: {
+    fields: ['tag'],
+    required: [],
+    description: 'List saved immutable material revisions, optionally filtered by tag.',
+  },
+  get: {
+    fields: ['materialId', 'revisionId'],
+    required: ['materialId'],
+    description:
+      'Read a material revision, provenance and portable specification. Omit revisionId only when exactly one revision exists.',
+  },
+  'create-procedural': {
+    fields: ['draft'],
+    required: ['draft'],
+    shapes: { draft: 'shape:material-draft' },
+    description:
+      'Create an immutable material from a bounded procedural draft. Does not fetch URLs or execute source.',
+  },
+  import: {
+    fields: ['payload'],
+    required: ['payload'],
+    shapes: { payload: 'shape:material-import' },
+    description:
+      'Import complete normalized material records and embedded PNGs. Does not fetch URLs or execute source.',
+  },
 };
 const record = (description: string) =>
   z.record(z.string(), z.unknown()).optional().describe(description);
@@ -74,9 +105,9 @@ const materialResult = (material: MaterialManifestV1) => ({
   material,
   portableSpec: materialLibraryPortableSpec(material),
 });
-const unknownMaterial = (materialId: string, revisionId?: string) =>
+const unknownMaterial = (materialId: string, revisionId: string | undefined, listCall: string) =>
   new Error(
-    `Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ''}. kiln_material { action: 'list' } lists the materials in this workspace with their revision IDs.`,
+    `Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ''}. ${listCall} lists the materials in this workspace with their revision IDs.`,
   );
 /**
  * The revision a `get` without `revisionId` means: the material's only one.
@@ -84,13 +115,17 @@ const unknownMaterial = (materialId: string, revisionId?: string) =>
  * caller to choose (two live sessions of 1 October 2026 called get with the
  * id alone and were refused).
  */
-async function onlyRevision(library: MaterialLibrary, materialId: string): Promise<string> {
+async function onlyRevision(
+  library: MaterialLibrary,
+  materialId: string,
+  listCall: string,
+): Promise<string> {
   const revisions = (await library.list())
     .filter((material) => material.materialId === materialId)
     .map((material) => material.revisionId)
     .sort();
   if (revisions.length === 1) return revisions[0]!;
-  if (revisions.length === 0) throw unknownMaterial(materialId);
+  if (revisions.length === 0) throw unknownMaterial(materialId, undefined, listCall);
   throw new Error(
     `Material ${materialId} has ${revisions.length} revisions: ${revisions.join(', ')}. Pass revisionId to get one.`,
   );
@@ -111,12 +146,20 @@ function aliasMaterialId(raw: unknown): unknown {
     );
   return { ...rest, materialId: resourceId };
 }
-export function createKilnMaterialDef(library: MaterialLibrary): KilnToolDef {
+export function createKilnMaterialDef(
+  library: MaterialLibrary,
+  presentation: 'grouped' | 'operations' = 'grouped',
+): KilnToolDef {
+  const listCall =
+    presentation === 'operations'
+      ? 'kiln_material_search({ scope: "saved" })'
+      : "kiln_material { action: 'list' }";
   return {
     name: 'kiln_material',
     description:
       'Manage optional immutable material resources in this workspace. presets discovers shipped architecture, wood, metal, fabric and ground recipes; create-preset bakes one with an explicit seed, creator and license; list returns compact material/revision summaries; get returns full provenance, hashes, map conventions, physical repeat scale and a code-ready portable material spec; create-procedural bakes bounded editable layer recipes including optional height-derived normals; import accepts complete normalized records with embedded PNG bytes. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before authored evaluation resolves the resources; no project is required.',
     inputSchema: materialToolInput,
+    actionContract: MATERIAL_CONTRACT,
     annotations: {
       readOnlyHint: false,
       destructiveHint: false,
@@ -126,7 +169,7 @@ export function createKilnMaterialDef(library: MaterialLibrary): KilnToolDef {
     async run(raw) {
       assertMaterialJson(raw);
       const input = materialToolInput.parse(aliasMaterialId(raw));
-      requireActionFields('kiln_material', input.action, input, REQUIREMENTS[input.action]);
+      requireActionFields('kiln_material', input.action, input, MATERIAL_CONTRACT[input.action]);
       switch (input.action) {
         case 'presets':
           return {
@@ -170,13 +213,14 @@ export function createKilnMaterialDef(library: MaterialLibrary): KilnToolDef {
           };
         }
         case 'get': {
-          const revisionId = input.revisionId ?? (await onlyRevision(library, input.materialId!));
+          const revisionId =
+            input.revisionId ?? (await onlyRevision(library, input.materialId!, listCall));
           try {
             return materialResult((await library.read(input.materialId!, revisionId)).manifest);
           } catch (error) {
             // Rule 9: an unknown id names the call that lists the known ones.
             if ((error as NodeJS.ErrnoException).code === 'ENOENT')
-              throw unknownMaterial(input.materialId!, revisionId);
+              throw unknownMaterial(input.materialId!, revisionId, listCall);
             throw error;
           }
         }

package/src/tools/operation-contract.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import type { ActionRequirements } from './actions';
+
+/** Domain action metadata shared by grouped execution and named presentations. */
+export interface KilnActionContract extends ActionRequirements {
+  readonly fields: readonly string[];
+  readonly description: string;
+}
+
+export function projectActionSchemas<A extends string>(
+  name: string,
+  input: z.ZodObject,
+  actions: Readonly<Record<A, KilnActionContract>>,
+): Record<A, z.ZodObject> {
+  if (input.def.checks?.length)
+    throw new Error(`${name}: cross-field constraints require an explicit operation schema`);
+  const json = z.toJSONSchema(input, { io: 'input' });
+  const selector = json.properties?.action as { enum?: unknown } | undefined;
+  const expected = Object.keys(actions).sort();
+  if (
+    !Array.isArray(selector?.enum) ||
+    JSON.stringify([...selector.enum].sort()) !== JSON.stringify(expected)
+  )
+    throw new Error(`${name}: unclassified actions`);
+  const classified = new Set([
+    'action',
+    ...Object.values<KilnActionContract>(actions).flatMap((contract) => [...contract.fields]),
+  ]);
+  const unclassified = Object.keys(input.shape).filter((field) => !classified.has(field));
+  if (unclassified.length)
+    throw new Error(`${name}: Unclassified fields: ${unclassified.join(', ')}`);
+  const schemas: [string, z.ZodObject][] = [];
+  for (const [action, contract] of Object.entries<KilnActionContract>(actions)) {
+    for (const field of contract.required)
+      if (!contract.fields.includes(field))
+        throw new Error(`${name}.${action}: unmapped required ${field}`);
+    for (const field of json.required ?? [])
+      if (field !== 'action' && !contract.fields.includes(field))
+        throw new Error(`${name}.${action}: would omit required ${field}`);
+    const shape: Record<string, z.ZodType> = {};
+    for (const field of contract.fields) {
+      if (field === 'action' || !Object.hasOwn(input.shape, field))
+        throw new Error(`${name}.${action}: missing or reserved field ${field}`);
+      classified.add(field);
+      const source = input.shape[field]!;
+      shape[field] = contract.required.includes(field) ? source.nonoptional() : source;
+    }
+    schemas.push([action, z.strictObject(shape)]);
+  }
+  return Object.fromEntries(schemas) as Record<A, z.ZodObject>;
+}