Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

Add shared named tool contract and prepare Kiln 1.2.0 (#161)

Matthew Kissingeraabe0d1111b5
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 3ac8c035..f26243e3 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "kiln",
"description": "Build and revise 3D assets with your coding agent. Write JavaScript, inspect selected views, edit saved source revisions, and export GLB files locally.",
- "version": "1.1.0",
+ "version": "1.2.0",
"author": {
"name": "Matthew Kissinger"
},
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index c2be4fbc..c04a39a6 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "kiln",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Create, review, save, and refine procedural 3D assets with portable source and GLB collections.",
"author": {
"name": "Matthew Kissinger"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b0e47876..41ad3ddf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,18 @@ Source releases and installable package publication are separate milestones.
Published versions and tags are recorded by the npm registry; changing this file
does not publish a package.
+## 1.2.0
+
+- Add an opt-in named MCP operation presentation generated from the shared
+ registry, including consolidated asset search, material browsing and typed
+ material creation. Existing grouped local tools remain the default.
+- Share action requirements with schema generation and reject unclassified
+ fields/actions instead of silently dropping required inputs.
+- Omit unsupported renderer controls from the named presentation and use its
+ available tool names in capability guidance and resource-recovery messages.
+
+This additive SDK contract does not establish production-hosting readiness.
+
## 1.1.0
Existing-project setup, public host interfaces and simpler onboarding. Hosted
diff --git a/dist/agent-run.mjs b/dist/agent-run.mjs
index 7d1cc8d6..b9a27af3 100644
--- a/dist/agent-run.mjs
+++ b/dist/agent-run.mjs
@@ -32234,7 +32234,7 @@ import {
// src/tools/registry.ts
init_capture_cache();
init_assets();
-import { z as z20 } from "zod";
+import { z as z22 } from "zod";
// src/requirements-assets.ts
init_requirements_context();
@@ -32939,7 +32939,7 @@ function createKilnSourceDef(store) {
}
// src/engine-identity.ts
-var ENGINE_VERSION = "1.1.0";
+var ENGINE_VERSION = "1.2.0";
var ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
function engineIdentity() {
return { version: ENGINE_VERSION, installUrl: ENGINE_INSTALL_URL };
@@ -36395,7 +36395,7 @@ var MAX_RESPONSE_BYTES = 64 * 1024;
var MAX_TEXT_CHARS = 16 * 1024;
var DETAIL_RESULT_BUDGET = 15000;
var compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-function createDiscoveryService(source, index, capabilities, retirements = {}, notes = async () => []) {
+function createDiscoveryService(source, index, capabilities, retirements = {}, notes = async () => [], 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]));
@@ -36418,7 +36418,7 @@ function createDiscoveryService(source, index, capabilities, retirements = {}, n
"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) => ({
@@ -36599,12 +36599,12 @@ var snapshot;
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);
}
// src/tools/discovery.ts
@@ -36613,8 +36613,8 @@ init_capture_limits();
init_geometry_export();
init_community_exporter();
init_material_resources();
-function createKilnDiscoveryDef(context) {
- const run = createDiscovery(() => currentCapabilities(context), async () => projectNotes(context));
+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.",
@@ -36638,7 +36638,7 @@ function projectNotes(context) {
`Project ${projectId} is configured for this workspace and applies when projectId is omitted: read its brief, design, inventory and material pins first with kiln_project { action: "get", projectId: "${projectId}" }; projectId: null selects standalone work.`
] : [];
}
-async function currentCapabilities(context) {
+async function currentCapabilities(context, presentation) {
const externalEvaluator = Boolean(context.evaluatorPort) || context.evaluatorProfile === "evaluator-required";
const approvedTextures = context.approvedTextureResources ? context.approvedTextureResources() : externalEvaluator ? null : approvedTextureCatalogV1();
const textureSlots = approvedTextures === null ? null : {};
@@ -36667,7 +36667,7 @@ async function currentCapabilities(context) {
requiresModel: false
},
engine: engineIdentity(),
- project: {
+ 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'
@@ -36686,7 +36686,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"
},
@@ -37071,13 +37071,39 @@ var MATERIAL_ACTIONS = [
"create-procedural",
"import"
];
-var REQUIREMENTS2 = {
- 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" } }
+var 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."
+ }
};
var record7 = (description) => z16.record(z16.string(), z16.unknown()).optional().describe(description);
var tag = z16.string().min(1).max(80).optional().describe("presets, list: keep one tag.");
@@ -37099,13 +37125,13 @@ var materialResult = (material) => ({
material,
portableSpec: materialLibraryPortableSpec(material)
});
-var 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.`);
-async function onlyRevision(library, materialId) {
+var unknownMaterial = (materialId, revisionId, listCall) => new Error(`Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ""}. ${listCall} lists the materials in this workspace with their revision IDs.`);
+async function onlyRevision(library, materialId, listCall) {
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);
+ throw unknownMaterial(materialId, undefined, listCall);
throw new Error(`Material ${materialId} has ${revisions.length} revisions: ${revisions.join(", ")}. Pass revisionId to get one.`);
}
function aliasMaterialId(raw) {
@@ -37118,11 +37144,13 @@ 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 };
}
-function createKilnMaterialDef(library) {
+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,
@@ -37132,7 +37160,7 @@ function createKilnMaterialDef(library) {
async run(raw) {
assertMaterialJson(raw);
const input = materialToolInput.parse(aliasMaterialId(raw));
- requireActionFields("kiln_material", input.action, input, REQUIREMENTS2[input.action]);
+ requireActionFields("kiln_material", input.action, input, MATERIAL_CONTRACT[input.action]);
switch (input.action) {
case "presets":
return {
@@ -37168,12 +37196,12 @@ 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) {
if (error.code === "ENOENT")
- throw unknownMaterial(input.materialId, revisionId);
+ throw unknownMaterial(input.materialId, revisionId, listCall);
throw error;
}
}
@@ -37224,7 +37252,7 @@ async function persistedPreviewFidelity(fidelity, glb) {
var operationId = z17.string().regex(/^op_[a-f0-9-]{36}$/);
var assetId = z17.string().regex(/^[a-z][a-z0-9_-]{0,79}$/);
var REVIEW_ACTIONS = ["list", "get", "pin", "save"];
-var REQUIREMENTS3 = {
+var REQUIREMENTS2 = {
list: { required: [] },
get: { required: ["operationId"] },
pin: { required: ["operationId", "pinned"] },
@@ -37306,7 +37334,7 @@ function createKilnReviewDef(context) {
},
async run(raw) {
const input = reviewToolInput.parse(raw);
- requireActionFields("kiln_review", input.action, input, REQUIREMENTS3[input.action]);
+ requireActionFields("kiln_review", input.action, input, REQUIREMENTS2[input.action]);
if (input.action === "list") {
const snapshot = await store.snapshot({ projectId: input.projectId });
const offset = input.offset ?? 0;
@@ -37496,6 +37524,12 @@ function withWorkspaceContext(def, context) {
};
}
+// src/tools/operations.ts
+import { z as z21 } from "zod";
+
+// src/tools/operation-contract.ts
+import { z as z20 } from "zod";
+
// src/build-cache.ts
init_protocol();
init_requirements_context();
@@ -38191,11 +38225,11 @@ function derivativeReviewFidelity(receipts) {
...reasonCodes.length ? { reasonCodes } : {}
};
}
-var validateInput = z20.object({
- code: z20.string().describe("Kiln source code (defines `meta` + `build()`, optional `animate()`).")
+var validateInput = z22.object({
+ code: z22.string().describe("Kiln source code (defines `meta` + `build()`, optional `animate()`).")
});
-var renderInput = z20.object({
- code: z20.string().describe("Kiln source code to execute and render to an in-memory GLB.")
+var renderInput = z22.object({
+ code: z22.string().describe("Kiln source code to execute and render to an in-memory GLB.")
});
var renderViewsInput = renderInput.extend({ capture: captureInput, detail: reviewDetailInput });
var reviewDetailOptions = (context) => ({
@@ -38208,26 +38242,26 @@ var reviewDetailOptions = (context) => ({
}
});
var renderViewsBufferInput = renderViewsInput.omit({ code: true });
-var screenshotAnimationInput = z20.object({
+var screenshotAnimationInput = z22.object({
shot: cameraShotInput.optional(),
- measureParts: z20.array(cameraShotInput.shape.subject.unwrap()).min(1).max(16).optional().describe("Exact names or paths of subtrees measured together at each phase, independent of camera selection."),
- frames: z20.number().int().min(2).max(6).optional(),
- frameTimes: z20.array(z20.number().min(0).max(1)).min(1).max(9).optional().describe("Ordered phase fractions 0..1; mutually exclusive with frames."),
- framing: z20.enum(["locked", "follow"]).optional(),
- size: z20.number().int().min(128).max(1024).optional().describe("Frame size in px; default 256."),
+ measureParts: z22.array(cameraShotInput.shape.subject.unwrap()).min(1).max(16).optional().describe("Exact names or paths of subtrees measured together at each phase, independent of camera selection."),
+ frames: z22.number().int().min(2).max(6).optional(),
+ frameTimes: z22.array(z22.number().min(0).max(1)).min(1).max(9).optional().describe("Ordered phase fractions 0..1; mutually exclusive with frames."),
+ framing: z22.enum(["locked", "follow"]).optional(),
+ size: z22.number().int().min(128).max(1024).optional().describe("Frame size in px; default 256."),
detail: reviewDetailInput,
- code: z20.string().describe("Kiln source code to execute; must define animate() returning the named clip."),
- clip: z20.string().describe('The animation clip to view, by name (e.g. "walk", "attack"). Must be one your animate() returns.'),
- camera: z20.string().optional().describe("Camera angle: right (default — side profile, best for leg swing + knee bend direction), front " + "(reveals sideways/lateral motion), back, left, top, or three-quarter."),
- perFrame: z20.boolean().optional().describe("Return the frames as separate high-res images instead of one composite grid. Default false.")
+ code: z22.string().describe("Kiln source code to execute; must define animate() returning the named clip."),
+ clip: z22.string().describe('The animation clip to view, by name (e.g. "walk", "attack"). Must be one your animate() returns.'),
+ camera: z22.string().optional().describe("Camera angle: right (default — side profile, best for leg swing + knee bend direction), front " + "(reveals sideways/lateral motion), back, left, top, or three-quarter."),
+ perFrame: z22.boolean().optional().describe("Return the frames as separate high-res images instead of one composite grid. Default false.")
});
var screenshotAnimationAdvertisedInput = screenshotAnimationInput.extend({
shot: cameraShotRecordInput
});
-var viewInteriorInput = z20.object({
+var viewInteriorInput = z22.object({
capture: advancedCaptureInput.optional(),
- code: z20.string().describe("Kiln source code to execute and render with the roof hidden."),
- nodeName: z20.string().optional().describe("Override: lift the roof by exact node name instead of by role. Matches that node and its " + "children. Normally OMIT it — Kiln finds the roof from its semantic role (anything built " + 'with createRoofPlanes/createGableRoof), falling back to historical "Roof" naming.')
+ code: z22.string().describe("Kiln source code to execute and render with the roof hidden."),
+ nodeName: z22.string().optional().describe("Override: lift the roof by exact node name instead of by role. Matches that node and its " + "children. Normally OMIT it — Kiln finds the roof from its semantic role (anything built " + 'with createRoofPlanes/createGableRoof), falling back to historical "Roof" naming.')
});
var viewInteriorAdvertisedInput = viewInteriorInput.extend({ capture: captureRecordInput });
function runValidate(input, context) {
@@ -38242,11 +38276,11 @@ function runValidate(input, context) {
warnings: result.warnings.map((w) => w.fixHint ? `${w.message} (${w.fixHint})` : w.message)
};
}
-var partListInput = z20.object({
- query: z20.string().max(4096).optional().describe("Case-insensitive substring of name or exact encoded path; not a regex."),
- offset: z20.number().int().min(0).optional(),
- limit: z20.number().int().min(1).max(100).optional(),
- placement: z20.boolean().optional().describe("Add world position, rotation, scale, mirroring and bounds per part; pages of 50.")
+var partListInput = z22.object({
+ query: z22.string().max(4096).optional().describe("Case-insensitive substring of name or exact encoded path; not a regex."),
+ offset: z22.number().int().min(0).optional(),
+ limit: z22.number().int().min(1).max(100).optional(),
+ placement: z22.boolean().optional().describe("Add world position, rotation, scale, mirroring and bounds per part; pages of 50.")
}).strict();
var PLACEMENT_PAGE_LIMIT = 50;
async function listPartNames2(root, options = {}) {
@@ -38713,35 +38747,35 @@ function createKilnViewInteriorDef(context = {}) {
};
}
var kilnViewInteriorDef = createKilnViewInteriorDef();
-var attachmentEndpointInput = z20.object({
- subject: z20.object({ path: z20.string().optional(), name: z20.string().optional() }).strict(),
+var attachmentEndpointInput = z22.object({
+ subject: z22.object({ path: z22.string().optional(), name: z22.string().optional() }).strict(),
point: cameraVec3Input.optional()
}).strict();
-var surfacePairInput = z20.array(z20.string().max(4096)).length(2);
-var inspectInput = z20.object({
- image: z20.boolean().optional().describe("False: requires listParts/measure/surfacePairs/compare; no image or camera controls. Default true."),
+var surfacePairInput = z22.array(z22.string().max(4096)).length(2);
+var inspectInput = z22.object({
+ image: z22.boolean().optional().describe("False: requires listParts/measure/surfacePairs/compare; no image or camera controls. Default true."),
detail: reviewDetailInput,
listParts: partListInput.optional().describe("List exported-scene paths, including nested parts. Default 80, max 100 per page. Follow partListing.nextOffset with the same programRef/query. image:false avoids rendering."),
- surfacePairs: z20.array(surfacePairInput).min(1).max(12).optional().describe("[from,to] pairs of exact listParts paths or unambiguous node names; check surfaceMeasurements.status and each result."),
- compare: z20.object({
- programRef: z20.string().regex(programRefPattern),
- offset: z20.number().int().min(0).optional(),
- limit: z20.number().int().min(1).max(100).optional(),
- paths: z20.array(z20.string().max(4096)).min(1).max(12).optional().describe("Exact baseline node paths, scene-prefixed without primitive children. Complete subtree summaries.")
+ surfacePairs: z22.array(surfacePairInput).min(1).max(12).optional().describe("[from,to] pairs of exact listParts paths or unambiguous node names; check surfaceMeasurements.status and each result."),
+ compare: z22.object({
+ programRef: z22.string().regex(programRefPattern),
+ offset: z22.number().int().min(0).optional(),
+ limit: z22.number().int().min(1).max(100).optional(),
+ paths: z22.array(z22.string().max(4096)).min(1).max(12).optional().describe("Exact baseline node paths, scene-prefixed without primitive children. Complete subtree summaries.")
}).strict().optional().describe("Static geometry/material/transform/bounds under current host settings. Follow nextOffset; paths adds complete subtrees."),
- measure: z20.object({
- mode: z20.enum(["anchors", "surface"]).optional(),
+ measure: z22.object({
+ mode: z22.enum(["anchors", "surface"]).optional(),
from: attachmentEndpointInput,
to: attachmentEndpointInput
}).strict().optional().describe("Default anchors: origin/local-point distance. Surface: disjoint mesh triangles, omit points. Rest pose, asset units. Check status/bounds; no solid clearance/attachment proof."),
shot: cameraShotInput.optional().describe("Exact shot; omit part/view/orbit controls."),
- code: z20.string().describe("Kiln source code to execute and inspect."),
- part: z20.string().optional().describe("Frame named part and descendants (case-insensitive, substring fallback). Omit for whole asset."),
- view: z20.string().optional().describe("front/right/back/left/top/three-quarter (default). Orbit angles override."),
- azimuthDeg: z20.number().optional().describe("Orbit degrees: 0 front, 90 right, 180 back, 270 left. Wraps."),
- elevationDeg: z20.number().optional().describe("Elevation degrees: 0 eye level, positive above. Clamped -89..89."),
- zoom: z20.number().optional().describe("Bounds padding 1..4; default 1.2. Larger = more context."),
- isolate: z20.boolean().optional().describe("Hide surrounding geometry. Requires part; default false.")
+ code: z22.string().describe("Kiln source code to execute and inspect."),
+ part: z22.string().optional().describe("Frame named part and descendants (case-insensitive, substring fallback). Omit for whole asset."),
+ view: z22.string().optional().describe("front/right/back/left/top/three-quarter (default). Orbit angles override."),
+ azimuthDeg: z22.number().optional().describe("Orbit degrees: 0 front, 90 right, 180 back, 270 left. Wraps."),
+ elevationDeg: z22.number().optional().describe("Elevation degrees: 0 eye level, positive above. Clamped -89..89."),
+ zoom: z22.number().optional().describe("Bounds padding 1..4; default 1.2. Larger = more context."),
+ isolate: z22.boolean().optional().describe("Hide surrounding geometry. Requires part; default false.")
});
var inspectBufferInput = inspectInput.omit({ code: true });
var inspectAdvertisedInput = inspectInput.extend({ shot: cameraShotRecordInput });
@@ -38901,15 +38935,15 @@ function createKilnInspectDef(context = {}) {
};
}
var kilnInspectDef = createKilnInspectDef();
-var editOperationInput = z20.object({
- oldString: z20.string().describe("The exact text to replace, copied verbatim from the program (including whitespace and indentation, and with no line-number prefixes). Must be unique unless replaceAll is true."),
- newString: z20.string().describe("The replacement text. Use an empty string to delete."),
- replaceAll: z20.boolean().optional().describe("Replace every occurrence instead of failing when oldString matches more than once.")
+var editOperationInput = z22.object({
+ oldString: z22.string().describe("The exact text to replace, copied verbatim from the program (including whitespace and indentation, and with no line-number prefixes). Must be unique unless replaceAll is true."),
+ newString: z22.string().describe("The replacement text. Use an empty string to delete."),
+ replaceAll: z22.boolean().optional().describe("Replace every occurrence instead of failing when oldString matches more than once.")
});
-var editInput = z20.object({
- code: z20.string().describe("The Kiln program to patch. The full current source."),
- edits: z20.array(editOperationInput).min(1).max(20).describe("Edits applied in order against the program. If any one fails to match, none are applied and the reply says which. Batch related changes into a single call."),
- render: z20.boolean().optional().describe("Render the patched program and return the views (default true). false = patch only."),
+var editInput = z22.object({
+ code: z22.string().describe("The Kiln program to patch. The full current source."),
+ edits: z22.array(editOperationInput).min(1).max(20).describe("Edits applied in order against the program. If any one fails to match, none are applied and the reply says which. Batch related changes into a single call."),
+ render: z22.boolean().optional().describe("Render the patched program and return the views (default true). false = patch only."),
capture: captureInput,
detail: reviewDetailInput
});
@@ -39135,24 +39169,27 @@ function withCaptureCache(context) {
} : {}
};
}
-var rendererInput = z20.strictObject({
- action: z20.enum(["status", "reprobe"]).default("status")
+var rendererInput = z22.strictObject({
+ action: z22.enum(["status", "reprobe"]).default("status")
});
-async function readSavedRevision(target, collection, assetId, revisionId) {
+async function readSavedRevision(target, collection, assetId, revisionId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
try {
return await target.read(collection, assetId, revisionId);
} catch (error) {
if (error.code === "ENOENT")
- throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. kiln_assets { action: 'list', collection: '${collection}' } lists the saved revisions.`);
+ throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. ${listCall} lists the saved revisions.`);
throw error;
}
}
function createKilnProgramToolRegistry(suppliedContext = {}) {
+ return createProgramDefs(suppliedContext, "grouped");
+}
+function createProgramDefs(suppliedContext, presentation) {
toolRequirements(suppliedContext);
const store = suppliedContext.programStore ?? new MemoryProgramStore;
const context = withCaptureCache(withBuildCache({ ...suppliedContext, programStore: store }));
return [
- createKilnDiscoveryDef({ ...suppliedContext, programStore: store }),
+ createKilnDiscoveryDef({ ...suppliedContext, programStore: store }, presentation),
{
name: "kiln_renderer",
description: "Inspect status, or reprobe after renderer setup/repair to refresh this session and reset failed starts. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart. Read viewFidelity after rendering.",
@@ -39192,7 +39229,7 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
].map((def) => withProgramReferences(def, store, context.readSourceFile)),
createKilnSourceDef(store),
...context.projectStore ? [createKilnProjectDef(context.projectStore, context.projectBundleReader)] : [],
- ...context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary)] : [],
+ ...context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary, presentation)] : [],
...context.reviewStore && context.assetLibrary ? [
createKilnReviewDef({
reviewStore: context.reviewStore,
@@ -39200,7 +39237,7 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
requirements: context.requirements
})
] : [],
- ...createKilnAssetDefs({ ...context, programStore: store })
+ ...createKilnAssetDefs({ ...context, programStore: store }, presentation)
].map((def) => withWorkspaceContext(def, context)).map((def) => ({
...def,
annotations: {
@@ -39220,14 +39257,14 @@ function createKilnNativeToolRegistry(suppliedContext, completion) {
programStore: suppliedContext.programStore ?? new MemoryProgramStore,
programArtifacts: suppliedContext.programArtifacts ?? new ProgramArtifactStore
};
- const inputSchema = z20.strictObject({
- programRef: z20.string().regex(programRefPattern)
+ const inputSchema = z22.strictObject({
+ programRef: z22.string().regex(programRefPattern)
});
- const skillResourceInput = z20.strictObject({
- skill: z20.string().min(1).max(64),
- path: z20.string().min(1).max(240).optional(),
- offset: z20.number().int().min(0).max(262144).default(0),
- limit: z20.number().int().min(1).max(16000).default(12000)
+ const skillResourceInput = z22.strictObject({
+ skill: z22.string().min(1).max(64),
+ path: z22.string().min(1).max(240).optional(),
+ offset: z22.number().int().min(0).max(262144).default(0),
+ limit: z22.number().int().min(1).max(16000).default(12000)
});
const delivery = new Set([
"kiln_save",
@@ -39278,14 +39315,41 @@ function createKilnNativeToolRegistry(suppliedContext, completion) {
];
}
var assetSelector = {
- collection: z20.string().regex(/^[a-z][a-z0-9_-]{0,79}$/).describe("Collection ID (list with kiln_assets action=collections): the user destination, else project.").default("project"),
- assetId: z20.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
- revisionId: z20.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)
+ collection: z22.string().regex(/^[a-z][a-z0-9_-]{0,79}$/).describe("Collection ID (list with kiln_assets action=collections): the user destination, else project.").default("project"),
+ assetId: z22.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
+ revisionId: z22.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)
};
-async function newestRevision(target, collection, assetId) {
+var ASSET_CONTRACT = {
+ collections: {
+ fields: [],
+ required: [],
+ description: "List configured asset storage collections. Collection is not project membership."
+ },
+ catalog: {
+ fields: ["assetId", "query", "offset", "limit"],
+ required: [],
+ description: "Search saved assets across configured collections with pagination."
+ },
+ list: {
+ fields: ["collection", "assetId", "query", "offset", "limit"],
+ required: [],
+ description: "Search saved assets in one collection with pagination."
+ },
+ get: {
+ fields: ["collection", "assetId", "revisionId"],
+ required: ["assetId"],
+ description: "Read a saved revision and its download descriptors. Omit revisionId for the newest revision."
+ },
+ restore: {
+ fields: ["collection", "assetId", "revisionId"],
+ required: ["assetId"],
+ description: "Restore exact saved source as programRef for editing or rendering. Omit revisionId for the newest revision. Does not overwrite the saved revision. Binary-only assets have no source."
+ }
+};
+async function newestRevision(target, collection, assetId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
const revisions = (await target.list(collection)).filter((a) => a.assetId === assetId);
if (!revisions.length)
- throw new Error(`Unknown asset ${assetId} in ${collection}; kiln_assets { action: 'list', collection: '${collection}' } lists them.`);
+ throw new Error(`Unknown asset ${assetId} in ${collection}; ${listCall} lists them.`);
const parents = new Set(revisions.map((a) => a.parentRevision).filter(Boolean));
const heads = revisions.filter((a) => !parents.has(a.revisionId));
const newest = (heads.length ? heads : revisions).sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
@@ -39350,7 +39414,12 @@ async function buildProgramAssetDraft(code, context, backdrop) {
}
};
}
-function createKilnAssetDefs(context) {
+function createKilnAssetDefs(context, presentation = "grouped") {
+ const listCall = (collection) => presentation === "operations" ? `kiln_assets_search({ collection: '${collection}' })` : `kiln_assets { action: 'list', collection: '${collection}' }`;
+ const selector = presentation === "operations" ? {
+ ...assetSelector,
+ collection: assetSelector.collection.describe("Collection ID from kiln_assets_collections; default project.")
+ } : assetSelector;
const library = () => {
if (!context.assetLibrary)
throw new Error("No asset library configured. The local CLI/MCP host supplies workspace collections; embedded hosts must inject assetLibrary.");
@@ -39378,38 +39447,38 @@ function createKilnAssetDefs(context) {
resources: (await Promise.resolve().then(() => (init_assets_resources(), exports_assets_resources))).assetLinks(collection, asset),
downloadUrls: await context.assetDownloadUrls?.(collection, asset.assetId, asset.revisionId)
});
- const saveInput = z20.object({
- collection: assetSelector.collection,
- programRef: z20.string(),
- name: z20.string().min(1).max(200),
- assetId: assetSelector.assetId.optional(),
- parentRevision: assetSelector.revisionId.optional(),
- tags: z20.array(z20.string().max(80)).max(30).optional(),
- brief: z20.string().max(8000).optional(),
- description: z20.string().max(4000).optional(),
- attribution: z20.object({
- model: z20.string().max(200).optional(),
- harness: z20.string().max(200).optional(),
- author: z20.string().max(200).optional()
+ const saveInput = z22.object({
+ collection: selector.collection,
+ programRef: z22.string(),
+ name: z22.string().min(1).max(200),
+ assetId: selector.assetId.optional(),
+ parentRevision: selector.revisionId.optional(),
+ tags: z22.array(z22.string().max(80)).max(30).optional(),
+ brief: z22.string().max(8000).optional(),
+ description: z22.string().max(4000).optional(),
+ attribution: z22.object({
+ model: z22.string().max(200).optional(),
+ harness: z22.string().max(200).optional(),
+ author: z22.string().max(200).optional()
}).optional(),
- backdrop: z20.enum(BACKDROP_IDS).optional().describe("Preview backdrop: the one the reviewed sheet used.")
- });
- const assetsInput = z20.object({
- action: z20.enum(["collections", "catalog", "list", "get", "restore"]).default("list"),
- collection: assetSelector.collection,
- assetId: assetSelector.assetId.optional(),
- revisionId: assetSelector.revisionId.optional().describe("get, restore: the saved revision; omitted, the newest."),
- query: z20.string().max(200).optional(),
- offset: z20.number().int().min(0).default(0),
- limit: z20.number().int().min(1).max(50).default(20)
- });
- const exportInput = z20.object(assetSelector);
+ backdrop: z22.enum(BACKDROP_IDS).optional().describe("Preview backdrop: the one the reviewed sheet used.")
+ });
+ const assetsInput = z22.object({
+ action: z22.enum(["collections", "catalog", "list", "get", "restore"]).default("list"),
+ collection: selector.collection,
+ assetId: selector.assetId.optional(),
+ revisionId: selector.revisionId.optional().describe("get, restore: the saved revision; omitted, the newest."),
+ query: z22.string().max(200).optional(),
+ offset: z22.number().int().min(0).default(0),
+ limit: z22.number().int().min(1).max(50).default(20)
+ });
+ const exportInput = z22.object(selector);
const profileExportInput = exportInput.extend({
- profile: z20.enum(["editable", "runtime"]).default("editable").describe("editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.")
+ profile: z22.enum(["editable", "runtime"]).default("editable").describe("editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.")
});
- const importInput = z20.object({
- ...assetSelector,
- sourceCollection: assetSelector.collection
+ const importInput = z22.object({
+ ...selector,
+ sourceCollection: selector.collection
});
return [
{
@@ -39425,7 +39494,7 @@ function createKilnAssetDefs(context) {
requirements: activeRequirements.binding
};
if (input.assetId && input.parentRevision) {
- const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision);
+ const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision, listCall(input.collection));
assertSavedRequirementsAuthorized(previous.manifest, activeRequirements);
}
const code = await context.programStore.get(input.programRef);
@@ -39440,6 +39509,7 @@ function createKilnAssetDefs(context) {
name: "kiln_assets",
description: "Browse saved assets: collections discovers storage; catalog searches all configured collections; list searches one. Both searches paginate. get returns a build record/downloads; restore loads exact source for kiln_source/kiln_edit. Collection is not project membership. Binary-only assets cannot restore source.",
inputSchema: assetsInput,
+ actionContract: ASSET_CONTRACT,
run: async (raw) => {
const input = assetsInput.parse(raw);
const activeRequirements = toolRequirements(context);
@@ -39484,10 +39554,10 @@ function createKilnAssetDefs(context) {
}))
};
}
- if (!input.assetId)
+ if (ASSET_CONTRACT[input.action].required.some((field) => !input[field]))
throw new Error(`kiln_assets ${input.action} requires assetId; kiln_assets { action: 'list', collection: '${input.collection}' } lists them.`);
- const revisionId = input.revisionId ?? await newestRevision(target, input.collection, input.assetId);
- const record = await readSavedRevision(target, input.collection, input.assetId, revisionId);
+ const revisionId = input.revisionId ?? await newestRevision(target, input.collection, input.assetId, listCall(input.collection));
+ const record = await readSavedRevision(target, input.collection, input.assetId, revisionId, listCall(input.collection));
if (input.action === "get")
return links(input.collection, record.manifest);
const saved = assertSavedRequirementsAuthorized(record.manifest, activeRequirements);
@@ -39507,9 +39577,9 @@ function createKilnAssetDefs(context) {
name: "kiln_present",
description: "Present one exact saved revision. Supporting MCP App clients show an interactive 3D card with GLB, editable ZIP, and source downloads. Every host receives exact artifact descriptors with resource URIs in the JSON result; verified hosts may also receive core MCP resource-link blocks. This tool does not launch a local browser in coding harnesses. Call after saving or when the user wants to see or download an asset.",
inputSchema: exportInput,
- outputSchema: z20.object({
- ok: z20.literal(true),
- collection: z20.string(),
+ outputSchema: z22.object({
+ ok: z22.literal(true),
+ collection: z22.string(),
asset: assetManifestSchema.pick({
assetId: true,
revisionId: true,
@@ -39520,25 +39590,25 @@ function createKilnAssetDefs(context) {
editable: true,
files: true
}).extend({
- build: z20.object({
- engine: z20.string(),
- rebuild: z20.enum(["engine-required", "external-dependencies-required"]),
- warningCount: z20.number().int(),
- warnings: z20.array(z20.string())
+ build: z22.object({
+ engine: z22.string(),
+ rebuild: z22.enum(["engine-required", "external-dependencies-required"]),
+ warningCount: z22.number().int(),
+ warnings: z22.array(z22.string())
}).optional()
}),
- resources: z20.array(z20.object({
- type: z20.literal("resource_link"),
- name: z20.string(),
- uri: z20.string(),
- mimeType: z20.string(),
- size: z20.number().int().nonnegative(),
- annotations: z20.object({
- audience: z20.array(z20.enum(["user", "assistant"])),
- priority: z20.number()
+ resources: z22.array(z22.object({
+ type: z22.literal("resource_link"),
+ name: z22.string(),
+ uri: z22.string(),
+ mimeType: z22.string(),
+ size: z22.number().int().nonnegative(),
+ annotations: z22.object({
+ audience: z22.array(z22.enum(["user", "assistant"])),
+ priority: z22.number()
})
})),
- downloadUrls: z20.record(z20.string(), z20.string()).optional()
+ downloadUrls: z22.record(z22.string(), z22.string()).optional()
}),
ui: {
resourceUri: KILN_ASSET_WIDGET_URI,
@@ -39555,7 +39625,7 @@ function createKilnAssetDefs(context) {
inputSchema: profileExportInput,
run: async (raw) => {
const input = profileExportInput.parse(raw);
- const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId);
+ const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId, listCall(input.collection));
await Promise.resolve().then(() => init_draw_diagnostics());
if (input.profile === "runtime") {
const output = await (await Promise.resolve().then(() => (init_asset_export(), exports_asset_export))).exportAssetGlb(record, {
@@ -39589,7 +39659,7 @@ function createKilnAssetDefs(context) {
run: async (raw) => {
const input = importInput.parse(raw);
const target = library();
- const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId);
+ const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId, listCall(input.sourceCollection));
await target.import(input.collection, [record]);
return links(input.collection, record.manifest);
}
diff --git a/dist/build.json b/dist/build.json
index e2423ba9..8a420314 100644
--- a/dist/build.json
+++ b/dist/build.json
@@ -2,10 +2,10 @@
"schemaVersion": 1,
"entries": {
"worker": {
- "identity": "sha256:adbc219831fef0d5cac0d2050a8171a3fd11860bb632b0e27545ed1cd571acfc",
- "engineVersion": "1.1.0",
+ "identity": "sha256:346e43cad83c3aa102b27bffa4c4a3e2a276058b5889ed44125596b9634eab5e",
+ "engineVersion": "1.2.0",
"toolchain": "[email protected]",
- "sourceHash": "31bf69f080bbcca05a98b7c485b5642e90e7f63625f4b03d89a91fbbb5f81e9c",
+ "sourceHash": "86a6a158a1c48dc9b8d1bf7b6b2a551edf7b1daa080c9c7402eec4ba246e3e7a",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "bb179f2715f8fd9059898ef3a2028947e8f5f7e7979ad7eafe59d7a464c18f9f",
"dependencies": {
@@ -39,10 +39,10 @@
"bundleHash": "sha256:37098a17b5304a5f5746131c9652498d937a5181c0fb0975861dec999721d5be"
},
"agent-run": {
- "identity": "sha256:adbc219831fef0d5cac0d2050a8171a3fd11860bb632b0e27545ed1cd571acfc",
- "engineVersion": "1.1.0",
+ "identity": "sha256:346e43cad83c3aa102b27bffa4c4a3e2a276058b5889ed44125596b9634eab5e",
+ "engineVersion": "1.2.0",
"toolchain": "[email protected]",
- "sourceHash": "31bf69f080bbcca05a98b7c485b5642e90e7f63625f4b03d89a91fbbb5f81e9c",
+ "sourceHash": "86a6a158a1c48dc9b8d1bf7b6b2a551edf7b1daa080c9c7402eec4ba246e3e7a",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "bb179f2715f8fd9059898ef3a2028947e8f5f7e7979ad7eafe59d7a464c18f9f",
"dependencies": {
@@ -73,13 +73,13 @@
},
"target": "node",
"file": "agent-run.mjs",
- "bundleHash": "sha256:3fdb17224ded3a55afff6cf0b84f3de902728834d32ffe6e0c449ed3b71ac641"
+ "bundleHash": "sha256:ba89d90f15b95d682dc64320e797ebe21c9cc281613eb0f68eab1855d56e4aca"
},
"agent-providers": {
- "identity": "sha256:adbc219831fef0d5cac0d2050a8171a3fd11860bb632b0e27545ed1cd571acfc",
- "engineVersion": "1.1.0",
+ "identity": "sha256:346e43cad83c3aa102b27bffa4c4a3e2a276058b5889ed44125596b9634eab5e",
+ "engineVersion": "1.2.0",
"toolchain": "[email protected]",
- "sourceHash": "31bf69f080bbcca05a98b7c485b5642e90e7f63625f4b03d89a91fbbb5f81e9c",
+ "sourceHash": "86a6a158a1c48dc9b8d1bf7b6b2a551edf7b1daa080c9c7402eec4ba246e3e7a",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "bb179f2715f8fd9059898ef3a2028947e8f5f7e7979ad7eafe59d7a464c18f9f",
"dependencies": {
@@ -113,10 +113,10 @@
"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"
},
"mcp": {
- "identity": "sha256:adbc219831fef0d5cac0d2050a8171a3fd11860bb632b0e27545ed1cd571acfc",
- "engineVersion": "1.1.0",
+ "identity": "sha256:346e43cad83c3aa102b27bffa4c4a3e2a276058b5889ed44125596b9634eab5e",
+ "engineVersion": "1.2.0",
"toolchain": "[email protected]",
- "sourceHash": "31bf69f080bbcca05a98b7c485b5642e90e7f63625f4b03d89a91fbbb5f81e9c",
+ "sourceHash": "86a6a158a1c48dc9b8d1bf7b6b2a551edf7b1daa080c9c7402eec4ba246e3e7a",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "bb179f2715f8fd9059898ef3a2028947e8f5f7e7979ad7eafe59d7a464c18f9f",
"dependencies": {
@@ -147,13 +147,13 @@
},
"target": "node",
"file": "mcp-server.mjs",
- "bundleHash": "sha256:8de0309a6995e5d49ed2c261b9e7cb7ab6d7eab13c2f2f16f12511d8fd703a27"
+ "bundleHash": "sha256:c9966be32621d48519ab7c0088ed808f155bc4450eaf09ed4ce2a6c843b64cc7"
},
"cli": {
- "identity": "sha256:adbc219831fef0d5cac0d2050a8171a3fd11860bb632b0e27545ed1cd571acfc",
- "engineVersion": "1.1.0",
+ "identity": "sha256:346e43cad83c3aa102b27bffa4c4a3e2a276058b5889ed44125596b9634eab5e",
+ "engineVersion": "1.2.0",
"toolchain": "[email protected]",
- "sourceHash": "31bf69f080bbcca05a98b7c485b5642e90e7f63625f4b03d89a91fbbb5f81e9c",
+ "sourceHash": "86a6a158a1c48dc9b8d1bf7b6b2a551edf7b1daa080c9c7402eec4ba246e3e7a",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "bb179f2715f8fd9059898ef3a2028947e8f5f7e7979ad7eafe59d7a464c18f9f",
"dependencies": {
@@ -184,13 +184,13 @@
},
"target": "node",
"file": "cli.mjs",
- "bundleHash": "sha256:d7ebfce5b290a5da221c5890778ddc3ceaec1beb5022360aef12a82e1a193685"
+ "bundleHash": "sha256:c1030e6929a5449b04f79d3f2bc7d331ccabc523e664cf537dbe42ab83a2d86b"
},
"engine": {
- "identity": "sha256:adbc219831fef0d5cac0d2050a8171a3fd11860bb632b0e27545ed1cd571acfc",
- "engineVersion": "1.1.0",
+ "identity": "sha256:346e43cad83c3aa102b27bffa4c4a3e2a276058b5889ed44125596b9634eab5e",
+ "engineVersion": "1.2.0",
"toolchain": "[email protected]",
- "sourceHash": "31bf69f080bbcca05a98b7c485b5642e90e7f63625f4b03d89a91fbbb5f81e9c",
+ "sourceHash": "86a6a158a1c48dc9b8d1bf7b6b2a551edf7b1daa080c9c7402eec4ba246e3e7a",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "bb179f2715f8fd9059898ef3a2028947e8f5f7e7979ad7eafe59d7a464c18f9f",
"dependencies": {
@@ -221,7 +221,7 @@
},
"target": "node",
"file": "mcp-engine.mjs",
- "bundleHash": "sha256:3cb423f905dddc8b3c248db00304b2da976e69c0c899e0f63bbdf065f9af8f08"
+ "bundleHash": "sha256:d286370c41304a3bcb313fb9427def5d5aad213d7b75d3ca10cabdc4f7db42df"
}
}
}
diff --git a/dist/cli.mjs b/dist/cli.mjs
index c450b9dd..386112d8 100644
--- a/dist/cli.mjs
+++ b/dist/cli.mjs
@@ -36171,7 +36171,7 @@ var init_program_artifacts = __esm(() => {
function engineIdentity() {
return { version: ENGINE_VERSION, installUrl: ENGINE_INSTALL_URL };
}
-var ENGINE_VERSION = "1.1.0", ENGINE_INSTALL_URL;
+var ENGINE_VERSION = "1.2.0", ENGINE_INSTALL_URL;
var init_engine_identity = __esm(() => {
ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
});
@@ -39652,7 +39652,7 @@ var init_query_schema = __esm(() => {
});
// src/discovery/service.ts
-function createDiscoveryService(source, index, capabilities, retirements = {}, notes = async () => []) {
+function createDiscoveryService(source, index, capabilities, retirements = {}, notes = async () => [], 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]));
@@ -39675,7 +39675,7 @@ function createDiscoveryService(source, index, capabilities, retirements = {}, n
"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) => ({
@@ -39861,12 +39861,12 @@ var init_service = __esm(() => {
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") {
snapshot2 ??= (() => {
const entries = listDiscoveryEntries();
return { entries, index: createLexicalDiscoveryIndex(entries) };
})();
- return createDiscoveryService(snapshot2.entries, snapshot2.index, capabilities, REMOVED_AUTHORING_HELPERS, notes);
+ return createDiscoveryService(snapshot2.entries, snapshot2.index, capabilities, REMOVED_AUTHORING_HELPERS, notes, capabilitiesCall);
}
var snapshot2;
var init_discovery = __esm(() => {
@@ -39881,8 +39881,8 @@ var init_discovery = __esm(() => {
});
// src/tools/discovery.ts
-function createKilnDiscoveryDef(context) {
- const run = createDiscovery(() => currentCapabilities(context), async () => projectNotes(context));
+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.",
@@ -39906,7 +39906,7 @@ function projectNotes(context) {
`Project ${projectId} is configured for this workspace and applies when projectId is omitted: read its brief, design, inventory and material pins first with kiln_project { action: "get", projectId: "${projectId}" }; projectId: null selects standalone work.`
] : [];
}
-async function currentCapabilities(context) {
+async function currentCapabilities(context, presentation) {
const externalEvaluator = Boolean(context.evaluatorPort) || context.evaluatorProfile === "evaluator-required";
const approvedTextures = context.approvedTextureResources ? context.approvedTextureResources() : externalEvaluator ? null : approvedTextureCatalogV1();
const textureSlots = approvedTextures === null ? null : {};
@@ -39935,7 +39935,7 @@ async function currentCapabilities(context) {
requiresModel: false
},
engine: engineIdentity(),
- project: {
+ 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'
@@ -39954,7 +39954,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"
},
@@ -40340,12 +40340,12 @@ var init_material_presets = __esm(() => {
// src/tools/materials.ts
import { z as z18 } from "zod";
-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).sort();
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.`);
}
function aliasMaterialId(raw) {
@@ -40358,11 +40358,13 @@ 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 };
}
-function createKilnMaterialDef(library) {
+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,
@@ -40372,7 +40374,7 @@ function createKilnMaterialDef(library) {
async run(raw) {
assertMaterialJson(raw);
const input = materialToolInput.parse(aliasMaterialId(raw));
- requireActionFields("kiln_material", input.action, input, REQUIREMENTS2[input.action]);
+ requireActionFields("kiln_material", input.action, input, MATERIAL_CONTRACT[input.action]);
switch (input.action) {
case "presets":
return {
@@ -40408,12 +40410,12 @@ 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) {
if (error.code === "ENOENT")
- throw unknownMaterial(input.materialId, revisionId);
+ throw unknownMaterial(input.materialId, revisionId, listCall);
throw error;
}
}
@@ -40437,11 +40439,11 @@ function createKilnMaterialDef(library) {
}
};
}
-var MATERIAL_ACTIONS, REQUIREMENTS2, record7 = (description) => z18.record(z18.string(), z18.unknown()).optional().describe(description), tag, materialToolInput, materialResult = (material) => ({
+var MATERIAL_ACTIONS, MATERIAL_CONTRACT, record7 = (description) => z18.record(z18.string(), z18.unknown()).optional().describe(description), tag, materialToolInput, materialResult = (material) => ({
ok: true,
material,
portableSpec: materialLibraryPortableSpec(material)
-}), 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.`);
+}), unknownMaterial = (materialId, revisionId, listCall) => new Error(`Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ""}. ${listCall} lists the materials in this workspace with their revision IDs.`);
var init_materials = __esm(() => {
init_material_library();
init_material_library_node();
@@ -40454,13 +40456,39 @@ var init_materials = __esm(() => {
"create-procedural",
"import"
];
- REQUIREMENTS2 = {
- 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" } }
+ 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."
+ }
};
tag = z18.string().min(1).max(80).optional().describe("presets, list: keep one tag.");
materialToolInput = z18.strictObject({
@@ -40556,7 +40584,7 @@ function createKilnReviewDef(context) {
},
async run(raw) {
const input = reviewToolInput.parse(raw);
- requireActionFields("kiln_review", input.action, input, REQUIREMENTS3[input.action]);
+ requireActionFields("kiln_review", input.action, input, REQUIREMENTS2[input.action]);
if (input.action === "list") {
const snapshot = await store.snapshot({ projectId: input.projectId });
const offset = input.offset ?? 0;
@@ -40663,7 +40691,7 @@ function createKilnReviewDef(context) {
}
};
}
-var operationId, assetId, REVIEW_ACTIONS, REQUIREMENTS3, reviewToolInput, DEFAULT_PAGE = 20;
+var operationId, assetId, REVIEW_ACTIONS, REQUIREMENTS2, reviewToolInput, DEFAULT_PAGE = 20;
var init_review = __esm(() => {
init_assets();
init_requirements_context();
@@ -40674,7 +40702,7 @@ var init_review = __esm(() => {
operationId = z19.string().regex(/^op_[a-f0-9-]{36}$/);
assetId = z19.string().regex(/^[a-z][a-z0-9_-]{0,79}$/);
REVIEW_ACTIONS = ["list", "get", "pin", "save"];
- REQUIREMENTS3 = {
+ REQUIREMENTS2 = {
list: { required: [] },
get: { required: ["operationId"] },
pin: { required: ["operationId", "pinned"] },
@@ -40765,6 +40793,16 @@ var init_workspace2 = __esm(() => {
]);
});
+// src/tools/operation-contract.ts
+import { z as z21 } from "zod";
+var init_operation_contract = () => {};
+
+// src/tools/operations.ts
+import { z as z22 } from "zod";
+var init_operations = __esm(() => {
+ init_operation_contract();
+});
+
// src/edit-buffer.ts
class KilnDraftBuffer {
buf;
@@ -42363,7 +42401,7 @@ var init_asset_widget = __esm(() => {
});
// src/tools/registry.ts
-import { z as z21 } from "zod";
+import { z as z23 } from "zod";
import * as THREE46 from "three";
function proceduralTextureMaterialContract(rendered, context) {
const required = [...new Set(context.requiredProceduralTextureUsages ?? [])];
@@ -43427,21 +43465,24 @@ function withCaptureCache(context) {
} : {}
};
}
-async function readSavedRevision(target, collection, assetId, revisionId) {
+async function readSavedRevision(target, collection, assetId, revisionId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
try {
return await target.read(collection, assetId, revisionId);
} catch (error) {
if (error.code === "ENOENT")
- throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. kiln_assets { action: 'list', collection: '${collection}' } lists the saved revisions.`);
+ throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. ${listCall} lists the saved revisions.`);
throw error;
}
}
function createKilnProgramToolRegistry(suppliedContext = {}) {
+ return createProgramDefs(suppliedContext, "grouped");
+}
+function createProgramDefs(suppliedContext, presentation) {
toolRequirements(suppliedContext);
const store = suppliedContext.programStore ?? new MemoryProgramStore;
const context = withCaptureCache(withBuildCache({ ...suppliedContext, programStore: store }));
return [
- createKilnDiscoveryDef({ ...suppliedContext, programStore: store }),
+ createKilnDiscoveryDef({ ...suppliedContext, programStore: store }, presentation),
{
name: "kiln_renderer",
description: "Inspect status, or reprobe after renderer setup/repair to refresh this session and reset failed starts. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart. Read viewFidelity after rendering.",
@@ -43481,7 +43522,7 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
].map((def) => withProgramReferences(def, store, context.readSourceFile)),
createKilnSourceDef(store),
...context.projectStore ? [createKilnProjectDef(context.projectStore, context.projectBundleReader)] : [],
- ...context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary)] : [],
+ ...context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary, presentation)] : [],
...context.reviewStore && context.assetLibrary ? [
createKilnReviewDef({
reviewStore: context.reviewStore,
@@ -43489,7 +43530,7 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
requirements: context.requirements
})
] : [],
- ...createKilnAssetDefs({ ...context, programStore: store })
+ ...createKilnAssetDefs({ ...context, programStore: store }, presentation)
].map((def) => withWorkspaceContext(def, context)).map((def) => ({
...def,
annotations: {
@@ -43501,10 +43542,10 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
}
}));
}
-async function newestRevision(target, collection, assetId) {
+async function newestRevision(target, collection, assetId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
const revisions = (await target.list(collection)).filter((a) => a.assetId === assetId);
if (!revisions.length)
- throw new Error(`Unknown asset ${assetId} in ${collection}; kiln_assets { action: 'list', collection: '${collection}' } lists them.`);
+ throw new Error(`Unknown asset ${assetId} in ${collection}; ${listCall} lists them.`);
const parents = new Set(revisions.map((a) => a.parentRevision).filter(Boolean));
const heads = revisions.filter((a) => !parents.has(a.revisionId));
const newest = (heads.length ? heads : revisions).sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
@@ -43569,7 +43610,12 @@ async function buildProgramAssetDraft(code, context, backdrop) {
}
};
}
-function createKilnAssetDefs(context) {
+function createKilnAssetDefs(context, presentation = "grouped") {
+ const listCall = (collection) => presentation === "operations" ? `kiln_assets_search({ collection: '${collection}' })` : `kiln_assets { action: 'list', collection: '${collection}' }`;
+ const selector = presentation === "operations" ? {
+ ...assetSelector,
+ collection: assetSelector.collection.describe("Collection ID from kiln_assets_collections; default project.")
+ } : assetSelector;
const library = () => {
if (!context.assetLibrary)
throw new Error("No asset library configured. The local CLI/MCP host supplies workspace collections; embedded hosts must inject assetLibrary.");
@@ -43597,38 +43643,38 @@ function createKilnAssetDefs(context) {
resources: (await Promise.resolve().then(() => (init_assets_resources(), exports_assets_resources))).assetLinks(collection, asset),
downloadUrls: await context.assetDownloadUrls?.(collection, asset.assetId, asset.revisionId)
});
- const saveInput = z21.object({
- collection: assetSelector.collection,
- programRef: z21.string(),
- name: z21.string().min(1).max(200),
- assetId: assetSelector.assetId.optional(),
- parentRevision: assetSelector.revisionId.optional(),
- tags: z21.array(z21.string().max(80)).max(30).optional(),
- brief: z21.string().max(8000).optional(),
- description: z21.string().max(4000).optional(),
- attribution: z21.object({
- model: z21.string().max(200).optional(),
- harness: z21.string().max(200).optional(),
- author: z21.string().max(200).optional()
+ const saveInput = z23.object({
+ collection: selector.collection,
+ programRef: z23.string(),
+ name: z23.string().min(1).max(200),
+ assetId: selector.assetId.optional(),
+ parentRevision: selector.revisionId.optional(),
+ tags: z23.array(z23.string().max(80)).max(30).optional(),
+ brief: z23.string().max(8000).optional(),
+ description: z23.string().max(4000).optional(),
+ attribution: z23.object({
+ model: z23.string().max(200).optional(),
+ harness: z23.string().max(200).optional(),
+ author: z23.string().max(200).optional()
}).optional(),
- backdrop: z21.enum(BACKDROP_IDS).optional().describe("Preview backdrop: the one the reviewed sheet used.")
- });
- const assetsInput = z21.object({
- action: z21.enum(["collections", "catalog", "list", "get", "restore"]).default("list"),
- collection: assetSelector.collection,
- assetId: assetSelector.assetId.optional(),
- revisionId: assetSelector.revisionId.optional().describe("get, restore: the saved revision; omitted, the newest."),
- query: z21.string().max(200).optional(),
- offset: z21.number().int().min(0).default(0),
- limit: z21.number().int().min(1).max(50).default(20)
- });
- const exportInput = z21.object(assetSelector);
+ backdrop: z23.enum(BACKDROP_IDS).optional().describe("Preview backdrop: the one the reviewed sheet used.")
+ });
+ const assetsInput = z23.object({
+ action: z23.enum(["collections", "catalog", "list", "get", "restore"]).default("list"),
+ collection: selector.collection,
+ assetId: selector.assetId.optional(),
+ revisionId: selector.revisionId.optional().describe("get, restore: the saved revision; omitted, the newest."),
+ query: z23.string().max(200).optional(),
+ offset: z23.number().int().min(0).default(0),
+ limit: z23.number().int().min(1).max(50).default(20)
+ });
+ const exportInput = z23.object(selector);
const profileExportInput = exportInput.extend({
- profile: z21.enum(["editable", "runtime"]).default("editable").describe("editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.")
+ profile: z23.enum(["editable", "runtime"]).default("editable").describe("editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.")
});
- const importInput = z21.object({
- ...assetSelector,
- sourceCollection: assetSelector.collection
+ const importInput = z23.object({
+ ...selector,
+ sourceCollection: selector.collection
});
return [
{
@@ -43644,7 +43690,7 @@ function createKilnAssetDefs(context) {
requirements: activeRequirements.binding
};
if (input.assetId && input.parentRevision) {
- const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision);
+ const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision, listCall(input.collection));
assertSavedRequirementsAuthorized(previous.manifest, activeRequirements);
}
const code = await context.programStore.get(input.programRef);
@@ -43659,6 +43705,7 @@ function createKilnAssetDefs(context) {
name: "kiln_assets",
description: "Browse saved assets: collections discovers storage; catalog searches all configured collections; list searches one. Both searches paginate. get returns a build record/downloads; restore loads exact source for kiln_source/kiln_edit. Collection is not project membership. Binary-only assets cannot restore source.",
inputSchema: assetsInput,
+ actionContract: ASSET_CONTRACT,
run: async (raw) => {
const input = assetsInput.parse(raw);
const activeRequirements = toolRequirements(context);
@@ -43703,10 +43750,10 @@ function createKilnAssetDefs(context) {
}))
};
}
- if (!input.assetId)
+ if (ASSET_CONTRACT[input.action].required.some((field) => !input[field]))
throw new Error(`kiln_assets ${input.action} requires assetId; kiln_assets { action: 'list', collection: '${input.collection}' } lists them.`);
- const revisionId = input.revisionId ?? await newestRevision(target, input.collection, input.assetId);
- const record = await readSavedRevision(target, input.collection, input.assetId, revisionId);
+ const revisionId = input.revisionId ?? await newestRevision(target, input.collection, input.assetId, listCall(input.collection));
+ const record = await readSavedRevision(target, input.collection, input.assetId, revisionId, listCall(input.collection));
if (input.action === "get")
return links(input.collection, record.manifest);
const saved = assertSavedRequirementsAuthorized(record.manifest, activeRequirements);
@@ -43726,9 +43773,9 @@ function createKilnAssetDefs(context) {
name: "kiln_present",
description: "Present one exact saved revision. Supporting MCP App clients show an interactive 3D card with GLB, editable ZIP, and source downloads. Every host receives exact artifact descriptors with resource URIs in the JSON result; verified hosts may also receive core MCP resource-link blocks. This tool does not launch a local browser in coding harnesses. Call after saving or when the user wants to see or download an asset.",
inputSchema: exportInput,
- outputSchema: z21.object({
- ok: z21.literal(true),
- collection: z21.string(),
+ outputSchema: z23.object({
+ ok: z23.literal(true),
+ collection: z23.string(),
asset: assetManifestSchema.pick({
assetId: true,
revisionId: true,
@@ -43739,25 +43786,25 @@ function createKilnAssetDefs(context) {
editable: true,
files: true
}).extend({
- build: z21.object({
- engine: z21.string(),
- rebuild: z21.enum(["engine-required", "external-dependencies-required"]),
- warningCount: z21.number().int(),
- warnings: z21.array(z21.string())
+ build: z23.object({
+ engine: z23.string(),
+ rebuild: z23.enum(["engine-required", "external-dependencies-required"]),
+ warningCount: z23.number().int(),
+ warnings: z23.array(z23.string())
}).optional()
}),
- resources: z21.array(z21.object({
- type: z21.literal("resource_link"),
- name: z21.string(),
- uri: z21.string(),
- mimeType: z21.string(),
- size: z21.number().int().nonnegative(),
- annotations: z21.object({
- audience: z21.array(z21.enum(["user", "assistant"])),
- priority: z21.number()
+ resources: z23.array(z23.object({
+ type: z23.literal("resource_link"),
+ name: z23.string(),
+ uri: z23.string(),
+ mimeType: z23.string(),
+ size: z23.number().int().nonnegative(),
+ annotations: z23.object({
+ audience: z23.array(z23.enum(["user", "assistant"])),
+ priority: z23.number()
})
})),
- downloadUrls: z21.record(z21.string(), z21.string()).optional()
+ downloadUrls: z23.record(z23.string(), z23.string()).optional()
}),
ui: {
resourceUri: KILN_ASSET_WIDGET_URI,
@@ -43774,7 +43821,7 @@ function createKilnAssetDefs(context) {
inputSchema: profileExportInput,
run: async (raw) => {
const input = profileExportInput.parse(raw);
- const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId);
+ const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId, listCall(input.collection));
await Promise.resolve().then(() => init_draw_diagnostics());
if (input.profile === "runtime") {
const output = await (await Promise.resolve().then(() => (init_asset_export(), exports_asset_export))).exportAssetGlb(record, {
@@ -43808,7 +43855,7 @@ function createKilnAssetDefs(context) {
run: async (raw) => {
const input = importInput.parse(raw);
const target = library();
- const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId);
+ const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId, listCall(input.sourceCollection));
await target.import(input.collection, [record]);
return links(input.collection, record.manifest);
}
@@ -43823,7 +43870,7 @@ var KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v5.html", DEFAULT_INLOOP_VIEW_RENDE
path: `.kiln/review/${operation.operationId}/evaluation.json`
} : undefined;
}
-}), renderViewsBufferInput, screenshotAnimationInput, screenshotAnimationAdvertisedInput, viewInteriorInput, viewInteriorAdvertisedInput, partListInput, PLACEMENT_PAGE_LIMIT = 50, lod0Views = (views) => Array.from({ length: views }, () => []), KILN_RENDER_VIEWS_DESCRIPTION, kilnRenderViewsDef, KILN_SCREENSHOT_ANIMATION_DESCRIPTION, kilnScreenshotAnimationDef, KILN_VIEW_INTERIOR_DESCRIPTION, kilnViewInteriorDef, attachmentEndpointInput, surfacePairInput, inspectInput, inspectBufferInput, inspectAdvertisedInput, KILN_INSPECT_DESCRIPTION, kilnInspectDef, editOperationInput, editInput, editAdvertisedInput, KILN_EDIT_DESCRIPTION = "Patch an EXISTING Kiln program with exact-string replacements and render the result in one call. This is the refine verb: use it to change an asset you already have rather than re-emitting the whole file, so every line you did not touch stays byte-for-byte identical and the reply carries a unified diff of what actually changed. Pass the full current source as `code` and one or more { oldString, newString } edits, copied verbatim from that source. Edits apply in order and the call is all-or-nothing: if any oldString does not match, or matches more than once without replaceAll, NOTHING is applied and the reply names the edit that failed -- fix it and call again. The patched program comes back as `code`; write it to your file to keep it. Renders by default, so you see the change immediately; pass render:false to patch without rendering. Writes no files.", kilnEditDef, localCacheScope = 0, NESTED_RECORD_SHAPES, rendererInput, assetSelector;
+}), renderViewsBufferInput, screenshotAnimationInput, screenshotAnimationAdvertisedInput, viewInteriorInput, viewInteriorAdvertisedInput, partListInput, PLACEMENT_PAGE_LIMIT = 50, lod0Views = (views) => Array.from({ length: views }, () => []), KILN_RENDER_VIEWS_DESCRIPTION, kilnRenderViewsDef, KILN_SCREENSHOT_ANIMATION_DESCRIPTION, kilnScreenshotAnimationDef, KILN_VIEW_INTERIOR_DESCRIPTION, kilnViewInteriorDef, attachmentEndpointInput, surfacePairInput, inspectInput, inspectBufferInput, inspectAdvertisedInput, KILN_INSPECT_DESCRIPTION, kilnInspectDef, editOperationInput, editInput, editAdvertisedInput, KILN_EDIT_DESCRIPTION = "Patch an EXISTING Kiln program with exact-string replacements and render the result in one call. This is the refine verb: use it to change an asset you already have rather than re-emitting the whole file, so every line you did not touch stays byte-for-byte identical and the reply carries a unified diff of what actually changed. Pass the full current source as `code` and one or more { oldString, newString } edits, copied verbatim from that source. Edits apply in order and the call is all-or-nothing: if any oldString does not match, or matches more than once without replaceAll, NOTHING is applied and the reply names the edit that failed -- fix it and call again. The patched program comes back as `code`; write it to your file to keep it. Renders by default, so you see the change immediately; pass render:false to patch without rendering. Writes no files.", kilnEditDef, localCacheScope = 0, NESTED_RECORD_SHAPES, rendererInput, assetSelector, ASSET_CONTRACT;
var init_registry2 = __esm(() => {
init_capture_cache();
init_assets();
@@ -43836,6 +43883,7 @@ var init_registry2 = __esm(() => {
init_materials();
init_review();
init_workspace2();
+ init_operations();
init_capture_input();
init_review_detail();
init_build_cache();
@@ -43850,41 +43898,41 @@ var init_registry2 = __esm(() => {
init_evidence_history();
init_background();
viewEvidenceHistoryByContext = new WeakMap;
- validateInput = z21.object({
- code: z21.string().describe("Kiln source code (defines `meta` + `build()`, optional `animate()`).")
+ validateInput = z23.object({
+ code: z23.string().describe("Kiln source code (defines `meta` + `build()`, optional `animate()`).")
});
- renderInput = z21.object({
- code: z21.string().describe("Kiln source code to execute and render to an in-memory GLB.")
+ renderInput = z23.object({
+ code: z23.string().describe("Kiln source code to execute and render to an in-memory GLB.")
});
renderViewsInput = renderInput.extend({ capture: captureInput, detail: reviewDetailInput });
renderViewsBufferInput = renderViewsInput.omit({ code: true });
- screenshotAnimationInput = z21.object({
+ screenshotAnimationInput = z23.object({
shot: cameraShotInput.optional(),
- measureParts: z21.array(cameraShotInput.shape.subject.unwrap()).min(1).max(16).optional().describe("Exact names or paths of subtrees measured together at each phase, independent of camera selection."),
- frames: z21.number().int().min(2).max(6).optional(),
- frameTimes: z21.array(z21.number().min(0).max(1)).min(1).max(9).optional().describe("Ordered phase fractions 0..1; mutually exclusive with frames."),
- framing: z21.enum(["locked", "follow"]).optional(),
- size: z21.number().int().min(128).max(1024).optional().describe("Frame size in px; default 256."),
+ measureParts: z23.array(cameraShotInput.shape.subject.unwrap()).min(1).max(16).optional().describe("Exact names or paths of subtrees measured together at each phase, independent of camera selection."),
+ frames: z23.number().int().min(2).max(6).optional(),
+ frameTimes: z23.array(z23.number().min(0).max(1)).min(1).max(9).optional().describe("Ordered phase fractions 0..1; mutually exclusive with frames."),
+ framing: z23.enum(["locked", "follow"]).optional(),
+ size: z23.number().int().min(128).max(1024).optional().describe("Frame size in px; default 256."),
detail: reviewDetailInput,
- code: z21.string().describe("Kiln source code to execute; must define animate() returning the named clip."),
- clip: z21.string().describe('The animation clip to view, by name (e.g. "walk", "attack"). Must be one your animate() returns.'),
- camera: z21.string().optional().describe("Camera angle: right (default — side profile, best for leg swing + knee bend direction), front " + "(reveals sideways/lateral motion), back, left, top, or three-quarter."),
- perFrame: z21.boolean().optional().describe("Return the frames as separate high-res images instead of one composite grid. Default false.")
+ code: z23.string().describe("Kiln source code to execute; must define animate() returning the named clip."),
+ clip: z23.string().describe('The animation clip to view, by name (e.g. "walk", "attack"). Must be one your animate() returns.'),
+ camera: z23.string().optional().describe("Camera angle: right (default — side profile, best for leg swing + knee bend direction), front " + "(reveals sideways/lateral motion), back, left, top, or three-quarter."),
+ perFrame: z23.boolean().optional().describe("Return the frames as separate high-res images instead of one composite grid. Default false.")
});
screenshotAnimationAdvertisedInput = screenshotAnimationInput.extend({
shot: cameraShotRecordInput
});
- viewInteriorInput = z21.object({
+ viewInteriorInput = z23.object({
capture: advancedCaptureInput.optional(),
- code: z21.string().describe("Kiln source code to execute and render with the roof hidden."),
- nodeName: z21.string().optional().describe("Override: lift the roof by exact node name instead of by role. Matches that node and its " + "children. Normally OMIT it — Kiln finds the roof from its semantic role (anything built " + 'with createRoofPlanes/createGableRoof), falling back to historical "Roof" naming.')
+ code: z23.string().describe("Kiln source code to execute and render with the roof hidden."),
+ nodeName: z23.string().optional().describe("Override: lift the roof by exact node name instead of by role. Matches that node and its " + "children. Normally OMIT it — Kiln finds the roof from its semantic role (anything built " + 'with createRoofPlanes/createGableRoof), falling back to historical "Roof" naming.')
});
viewInteriorAdvertisedInput = viewInteriorInput.extend({ capture: captureRecordInput });
- partListInput = z21.object({
- query: z21.string().max(4096).optional().describe("Case-insensitive substring of name or exact encoded path; not a regex."),
- offset: z21.number().int().min(0).optional(),
- limit: z21.number().int().min(1).max(100).optional(),
- placement: z21.boolean().optional().describe("Add world position, rotation, scale, mirroring and bounds per part; pages of 50.")
+ partListInput = z23.object({
+ query: z23.string().max(4096).optional().describe("Case-insensitive substring of name or exact encoded path; not a regex."),
+ offset: z23.number().int().min(0).optional(),
+ limit: z23.number().int().min(1).max(100).optional(),
+ placement: z23.boolean().optional().describe("Add world position, rotation, scale, mirroring and bounds per part; pages of 50.")
}).strict();
KILN_RENDER_VIEWS_DESCRIPTION = "Build the current asset and return geometry metrics, exact part paths and images. Omit capture for six orthographic views. Choose preset/cells for a smaller orbit sheet, or version kiln.capture.v1 with shots for per-part framing, local axes, perspective and separate images. +X is forward, +Y up, +Z right. Review silhouette, attachments, proportion and ground contact. GPU PBR shading supports textured or metallic materials; a flat-shaded CPU render supports geometry review. Read viewFidelity; do not judge material fidelity from CPU views. Failed builds return errors without images." + VIEW_EVIDENCE_GUIDANCE;
kilnRenderViewsDef = createKilnRenderViewsDef();
@@ -43892,49 +43940,49 @@ var init_registry2 = __esm(() => {
kilnScreenshotAnimationDef = createKilnScreenshotAnimationDef();
KILN_VIEW_INTERIOR_DESCRIPTION = "SEE INSIDE an enterable building: renders it with the roof lifted off, as a " + "three-view grid. (1) Floor plan: top-down — check the interior is open and walkable and the footprint " + "is right. (2) Dollhouse: a 3/4 cutaway — check built-in fixtures (hearth, counter, shelves) rest ON the " + "floor, not floating or sunk, and the walls enclose a real volume with headroom. (3) Eye-level: a low " + "angle looking in through the doorway with the near walls also removed — confirm the doorway is a REAL " + "gap you could walk through (not a panel) and no wall or glass is buried inside a solid mass. Call this before finalizing any building. Take no argument: the roof is found from its semantic role, so any roof built with createRoofPlanes/createGableRoof lifts whatever it is named. If " + "roofsHidden comes back 0 no roof was resolvable and the interior stays hidden — build the roof " + 'with a roof primitive (or name the group "Roof"). Each cell is rendered from deterministic cutaway GLB bytes: GPU PBR when available, otherwise a GLB-native geometry-flat fallback. Read viewFidelity before judging materials; writes no files.' + VIEW_EVIDENCE_GUIDANCE;
kilnViewInteriorDef = createKilnViewInteriorDef();
- attachmentEndpointInput = z21.object({
- subject: z21.object({ path: z21.string().optional(), name: z21.string().optional() }).strict(),
+ attachmentEndpointInput = z23.object({
+ subject: z23.object({ path: z23.string().optional(), name: z23.string().optional() }).strict(),
point: cameraVec3Input.optional()
}).strict();
- surfacePairInput = z21.array(z21.string().max(4096)).length(2);
- inspectInput = z21.object({
- image: z21.boolean().optional().describe("False: requires listParts/measure/surfacePairs/compare; no image or camera controls. Default true."),
+ surfacePairInput = z23.array(z23.string().max(4096)).length(2);
+ inspectInput = z23.object({
+ image: z23.boolean().optional().describe("False: requires listParts/measure/surfacePairs/compare; no image or camera controls. Default true."),
detail: reviewDetailInput,
listParts: partListInput.optional().describe("List exported-scene paths, including nested parts. Default 80, max 100 per page. Follow partListing.nextOffset with the same programRef/query. image:false avoids rendering."),
- surfacePairs: z21.array(surfacePairInput).min(1).max(12).optional().describe("[from,to] pairs of exact listParts paths or unambiguous node names; check surfaceMeasurements.status and each result."),
- compare: z21.object({
- programRef: z21.string().regex(programRefPattern),
- offset: z21.number().int().min(0).optional(),
- limit: z21.number().int().min(1).max(100).optional(),
- paths: z21.array(z21.string().max(4096)).min(1).max(12).optional().describe("Exact baseline node paths, scene-prefixed without primitive children. Complete subtree summaries.")
+ surfacePairs: z23.array(surfacePairInput).min(1).max(12).optional().describe("[from,to] pairs of exact listParts paths or unambiguous node names; check surfaceMeasurements.status and each result."),
+ compare: z23.object({
+ programRef: z23.string().regex(programRefPattern),
+ offset: z23.number().int().min(0).optional(),
+ limit: z23.number().int().min(1).max(100).optional(),
+ paths: z23.array(z23.string().max(4096)).min(1).max(12).optional().describe("Exact baseline node paths, scene-prefixed without primitive children. Complete subtree summaries.")
}).strict().optional().describe("Static geometry/material/transform/bounds under current host settings. Follow nextOffset; paths adds complete subtrees."),
- measure: z21.object({
- mode: z21.enum(["anchors", "surface"]).optional(),
+ measure: z23.object({
+ mode: z23.enum(["anchors", "surface"]).optional(),
from: attachmentEndpointInput,
to: attachmentEndpointInput
}).strict().optional().describe("Default anchors: origin/local-point distance. Surface: disjoint mesh triangles, omit points. Rest pose, asset units. Check status/bounds; no solid clearance/attachment proof."),
shot: cameraShotInput.optional().describe("Exact shot; omit part/view/orbit controls."),
- code: z21.string().describe("Kiln source code to execute and inspect."),
- part: z21.string().optional().describe("Frame named part and descendants (case-insensitive, substring fallback). Omit for whole asset."),
- view: z21.string().optional().describe("front/right/back/left/top/three-quarter (default). Orbit angles override."),
- azimuthDeg: z21.number().optional().describe("Orbit degrees: 0 front, 90 right, 180 back, 270 left. Wraps."),
- elevationDeg: z21.number().optional().describe("Elevation degrees: 0 eye level, positive above. Clamped -89..89."),
- zoom: z21.number().optional().describe("Bounds padding 1..4; default 1.2. Larger = more context."),
- isolate: z21.boolean().optional().describe("Hide surrounding geometry. Requires part; default false.")
+ code: z23.string().describe("Kiln source code to execute and inspect."),
+ part: z23.string().optional().describe("Frame named part and descendants (case-insensitive, substring fallback). Omit for whole asset."),
+ view: z23.string().optional().describe("front/right/back/left/top/three-quarter (default). Orbit angles override."),
+ azimuthDeg: z23.number().optional().describe("Orbit degrees: 0 front, 90 right, 180 back, 270 left. Wraps."),
+ elevationDeg: z23.number().optional().describe("Elevation degrees: 0 eye level, positive above. Clamped -89..89."),
+ zoom: z23.number().optional().describe("Bounds padding 1..4; default 1.2. Larger = more context."),
+ isolate: z23.boolean().optional().describe("Hide surrounding geometry. Requires part; default false.")
});
inspectBufferInput = inspectInput.omit({ code: true });
inspectAdvertisedInput = inspectInput.extend({ shot: cameraShotRecordInput });
KILN_INSPECT_DESCRIPTION = "List complete part paths with listParts and image:false; query filters names/paths, offset/limit paginate. Follow partListing.nextOffset. ZOOM IN on one part: renders a single 512x512 close-up framed to the named part (the node name you gave createPart, matched case-insensitively with a substring fallback) and its descendants, " + "from one camera. Use it after kiln_render reveals a suspect region — a floating part, a bad " + "joint, a wrong proportion — to see fine detail one grid cell cannot show. args: part (omit to " + "frame the whole asset in one large view), view (front/right/back/left/top/three-quarter, default three-quarter), azimuthDeg + elevationDeg (orbit to ANY angle instead of a named view: azimuth 0 = front, 90 = right, 180 = back, 270 = left; elevation 0 = eye level, positive looks down, clamped to -89..89), zoom (padding multiplier around the part bounds, 1 = tight crop up to 4 = wide context, default 1.2), isolate (hide everything except that part, default false). Reach for the orbit angles when a named view puts the thing you need to judge edge-on or " + "behind something — the reply always tells you the azimuth/elevation it used, so you can step " + "from there. " + "If the part name does not resolve you get the list of available part names back — pick one and " + "retry. By default surrounding geometry stays visible for context and can occlude the part: either pick a different view, or set isolate:true to hide everything else and see the part unobstructed (use it for anything buried inside or behind other geometry). The view is rendered from deterministic derivative GLB bytes; GPU PBR is used only when it can preserve the requested framing, otherwise the GLB-native geometry-flat fallback reports why in viewFidelity. Writes no files." + VIEW_EVIDENCE_GUIDANCE;
kilnInspectDef = createKilnInspectDef();
- editOperationInput = z21.object({
- oldString: z21.string().describe("The exact text to replace, copied verbatim from the program (including whitespace and indentation, and with no line-number prefixes). Must be unique unless replaceAll is true."),
- newString: z21.string().describe("The replacement text. Use an empty string to delete."),
- replaceAll: z21.boolean().optional().describe("Replace every occurrence instead of failing when oldString matches more than once.")
- });
- editInput = z21.object({
- code: z21.string().describe("The Kiln program to patch. The full current source."),
- edits: z21.array(editOperationInput).min(1).max(20).describe("Edits applied in order against the program. If any one fails to match, none are applied and the reply says which. Batch related changes into a single call."),
- render: z21.boolean().optional().describe("Render the patched program and return the views (default true). false = patch only."),
+ editOperationInput = z23.object({
+ oldString: z23.string().describe("The exact text to replace, copied verbatim from the program (including whitespace and indentation, and with no line-number prefixes). Must be unique unless replaceAll is true."),
+ newString: z23.string().describe("The replacement text. Use an empty string to delete."),
+ replaceAll: z23.boolean().optional().describe("Replace every occurrence instead of failing when oldString matches more than once.")
+ });
+ editInput = z23.object({
+ code: z23.string().describe("The Kiln program to patch. The full current source."),
+ edits: z23.array(editOperationInput).min(1).max(20).describe("Edits applied in order against the program. If any one fails to match, none are applied and the reply says which. Batch related changes into a single call."),
+ render: z23.boolean().optional().describe("Render the patched program and return the views (default true). false = patch only."),
capture: captureInput,
detail: reviewDetailInput
});
@@ -43944,13 +43992,40 @@ var init_registry2 = __esm(() => {
shot: "shape:camera-shot",
capture: "shape:capture"
};
- rendererInput = z21.strictObject({
- action: z21.enum(["status", "reprobe"]).default("status")
+ rendererInput = z23.strictObject({
+ action: z23.enum(["status", "reprobe"]).default("status")
});
assetSelector = {
- collection: z21.string().regex(/^[a-z][a-z0-9_-]{0,79}$/).describe("Collection ID (list with kiln_assets action=collections): the user destination, else project.").default("project"),
- assetId: z21.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
- revisionId: z21.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)
+ collection: z23.string().regex(/^[a-z][a-z0-9_-]{0,79}$/).describe("Collection ID (list with kiln_assets action=collections): the user destination, else project.").default("project"),
+ assetId: z23.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
+ revisionId: z23.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)
+ };
+ ASSET_CONTRACT = {
+ collections: {
+ fields: [],
+ required: [],
+ description: "List configured asset storage collections. Collection is not project membership."
+ },
+ catalog: {
+ fields: ["assetId", "query", "offset", "limit"],
+ required: [],
+ description: "Search saved assets across configured collections with pagination."
+ },
+ list: {
+ fields: ["collection", "assetId", "query", "offset", "limit"],
+ required: [],
+ description: "Search saved assets in one collection with pagination."
+ },
+ get: {
+ fields: ["collection", "assetId", "revisionId"],
+ required: ["assetId"],
+ description: "Read a saved revision and its download descriptors. Omit revisionId for the newest revision."
+ },
+ restore: {
+ fields: ["collection", "assetId", "revisionId"],
+ required: ["assetId"],
+ description: "Restore exact saved source as programRef for editing or rendering. Omit revisionId for the newest revision. Does not overwrite the saved revision. Binary-only assets have no source."
+ }
};
});
@@ -44750,7 +44825,7 @@ var init_loopback = __esm(() => {
});
// src/workspace-http.ts
-import { z as z22 } from "zod";
+import { z as z24 } from "zod";
async function readJson(req, origin) {
if (req.headers.origin !== origin)
throw new WorkspaceHttpError(403, "Same-origin writes only");
@@ -44919,11 +44994,11 @@ var init_workspace_http = __esm(() => {
this.status = status;
}
};
- updateSchema = z22.strictObject({
+ updateSchema = z24.strictObject({
expectedRevision: projectRevisionIdSchema,
patch: projectPatchSchema
});
- pinSchema = z22.strictObject({ pinned: z22.boolean() });
+ pinSchema = z24.strictObject({ pinned: z24.boolean() });
filePattern3 = /^(asset\.glb|source\.kiln\.js|evaluation\.json|capture-\d{1,2}\.png)$/;
});
diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjs
index e7343204..071ea508 100644
--- a/dist/mcp-engine.mjs
+++ b/dist/mcp-engine.mjs
@@ -36106,7 +36106,7 @@ import { readFile as readFile8 } from "node:fs/promises";
var KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v5.html";
// src/engine-identity.ts
-var ENGINE_VERSION = "1.1.0";
+var ENGINE_VERSION = "1.2.0";
var ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
function engineIdentity() {
return { version: ENGINE_VERSION, installUrl: ENGINE_INSTALL_URL };
@@ -36117,6 +36117,7 @@ init_requirements_json();
var MCP_SERVER_NAME = "kiln";
var MCP_SERVER_VERSION = ENGINE_VERSION;
var 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.";
+var 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.";
var KILN_WIDGET_META = {
ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } },
"openai/widgetDescription": "Inspect the saved 3D asset and download its GLB or editable bundle.",
@@ -36243,7 +36244,7 @@ var PRE_HANDSHAKE_METHODS = new Set(["initialize", "ping"]);
// src/tools/registry.ts
init_capture_cache();
init_assets();
-import { z as z21 } from "zod";
+import { z as z23 } from "zod";
// src/requirements-assets.ts
init_requirements_context();
@@ -40400,7 +40401,7 @@ var MAX_RESPONSE_BYTES = 64 * 1024;
var MAX_TEXT_CHARS = 16 * 1024;
var DETAIL_RESULT_BUDGET = 15000;
var compare2 = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-function createDiscoveryService(source, index, capabilities, retirements = {}, notes = async () => []) {
+function createDiscoveryService(source, index, capabilities, retirements = {}, notes = async () => [], 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]));
@@ -40423,7 +40424,7 @@ function createDiscoveryService(source, index, capabilities, retirements = {}, n
"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) => ({
@@ -40604,12 +40605,12 @@ var snapshot2;
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") {
snapshot2 ??= (() => {
const entries = listDiscoveryEntries();
return { entries, index: createLexicalDiscoveryIndex(entries) };
})();
- return createDiscoveryService(snapshot2.entries, snapshot2.index, capabilities, REMOVED_AUTHORING_HELPERS, notes);
+ return createDiscoveryService(snapshot2.entries, snapshot2.index, capabilities, REMOVED_AUTHORING_HELPERS, notes, capabilitiesCall);
}
// src/tools/discovery.ts
@@ -40618,8 +40619,8 @@ init_capture_limits();
init_geometry_export();
init_community_exporter();
init_material_resources();
-function createKilnDiscoveryDef(context) {
- const run = createDiscovery(() => currentCapabilities(context), async () => projectNotes(context));
+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.",
@@ -40643,7 +40644,7 @@ function projectNotes(context) {
`Project ${projectId} is configured for this workspace and applies when projectId is omitted: read its brief, design, inventory and material pins first with kiln_project { action: "get", projectId: "${projectId}" }; projectId: null selects standalone work.`
] : [];
}
-async function currentCapabilities(context) {
+async function currentCapabilities(context, presentation) {
const externalEvaluator = Boolean(context.evaluatorPort) || context.evaluatorProfile === "evaluator-required";
const approvedTextures = context.approvedTextureResources ? context.approvedTextureResources() : externalEvaluator ? null : approvedTextureCatalogV1();
const textureSlots = approvedTextures === null ? null : {};
@@ -40672,7 +40673,7 @@ async function currentCapabilities(context) {
requiresModel: false
},
engine: engineIdentity(),
- project: {
+ 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'
@@ -40691,7 +40692,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"
},
@@ -41080,13 +41081,39 @@ var MATERIAL_ACTIONS = [
"create-procedural",
"import"
];
-var REQUIREMENTS2 = {
- 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" } }
+var 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."
+ }
};
var record7 = (description) => z18.record(z18.string(), z18.unknown()).optional().describe(description);
var tag = z18.string().min(1).max(80).optional().describe("presets, list: keep one tag.");
@@ -41108,13 +41135,13 @@ var materialResult = (material) => ({
material,
portableSpec: materialLibraryPortableSpec(material)
});
-var 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.`);
-async function onlyRevision(library, materialId) {
+var unknownMaterial = (materialId, revisionId, listCall) => new Error(`Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ""}. ${listCall} lists the materials in this workspace with their revision IDs.`);
+async function onlyRevision(library, materialId, listCall) {
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);
+ throw unknownMaterial(materialId, undefined, listCall);
throw new Error(`Material ${materialId} has ${revisions.length} revisions: ${revisions.join(", ")}. Pass revisionId to get one.`);
}
function aliasMaterialId(raw) {
@@ -41127,11 +41154,13 @@ 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 };
}
-function createKilnMaterialDef(library) {
+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,
@@ -41141,7 +41170,7 @@ function createKilnMaterialDef(library) {
async run(raw) {
assertMaterialJson(raw);
const input = materialToolInput.parse(aliasMaterialId(raw));
- requireActionFields("kiln_material", input.action, input, REQUIREMENTS2[input.action]);
+ requireActionFields("kiln_material", input.action, input, MATERIAL_CONTRACT[input.action]);
switch (input.action) {
case "presets":
return {
@@ -41177,12 +41206,12 @@ 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) {
if (error.code === "ENOENT")
- throw unknownMaterial(input.materialId, revisionId);
+ throw unknownMaterial(input.materialId, revisionId, listCall);
throw error;
}
}
@@ -41233,7 +41262,7 @@ async function persistedPreviewFidelity(fidelity, glb) {
var operationId = z19.string().regex(/^op_[a-f0-9-]{36}$/);
var assetId = z19.string().regex(/^[a-z][a-z0-9_-]{0,79}$/);
var REVIEW_ACTIONS = ["list", "get", "pin", "save"];
-var REQUIREMENTS3 = {
+var REQUIREMENTS2 = {
list: { required: [] },
get: { required: ["operationId"] },
pin: { required: ["operationId", "pinned"] },
@@ -41315,7 +41344,7 @@ function createKilnReviewDef(context) {
},
async run(raw) {
const input = reviewToolInput.parse(raw);
- requireActionFields("kiln_review", input.action, input, REQUIREMENTS3[input.action]);
+ requireActionFields("kiln_review", input.action, input, REQUIREMENTS2[input.action]);
if (input.action === "list") {
const snapshot = await store.snapshot({ projectId: input.projectId });
const offset = input.offset ?? 0;
@@ -41487,6 +41516,191 @@ function withWorkspaceContext(def, context) {
};
}
+// src/tools/operations.ts
+import { z as z22 } from "zod";
+
+// src/tools/operation-contract.ts
+import { z as z21 } from "zod";
+function projectActionSchemas(name, input, actions) {
+ if (input.def.checks?.length)
+ throw new Error(`${name}: cross-field constraints require an explicit operation schema`);
+ const json = z21.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, z21.strictObject(shape)]);
+ }
+ return Object.fromEntries(schemas);
+}
+
+// src/tools/operations.ts
+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 z22.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;
+ 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: z22.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 = z22.strictObject({
+ definition: z22.discriminatedUnion("kind", [
+ preset.inputSchema.extend({ kind: z22.literal("preset") }),
+ procedural.inputSchema.extend({ kind: z22.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 = z22.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 = z22.strictObject(fields);
+ const empty = z22.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 });
+ }
+ }
+ ];
+}
+
// src/tools/registry.ts
init_validation();
init_source_check();
@@ -41952,11 +42166,11 @@ function derivativeReviewFidelity(receipts) {
...reasonCodes.length ? { reasonCodes } : {}
};
}
-var validateInput = z21.object({
- code: z21.string().describe("Kiln source code (defines `meta` + `build()`, optional `animate()`).")
+var validateInput = z23.object({
+ code: z23.string().describe("Kiln source code (defines `meta` + `build()`, optional `animate()`).")
});
-var renderInput = z21.object({
- code: z21.string().describe("Kiln source code to execute and render to an in-memory GLB.")
+var renderInput = z23.object({
+ code: z23.string().describe("Kiln source code to execute and render to an in-memory GLB.")
});
var renderViewsInput = renderInput.extend({ capture: captureInput, detail: reviewDetailInput });
var reviewDetailOptions = (context) => ({
@@ -41969,26 +42183,26 @@ var reviewDetailOptions = (context) => ({
}
});
var renderViewsBufferInput = renderViewsInput.omit({ code: true });
-var screenshotAnimationInput = z21.object({
+var screenshotAnimationInput = z23.object({
shot: cameraShotInput.optional(),
- measureParts: z21.array(cameraShotInput.shape.subject.unwrap()).min(1).max(16).optional().describe("Exact names or paths of subtrees measured together at each phase, independent of camera selection."),
- frames: z21.number().int().min(2).max(6).optional(),
- frameTimes: z21.array(z21.number().min(0).max(1)).min(1).max(9).optional().describe("Ordered phase fractions 0..1; mutually exclusive with frames."),
- framing: z21.enum(["locked", "follow"]).optional(),
- size: z21.number().int().min(128).max(1024).optional().describe("Frame size in px; default 256."),
+ measureParts: z23.array(cameraShotInput.shape.subject.unwrap()).min(1).max(16).optional().describe("Exact names or paths of subtrees measured together at each phase, independent of camera selection."),
+ frames: z23.number().int().min(2).max(6).optional(),
+ frameTimes: z23.array(z23.number().min(0).max(1)).min(1).max(9).optional().describe("Ordered phase fractions 0..1; mutually exclusive with frames."),
+ framing: z23.enum(["locked", "follow"]).optional(),
+ size: z23.number().int().min(128).max(1024).optional().describe("Frame size in px; default 256."),
detail: reviewDetailInput,
- code: z21.string().describe("Kiln source code to execute; must define animate() returning the named clip."),
- clip: z21.string().describe('The animation clip to view, by name (e.g. "walk", "attack"). Must be one your animate() returns.'),
- camera: z21.string().optional().describe("Camera angle: right (default — side profile, best for leg swing + knee bend direction), front " + "(reveals sideways/lateral motion), back, left, top, or three-quarter."),
- perFrame: z21.boolean().optional().describe("Return the frames as separate high-res images instead of one composite grid. Default false.")
+ code: z23.string().describe("Kiln source code to execute; must define animate() returning the named clip."),
+ clip: z23.string().describe('The animation clip to view, by name (e.g. "walk", "attack"). Must be one your animate() returns.'),
+ camera: z23.string().optional().describe("Camera angle: right (default — side profile, best for leg swing + knee bend direction), front " + "(reveals sideways/lateral motion), back, left, top, or three-quarter."),
+ perFrame: z23.boolean().optional().describe("Return the frames as separate high-res images instead of one composite grid. Default false.")
});
var screenshotAnimationAdvertisedInput = screenshotAnimationInput.extend({
shot: cameraShotRecordInput
});
-var viewInteriorInput = z21.object({
+var viewInteriorInput = z23.object({
capture: advancedCaptureInput.optional(),
- code: z21.string().describe("Kiln source code to execute and render with the roof hidden."),
- nodeName: z21.string().optional().describe("Override: lift the roof by exact node name instead of by role. Matches that node and its " + "children. Normally OMIT it — Kiln finds the roof from its semantic role (anything built " + 'with createRoofPlanes/createGableRoof), falling back to historical "Roof" naming.')
+ code: z23.string().describe("Kiln source code to execute and render with the roof hidden."),
+ nodeName: z23.string().optional().describe("Override: lift the roof by exact node name instead of by role. Matches that node and its " + "children. Normally OMIT it — Kiln finds the roof from its semantic role (anything built " + 'with createRoofPlanes/createGableRoof), falling back to historical "Roof" naming.')
});
var viewInteriorAdvertisedInput = viewInteriorInput.extend({ capture: captureRecordInput });
function runValidate(input, context) {
@@ -42003,11 +42217,11 @@ function runValidate(input, context) {
warnings: result.warnings.map((w) => w.fixHint ? `${w.message} (${w.fixHint})` : w.message)
};
}
-var partListInput = z21.object({
- query: z21.string().max(4096).optional().describe("Case-insensitive substring of name or exact encoded path; not a regex."),
- offset: z21.number().int().min(0).optional(),
- limit: z21.number().int().min(1).max(100).optional(),
- placement: z21.boolean().optional().describe("Add world position, rotation, scale, mirroring and bounds per part; pages of 50.")
+var partListInput = z23.object({
+ query: z23.string().max(4096).optional().describe("Case-insensitive substring of name or exact encoded path; not a regex."),
+ offset: z23.number().int().min(0).optional(),
+ limit: z23.number().int().min(1).max(100).optional(),
+ placement: z23.boolean().optional().describe("Add world position, rotation, scale, mirroring and bounds per part; pages of 50.")
}).strict();
var PLACEMENT_PAGE_LIMIT = 50;
async function listPartNames2(root, options = {}) {
@@ -42474,35 +42688,35 @@ function createKilnViewInteriorDef(context = {}) {
};
}
var kilnViewInteriorDef = createKilnViewInteriorDef();
-var attachmentEndpointInput = z21.object({
- subject: z21.object({ path: z21.string().optional(), name: z21.string().optional() }).strict(),
+var attachmentEndpointInput = z23.object({
+ subject: z23.object({ path: z23.string().optional(), name: z23.string().optional() }).strict(),
point: cameraVec3Input.optional()
}).strict();
-var surfacePairInput = z21.array(z21.string().max(4096)).length(2);
-var inspectInput = z21.object({
- image: z21.boolean().optional().describe("False: requires listParts/measure/surfacePairs/compare; no image or camera controls. Default true."),
+var surfacePairInput = z23.array(z23.string().max(4096)).length(2);
+var inspectInput = z23.object({
+ image: z23.boolean().optional().describe("False: requires listParts/measure/surfacePairs/compare; no image or camera controls. Default true."),
detail: reviewDetailInput,
listParts: partListInput.optional().describe("List exported-scene paths, including nested parts. Default 80, max 100 per page. Follow partListing.nextOffset with the same programRef/query. image:false avoids rendering."),
- surfacePairs: z21.array(surfacePairInput).min(1).max(12).optional().describe("[from,to] pairs of exact listParts paths or unambiguous node names; check surfaceMeasurements.status and each result."),
- compare: z21.object({
- programRef: z21.string().regex(programRefPattern),
- offset: z21.number().int().min(0).optional(),
- limit: z21.number().int().min(1).max(100).optional(),
- paths: z21.array(z21.string().max(4096)).min(1).max(12).optional().describe("Exact baseline node paths, scene-prefixed without primitive children. Complete subtree summaries.")
+ surfacePairs: z23.array(surfacePairInput).min(1).max(12).optional().describe("[from,to] pairs of exact listParts paths or unambiguous node names; check surfaceMeasurements.status and each result."),
+ compare: z23.object({
+ programRef: z23.string().regex(programRefPattern),
+ offset: z23.number().int().min(0).optional(),
+ limit: z23.number().int().min(1).max(100).optional(),
+ paths: z23.array(z23.string().max(4096)).min(1).max(12).optional().describe("Exact baseline node paths, scene-prefixed without primitive children. Complete subtree summaries.")
}).strict().optional().describe("Static geometry/material/transform/bounds under current host settings. Follow nextOffset; paths adds complete subtrees."),
- measure: z21.object({
- mode: z21.enum(["anchors", "surface"]).optional(),
+ measure: z23.object({
+ mode: z23.enum(["anchors", "surface"]).optional(),
from: attachmentEndpointInput,
to: attachmentEndpointInput
}).strict().optional().describe("Default anchors: origin/local-point distance. Surface: disjoint mesh triangles, omit points. Rest pose, asset units. Check status/bounds; no solid clearance/attachment proof."),
shot: cameraShotInput.optional().describe("Exact shot; omit part/view/orbit controls."),
- code: z21.string().describe("Kiln source code to execute and inspect."),
- part: z21.string().optional().describe("Frame named part and descendants (case-insensitive, substring fallback). Omit for whole asset."),
- view: z21.string().optional().describe("front/right/back/left/top/three-quarter (default). Orbit angles override."),
- azimuthDeg: z21.number().optional().describe("Orbit degrees: 0 front, 90 right, 180 back, 270 left. Wraps."),
- elevationDeg: z21.number().optional().describe("Elevation degrees: 0 eye level, positive above. Clamped -89..89."),
- zoom: z21.number().optional().describe("Bounds padding 1..4; default 1.2. Larger = more context."),
- isolate: z21.boolean().optional().describe("Hide surrounding geometry. Requires part; default false.")
+ code: z23.string().describe("Kiln source code to execute and inspect."),
+ part: z23.string().optional().describe("Frame named part and descendants (case-insensitive, substring fallback). Omit for whole asset."),
+ view: z23.string().optional().describe("front/right/back/left/top/three-quarter (default). Orbit angles override."),
+ azimuthDeg: z23.number().optional().describe("Orbit degrees: 0 front, 90 right, 180 back, 270 left. Wraps."),
+ elevationDeg: z23.number().optional().describe("Elevation degrees: 0 eye level, positive above. Clamped -89..89."),
+ zoom: z23.number().optional().describe("Bounds padding 1..4; default 1.2. Larger = more context."),
+ isolate: z23.boolean().optional().describe("Hide surrounding geometry. Requires part; default false.")
});
var inspectBufferInput = inspectInput.omit({ code: true });
var inspectAdvertisedInput = inspectInput.extend({ shot: cameraShotRecordInput });
@@ -42662,15 +42876,15 @@ function createKilnInspectDef(context = {}) {
};
}
var kilnInspectDef = createKilnInspectDef();
-var editOperationInput = z21.object({
- oldString: z21.string().describe("The exact text to replace, copied verbatim from the program (including whitespace and indentation, and with no line-number prefixes). Must be unique unless replaceAll is true."),
- newString: z21.string().describe("The replacement text. Use an empty string to delete."),
- replaceAll: z21.boolean().optional().describe("Replace every occurrence instead of failing when oldString matches more than once.")
+var editOperationInput = z23.object({
+ oldString: z23.string().describe("The exact text to replace, copied verbatim from the program (including whitespace and indentation, and with no line-number prefixes). Must be unique unless replaceAll is true."),
+ newString: z23.string().describe("The replacement text. Use an empty string to delete."),
+ replaceAll: z23.boolean().optional().describe("Replace every occurrence instead of failing when oldString matches more than once.")
});
-var editInput = z21.object({
- code: z21.string().describe("The Kiln program to patch. The full current source."),
- edits: z21.array(editOperationInput).min(1).max(20).describe("Edits applied in order against the program. If any one fails to match, none are applied and the reply says which. Batch related changes into a single call."),
- render: z21.boolean().optional().describe("Render the patched program and return the views (default true). false = patch only."),
+var editInput = z23.object({
+ code: z23.string().describe("The Kiln program to patch. The full current source."),
+ edits: z23.array(editOperationInput).min(1).max(20).describe("Edits applied in order against the program. If any one fails to match, none are applied and the reply says which. Batch related changes into a single call."),
+ render: z23.boolean().optional().describe("Render the patched program and return the views (default true). false = patch only."),
capture: captureInput,
detail: reviewDetailInput
});
@@ -42896,24 +43110,27 @@ function withCaptureCache(context) {
} : {}
};
}
-var rendererInput = z21.strictObject({
- action: z21.enum(["status", "reprobe"]).default("status")
+var rendererInput = z23.strictObject({
+ action: z23.enum(["status", "reprobe"]).default("status")
});
-async function readSavedRevision(target, collection, assetId, revisionId) {
+async function readSavedRevision(target, collection, assetId, revisionId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
try {
return await target.read(collection, assetId, revisionId);
} catch (error) {
if (error.code === "ENOENT")
- throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. kiln_assets { action: 'list', collection: '${collection}' } lists the saved revisions.`);
+ throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. ${listCall} lists the saved revisions.`);
throw error;
}
}
function createKilnProgramToolRegistry(suppliedContext = {}) {
+ return createProgramDefs(suppliedContext, "grouped");
+}
+function createProgramDefs(suppliedContext, presentation) {
toolRequirements(suppliedContext);
const store = suppliedContext.programStore ?? new MemoryProgramStore;
const context = withCaptureCache(withBuildCache({ ...suppliedContext, programStore: store }));
return [
- createKilnDiscoveryDef({ ...suppliedContext, programStore: store }),
+ createKilnDiscoveryDef({ ...suppliedContext, programStore: store }, presentation),
{
name: "kiln_renderer",
description: "Inspect status, or reprobe after renderer setup/repair to refresh this session and reset failed starts. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart. Read viewFidelity after rendering.",
@@ -42953,7 +43170,7 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
].map((def) => withProgramReferences(def, store, context.readSourceFile)),
createKilnSourceDef(store),
...context.projectStore ? [createKilnProjectDef(context.projectStore, context.projectBundleReader)] : [],
- ...context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary)] : [],
+ ...context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary, presentation)] : [],
...context.reviewStore && context.assetLibrary ? [
createKilnReviewDef({
reviewStore: context.reviewStore,
@@ -42961,7 +43178,7 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
requirements: context.requirements
})
] : [],
- ...createKilnAssetDefs({ ...context, programStore: store })
+ ...createKilnAssetDefs({ ...context, programStore: store }, presentation)
].map((def) => withWorkspaceContext(def, context)).map((def) => ({
...def,
annotations: {
@@ -42973,15 +43190,45 @@ function createKilnProgramToolRegistry(suppliedContext = {}) {
}
}));
}
+function createKilnOperationToolRegistry(context = {}) {
+ return projectOperationDefs(createProgramDefs(context, "operations"), context);
+}
var assetSelector = {
- collection: z21.string().regex(/^[a-z][a-z0-9_-]{0,79}$/).describe("Collection ID (list with kiln_assets action=collections): the user destination, else project.").default("project"),
- assetId: z21.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
- revisionId: z21.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)
+ collection: z23.string().regex(/^[a-z][a-z0-9_-]{0,79}$/).describe("Collection ID (list with kiln_assets action=collections): the user destination, else project.").default("project"),
+ assetId: z23.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
+ revisionId: z23.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)
};
-async function newestRevision(target, collection, assetId) {
+var ASSET_CONTRACT = {
+ collections: {
+ fields: [],
+ required: [],
+ description: "List configured asset storage collections. Collection is not project membership."
+ },
+ catalog: {
+ fields: ["assetId", "query", "offset", "limit"],
+ required: [],
+ description: "Search saved assets across configured collections with pagination."
+ },
+ list: {
+ fields: ["collection", "assetId", "query", "offset", "limit"],
+ required: [],
+ description: "Search saved assets in one collection with pagination."
+ },
+ get: {
+ fields: ["collection", "assetId", "revisionId"],
+ required: ["assetId"],
+ description: "Read a saved revision and its download descriptors. Omit revisionId for the newest revision."
+ },
+ restore: {
+ fields: ["collection", "assetId", "revisionId"],
+ required: ["assetId"],
+ description: "Restore exact saved source as programRef for editing or rendering. Omit revisionId for the newest revision. Does not overwrite the saved revision. Binary-only assets have no source."
+ }
+};
+async function newestRevision(target, collection, assetId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
const revisions = (await target.list(collection)).filter((a) => a.assetId === assetId);
if (!revisions.length)
- throw new Error(`Unknown asset ${assetId} in ${collection}; kiln_assets { action: 'list', collection: '${collection}' } lists them.`);
+ throw new Error(`Unknown asset ${assetId} in ${collection}; ${listCall} lists them.`);
const parents = new Set(revisions.map((a) => a.parentRevision).filter(Boolean));
const heads = revisions.filter((a) => !parents.has(a.revisionId));
const newest = (heads.length ? heads : revisions).sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
@@ -43046,7 +43293,12 @@ async function buildProgramAssetDraft(code, context, backdrop) {
}
};
}
-function createKilnAssetDefs(context) {
+function createKilnAssetDefs(context, presentation = "grouped") {
+ const listCall = (collection) => presentation === "operations" ? `kiln_assets_search({ collection: '${collection}' })` : `kiln_assets { action: 'list', collection: '${collection}' }`;
+ const selector = presentation === "operations" ? {
+ ...assetSelector,
+ collection: assetSelector.collection.describe("Collection ID from kiln_assets_collections; default project.")
+ } : assetSelector;
const library = () => {
if (!context.assetLibrary)
throw new Error("No asset library configured. The local CLI/MCP host supplies workspace collections; embedded hosts must inject assetLibrary.");
@@ -43074,38 +43326,38 @@ function createKilnAssetDefs(context) {
resources: (await Promise.resolve().then(() => (init_assets_resources(), exports_assets_resources))).assetLinks(collection, asset),
downloadUrls: await context.assetDownloadUrls?.(collection, asset.assetId, asset.revisionId)
});
- const saveInput = z21.object({
- collection: assetSelector.collection,
- programRef: z21.string(),
- name: z21.string().min(1).max(200),
- assetId: assetSelector.assetId.optional(),
- parentRevision: assetSelector.revisionId.optional(),
- tags: z21.array(z21.string().max(80)).max(30).optional(),
- brief: z21.string().max(8000).optional(),
- description: z21.string().max(4000).optional(),
- attribution: z21.object({
- model: z21.string().max(200).optional(),
- harness: z21.string().max(200).optional(),
- author: z21.string().max(200).optional()
+ const saveInput = z23.object({
+ collection: selector.collection,
+ programRef: z23.string(),
+ name: z23.string().min(1).max(200),
+ assetId: selector.assetId.optional(),
+ parentRevision: selector.revisionId.optional(),
+ tags: z23.array(z23.string().max(80)).max(30).optional(),
+ brief: z23.string().max(8000).optional(),
+ description: z23.string().max(4000).optional(),
+ attribution: z23.object({
+ model: z23.string().max(200).optional(),
+ harness: z23.string().max(200).optional(),
+ author: z23.string().max(200).optional()
}).optional(),
- backdrop: z21.enum(BACKDROP_IDS).optional().describe("Preview backdrop: the one the reviewed sheet used.")
- });
- const assetsInput = z21.object({
- action: z21.enum(["collections", "catalog", "list", "get", "restore"]).default("list"),
- collection: assetSelector.collection,
- assetId: assetSelector.assetId.optional(),
- revisionId: assetSelector.revisionId.optional().describe("get, restore: the saved revision; omitted, the newest."),
- query: z21.string().max(200).optional(),
- offset: z21.number().int().min(0).default(0),
- limit: z21.number().int().min(1).max(50).default(20)
- });
- const exportInput = z21.object(assetSelector);
+ backdrop: z23.enum(BACKDROP_IDS).optional().describe("Preview backdrop: the one the reviewed sheet used.")
+ });
+ const assetsInput = z23.object({
+ action: z23.enum(["collections", "catalog", "list", "get", "restore"]).default("list"),
+ collection: selector.collection,
+ assetId: selector.assetId.optional(),
+ revisionId: selector.revisionId.optional().describe("get, restore: the saved revision; omitted, the newest."),
+ query: z23.string().max(200).optional(),
+ offset: z23.number().int().min(0).default(0),
+ limit: z23.number().int().min(1).max(50).default(20)
+ });
+ const exportInput = z23.object(selector);
const profileExportInput = exportInput.extend({
- profile: z21.enum(["editable", "runtime"]).default("editable").describe("editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.")
+ profile: z23.enum(["editable", "runtime"]).default("editable").describe("editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.")
});
- const importInput = z21.object({
- ...assetSelector,
- sourceCollection: assetSelector.collection
+ const importInput = z23.object({
+ ...selector,
+ sourceCollection: selector.collection
});
return [
{
@@ -43121,7 +43373,7 @@ function createKilnAssetDefs(context) {
requirements: activeRequirements.binding
};
if (input.assetId && input.parentRevision) {
- const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision);
+ const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision, listCall(input.collection));
assertSavedRequirementsAuthorized(previous.manifest, activeRequirements);
}
const code = await context.programStore.get(input.programRef);
@@ -43136,6 +43388,7 @@ function createKilnAssetDefs(context) {
name: "kiln_assets",
description: "Browse saved assets: collections discovers storage; catalog searches all configured collections; list searches one. Both searches paginate. get returns a build record/downloads; restore loads exact source for kiln_source/kiln_edit. Collection is not project membership. Binary-only assets cannot restore source.",
inputSchema: assetsInput,
+ actionContract: ASSET_CONTRACT,
run: async (raw) => {
const input = assetsInput.parse(raw);
const activeRequirements = toolRequirements(context);
@@ -43180,10 +43433,10 @@ function createKilnAssetDefs(context) {
}))
};
}
- if (!input.assetId)
+ if (ASSET_CONTRACT[input.action].required.some((field) => !input[field]))
throw new Error(`kiln_assets ${input.action} requires assetId; kiln_assets { action: 'list', collection: '${input.collection}' } lists them.`);
- const revisionId = input.revisionId ?? await newestRevision(target, input.collection, input.assetId);
- const record = await readSavedRevision(target, input.collection, input.assetId, revisionId);
+ const revisionId = input.revisionId ?? await newestRevision(target, input.collection, input.assetId, listCall(input.collection));
+ const record = await readSavedRevision(target, input.collection, input.assetId, revisionId, listCall(input.collection));
if (input.action === "get")
return links(input.collection, record.manifest);
const saved = assertSavedRequirementsAuthorized(record.manifest, activeRequirements);
@@ -43203,9 +43456,9 @@ function createKilnAssetDefs(context) {
name: "kiln_present",
description: "Present one exact saved revision. Supporting MCP App clients show an interactive 3D card with GLB, editable ZIP, and source downloads. Every host receives exact artifact descriptors with resource URIs in the JSON result; verified hosts may also receive core MCP resource-link blocks. This tool does not launch a local browser in coding harnesses. Call after saving or when the user wants to see or download an asset.",
inputSchema: exportInput,
- outputSchema: z21.object({
- ok: z21.literal(true),
- collection: z21.string(),
+ outputSchema: z23.object({
+ ok: z23.literal(true),
+ collection: z23.string(),
asset: assetManifestSchema.pick({
assetId: true,
revisionId: true,
@@ -43216,25 +43469,25 @@ function createKilnAssetDefs(context) {
editable: true,
files: true
}).extend({
- build: z21.object({
- engine: z21.string(),
- rebuild: z21.enum(["engine-required", "external-dependencies-required"]),
- warningCount: z21.number().int(),
- warnings: z21.array(z21.string())
+ build: z23.object({
+ engine: z23.string(),
+ rebuild: z23.enum(["engine-required", "external-dependencies-required"]),
+ warningCount: z23.number().int(),
+ warnings: z23.array(z23.string())
}).optional()
}),
- resources: z21.array(z21.object({
- type: z21.literal("resource_link"),
- name: z21.string(),
- uri: z21.string(),
- mimeType: z21.string(),
- size: z21.number().int().nonnegative(),
- annotations: z21.object({
- audience: z21.array(z21.enum(["user", "assistant"])),
- priority: z21.number()
+ resources: z23.array(z23.object({
+ type: z23.literal("resource_link"),
+ name: z23.string(),
+ uri: z23.string(),
+ mimeType: z23.string(),
+ size: z23.number().int().nonnegative(),
+ annotations: z23.object({
+ audience: z23.array(z23.enum(["user", "assistant"])),
+ priority: z23.number()
})
})),
- downloadUrls: z21.record(z21.string(), z21.string()).optional()
+ downloadUrls: z23.record(z23.string(), z23.string()).optional()
}),
ui: {
resourceUri: KILN_ASSET_WIDGET_URI2,
@@ -43251,7 +43504,7 @@ function createKilnAssetDefs(context) {
inputSchema: profileExportInput,
run: async (raw) => {
const input = profileExportInput.parse(raw);
- const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId);
+ const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId, listCall(input.collection));
await Promise.resolve().then(() => init_draw_diagnostics());
if (input.profile === "runtime") {
const output = await (await Promise.resolve().then(() => (init_asset_export(), exports_asset_export))).exportAssetGlb(record, {
@@ -43285,7 +43538,7 @@ function createKilnAssetDefs(context) {
run: async (raw) => {
const input = importInput.parse(raw);
const target = library();
- const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId);
+ const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId, listCall(input.sourceCollection));
await target.import(input.collection, [record]);
return links(input.collection, record.manifest);
}
@@ -43409,7 +43662,7 @@ 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,
@@ -43476,6 +43729,7 @@ function resourceText(name, bytes) {
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
});
diff --git a/dist/mcp-server.mjs b/dist/mcp-server.mjs
index 7973553f..16341298 100644
--- a/dist/mcp-server.mjs
+++ b/dist/mcp-server.mjs
@@ -2085,7 +2085,7 @@ import { readFile } from "node:fs/promises";
var KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v5.html";
// src/engine-identity.ts
-var ENGINE_VERSION = "1.1.0";
+var ENGINE_VERSION = "1.2.0";
var ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
// src/requirements-json.ts
diff --git a/docs/sdk.md b/docs/sdk.md
index a3768251..de9284d8 100644
--- a/docs/sdk.md
+++ b/docs/sdk.md
@@ -136,6 +136,29 @@ the stability of the helpers it uses. Exact details retain the same structured
`stability` field. Implicit modeling remains available without a new opt-in switch;
the community exporter retains its explicit selection.
+## Named operation presentation
+
+In package version 1.2.0 and later, embeddings can select
+`createKilnMcpServer(context, { toolPresentation: 'operations' })`, or obtain the
+same definitions through `createKilnOperationToolRegistry(context)` from `tools`.
+The default MCP and native interfaces retain their existing grouped tools.
+
+With asset and material storage, and without project/review or renderer-control
+callbacks, the named presentation exposes 21 tools. Asset browsing becomes
+`kiln_assets_search` with an optional collection; material browsing becomes
+`kiln_material_search` with `scope: 'all' | 'presets' | 'saved'`. Material creation
+uses `kiln_material_create` with a required `definition` discriminated by
+`kind: 'preset' | 'procedural'`. Saving, importing, retrieval and source restoration
+remain explicit operations. Renderer controls appear only when their callbacks
+exist. Connected `tools/list` remains authoritative.
+
+Action requirements and field constraints come from the shared engine registry.
+Generation rejects unclassified action/field additions and missing required
+fields. Hosts select supported operations and add their actual execution and
+persistence policy; do not copy domain schemas or assume a local read hint
+describes a quota-admitted cloud job. This API change does not publish a package
+or deploy a hosted service. Actual client acceptance is still required.
+
## Maintainer qualification
`node scripts/build-runtime.mjs all` builds both executable bundles and the ESM SDK.
diff --git a/docs/tools-operations.md b/docs/tools-operations.md
new file mode 100644
index 00000000..deabdc11
--- /dev/null
+++ b/docs/tools-operations.md
@@ -0,0 +1,1529 @@
+# Named operation reference
+
+Available in package version 1.2.0 and later. Generated with `bun run docs:tools` from the same engine registry as the default [local tools](tools.md). This profile supplies asset and material storage without project/review or renderer-control callbacks. Other host capabilities can change the tool list; connected tools/list is authoritative. See the [embedding contract](sdk.md#named-operation-presentation).
+
+Select this presentation explicitly with `createKilnMcpServer(context, { toolPresentation: "operations" })`. Existing local tool names and actions remain the default. Host authentication, request quotas, isolation and persistence policy are outside this engine reference.
+
+Use kiln_discover for helper contracts and complete shape: records; kiln_capabilities reports configuration, not proof of successful rendering. Material creation requires a typed definition. Search results preserve collection, asset/material and revision identity. Saving remains an explicit decision.
+
+## kiln_discover
+
+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.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 500
+ },
+ "ids": {
+ "minItems": 1,
+ "maxItems": 6,
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 120
+ }
+ },
+ "overview": {
+ "type": "boolean",
+ "const": true
+ },
+ "family": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 120
+ },
+ "kind": {
+ "type": "string",
+ "enum": [
+ "operation",
+ "assembly",
+ "recipe",
+ "shape"
+ ]
+ },
+ "tags": {
+ "minItems": 1,
+ "maxItems": 8,
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 120
+ }
+ },
+ "offset": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 10000
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 12
+ }
+ },
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_capabilities
+
+Inspect declared host capabilities, execution limits and available storage. Observed rendering fidelity is returned by each render.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {},
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_validate
+
+Check program syntax, sandbox rules and retired globals before building. Returns findings with codes, lines and repair hints where available; use kiln_render to evaluate geometry and see the asset. Supply code OR programRef (kept in this process until it ends). Invalid drafts keep a ref.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "code": {
+ "description": "New source.",
+ "type": "string"
+ },
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])",
+ "description": "Returned p_ handle or full sha256 ref."
+ }
+ }
+}
+```
+
+</details>
+
+## kiln_render
+
+Build and return metrics, part paths and images. If partsTruncated, use kiln_inspect listParts. Omit capture for six views, preset/cells for orbit grids, or kiln.capture.v1/v2 shots for exact orthographic/perspective cameras; v2 adds hide. Check viewFidelity before judging materials. Failed builds return errors without images. Supply code OR programRef (kept in this process until it ends). Invalid drafts keep a ref.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "code": {
+ "description": "New source.",
+ "type": "string"
+ },
+ "capture": {
+ "description": "Omit for six views; preset/cells for orbit sheets. Use kiln.capture.v1 or v2 with 1..9 shots for exact cameras. v2 adds hide: exact paths or unique names. Framing retains subject bounds.",
+ "anyOf": [
+ {
+ "type": "object",
+ "properties": {
+ "version": {
+ "type": "string",
+ "enum": [
+ "kiln.capture.v1",
+ "kiln.capture.v2"
+ ]
+ },
+ "shots": {
+ "minItems": 1,
+ "maxItems": 9,
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "subject": {
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false
+ },
+ "visibility": {
+ "type": "string",
+ "enum": [
+ "context",
+ "isolate"
+ ]
+ },
+ "hide": {
+ "maxItems": 64,
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 1024
+ }
+ },
+ "camera": {
+ "oneOf": [
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "const": "orbit"
+ },
+ "azimuthDeg": {
+ "type": "number"
+ },
+ "elevationDeg": {
+ "type": "number"
+ },
+ "relativeTo": {
+ "type": "string",
+ "enum": [
+ "world",
+ "asset",
+ "part"
+ ]
+ },
+ "padding": {
+ "type": "number",
+ "exclusiveMinimum": 0,
+ "maximum": 100
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "const": "explicit"
+ },
+ "projection": {
+ "type": "string",
+ "enum": [
+ "orthographic",
+ "perspective"
+ ]
+ },
+ "position": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ },
+ "target": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ },
+ "relativeTo": {
+ "type": "string",
+ "enum": [
+ "world",
+ "asset",
+ "part",
+ "local"
+ ]
+ },
+ "frame": {
+ "type": "object",
+ "properties": {
+ "origin": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ },
+ "rotation": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ }
+ },
+ "additionalProperties": false
+ },
+ "framing": {
+ "type": "string",
+ "enum": [
+ "explicit",
+ "bounds"
+ ]
+ },
+ "padding": {
+ "type": "number",
+ "exclusiveMinimum": 0,
+ "maximum": 100
+ },
+ "targetOffset": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ },
+ "up": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ },
+ "halfHeight": {
+ "type": "number",
+ "exclusiveMinimum": 0
+ },
+ "fovDeg": {
+ "type": "number",
+ "exclusiveMinimum": 0,
+ "exclusiveMaximum": 180
+ },
+ "near": {
+ "type": "number",
+ "exclusiveMinimum": 0
+ },
+ "far": {
+ "type": "number",
+ "exclusiveMinimum": 0
+ }
+ },
+ "required": [
+ "type",
+ "projection",
+ "position"
+ ],
+ "additionalProperties": false
+ }
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ },
+ "cols": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 3
+ },
+ "size": {
+ "type": "integer",
+ "minimum": 128,
+ "maximum": 2048
+ },
+ "output": {
+ "type": "string",
+ "enum": [
+ "grid",
+ "separate"
+ ]
+ },
+ "backdrop": {
+ "description": "neutral (default); light for dark parts, dark for light parts.",
+ "type": "string",
+ "enum": [
+ "neutral",
+ "dark",
+ "light"
+ ]
+ }
+ },
+ "required": [
+ "version",
+ "shots"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "preset": {
+ "description": "COLSxROWS; default 3x2. Fewer views for simple shapes, up to 3x3.",
+ "type": "string",
+ "enum": [
+ "1x1",
+ "1x2",
+ "2x1",
+ "3x1",
+ "2x2",
+ "3x2",
+ "3x3"
+ ]
+ },
+ "cells": {
+ "description": "Row-major cameras; omit for preset defaults. Count cannot exceed preset capacity (max 9).",
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "azimuthDeg": {
+ "type": "number",
+ "description": "0 = front, 90 = right, 180 = back, 270 = left. Wraps."
+ },
+ "elevationDeg": {
+ "type": "number",
+ "description": "0 eye level; positive above, negative below. Clamped -89..89."
+ },
+ "zoom": {
+ "description": "Bounds padding: below 1 crops, above 1 pulls back; omit for auto-framing.",
+ "type": "number"
+ },
+ "name": {
+ "description": "Label; defaults to angles.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "azimuthDeg",
+ "elevationDeg"
+ ]
+ }
+ },
+ "backdrop": {
+ "description": "neutral (default); light for dark parts, dark for light parts.",
+ "type": "string",
+ "enum": [
+ "neutral",
+ "dark",
+ "light"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ ]
+ },
+ "detail": {
+ "description": "compact (default) groups findings by code; lean: verdict, blockers, metrics only; full: every finding, rule and part plus the retained report path",
+ "type": "string",
+ "enum": [
+ "lean",
+ "compact",
+ "full"
+ ]
+ },
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])",
+ "description": "Returned p_ handle or full sha256 ref."
+ }
+ }
+}
+```
+
+</details>
+
+## kiln_screenshot_animation
+
+Review animation images, poseBounds and loopClosure endpoint evidence. loopIntent is createClip({loop}); open is valid for one-shots; closed endpoints do not prove smooth velocity. Check motion, attachments and requested clearance; sampled bounds do not certify continuous contact or collision safety. Use shot for camera/subject, frameTimes for phases, and framing locked (default) or follow. Add phases when symmetry hides motion. The program must define animate(). Check viewFidelity before judging materials. Supply code OR programRef (kept in this process until it ends). Invalid drafts keep a ref.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "shot": {
+ "description": "One exact camera shot. Shape: kiln_discover ids [\"shape:camera-shot\"].",
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ },
+ "measureParts": {
+ "description": "Exact names or paths of subtrees measured together at each phase, independent of camera selection.",
+ "minItems": 1,
+ "maxItems": 16,
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false
+ }
+ },
+ "frames": {
+ "type": "integer",
+ "minimum": 2,
+ "maximum": 6
+ },
+ "frameTimes": {
+ "description": "Ordered phase fractions 0..1; mutually exclusive with frames.",
+ "minItems": 1,
+ "maxItems": 9,
+ "type": "array",
+ "items": {
+ "type": "number",
+ "minimum": 0,
+ "maximum": 1
+ }
+ },
+ "framing": {
+ "type": "string",
+ "enum": [
+ "locked",
+ "follow"
+ ]
+ },
+ "size": {
+ "description": "Frame size in px; default 256.",
+ "type": "integer",
+ "minimum": 128,
+ "maximum": 1024
+ },
+ "detail": {
+ "description": "compact (default) groups findings by code; lean: verdict, blockers, metrics only; full: every finding, rule and part plus the retained report path",
+ "type": "string",
+ "enum": [
+ "lean",
+ "compact",
+ "full"
+ ]
+ },
+ "code": {
+ "description": "New source.",
+ "type": "string"
+ },
+ "clip": {
+ "type": "string",
+ "description": "The animation clip to view, by name (e.g. \"walk\", \"attack\"). Must be one your animate() returns."
+ },
+ "camera": {
+ "description": "Camera angle: right (default — side profile, best for leg swing + knee bend direction), front (reveals sideways/lateral motion), back, left, top, or three-quarter.",
+ "type": "string"
+ },
+ "perFrame": {
+ "description": "Return the frames as separate high-res images instead of one composite grid. Default false.",
+ "type": "boolean"
+ },
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])",
+ "description": "Returned p_ handle or full sha256 ref."
+ }
+ },
+ "required": [
+ "clip"
+ ]
+}
+```
+
+</details>
+
+## kiln_view_interior
+
+Render roof-off floor-plan, dollhouse, and eye-level cutaway views. Optional versioned capture selects custom roof-off shots. Select a roof by nodeName or let Kiln resolve its role/name. Review roofsHidden and warnings for unresolved occlusion. Supply code OR programRef (kept in this process until it ends). Invalid drafts keep a ref.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "capture": {
+ "description": "Cameras, as kiln_render capture takes them. Shape: kiln_discover ids [\"shape:capture\"].",
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ },
+ "code": {
+ "description": "New source.",
+ "type": "string"
+ },
+ "nodeName": {
+ "description": "Override: lift the roof by exact node name instead of by role. Matches that node and its children. Normally OMIT it — Kiln finds the roof from its semantic role (anything built with createRoofPlanes/createGableRoof), falling back to historical \"Roof\" naming.",
+ "type": "string"
+ },
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])",
+ "description": "Returned p_ handle or full sha256 ref."
+ }
+ }
+}
+```
+
+</details>
+
+## kiln_inspect
+
+List part paths and inspect joints, clearances and edit preservation. listParts filters names/paths with query; follow partListing.nextOffset on the same programRef/query. measure/surfacePairs return distances, not fit certificates. compare reports static changes and separate animation channel changes; paths adds complete static subtree summaries. image:false skips rendering. Otherwise use part/orbit or exact shot; check viewFidelity for materials. Supply code OR programRef (kept in this process until it ends). Invalid drafts keep a ref.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "image": {
+ "description": "False: requires listParts/measure/surfacePairs/compare; no image or camera controls. Default true.",
+ "type": "boolean"
+ },
+ "detail": {
+ "description": "compact (default) groups findings by code; lean: verdict, blockers, metrics only; full: every finding, rule and part plus the retained report path",
+ "type": "string",
+ "enum": [
+ "lean",
+ "compact",
+ "full"
+ ]
+ },
+ "listParts": {
+ "description": "List exported-scene paths, including nested parts. Default 80, max 100 per page. Follow partListing.nextOffset with the same programRef/query. image:false avoids rendering.",
+ "type": "object",
+ "properties": {
+ "query": {
+ "description": "Case-insensitive substring of name or exact encoded path; not a regex.",
+ "type": "string",
+ "maxLength": 4096
+ },
+ "offset": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 9007199254740991
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 100
+ },
+ "placement": {
+ "description": "Add world position, rotation, scale, mirroring and bounds per part; pages of 50.",
+ "type": "boolean"
+ }
+ },
+ "additionalProperties": false
+ },
+ "surfacePairs": {
+ "description": "[from,to] pairs of exact listParts paths or unambiguous node names; check surfaceMeasurements.status and each result.",
+ "minItems": 1,
+ "maxItems": 12,
+ "type": "array",
+ "items": {
+ "minItems": 2,
+ "maxItems": 2,
+ "type": "array",
+ "items": {
+ "type": "string",
+ "maxLength": 4096
+ }
+ }
+ },
+ "compare": {
+ "description": "Static geometry/material/transform/bounds under current host settings. Follow nextOffset; paths adds complete subtrees.",
+ "type": "object",
+ "properties": {
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])"
+ },
+ "offset": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 9007199254740991
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 100
+ },
+ "paths": {
+ "description": "Exact baseline node paths, scene-prefixed without primitive children. Complete subtree summaries.",
+ "minItems": 1,
+ "maxItems": 12,
+ "type": "array",
+ "items": {
+ "type": "string",
+ "maxLength": 4096
+ }
+ }
+ },
+ "required": [
+ "programRef"
+ ],
+ "additionalProperties": false
+ },
+ "measure": {
+ "description": "Default anchors: origin/local-point distance. Surface: disjoint mesh triangles, omit points. Rest pose, asset units. Check status/bounds; no solid clearance/attachment proof.",
+ "type": "object",
+ "properties": {
+ "mode": {
+ "type": "string",
+ "enum": [
+ "anchors",
+ "surface"
+ ]
+ },
+ "from": {
+ "type": "object",
+ "properties": {
+ "subject": {
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false
+ },
+ "point": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ }
+ },
+ "required": [
+ "subject"
+ ],
+ "additionalProperties": false
+ },
+ "to": {
+ "type": "object",
+ "properties": {
+ "subject": {
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false
+ },
+ "point": {
+ "minItems": 3,
+ "maxItems": 3,
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ }
+ },
+ "required": [
+ "subject"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "required": [
+ "from",
+ "to"
+ ],
+ "additionalProperties": false
+ },
+ "shot": {
+ "description": "One exact camera shot. Shape: kiln_discover ids [\"shape:camera-shot\"].",
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ },
+ "code": {
+ "description": "New source.",
+ "type": "string"
+ },
+ "part": {
+ "description": "Frame named part and descendants (case-insensitive, substring fallback). Omit for whole asset.",
+ "type": "string"
+ },
+ "view": {
+ "description": "front/right/back/left/top/three-quarter (default). Orbit angles override.",
+ "type": "string"
+ },
+ "azimuthDeg": {
+ "description": "Orbit degrees: 0 front, 90 right, 180 back, 270 left. Wraps.",
+ "type": "number"
+ },
+ "elevationDeg": {
+ "description": "Elevation degrees: 0 eye level, positive above. Clamped -89..89.",
+ "type": "number"
+ },
+ "zoom": {
+ "description": "Bounds padding 1..4; default 1.2. Larger = more context.",
+ "type": "number"
+ },
+ "isolate": {
+ "description": "Hide surrounding geometry. Requires part; default false.",
+ "type": "boolean"
+ },
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])",
+ "description": "Returned p_ handle or full sha256 ref."
+ }
+ }
+}
+```
+
+</details>
+
+## kiln_edit
+
+Atomically apply ordered exact-string replacements and render. Copy anchors from kiln_source. Supply code OR programRef. Returns programRef (kept in this process until it ends), parentRef, diff and preservation comparing static data and animation channels. Review changes; use kiln_inspect compare for more pages or protected subtrees. Failed comparison preserves the repair; render:false leaves preservation not_assessed. capture selects cameras; includeCode adds the patched source, bounded.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "code": {
+ "description": "New source.",
+ "type": "string"
+ },
+ "edits": {
+ "minItems": 1,
+ "maxItems": 20,
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "oldString": {
+ "type": "string",
+ "description": "The exact text to replace, copied verbatim from the program (including whitespace and indentation, and with no line-number prefixes). Must be unique unless replaceAll is true."
+ },
+ "newString": {
+ "type": "string",
+ "description": "The replacement text. Use an empty string to delete."
+ },
+ "replaceAll": {
+ "description": "Replace every occurrence instead of failing when oldString matches more than once.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "oldString",
+ "newString"
+ ]
+ },
+ "description": "Edits applied in order against the program. If any one fails to match, none are applied and the reply says which. Batch related changes into a single call."
+ },
+ "render": {
+ "description": "Render the patched program and return the views (default true). false = patch only.",
+ "type": "boolean"
+ },
+ "capture": {
+ "description": "Cameras, as kiln_render capture takes them. Shape: kiln_discover ids [\"shape:capture\"].",
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ },
+ "detail": {
+ "description": "compact (default) groups findings by code; lean: verdict, blockers, metrics only; full: every finding, rule and part plus the retained report path",
+ "type": "string",
+ "enum": [
+ "lean",
+ "compact",
+ "full"
+ ]
+ },
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])",
+ "description": "Returned p_ handle or full sha256 ref."
+ },
+ "includeCode": {
+ "description": "Also return the patched source, bounded with the result; kiln_source pages it. Default false.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "edits"
+ ]
+}
+```
+
+</details>
+
+## kiln_source
+
+Read a saved program revision without changing it. Returns exact source text in bounded pages, or searches for literal text with surrounding context. Copy edit anchors from code. Follow nextOffset for more; use matchOffset + 1 to find the next match. Offsets count UTF-16 characters, not bytes.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "programRef": {
+ "type": "string",
+ "pattern": "^(?:sha256:[a-f0-9]{64}|p_[a-f0-9]{12}(?:[a-f0-9]{4}){0,13})(?![\\s\\S])",
+ "description": "Returned p_ handle or full sha256 ref."
+ },
+ "offset": {
+ "default": 0,
+ "description": "UTF-16 character offset; use nextOffset to continue.",
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 9007199254740991
+ },
+ "limit": {
+ "default": 8000,
+ "description": "Maximum characters returned.",
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 16000
+ },
+ "query": {
+ "description": "Find literal text at or after offset; return bounded surrounding source.",
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 1000
+ }
+ },
+ "required": [
+ "programRef"
+ ]
+}
+```
+
+</details>
+
+## kiln_material_search
+
+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.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "tag": {
+ "description": "presets, list: keep one tag.",
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 80
+ },
+ "scope": {
+ "default": "all",
+ "type": "string",
+ "enum": [
+ "all",
+ "presets",
+ "saved"
+ ]
+ }
+ },
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_material_get
+
+Read a material revision, provenance and portable specification. Omit revisionId only when exactly one revision exists.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "materialId": {
+ "description": "get: the id a project palette lists as resourceId; create-preset: optional id.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "revisionId": {
+ "description": "get: the immutable revision; omitted, the material's only revision.",
+ "type": "string",
+ "pattern": "^sha256:[a-f0-9]{64}$"
+ }
+ },
+ "required": [
+ "materialId"
+ ],
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_material_create
+
+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.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "definition": {
+ "oneOf": [
+ {
+ "type": "object",
+ "properties": {
+ "presetId": {
+ "description": "create-preset: an id from presets.",
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 80
+ },
+ "seed": {
+ "description": "create-preset.",
+ "type": "integer",
+ "minimum": -2147483648,
+ "maximum": 2147483647
+ },
+ "creator": {
+ "description": "create-preset.",
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 1000
+ },
+ "license": {
+ "description": "create-preset: spdx, url and attribution.",
+ "type": "object",
+ "properties": {
+ "spdx": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 1000
+ },
+ "url": {
+ "type": "string",
+ "maxLength": 2000,
+ "format": "uri"
+ },
+ "attribution": {
+ "type": "string",
+ "maxLength": 4000
+ }
+ },
+ "required": [
+ "spdx",
+ "url",
+ "attribution"
+ ],
+ "additionalProperties": false
+ },
+ "size": {
+ "description": "create-preset: map edge in pixels; default 256.",
+ "anyOf": [
+ {
+ "type": "number",
+ "const": 64
+ },
+ {
+ "type": "number",
+ "const": 128
+ },
+ {
+ "type": "number",
+ "const": 256
+ },
+ {
+ "type": "number",
+ "const": 512
+ }
+ ]
+ },
+ "materialId": {
+ "description": "get: the id a project palette lists as resourceId; create-preset: optional id.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "kind": {
+ "type": "string",
+ "const": "preset"
+ }
+ },
+ "required": [
+ "presetId",
+ "seed",
+ "creator",
+ "license",
+ "kind"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "draft": {
+ "description": "create-procedural: materialId, name, tileable, sources, maps with layered procedural specs; optional tags, physicalSizeMeters, parameters. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ },
+ "kind": {
+ "type": "string",
+ "const": "procedural"
+ }
+ },
+ "required": [
+ "draft",
+ "kind"
+ ],
+ "additionalProperties": false
+ }
+ ]
+ }
+ },
+ "required": [
+ "definition"
+ ],
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_material_import
+
+Import complete normalized material records and embedded PNGs. Does not fetch URLs or execute source.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "payload": {
+ "description": "import: schemaVersion 1 and complete normalized records with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
+ "type": "object",
+ "propertyNames": {
+ "type": "string"
+ },
+ "additionalProperties": {}
+ }
+ },
+ "required": [
+ "payload"
+ ],
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_save
+
+Save a completed source revision into the user-requested collection, or project when none was requested. Persists exact GLB, source, preview and build record. Use programRef returned by render/edit. To revise an asset, pass assetId and parentRevision; earlier revisions stay intact. Returns downloadable resources; draft renders never populate collections.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "collection": {
+ "default": "project",
+ "description": "Collection ID from kiln_assets_collections; default project.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "programRef": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 200
+ },
+ "assetId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "parentRevision": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "tags": {
+ "maxItems": 30,
+ "type": "array",
+ "items": {
+ "type": "string",
+ "maxLength": 80
+ }
+ },
+ "brief": {
+ "type": "string",
+ "maxLength": 8000
+ },
+ "description": {
+ "type": "string",
+ "maxLength": 4000
+ },
+ "attribution": {
+ "type": "object",
+ "properties": {
+ "model": {
+ "type": "string",
+ "maxLength": 200
+ },
+ "harness": {
+ "type": "string",
+ "maxLength": 200
+ },
+ "author": {
+ "type": "string",
+ "maxLength": 200
+ }
+ }
+ },
+ "backdrop": {
+ "description": "Preview backdrop: the one the reviewed sheet used.",
+ "type": "string",
+ "enum": [
+ "neutral",
+ "dark",
+ "light"
+ ]
+ }
+ },
+ "required": [
+ "programRef",
+ "name"
+ ]
+}
+```
+
+</details>
+
+## kiln_assets_collections
+
+List configured asset storage collections. Collection is not project membership.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {},
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_assets_search
+
+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.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "collection": {
+ "description": "Collection ID from kiln_assets_collections; omitted searches all configured collections.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "assetId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "query": {
+ "type": "string",
+ "maxLength": 200
+ },
+ "offset": {
+ "default": 0,
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 9007199254740991
+ },
+ "limit": {
+ "default": 20,
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 50
+ }
+ },
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_assets_get
+
+Read a saved revision and its download descriptors. Omit revisionId for the newest revision.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "collection": {
+ "default": "project",
+ "description": "Collection ID from kiln_assets_collections; default project.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "assetId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "revisionId": {
+ "description": "get, restore: the saved revision; omitted, the newest.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ }
+ },
+ "required": [
+ "assetId"
+ ],
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_assets_restore
+
+Restore exact saved source as programRef for editing or rendering. Omit revisionId for the newest revision. Does not overwrite the saved revision. Binary-only assets have no source.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "collection": {
+ "default": "project",
+ "description": "Collection ID from kiln_assets_collections; default project.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "assetId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "revisionId": {
+ "description": "get, restore: the saved revision; omitted, the newest.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ }
+ },
+ "required": [
+ "assetId"
+ ],
+ "additionalProperties": false
+}
+```
+
+</details>
+
+## kiln_present
+
+Present one exact saved revision. Supporting MCP App clients show an interactive 3D card with GLB, editable ZIP, and source downloads. Every host receives exact artifact descriptors with resource URIs in the JSON result; verified hosts may also receive core MCP resource-link blocks. This tool does not launch a local browser in coding harnesses. Call after saving or when the user wants to see or download an asset.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "collection": {
+ "default": "project",
+ "description": "Collection ID from kiln_assets_collections; default project.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "assetId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "revisionId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ }
+ },
+ "required": [
+ "assetId",
+ "revisionId"
+ ]
+}
+```
+
+</details>
+
+## kiln_export
+
+Export one saved revision. Default editable returns exact GLB, source, preview, and manifest descriptors; configured hosts may include portable editable ZIP download URLs. Opt-in runtime returns a standalone GLB plus a versioned metadata sidecar, moving only Kiln review clips out of GLB extras while preserving native animation and application metadata. Resource URIs remain readable through resources/read. Canonical revisions never change; no binary bytes are placed in tool text.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "collection": {
+ "default": "project",
+ "description": "Collection ID from kiln_assets_collections; default project.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "assetId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "revisionId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "profile": {
+ "default": "editable",
+ "description": "editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.",
+ "type": "string",
+ "enum": [
+ "editable",
+ "runtime"
+ ]
+ }
+ },
+ "required": [
+ "assetId",
+ "revisionId"
+ ]
+}
+```
+
+</details>
+
+## kiln_import
+
+Copy a pinned asset revision between configured collections, preserving identity and provenance. Copies never track later edits automatically. For a GLB or downloaded ZIP on disk, use kiln import <file> --collection <name> in the CLI.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "collection": {
+ "default": "project",
+ "description": "Collection ID from kiln_assets_collections; default project.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "assetId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "revisionId": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ },
+ "sourceCollection": {
+ "default": "project",
+ "description": "Collection ID from kiln_assets_collections; default project.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_-]{0,79}$"
+ }
+ },
+ "required": [
+ "assetId",
+ "revisionId"
+ ]
+}
+```
+
+</details>
diff --git a/package.json b/package.json
index 2a0cbd92..ff965f2d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@instruktlabs/kiln",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Create and refine procedural 3D assets with JavaScript, image feedback, and reusable source revisions.",
"license": "MIT",
"author": "Matthew Kissinger",
@@ -299,6 +299,7 @@
"docs/runtime.md",
"docs/sdk.md",
"docs/tools.md",
+ "docs/tools-operations.md",
"README.md",
"CONTRIBUTING.md",
"LICENSE",
diff --git a/plugin.json b/plugin.json
index 49cc30fd..4132c8e9 100644
--- a/plugin.json
+++ b/plugin.json
@@ -2,7 +2,7 @@
"name": "kiln",
"displayName": "Kiln",
"description": "Build and revise 3D assets with your coding agent. Write JavaScript, inspect selected views, edit saved source revisions, and export GLB files locally.",
- "version": "1.1.0",
+ "version": "1.2.0",
"license": "MIT",
"homepage": "https://github.com/instruktlabs/kiln",
"keywords": [
diff --git a/plugins/kiln-engine.release.json b/plugins/kiln-engine.release.json
index a96d1a7c..a4a3c717 100644
--- a/plugins/kiln-engine.release.json
+++ b/plugins/kiln-engine.release.json
@@ -1,4 +1,4 @@
{
- "version": "1.1.0",
- "engineVersion": "1.1.0"
+ "version": "1.2.0",
+ "engineVersion": "1.2.0"
}
diff --git a/plugins/kiln-engine/.claude-plugin/plugin.json b/plugins/kiln-engine/.claude-plugin/plugin.json
index 8fb43ee2..c8e99cea 100644
--- a/plugins/kiln-engine/.claude-plugin/plugin.json
+++ b/plugins/kiln-engine/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "kiln-engine",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Set up a local Kiln workspace to create, inspect and revise editable 3D assets with Claude Code or Codex.",
"author": {
"name": "Instrukt Labs",
diff --git a/plugins/kiln-engine/README.md b/plugins/kiln-engine/README.md
index d3feb542..d20d6192 100644
--- a/plugins/kiln-engine/README.md
+++ b/plugins/kiln-engine/README.md
@@ -1,7 +1,7 @@
# Kiln local plugin
-Plugin version 1.1.0, maintained by Instrukt Labs under the MIT license.
-This plugin pins engine 1.1.0. Registry setup requires that exact version
+Plugin version 1.2.0, maintained by Instrukt Labs under the MIT license.
+This plugin pins engine 1.2.0. Registry setup requires that exact version
to be published. Use a published release tag for normal installation or a reviewed
local archive for development qualification. The installation ID remains
`kiln-engine@instruktlabs`.
@@ -31,7 +31,7 @@ codex plugin add kiln-engine@instruktlabs
Restart or reload your coding agent's plugins as its installation message directs.
Then ask it to set up a Kiln workspace. The maintained setup skill runs this
plugin's `bin/kiln-setup-workspace.mjs` with Node, installs
-`@instruktlabs/[email protected]` outside the project and configures your chosen
+`@instruktlabs/[email protected]` outside the project and configures your chosen
workspace. The same initializer supports existing projects and new workspaces.
The plugin registers setup only. The workspace supplies authoring skills and one
diff --git a/plugins/kiln-engine/package-provenance.json b/plugins/kiln-engine/package-provenance.json
index db5172e5..e3173fe8 100644
--- a/plugins/kiln-engine/package-provenance.json
+++ b/plugins/kiln-engine/package-provenance.json
@@ -1,20 +1,20 @@
{
"schemaVersion": 1,
"kind": "kiln-local-plugin",
- "pluginVersion": "1.1.0",
- "engineVersion": "1.1.0",
+ "pluginVersion": "1.2.0",
+ "engineVersion": "1.2.0",
"executables": [
"bin/kiln-setup-workspace.mjs"
],
"files": {
".claude-plugin/icon.png": "sha256:b4b651c402793b7e27cab780f04b14f80daec6d0cd5b7e4e90313930581a54e9",
- ".claude-plugin/plugin.json": "sha256:189394253cf57f988fd82b31dad05012d693615a50126eebb29bab3e80e3a2a9",
+ ".claude-plugin/plugin.json": "sha256:616a6a61da072fcfdd4d0e1cf513e0e91bf1e56fb61b9b02d23e72fa291556bc",
"bin/kiln-setup-workspace.mjs": "sha256:3d9a30236919a6ca91acb6b26f808cec442e6edc3dd88fe010645b010d76e838",
"LICENSE": "sha256:cdba278ebf1d6de618869936226bf03be4887179c128efc7aaa13d22034826a5",
- "plugin.json": "sha256:428ab085c6257ccc0e2dec3c7d4f9b6e02db0024a5f0b355410a30d6282dcd1d",
+ "plugin.json": "sha256:3437107d46ad4fef4a710a8e821e56b43894cc1722504fe4e8ff0120fa6a8d8d",
"PRIVACY.md": "sha256:5f58d981667e40441e21c2dec411f269a9a67a6141cec61976d27088fb12573b",
- "README.md": "sha256:6a7fc436113f7493c884b2c495629351b01b2cd7e82e7b808f3abe73b9eb9af4",
- "runtime.json": "sha256:253f76044dcc162295ca760ff584d1d6894068357c727a56b077b44278f38eb3",
+ "README.md": "sha256:0b82e6eb8b679f8b991c1a5567957574ed7b3341a87ef989403e5521f83ab50e",
+ "runtime.json": "sha256:5ebac8387f4bedcc7cac02a36f73c5ffba969ce6c8c6e2b0e356ef569168d0a5",
"skills/kiln-setup-workspace/references/plugin-install.md": "sha256:c338fb792e7fad0364c3e1a13c94c506afa1395489ec1b6e83b36d04728935fb",
"skills/kiln-setup-workspace/references/renderer-setup.md": "sha256:b743b1b2827fa814385990e1e5b849391cb427413e9c016d273aa19cebd46031",
"skills/kiln-setup-workspace/SKILL.md": "sha256:65ed926b3503a33f4fe793e84e4a045ce36e3967f0e6b340e456a15dd010ce54"
diff --git a/plugins/kiln-engine/plugin.json b/plugins/kiln-engine/plugin.json
index 29f6a733..ffca8188 100644
--- a/plugins/kiln-engine/plugin.json
+++ b/plugins/kiln-engine/plugin.json
@@ -1,7 +1,7 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "kiln-engine",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Set up a local Kiln workspace to create, inspect and revise editable 3D assets with Claude Code or Codex.",
"author": {
"name": "Instrukt Labs",
diff --git a/plugins/kiln-engine/runtime.json b/plugins/kiln-engine/runtime.json
index 5d821ecb..df4e63ac 100644
--- a/plugins/kiln-engine/runtime.json
+++ b/plugins/kiln-engine/runtime.json
@@ -1,6 +1,6 @@
{
"name": "@instruktlabs/kiln",
- "version": "1.1.0",
+ "version": "1.2.0",
"harnesses": [
"claude",
"codex",
diff --git a/plugins/kiln-hosted/README.md b/plugins/kiln-hosted/README.md
index 30315d88..d9d2d867 100644
--- a/plugins/kiln-hosted/README.md
+++ b/plugins/kiln-hosted/README.md
@@ -46,12 +46,14 @@ application builds independently in the private `instruktlabs/kiln-hosted`
repository. No private application source or credentials are needed to build this
draft with `node scripts/package-hosted-plugin.mjs FRESH_OUTPUT_DIRECTORY`.
-`tool-surface.json` records the 26 public operation names generated from the
-qualified private candidate using the published engine 1.0.0. It contains no
-service configuration or tool implementation. The private candidate's protocol
-parity checks establish these names; the packaging tests validate review cases
-against them. Refresh this generated record when the qualified service contract
-changes. The plugin version and hosted engine version are recorded separately.
+`tool-surface.json` and the accompanying skill/review cases retain the historical
+26-operation snapshot from the engine 1.0.0 private candidate. They do not describe
+the approved replacement design or establish current service readiness. The
+engine 1.2.0 adds a shared 21-tool presentation.
+After the private service adopts and qualifies that package, regenerate this
+snapshot and align its skill/review cases from that exact candidate before any
+directory submission. The draft plugin version and historical hosted engine
+version are recorded separately; neither is a deployment receipt.
The public product name is Kiln, published by Instrukt Labs. Directory submissions
and live-service qualification remain deferred to the private hosting work.
diff --git a/plugins/kiln-hosted/plugin.json b/plugins/kiln-hosted/plugin.json
index f8c939be..2cf87260 100644
--- a/plugins/kiln-hosted/plugin.json
+++ b/plugins/kiln-hosted/plugin.json
@@ -1,7 +1,7 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "kiln-engine",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Create, review and revise editable 3D assets, with private saved revisions and GLB downloads.",
"author": {
"name": "Instrukt Labs",
@@ -47,7 +47,7 @@
},
"onboardingSkill": "./skills/kiln-hosted/SKILL.md",
"publication": {
- "release_notes": "Initial hosted integration for creating, reviewing, saving and revising private editable 3D assets with the Kiln 1.0 engine."
+ "release_notes": "Unreleased hosted integration draft for creating, reviewing, saving and revising private editable 3D assets. Live service qualification remains pending."
}
}
}
diff --git a/scripts/generate-tool-reference.ts b/scripts/generate-tool-reference.ts
index adcf4f21..58c5e438 100644
--- a/scripts/generate-tool-reference.ts
+++ b/scripts/generate-tool-reference.ts
@@ -2,8 +2,36 @@ import { readFile, writeFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { packagedMcpManifest } from '../src/mcp-manifest';
+import { toolManifestEntry } from '../src/mcp-manifest';
+import { createKilnOperationToolRegistry } from '../src/tools/registry';
+import { createLocalToolContext } from '../src/local-runtime';
+import { localAssetLibrary } from '../src/assets-node';
export const toolReferencePath = fileURLToPath(new URL('../docs/tools.md', import.meta.url));
+export const operationReferencePath = fileURLToPath(
+ new URL('../docs/tools-operations.md', import.meta.url),
+);
+
+/** Host-neutral named profile with asset/material storage and no local-only services. */
+export function operationReferenceMarkdown(): string {
+ const local = createLocalToolContext({ assetLibrary: localAssetLibrary() }, {});
+ const tools = createKilnOperationToolRegistry({
+ assetLibrary: local.assetLibrary,
+ materialLibrary: local.materialLibrary,
+ }).map(toolManifestEntry);
+ return `${[
+ '# Named operation reference',
+ 'Available in package version 1.2.0 and later. Generated with `bun run docs:tools` from the same engine registry as the default [local tools](tools.md). This profile supplies asset and material storage without project/review or renderer-control callbacks. Other host capabilities can change the tool list; connected tools/list is authoritative. See the [embedding contract](sdk.md#named-operation-presentation).',
+ 'Select this presentation explicitly with `createKilnMcpServer(context, { toolPresentation: "operations" })`. Existing local tool names and actions remain the default. Host authentication, request quotas, isolation and persistence policy are outside this engine reference.',
+ 'Use kiln_discover for helper contracts and complete shape: records; kiln_capabilities reports configuration, not proof of successful rendering. Material creation requires a typed definition. Search results preserve collection, asset/material and revision identity. Saving remains an explicit decision.',
+ ...tools.flatMap((tool) => [
+ `## ${tool.name}`,
+ tool.description,
+ '<details>\n<summary>Input JSON Schema</summary>\n',
+ `\`\`\`json\n${JSON.stringify(tool.inputSchema, null, 2)}\n\`\`\`\n\n</details>`,
+ ]),
+ ].join('\n\n')}\n`;
+}
/**
* The published tool reference: the definitions the packaged server advertises,
@@ -37,14 +65,18 @@ export function toolReferenceMarkdown(): string {
// Only when run as a command. Importing this module must not write a file or set
// an exit code -- the test below it imports the builder.
if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
- const content = toolReferenceMarkdown();
- if (process.argv.includes('--check')) {
- if ((await readFile(toolReferencePath, 'utf8').catch(() => '')) !== content) {
- console.error('Tool reference differs from the registry. Run bun run docs:tools.');
- process.exitCode = 1;
+ for (const [path, content] of [
+ [toolReferencePath, toolReferenceMarkdown()],
+ [operationReferencePath, operationReferenceMarkdown()],
+ ] as const) {
+ if (process.argv.includes('--check')) {
+ if ((await readFile(path, 'utf8').catch(() => '')) !== content) {
+ console.error('Tool reference differs from the registry. Run bun run docs:tools.');
+ process.exitCode = 1;
+ }
+ } else {
+ await writeFile(path, content);
+ console.log(`Wrote ${path}.`);
}
- } else {
- await writeFile(toolReferencePath, content);
- console.log(`Wrote ${packagedMcpManifest().tools.length} tool definitions to docs/tools.md.`);
}
}
diff --git a/scripts/smoke-package.mjs b/scripts/smoke-package.mjs
index f723a839..8716cb92 100644
--- a/scripts/smoke-package.mjs
+++ b/scripts/smoke-package.mjs
@@ -10,6 +10,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
import { smokePackageExporter } from './smoke-package-exporter.mjs';
import { smokeSdkTypes } from './smoke-sdk-types.mjs';
import { smokePackageAdoption } from './smoke-package-adoption.mjs';
+import { requiresNamedOperationCheck } from './verify-package-receipt.mjs';
const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
// macOS exposes /var through /private/var. Match Node's canonical module URLs
@@ -300,6 +301,21 @@ for (const subpath of ${JSON.stringify(coreExports)}) {
}
assert.equal(typeof sdk.validateKilnCode, 'function');
assert.equal(typeof sdk.createDiscovery, 'function');
+if (${requiresNamedOperationCheck(pkg.version)}) {
+const { createKilnOperationToolRegistry } = await import(name + '/tools');
+const { createKilnToolHost } = await import(name + '/mcp');
+const operationContext = {
+ assetLibrary: { collections: () => [], list: async () => [] },
+ materialLibrary: { list: async () => [] },
+};
+const operations = createKilnOperationToolRegistry(operationContext);
+assert.equal(operations.length, 21);
+const operationHost = createKilnToolHost(operationContext, { toolPresentation: 'operations' });
+assert.deepEqual(operationHost.defs.map(tool => tool.name), operations.map(tool => tool.name));
+assert.deepEqual(await operations.find(tool => tool.name === 'kiln_material_search').run({ scope: 'saved' }),
+ { ok: true, presets: [], materials: [] });
+await assert.rejects(() => operations.find(tool => tool.name === 'kiln_material_create').run({ definition: { kind: 'preset' } }));
+}
const arena = await import(name + '/arena');
assert.equal(arena.fitBradleyTerry([{winner:'a',loser:'b'}]).items[0].id, 'a');
assert.deepEqual(arena.pickNextPair(['a','b'], []), {a:'a',b:'b'});
@@ -316,6 +332,8 @@ console.log(JSON.stringify({ imports: ${coreExports.length}, renderBytes: result
}),
);
receipt.checks.push('plain-node-sdk-exports', 'sdk-subprocess-render');
+ if (requiresNamedOperationCheck(pkg.version))
+ receipt.checks.push('installed-named-operation-contract');
// Qualify the compiled worker's native imports and wire protocol. This runs
// trusted fixture code without an OS sandbox; provider isolation is a separate gate.
await writeFile(
diff --git a/scripts/tool-reference.test.mjs b/scripts/tool-reference.test.mjs
index f615e2f9..17baf4b3 100644
--- a/scripts/tool-reference.test.mjs
+++ b/scripts/tool-reference.test.mjs
@@ -13,6 +13,7 @@
import { expect, test } from 'bun:test';
import { readFile } from 'node:fs/promises';
import { toolReferenceMarkdown, toolReferencePath } from './generate-tool-reference.ts';
+import { operationReferenceMarkdown, operationReferencePath } from './generate-tool-reference.ts';
test('docs/tools.md matches the registry it is generated from', async () => {
const published = await readFile(toolReferencePath, 'utf8');
@@ -23,3 +24,8 @@ test('docs/tools.md matches the registry it is generated from', async () => {
'docs/tools.md is stale — run `bun run docs:tools`',
).toBe(true);
});
+
+test('named operation reference matches the registry without changing default tools', async () => {
+ expect(await readFile(operationReferencePath, 'utf8')).toBe(operationReferenceMarkdown());
+ expect(operationReferenceMarkdown().match(/^## kiln_/gm)).toHaveLength(21);
+});
diff --git a/scripts/verify-package-receipt.mjs b/scripts/verify-package-receipt.mjs
index 1162b3d4..7820ca67 100644
--- a/scripts/verify-package-receipt.mjs
+++ b/scripts/verify-package-receipt.mjs
@@ -39,6 +39,12 @@ const REQUIRED_CHECKS = [
const PLATFORMS = new Set(['darwin', 'linux', 'win32']);
+/** Registry checks can exercise an older published package than this checkout. */
+export function requiresNamedOperationCheck(version) {
+ const [major, minor] = version.split('.').map(Number);
+ return major > 1 || (major === 1 && minor >= 2);
+}
+
function option(argv, name) {
const at = argv.indexOf(`--${name}`);
return at === -1 ? undefined : argv[at + 1];
@@ -62,6 +68,10 @@ export function receiptProblems(receipt, { platform, arch, manifest, toolchain,
for (const check of REQUIRED_CHECKS) {
if (!receipt.checks?.includes(check)) problems.push(`missing check: ${check}`);
}
+ if (requiresNamedOperationCheck(manifest.version)) {
+ const check = 'installed-named-operation-contract';
+ if (!receipt.checks?.includes(check)) problems.push(`missing check: ${check}`);
+ }
if (manifest.files?.includes('scripts/workspace-project.mjs')) {
const check = 'installed-project-adoption-and-cross-client-storage';
if (!receipt.checks?.includes(check)) problems.push(`missing check: ${check}`);
diff --git a/scripts/verify-package-receipt.test.mjs b/scripts/verify-package-receipt.test.mjs
index 8aa1b1d0..9e7d7ff7 100644
--- a/scripts/verify-package-receipt.test.mjs
+++ b/scripts/verify-package-receipt.test.mjs
@@ -47,6 +47,31 @@ describe('package receipt verification', () => {
expect(receiptProblems(good(), target)).toEqual([]);
});
+ test.each(['1.2.0', '1.2.0-rc.1', '1.10.0', '2.0.0'])(
+ '%s requires the installed named operation check',
+ (version) => {
+ const candidate = { ...target, manifest: { ...manifest, version } };
+ const receipt = { ...good(), engineVersion: version };
+ expect(receiptProblems(receipt, candidate)).toEqual([
+ 'missing check: installed-named-operation-contract',
+ ]);
+ receipt.checks.push('installed-named-operation-contract');
+ expect(receiptProblems(receipt, candidate)).toEqual([]);
+ },
+ );
+
+ test('published 1.1 does not claim a future operation API', () => {
+ expect(
+ receiptProblems(
+ { ...good(), engineVersion: '1.1.0' },
+ {
+ ...target,
+ manifest: { ...manifest, version: '1.1.0' },
+ },
+ ),
+ ).toEqual([]);
+ });
+
test('consumer qualification requires the exact explicitly selected Node and npm', () => {
const consumer = { ...good(), node: 'v20.15.0', npm: '10.7.0' };
const selected = { ...target, node: '20.15.0', npm: '10.7.0' };
diff --git a/src/discovery/index.ts b/src/discovery/index.ts
index 15da39d7..20b51372 100644
--- a/src/discovery/index.ts
+++ b/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,
);
}
diff --git a/src/discovery/service.ts b/src/discovery/service.ts
index 3e2932ed..99a00c4f 100644
--- a/src/discovery/service.ts
+++ b/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 = (
diff --git a/src/engine-identity.ts b/src/engine-identity.ts
index da4dea85..66ac05ed 100644
--- a/src/engine-identity.ts
+++ b/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.1.0';
+export const ENGINE_VERSION = '1.2.0';
/**
* Where this engine was loaded from, as a `file://` URL of the package root.
diff --git a/src/mcp-core.ts b/src/mcp-core.ts
index 84d800bb..7f05d0ef 100644
--- a/src/mcp-core.ts
+++ b/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
diff --git a/src/mcp-engine.ts b/src/mcp-engine.ts
index 5cce701d..197b88de 100644
--- a/src/mcp-engine.ts
+++ b/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,
});
diff --git a/src/tools/__tests__/operation-contract.test.ts b/src/tools/__tests__/operation-contract.test.ts
new file mode 100644
index 00000000..56e4a945
--- /dev/null
+++ b/src/tools/__tests__/operation-contract.test.ts
@@ -0,0 +1,62 @@
+import { expect, test } from 'bun:test';
+import { z } from 'zod';
+import { projectActionSchemas } from '../operation-contract';
+
+const actions = {
+ list: { fields: ['query'], required: [], description: 'List records.' },
+ get: { fields: ['id'], required: ['id'], description: 'Read one record.' },
+} as const;
+const input = z.strictObject({
+ action: z.enum(['list', 'get']),
+ query: z.string().max(200).optional(),
+ id: z.string().min(1).optional(),
+});
+
+test('action schemas advertise and enforce the same conditional requirements', () => {
+ const schemas = projectActionSchemas('records', input, actions);
+ expect(schemas.get.safeParse({}).success).toBe(false);
+ expect(schemas.get.safeParse({ id: '' }).success).toBe(false);
+ expect(schemas.get.parse({ id: 'one' })).toEqual({ id: 'one' });
+ expect(schemas.get.safeParse({ id: 'one', action: 'list' }).success).toBe(false);
+ expect(z.toJSONSchema(schemas.get).required).toEqual(['id']);
+ expect(schemas.list.parse({})).toEqual({});
+});
+
+test('projection rejects new fields and actions until the shared contract classifies them', () => {
+ expect(() =>
+ projectActionSchemas('records', input.extend({ futureRequired: z.string() }), actions),
+ ).toThrow(/Unclassified.*futureRequired/);
+ expect(() =>
+ projectActionSchemas(
+ 'records',
+ input.extend({ futureOptional: z.string().optional() }),
+ actions,
+ ),
+ ).toThrow(/Unclassified.*futureOptional/);
+ expect(() =>
+ projectActionSchemas(
+ 'records',
+ input.extend({ action: z.enum(['list', 'get', 'delete']) }),
+ actions,
+ ),
+ ).toThrow(/actions/);
+ expect(() => projectActionSchemas('records', input.omit({ id: true }), actions)).toThrow(/id/);
+});
+
+test('projection never silently drops globally required inputs or constraints', () => {
+ expect(() => projectActionSchemas('records', input.extend({ id: z.string() }), actions)).toThrow(
+ /required.*id/,
+ );
+ const schemas = projectActionSchemas(
+ 'records',
+ input.extend({ query: z.string().max(2).optional() }),
+ actions,
+ );
+ expect(schemas.list.safeParse({ query: 'long' }).success).toBe(false);
+ expect(z.toJSONSchema(schemas.list).properties?.query).toMatchObject({ maxLength: 2 });
+});
+
+test('cross-field refinements require explicit operation design instead of being discarded', () => {
+ const refined = input.refine((value) => value.action !== 'get' || value.id !== 'forbidden');
+ expect(() => projectActionSchemas('records', refined, actions)).toThrow(/cross-field/);
+});
diff --git a/src/tools/__tests__/operation-mcp.test.ts b/src/tools/__tests__/operation-mcp.test.ts
new file mode 100644
index 00000000..f2c0ea8f
--- /dev/null
+++ b/src/tools/__tests__/operation-mcp.test.ts
@@ -0,0 +1,88 @@
+import { expect, test } from 'bun:test';
+import { createMcpHandler, type Tool } from '@modelcontextprotocol/server';
+import { createKilnMcpServer } from '../../mcp-engine';
+import type { MaterialLibrary } from '../../material-library';
+import type { AssetLibrary } from '../../assets';
+
+test('MCP SDK transports nested creation requirements and rejects invalid calls before storage', async () => {
+ let storageCalls = 0;
+ const materialLibrary = {
+ list: async () => {
+ storageCalls++;
+ return [];
+ },
+ } as unknown as MaterialLibrary;
+ const handler = createMcpHandler(
+ () =>
+ createKilnMcpServer(
+ { materialLibrary, assetLibrary: { collections: () => [] } as unknown as AssetLibrary },
+ { toolPresentation: 'operations' },
+ ),
+ { legacy: 'stateless', maxSubscriptions: 0 },
+ );
+ const rpc = async (method: string, params: Record<string, unknown> = {}) => {
+ const response = await handler.fetch(
+ new Request('http://localhost/mcp', {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ accept: 'application/json, text/event-stream',
+ 'mcp-protocol-version': '2025-11-25',
+ },
+ body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+ }),
+ );
+ const text = await response.text();
+ expect(response.status).toBe(200);
+ const message = response.headers.get('content-type')?.includes('text/event-stream')
+ ? text
+ .split('\n')
+ .filter((line) => line.startsWith('data:'))
+ .map((line) => JSON.parse(line.slice(5)))
+ .findLast((value) => value.id !== undefined)
+ : JSON.parse(text);
+ expect(message.error).toBeUndefined();
+ return message.result;
+ };
+ try {
+ const init = await rpc('initialize', {
+ protocolVersion: '2025-11-25',
+ capabilities: {},
+ clientInfo: { name: 'operation-contract-test', version: '1' },
+ });
+ expect(init.instructions).toContain('kiln_capabilities');
+ expect(init.instructions).not.toContain('capabilities:true');
+ const { tools } = (await rpc('tools/list')) as { tools: Tool[] };
+ expect(tools).toHaveLength(21);
+ const create = tools.find((tool) => tool.name === 'kiln_material_create')!;
+ expect(create.inputSchema.required).toEqual(['definition']);
+ const variants = (
+ create.inputSchema.properties!.definition as { oneOf: { required: string[] }[] }
+ ).oneOf;
+ expect(variants).toHaveLength(2);
+ expect(variants[0]!.required).toEqual(
+ expect.arrayContaining(['kind', 'presetId', 'seed', 'creator', 'license']),
+ );
+ expect(variants[1]!.required).toEqual(expect.arrayContaining(['kind', 'draft']));
+ for (const tool of tools) {
+ expect(tool.inputSchema.type).toBe('object');
+ expect(Buffer.byteLength(JSON.stringify(tool.inputSchema))).toBeLessThanOrEqual(5000);
+ }
+ expect(
+ (
+ await rpc('tools/call', {
+ name: create.name,
+ arguments: { definition: { kind: 'preset', presetId: 'wood' } },
+ })
+ ).isError,
+ ).toBe(true);
+ expect(storageCalls).toBe(0);
+ expect(
+ (await rpc('tools/call', { name: 'kiln_material_search', arguments: { scope: 'saved' } }))
+ .isError,
+ ).not.toBe(true);
+ expect(storageCalls).toBe(1);
+ } finally {
+ await handler.close();
+ }
+});
diff --git a/src/tools/__tests__/operation-registry.test.ts b/src/tools/__tests__/operation-registry.test.ts
new file mode 100644
index 00000000..666219d6
--- /dev/null
+++ b/src/tools/__tests__/operation-registry.test.ts
@@ -0,0 +1,166 @@
+import { expect, test } from 'bun:test';
+import { z } from 'zod';
+import { createKilnOperationToolRegistry } from '../registry';
+import { createKilnToolHost } from '../../mcp-engine';
+import type { AssetLibrary } from '../../assets';
+import type { MaterialLibrary } from '../../material-library';
+
+const assets = {
+ collections: () => [{ id: 'project', label: 'Project', writable: true }],
+ list: async () => [],
+} as unknown as AssetLibrary;
+const materials = { list: async () => [] } as unknown as MaterialLibrary;
+const context = { assetLibrary: assets, materialLibrary: materials };
+const defs = () => createKilnOperationToolRegistry(context);
+const find = (name: string) => defs().find((def) => def.name === name)!;
+
+test('named presentation preserves capabilities with 21 tools and no unsupported renderer controls', () => {
+ const names = defs().map((def) => def.name);
+ expect(names).toHaveLength(21);
+ expect(new Set(names).size).toBe(21);
+ for (const name of [
+ 'kiln_assets_search',
+ 'kiln_material_search',
+ 'kiln_material_create',
+ 'kiln_capabilities',
+ ])
+ expect(names).toContain(name);
+ for (const name of [
+ 'kiln_renderer',
+ 'kiln_renderer_status',
+ 'kiln_renderer_reprobe',
+ 'kiln_project',
+ 'kiln_review',
+ ])
+ expect(names).not.toContain(name);
+});
+
+test('named required inputs are enforced and visible in JSON schemas', async () => {
+ for (const [name, field] of [
+ ['kiln_assets_get', 'assetId'],
+ ['kiln_assets_restore', 'assetId'],
+ ['kiln_material_get', 'materialId'],
+ ['kiln_material_import', 'payload'],
+ ]) {
+ const def = find(name!);
+ expect(z.toJSONSchema(def.inputSchema, { io: 'input' }).required).toContain(field);
+ await expect(def.run({})).rejects.toThrow();
+ }
+});
+
+test('asset search normalizes collection identity without changing local list defaults', async () => {
+ expect(await find('kiln_assets_search').run({ collection: 'project' })).toEqual({
+ errors: [],
+ total: 0,
+ nextOffset: null,
+ assets: [],
+ });
+ await expect(find('kiln_assets_search').run({ collection: '' })).rejects.toThrow();
+ await expect(find('kiln_assets_search').run({ collection: 'missing' })).rejects.toThrow();
+ const legacy = createKilnToolHost(context).defs.find((def) => def.name === 'kiln_assets')!;
+ expect(await legacy.run({ action: 'list' })).toMatchObject({ collection: 'project' });
+});
+
+test('material browsing keeps recipe and saved identities distinct', async () => {
+ const result = (await find('kiln_material_search').run({ scope: 'presets' })) as {
+ presets: { kind: string }[];
+ materials: unknown[];
+ };
+ expect(result.presets.length).toBeGreaterThan(0);
+ expect(result.presets.every((entry) => entry.kind === 'preset')).toBe(true);
+ expect(result.materials).toEqual([]);
+ expect(await find('kiln_material_search').run({ scope: 'saved' })).toEqual({
+ ok: true,
+ presets: [],
+ materials: [],
+ });
+});
+
+test('material creation exposes nested variants and rejects incomplete or widened definitions', () => {
+ const schema = find('kiln_material_create').inputSchema;
+ const json = z.toJSONSchema(schema, { io: 'input' });
+ expect(json.type).toBe('object');
+ expect(json.required).toEqual(['definition']);
+ expect(JSON.stringify(json.properties?.definition)).toContain('presetId');
+ expect(schema.safeParse({ definition: { kind: 'preset', presetId: 'wood' } }).success).toBe(
+ false,
+ );
+ expect(schema.safeParse({ definition: { kind: 'procedural' } }).success).toBe(false);
+ expect(
+ schema.safeParse({ definition: { kind: 'procedural', draft: {}, action: 'import' } }).success,
+ ).toBe(false);
+});
+
+test('MCP presentation is explicitly selected; grouped tools remain the default', () => {
+ expect(createKilnToolHost(context).defs.map((def) => def.name)).toContain('kiln_material');
+ expect(
+ createKilnToolHost(context, { toolPresentation: 'operations' }).defs.map((def) => def.name),
+ ).toEqual(defs().map((def) => def.name));
+});
+
+test('named discovery and capabilities only recommend available calls', async () => {
+ const caps = await find('kiln_capabilities').run({});
+ expect(JSON.stringify(caps)).not.toMatch(/kiln_project|kiln_assets action=restore/);
+ expect(JSON.stringify(caps)).toContain('kiln_assets_restore');
+ const overview = await find('kiln_discover').run({});
+ expect(JSON.stringify(overview)).not.toContain('capabilities:true');
+ expect(JSON.stringify(overview)).toContain('kiln_capabilities');
+});
+
+test('named searches preserve collection identity and partial failures', async () => {
+ const library = {
+ ...assets,
+ collections: () => [
+ { id: 'project', label: 'Project' },
+ { id: 'other', label: 'Other' },
+ ],
+ list: async (collection: string) => {
+ if (collection === 'other') throw new Error('Unavailable collection');
+ return [
+ {
+ assetId: 'one',
+ revisionId: 'r1',
+ name: 'One',
+ tags: [],
+ editable: true,
+ createdAt: '2026-10-09',
+ },
+ ];
+ },
+ } as unknown as AssetLibrary;
+ const search = createKilnOperationToolRegistry({ ...context, assetLibrary: library }).find(
+ (def) => def.name === 'kiln_assets_search',
+ )!;
+ const all = (await search.run({})) as { assets: unknown[]; errors: unknown[]; total: number };
+ expect(all.total).toBe(1);
+ expect(all.assets[0]).toMatchObject({ collection: 'project', assetId: 'one', revisionId: 'r1' });
+ expect(all.errors).toHaveLength(1);
+ expect(await search.run({ collection: 'project' })).toMatchObject({
+ assets: all.assets,
+ errors: [],
+ });
+});
+
+test('missing saved resources give recovery calls from the selected presentation', async () => {
+ await expect(find('kiln_material_get').run({ materialId: 'missing' })).rejects.toThrow(
+ 'kiln_material_search',
+ );
+ await expect(find('kiln_assets_get').run({ assetId: 'missing' })).rejects.toThrow(
+ 'kiln_assets_search',
+ );
+});
+
+test('named embeddings only advertise persistence operations with the corresponding storage', () => {
+ const bare = createKilnOperationToolRegistry().map((def) => def.name);
+ for (const name of [
+ 'kiln_save',
+ 'kiln_present',
+ 'kiln_export',
+ 'kiln_import',
+ 'kiln_assets_search',
+ 'kiln_material_create',
+ ])
+ expect(bare).not.toContain(name);
+ expect(bare).toContain('kiln_render');
+ expect(bare).toContain('kiln_capabilities');
+});
diff --git a/src/tools/discovery.ts b/src/tools/discovery.ts
index 1f7d603b..1dfba112 100644
--- a/src/tools/discovery.ts
+++ b/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',
diff --git a/src/tools/materials.test.ts b/src/tools/materials.test.ts
index aa6532ba..2a2beef3 100644
--- a/src/tools/materials.test.ts
+++ b/src/tools/materials.test.ts
@@ -5,6 +5,7 @@ import { join } from 'node:path';
import { z } from 'zod';
import { FileMaterialLibrary, createMaterialLibraryPayload } from '../material-library-node';
import { createKilnMaterialDef, materialToolInput } from './materials';
+import { createKilnOperationToolRegistry } from './registry';
const roots: string[] = [];
afterEach(async () => {
@@ -48,6 +49,27 @@ async function library() {
roots.push(root);
return new FileMaterialLibrary(root);
}
+
+test('named material creation and grouped creation retain identical revisions and portable specs', async () => {
+ const store = await library();
+ const named = createKilnOperationToolRegistry({ materialLibrary: store }).find(
+ (def) => def.name === 'kiln_material_create',
+ )!;
+ const legacy = createKilnMaterialDef(store);
+ const created = await named.run({ definition: { kind: 'procedural', draft } });
+ expect(await legacy.run({ action: 'create-procedural', draft })).toEqual(created);
+ const options = {
+ presetId: 'wood-oak',
+ seed: 12,
+ size: 64,
+ creator: 'Test author',
+ license: draft.sources[0]!.license,
+ };
+ const presets = (await legacy.run({ action: 'presets' })) as { presets: { id: string }[] };
+ options.presetId = presets.presets[0]!.id;
+ const fromPreset = await named.run({ definition: { kind: 'preset', ...options } });
+ expect(await legacy.run({ action: 'create-preset', ...options })).toEqual(fromPreset);
+});
test('material tool creates repeatable recipes, lists summaries and reads code-ready portable specs', async () => {
const store = await library();
const tool = createKilnMaterialDef(store);
diff --git a/src/tools/materials.ts b/src/tools/materials.ts
index 96a4ef55..7adbc8e9 100644
--- a/src/tools/materials.ts
+++ b/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;
}
}
diff --git a/src/tools/operation-contract.ts b/src/tools/operation-contract.ts
new file mode 100644
index 00000000..719c2ad6
--- /dev/null
+++ b/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>;
+}
diff --git a/src/tools/operations.ts b/src/tools/operations.ts
new file mode 100644
index 00000000..597aebce
--- /dev/null
+++ b/src/tools/operations.ts
@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import type { KilnToolContext, KilnToolDef } from './registry';
+import { projectActionSchemas } from './operation-contract';
+
+/** Adapt domain operations in the engine, never in a transport-specific skin. */
+export function projectOperationDefs(
+ defs: readonly KilnToolDef[],
+ context: KilnToolContext,
+): KilnToolDef[] {
+ 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: KilnToolDef) {
+ 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: unknown) => def.run({ ...schemas[action]!.parse(raw), action }),
+ } satisfies KilnToolDef,
+ ]),
+ );
+}
+
+function assetOperations(def: KilnToolDef, context: KilnToolContext): KilnToolDef[] {
+ const tools = actionTools(def);
+ const list = tools.list!;
+ const listSchema = list.inputSchema as z.ZodObject;
+ // Remove only the legacy default: omission means all collections in this operation.
+ const collection = (listSchema.shape.collection as z.ZodDefault<z.ZodString>)
+ .unwrap()
+ .optional()
+ .describe(
+ 'Collection ID from kiln_assets_collections; omitted searches all configured collections.',
+ );
+ const inputSchema = listSchema.extend({ collection });
+ const search: KilnToolDef = {
+ ...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)) as {
+ total: number;
+ nextOffset: number | null;
+ assets: Record<string, unknown>[];
+ };
+ 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: KilnToolDef): KilnToolDef[] {
+ const tools = actionTools(def);
+ const presets = tools.presets!;
+ const inputSchema = (presets.inputSchema as z.ZodObject).extend({
+ scope: z.enum(['all', 'presets', 'saved']).default('all'),
+ });
+ const search: KilnToolDef = {
+ ...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)) as { presets: Record<string, unknown>[] });
+ const saved =
+ scope === 'presets'
+ ? { materials: [] }
+ : ((await tools.list!.run(input)) as { materials: Record<string, unknown>[] });
+ 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 as z.ZodObject).extend({ kind: z.literal('preset') }),
+ (procedural.inputSchema as z.ZodObject).extend({ kind: z.literal('procedural') }),
+ ]),
+ });
+ const create: KilnToolDef = {
+ ...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: KilnToolDef, context: KilnToolContext): KilnToolDef[] {
+ 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: unknown) => {
+ inputSchema.parse(raw);
+ return def.run({ action });
+ },
+ };
+ });
+}
+
+function discoveryOperations(def: KilnToolDef): KilnToolDef[] {
+ const original = def.inputSchema as z.ZodObject;
+ 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 });
+ },
+ },
+ ];
+}
diff --git a/src/tools/registry.ts b/src/tools/registry.ts
index ef1d086d..0e133343 100644
--- a/src/tools/registry.ts
+++ b/src/tools/registry.ts
@@ -24,6 +24,8 @@ import { createKilnMaterialDef } from './materials';
import { createKilnReviewDef, type ReviewStore } from './review';
import { withWorkspaceContext } from './workspace';
import { describeInputError } from './actions';
+import { projectOperationDefs } from './operations';
+import type { KilnActionContract } from './operation-contract';
import {
advancedCaptureInput,
cameraShotInput,
@@ -94,6 +96,8 @@ import type { TextureUsage } from '../textures';
export 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').KilnActionContract>>;
outputSchema?: z.ZodType;
/** Optional MCP App presentation; metadata is hidden from the language model. */
ui?: {
@@ -2498,13 +2502,14 @@ async function readSavedRevision(
collection: string,
assetId: string,
revisionId: string,
+ listCall = `kiln_assets { action: 'list', collection: '${collection}' }`,
) {
try {
return await target.read(collection, assetId, revisionId);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT')
throw new Error(
- `Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. kiln_assets { action: 'list', collection: '${collection}' } lists the saved revisions.`,
+ `Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. ${listCall} lists the saved revisions.`,
);
throw error;
}
@@ -2512,12 +2517,19 @@ async function readSavedRevision(
export function createKilnProgramToolRegistry(
suppliedContext: KilnToolContext = {},
+): KilnToolDef[] {
+ return createProgramDefs(suppliedContext, 'grouped');
+}
+
+function createProgramDefs(
+ suppliedContext: KilnToolContext,
+ presentation: 'grouped' | 'operations',
): KilnToolDef[] {
toolRequirements(suppliedContext);
const store = suppliedContext.programStore ?? new MemoryProgramStore();
const context = withCaptureCache(withBuildCache({ ...suppliedContext, programStore: store }));
return [
- createKilnDiscoveryDef({ ...suppliedContext, programStore: store }),
+ createKilnDiscoveryDef({ ...suppliedContext, programStore: store }, presentation),
{
name: 'kiln_renderer',
description:
@@ -2564,7 +2576,9 @@ export function createKilnProgramToolRegistry(
...(context.projectStore
? [createKilnProjectDef(context.projectStore, context.projectBundleReader)]
: []),
- ...(context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary)] : []),
+ ...(context.materialLibrary
+ ? [createKilnMaterialDef(context.materialLibrary, presentation)]
+ : []),
...(context.reviewStore && context.assetLibrary
? [
createKilnReviewDef({
@@ -2574,7 +2588,7 @@ export function createKilnProgramToolRegistry(
}),
]
: []),
- ...createKilnAssetDefs({ ...context, programStore: store }),
+ ...createKilnAssetDefs({ ...context, programStore: store }, presentation),
]
.map((def) => withWorkspaceContext(def, context))
.map((def) => ({
@@ -2591,6 +2605,11 @@ export function createKilnProgramToolRegistry(
}));
}
+/** Opt-in named domain operations; grouped local/native contracts remain unchanged. */
+export function createKilnOperationToolRegistry(context: KilnToolContext = {}): KilnToolDef[] {
+ return projectOperationDefs(createProgramDefs(context, 'operations'), context);
+}
+
/** Canonical native workflow: shared definitions plus one host-owned terminal. */
export function createKilnNativeToolRegistry(
suppliedContext: KilnToolContext,
@@ -2686,6 +2705,36 @@ const assetSelector = {
revisionId: z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
};
+const ASSET_CONTRACT = {
+ collections: {
+ fields: [],
+ required: [],
+ description: 'List configured asset storage collections. Collection is not project membership.',
+ },
+ catalog: {
+ fields: ['assetId', 'query', 'offset', 'limit'],
+ required: [],
+ description: 'Search saved assets across configured collections with pagination.',
+ },
+ list: {
+ fields: ['collection', 'assetId', 'query', 'offset', 'limit'],
+ required: [],
+ description: 'Search saved assets in one collection with pagination.',
+ },
+ get: {
+ fields: ['collection', 'assetId', 'revisionId'],
+ required: ['assetId'],
+ description:
+ 'Read a saved revision and its download descriptors. Omit revisionId for the newest revision.',
+ },
+ restore: {
+ fields: ['collection', 'assetId', 'revisionId'],
+ required: ['assetId'],
+ description:
+ 'Restore exact saved source as programRef for editing or rendering. Omit revisionId for the newest revision. Does not overwrite the saved revision. Binary-only assets have no source.',
+ },
+} satisfies Record<string, KilnActionContract>;
+
/**
* The revision a get or restore without `revisionId` means: the newest, the
* one no later revision names as its parent, ties to the latest `createdAt`
@@ -2701,12 +2750,11 @@ export async function newestRevision(
},
collection: string,
assetId: string,
+ listCall = `kiln_assets { action: 'list', collection: '${collection}' }`,
): Promise<string> {
const revisions = (await target.list(collection)).filter((a) => a.assetId === assetId);
if (!revisions.length)
- throw new Error(
- `Unknown asset ${assetId} in ${collection}; kiln_assets { action: 'list', collection: '${collection}' } lists them.`,
- );
+ throw new Error(`Unknown asset ${assetId} in ${collection}; ${listCall} lists them.`);
const parents = new Set(revisions.map((a) => a.parentRevision).filter(Boolean));
const heads = revisions.filter((a) => !parents.has(a.revisionId));
const newest = (heads.length ? heads : revisions).sort((a, b) =>
@@ -2797,7 +2845,23 @@ export async function buildProgramAssetDraft(
}
/** All asset operation schemas live here, alongside the existing tool definitions. */
-export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
+export function createKilnAssetDefs(
+ context: KilnToolContext,
+ presentation: 'grouped' | 'operations' = 'grouped',
+): KilnToolDef[] {
+ const listCall = (collection: string) =>
+ presentation === 'operations'
+ ? `kiln_assets_search({ collection: '${collection}' })`
+ : `kiln_assets { action: 'list', collection: '${collection}' }`;
+ const selector =
+ presentation === 'operations'
+ ? {
+ ...assetSelector,
+ collection: assetSelector.collection.describe(
+ 'Collection ID from kiln_assets_collections; default project.',
+ ),
+ }
+ : assetSelector;
const library = () => {
if (!context.assetLibrary)
throw new Error(
@@ -2828,11 +2892,11 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
downloadUrls: await context.assetDownloadUrls?.(collection, asset.assetId, asset.revisionId),
});
const saveInput = z.object({
- collection: assetSelector.collection,
+ collection: selector.collection,
programRef: z.string(),
name: z.string().min(1).max(200),
- assetId: assetSelector.assetId.optional(),
- parentRevision: assetSelector.revisionId.optional(),
+ assetId: selector.assetId.optional(),
+ parentRevision: selector.revisionId.optional(),
tags: z.array(z.string().max(80)).max(30).optional(),
brief: z.string().max(8000).optional(),
description: z.string().max(4000).optional(),
@@ -2850,16 +2914,16 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
});
const assetsInput = z.object({
action: z.enum(['collections', 'catalog', 'list', 'get', 'restore']).default('list'),
- collection: assetSelector.collection,
- assetId: assetSelector.assetId.optional(),
- revisionId: assetSelector.revisionId
+ collection: selector.collection,
+ assetId: selector.assetId.optional(),
+ revisionId: selector.revisionId
.optional()
.describe('get, restore: the saved revision; omitted, the newest.'),
query: z.string().max(200).optional(),
offset: z.number().int().min(0).default(0),
limit: z.number().int().min(1).max(50).default(20),
});
- const exportInput = z.object(assetSelector);
+ const exportInput = z.object(selector);
const profileExportInput = exportInput.extend({
profile: z
.enum(['editable', 'runtime'])
@@ -2869,8 +2933,8 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
),
});
const importInput = z.object({
- ...assetSelector,
- sourceCollection: assetSelector.collection,
+ ...selector,
+ sourceCollection: selector.collection,
});
return [
{
@@ -2892,6 +2956,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
input.collection,
input.assetId,
input.parentRevision,
+ listCall(input.collection),
);
assertSavedRequirementsAuthorized(previous.manifest, activeRequirements);
}
@@ -2908,6 +2973,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
description:
'Browse saved assets: collections discovers storage; catalog searches all configured collections; list searches one. Both searches paginate. get returns a build record/downloads; restore loads exact source for kiln_source/kiln_edit. Collection is not project membership. Binary-only assets cannot restore source.',
inputSchema: assetsInput,
+ actionContract: ASSET_CONTRACT,
run: async (raw) => {
const input = assetsInput.parse(raw);
const activeRequirements = toolRequirements(context);
@@ -2961,13 +3027,25 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
})),
};
}
- if (!input.assetId)
+ if (ASSET_CONTRACT[input.action].required.some((field) => !input[field as 'assetId']))
throw new Error(
`kiln_assets ${input.action} requires assetId; kiln_assets { action: 'list', collection: '${input.collection}' } lists them.`,
);
const revisionId =
- input.revisionId ?? (await newestRevision(target, input.collection, input.assetId));
- const record = await readSavedRevision(target, input.collection, input.assetId, revisionId);
+ input.revisionId ??
+ (await newestRevision(
+ target,
+ input.collection,
+ input.assetId!,
+ listCall(input.collection),
+ ));
+ const record = await readSavedRevision(
+ target,
+ input.collection,
+ input.assetId!,
+ revisionId,
+ listCall(input.collection),
+ );
if (input.action === 'get') return links(input.collection, record.manifest);
const saved = assertSavedRequirementsAuthorized(record.manifest, activeRequirements);
const code = record.files['source.kiln.js'];
@@ -3059,6 +3137,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
input.collection,
input.assetId,
input.revisionId,
+ listCall(input.collection),
);
const { inspectDrawDiagnostics } = await import('../draw-diagnostics');
if (input.profile === 'runtime') {
@@ -3102,6 +3181,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
input.sourceCollection,
input.assetId,
input.revisionId,
+ listCall(input.sourceCollection),
);
await target.import(input.collection, [record]);
return links(input.collection, record.manifest);