@instruktlabs/kiln 1.1.0 → 1.2.0

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

package/lib/mcp-core.d.ts

@@ -23,7 +23,7 @@ import { type ServeStdioOptions, type StdioServerHandle } from '@modelcontextpro
 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.1.0";
+export declare const MCP_SERVER_VERSION = "1.2.0";
 /**
  * The spec's optional `instructions` field, returned by `initialize` and
  * `server/discover`.
@@ -39,6 +39,7 @@ export declare const MCP_SERVER_VERSION = "1.1.0";
  * 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';

package/lib/mcp-core.js

@@ -43,6 +43,7 @@ export const MCP_SERVER_VERSION = ENGINE_VERSION;
  * same bytes serve every installation.
  */
 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.';
 /** Presentation hints for the asset viewer app, hidden from the language model. */
 export const KILN_WIDGET_META = {
     ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } },

package/lib/mcp-engine.d.ts

@@ -14,6 +14,8 @@ import { type KilnToolContext, type KilnToolDef } from "./tools/registry.js";
 export type { KilnToolResult } from "./mcp-core.js";
 /** 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.
      *

package/lib/mcp-engine.js

@@ -14,12 +14,12 @@ import { buildRenderPort, resolveRenderMode } from "./cli-render-mode.js";
 import { FileLiveReview } from "./live-review-node.js";
 import { createPackagedLocalToolContext } from "./local-runtime.js";
 import { LOOPBACK_HOSTNAMES } from "./loopback.js";
-import { createKilnServer, errorMessage, withoutLocalPaths, } from "./mcp-core.js";
+import { createKilnServer, errorMessage, withoutLocalPaths, MCP_OPERATION_INSTRUCTIONS, } from "./mcp-core.js";
 import { buildMcpManifest } from "./mcp-manifest.js";
 import { localProgramStore } from "./program-store-node.js";
 import { validateRequirementsBinding } from "./requirements-context.js";
 import { describeInputError, schemaFields } from "./tools/actions.js";
-import { createKilnProgramToolRegistry, } from "./tools/registry.js";
+import { createKilnProgramToolRegistry, createKilnOperationToolRegistry, } from "./tools/registry.js";
 import { localWorkspaceRoot } from "./workspace-node.js";
 /** Use the shared program-aware definitions, including standalone validation. */
 export function kilnMcpToolDefs(context = {}) {
@@ -112,7 +112,9 @@ export function createKilnToolHost(context = {}, options = {}) {
             };
         },
     };
-    const defs = kilnMcpToolDefs(requestContext);
+    const defs = options.toolPresentation === 'operations'
+        ? createKilnOperationToolRegistry(requestContext)
+        : kilnMcpToolDefs(requestContext);
     const byName = new Map(defs.map((def) => [def.name, def]));
     return {
         defs,
@@ -200,6 +202,9 @@ function resourceText(name, bytes) {
 export function createKilnMcpServer(context = {}, options = {}) {
     const host = createKilnToolHost(context, options);
     return createKilnServer({
+        ...(options.toolPresentation === 'operations'
+            ? { instructions: MCP_OPERATION_INSTRUCTIONS }
+            : {}),
         manifest: buildMcpManifest(host.defs, context),
         host: async () => host,
     });

package/lib/tools/discovery.d.ts

@@ -1,3 +1,3 @@
 import type { KilnToolContext, KilnToolDef } from "./registry.js";
 /** Shared native tool definition; all transports use the same Discovery service. */
-export declare function createKilnDiscoveryDef(context: KilnToolContext): KilnToolDef;
+export declare function createKilnDiscoveryDef(context: KilnToolContext, presentation?: 'grouped' | 'operations'): KilnToolDef;

package/lib/tools/discovery.js

@@ -8,8 +8,8 @@ import { geometryExportAttributes } from "../geometry-export.js";
 import { resolveGltfExporter } from "../community-exporter.js";
 import { approvedTextureCatalogV1 } from "../material-resources.js";
 /** Shared native tool definition; all transports use the same Discovery service. */
-export function createKilnDiscoveryDef(context) {
-    const run = createDiscovery(() => currentCapabilities(context), async () => projectNotes(context));
+export function createKilnDiscoveryDef(context, presentation = 'grouped') {
+    const run = createDiscovery(() => currentCapabilities(context, presentation), async () => projectNotes(context), presentation === 'operations' ? 'kiln_capabilities({})' : 'capabilities:true');
     return {
         name: 'kiln_discover',
         description: 'Discover Kiln operations, assemblies, recipes, tool-input shapes and current host capabilities. Omit arguments for a compact overview. Search with ordinary modeling language using query; refine with family, kind or tags. Fetch complete contracts/examples with ids (up to six exact IDs, executable names or shape: ids). Overview/search pages default to six summaries. Recipes guide construction without restricting the asset. Search runs locally without models or network calls.',
@@ -39,7 +39,7 @@ function projectNotes(context) {
         ]
         : [];
 }
-async function currentCapabilities(context) {
+async function currentCapabilities(context, presentation) {
     const externalEvaluator = Boolean(context.evaluatorPort) || context.evaluatorProfile === 'evaluator-required';
     const approvedTextures = context.approvedTextureResources
         ? context.approvedTextureResources()
@@ -91,11 +91,13 @@ async function currentCapabilities(context) {
         // 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 ??
             (context.evaluatorPort
@@ -115,7 +117,7 @@ async function currentCapabilities(context) {
             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/lib/tools/materials.d.ts

@@ -26,4 +26,4 @@ export declare const materialToolInput: z.ZodObject<{
     draft: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;
-export declare function createKilnMaterialDef(library: MaterialLibrary): KilnToolDef;
+export declare function createKilnMaterialDef(library: MaterialLibrary, presentation?: 'grouped' | 'operations'): KilnToolDef;

package/lib/tools/materials.js

@@ -11,13 +11,39 @@ const MATERIAL_ACTIONS = [
     'create-procedural',
     'import',
 ];
-const REQUIREMENTS = {
-    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 = {
+    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) => z.record(z.string(), z.unknown()).optional().describe(description);
 const tag = z.string().min(1).max(80).optional().describe('presets, list: keep one tag.');
@@ -49,14 +75,14 @@ const materialResult = (material) => ({
     material,
     portableSpec: materialLibraryPortableSpec(material),
 });
-const unknownMaterial = (materialId, revisionId) => new Error(`Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ''}. kiln_material { action: 'list' } lists the materials in this workspace with their revision IDs.`);
+const unknownMaterial = (materialId, revisionId, listCall) => new Error(`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.
  * Revisions are content hashes with no order, so several are named for the
  * caller to choose (two live sessions of 1 October 2026 called get with the
  * id alone and were refused).
  */
-async function onlyRevision(library, materialId) {
+async function onlyRevision(library, materialId, listCall) {
     const revisions = (await library.list())
         .filter((material) => material.materialId === materialId)
         .map((material) => material.revisionId)
@@ -64,7 +90,7 @@ async function onlyRevision(library, materialId) {
     if (revisions.length === 1)
         return revisions[0];
     if (revisions.length === 0)
-        throw unknownMaterial(materialId);
+        throw unknownMaterial(materialId, undefined, listCall);
     throw new Error(`Material ${materialId} has ${revisions.length} revisions: ${revisions.join(', ')}. Pass revisionId to get one.`);
 }
 /**
@@ -83,11 +109,15 @@ function aliasMaterialId(raw) {
         throw new Error(`kiln_material: resourceId (${String(resourceId)}) and materialId (${String(rest.materialId)}) name different materials; pass materialId alone.`);
     return { ...rest, materialId: resourceId };
 }
-export function createKilnMaterialDef(library) {
+export function createKilnMaterialDef(library, presentation = 'grouped') {
+    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,
@@ -97,7 +127,7 @@ export function createKilnMaterialDef(library) {
         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 {
@@ -135,14 +165,14 @@ export function createKilnMaterialDef(library) {
                     };
                 }
                 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.code === 'ENOENT')
-                            throw unknownMaterial(input.materialId, revisionId);
+                            throw unknownMaterial(input.materialId, revisionId, listCall);
                         throw error;
                     }
                 }

package/lib/tools/operation-contract.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { ActionRequirements } from "./actions.js";
+/** Domain action metadata shared by grouped execution and named presentations. */
+export interface KilnActionContract extends ActionRequirements {
+    readonly fields: readonly string[];
+    readonly description: string;
+}
+export declare function projectActionSchemas<A extends string>(name: string, input: z.ZodObject, actions: Readonly<Record<A, KilnActionContract>>): Record<A, z.ZodObject>;

package/lib/tools/operation-contract.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export function projectActionSchemas(name, input, actions) {
+    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;
+    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(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 = [];
+    for (const [action, contract] of Object.entries(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 = {};
+        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);
+}

package/lib/tools/operations.d.ts

@@ -0,0 +1,3 @@
+import type { KilnToolContext, KilnToolDef } from "./registry.js";
+/** Adapt domain operations in the engine, never in a transport-specific skin. */
+export declare function projectOperationDefs(defs: readonly KilnToolDef[], context: KilnToolContext): KilnToolDef[];

package/lib/tools/operations.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { projectActionSchemas } from "./operation-contract.js";
+/** Adapt domain operations in the engine, never in a transport-specific skin. */
+export function projectOperationDefs(defs, context) {
+    return defs.flatMap((def) => {
+        if (!context.assetLibrary &&
+            ['kiln_save', 'kiln_assets', 'kiln_present', 'kiln_export', 'kiln_import'].includes(def.name))
+            return [];
+        if (def.name === 'kiln_renderer')
+            return rendererOperations(def, context);
+        if (def.name === 'kiln_discover')
+            return discoveryOperations(def);
+        if (def.name === 'kiln_material')
+            return materialOperations(def);
+        if (def.name === 'kiln_assets')
+            return assetOperations(def, context);
+        return [def];
+    });
+}
+function actionTools(def) {
+    if (!(def.inputSchema instanceof z.ZodObject) || !def.actionContract)
+        throw new Error(`${def.name}: missing shared action contract`);
+    const schemas = projectActionSchemas(def.name, def.inputSchema, def.actionContract);
+    return Object.fromEntries(Object.entries(def.actionContract).map(([action, contract]) => [
+        action,
+        {
+            ...def,
+            actionContract: undefined,
+            name: `${def.name}_${action.replaceAll('-', '_')}`,
+            description: contract.description,
+            inputSchema: schemas[action],
+            run: async (raw) => def.run({ ...schemas[action].parse(raw), action }),
+        },
+    ]));
+}
+function assetOperations(def, context) {
+    const tools = actionTools(def);
+    const list = tools.list;
+    const listSchema = list.inputSchema;
+    // Remove only the legacy default: omission means all collections in this operation.
+    const collection = listSchema.shape.collection
+        .unwrap()
+        .optional()
+        .describe('Collection ID from kiln_assets_collections; omitted searches all configured collections.');
+    const inputSchema = listSchema.extend({ collection });
+    const search = {
+        ...list,
+        name: 'kiln_assets_search',
+        description: 'Search saved assets with pagination. Omit collection for all configured collections, or select one explicitly. Results identify exact collection, asset and revision; partial read failures are reported.',
+        inputSchema,
+        run: async (raw) => {
+            const input = inputSchema.parse(raw);
+            const { collection: _collection, ...filters } = input;
+            if (input.collection === undefined)
+                return tools.catalog.run(filters);
+            if (!context.assetLibrary?.collections().some((item) => item.id === input.collection))
+                throw new Error('Unknown collection. Use kiln_assets_collections to list available destinations.');
+            const result = (await list.run(input));
+            return {
+                errors: [],
+                total: result.total,
+                nextOffset: result.nextOffset,
+                assets: result.assets.map((asset) => ({ ...asset, collection: input.collection })),
+            };
+        },
+    };
+    return [tools.collections, search, tools.get, tools.restore];
+}
+function materialOperations(def) {
+    const tools = actionTools(def);
+    const presets = tools.presets;
+    const inputSchema = presets.inputSchema.extend({
+        scope: z.enum(['all', 'presets', 'saved']).default('all'),
+    });
+    const search = {
+        ...presets,
+        name: 'kiln_material_search',
+        description: 'Browse shipped material recipes and saved material revisions, optionally filtered by exact tag. Recipe IDs and saved material IDs are distinct. Use scope to select presets, saved or both.',
+        inputSchema,
+        run: async (raw) => {
+            const { scope, ...input } = inputSchema.parse(raw);
+            const recipes = scope === 'saved'
+                ? { presets: [] }
+                : (await presets.run(input));
+            const saved = scope === 'presets'
+                ? { materials: [] }
+                : (await tools.list.run(input));
+            return {
+                ok: true,
+                presets: recipes.presets.map((item) => ({ ...item, kind: 'preset' })),
+                materials: saved.materials.map((item) => ({ ...item, kind: 'saved' })),
+            };
+        },
+    };
+    const preset = tools['create-preset'];
+    const procedural = tools['create-procedural'];
+    const createInput = z.strictObject({
+        definition: z.discriminatedUnion('kind', [
+            preset.inputSchema.extend({ kind: z.literal('preset') }),
+            procedural.inputSchema.extend({ kind: z.literal('procedural') }),
+        ]),
+    });
+    const create = {
+        ...preset,
+        name: 'kiln_material_create',
+        description: 'Create and retain one immutable material from a preset or procedural definition. Presets require explicit seed, creator and license. Pin the returned materialId/revisionId for rendering. Does not fetch URLs or execute source.',
+        inputSchema: createInput,
+        run: async (raw) => {
+            const { kind, ...input } = createInput.parse(raw).definition;
+            return (kind === 'preset' ? preset : procedural).run(input);
+        },
+    };
+    return [search, tools.get, create, tools.import];
+}
+function rendererOperations(def, context) {
+    if (!context.renderCapabilities)
+        return [];
+    return ['status', ...(context.reprobeRenderer ? ['reprobe'] : [])].map((action) => {
+        const inputSchema = z.strictObject({});
+        return {
+            ...def,
+            name: `kiln_renderer_${action}`,
+            inputSchema,
+            run: async (raw) => {
+                inputSchema.parse(raw);
+                return def.run({ action });
+            },
+        };
+    });
+}
+function discoveryOperations(def) {
+    const original = def.inputSchema;
+    const { capabilities: _capabilities, ...fields } = original.shape;
+    const inputSchema = z.strictObject(fields);
+    const empty = z.strictObject({});
+    return [
+        {
+            ...def,
+            description: 'Discover geometry helpers, assemblies, recipes and complete input shapes. Search with modeling language or fetch up to six exact IDs. Use kiln_capabilities for current host facts.',
+            inputSchema,
+            run: async (raw) => def.run(inputSchema.parse(raw)),
+        },
+        {
+            ...def,
+            name: 'kiln_capabilities',
+            description: 'Inspect declared host capabilities, execution limits and available storage. Observed rendering fidelity is returned by each render.',
+            inputSchema: empty,
+            run: async (raw) => {
+                empty.parse(raw);
+                return def.run({ capabilities: true });
+            },
+        },
+    ];
+}

package/lib/tools/registry.d.ts

@@ -19,6 +19,8 @@ import { type BackdropId } from "../views/background.js";
 import type { TextureUsage } from "../textures.js";
 export declare const KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v5.html";
 export interface KilnToolDef {
+    /** Shared action ownership and requirements; never hand-maintained by transports. */
+    actionContract?: Readonly<Record<string, import("./operation-contract.js").KilnActionContract>>;
     outputSchema?: z.ZodType;
     /** Optional MCP App presentation; metadata is hidden from the language model. */
     ui?: {
@@ -770,6 +772,8 @@ export declare function createKilnEditDef(context?: KilnToolContext): KilnToolDe
 /** Neutral compatibility export. */
 export declare const kilnEditDef: KilnToolDef;
 export declare function createKilnProgramToolRegistry(suppliedContext?: KilnToolContext): KilnToolDef[];
+/** Opt-in named domain operations; grouped local/native contracts remain unchanged. */
+export declare function createKilnOperationToolRegistry(context?: KilnToolContext): KilnToolDef[];
 /** Canonical native workflow: shared definitions plus one host-owned terminal. */
 export declare function createKilnNativeToolRegistry(suppliedContext: KilnToolContext, completion: NativeCompletion): KilnToolDef[];
 /**
@@ -784,9 +788,9 @@ export declare function newestRevision(target: {
         parentRevision?: string | null;
         createdAt: string;
     }[]>;
-}, collection: string, assetId: string): Promise<string>;
+}, collection: string, assetId: string, listCall?: string): Promise<string>;
 /** Build one current-policy revision for ordinary save or explicit migration. */
 export declare function buildProgramAssetDraft(code: string, context: KilnToolContext, backdrop?: BackdropId): Promise<Pick<import("../assets.js").AssetDraft, 'code' | 'glb' | 'preview' | 'previewInfo' | 'build'>>;
 /** All asset operation schemas live here, alongside the existing tool definitions. */
-export declare function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[];
+export declare function createKilnAssetDefs(context: KilnToolContext, presentation?: 'grouped' | 'operations'): KilnToolDef[];
 export {};