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.

feat(tools): advertise read-only renderer status (#206) (#222)

Matthew Kissingerd82fc72ba52a
diff --git a/.agents/skills/kiln-setup-workspace/references/renderer-setup.md b/.agents/skills/kiln-setup-workspace/references/renderer-setup.md
index 8cdd06cd..9dcbc2b5 100644
--- a/.agents/skills/kiln-setup-workspace/references/renderer-setup.md
+++ b/.agents/skills/kiln-setup-workspace/references/renderer-setup.md
@@ -6,6 +6,6 @@ The renderer code is included with Kiln; its native GPU dependency is optional a
Once dependencies are available, local CLI/MCP auto mode starts a managed service lazily for a view that needs PBR shading. Compatible clients share it; it survives the initiating session and exits after five minutes without admitted uploads, queued jobs or active renders. From the installation root, `node --import ./render-service/src/register-hooks.mjs render-service/src/server.mjs` starts a manual service that remains running while idle. It binds loopback; widening `HOST` requires `RENDER_SERVICE_TOKEN`.
-`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. After dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
+`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. Inside an MCP session, `kiln_renderer_status` is read-only, so call it freely: `activeRoute` (`gpu` or `cpu`), `ready` and `fallback` say what the next render uses, and an active `fallback` means CPU geometry views, not material evidence. Reprobe only after a repair: after dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
A `KILN_RENDER_PORT_URL` whose origin is exactly the shared local socket (`http://127.0.0.1:8000` by default) takes the local route: it starts on demand and restarts after an idle exit. For rendering on another device, configure the MCP server process's `KILN_RENDER_PORT_URL` and, when needed, `KILN_RENDER_TOKEN` through the chosen harness. CLI accepts `--render-port URL` and reads `KILN_RENDER_TOKEN`. Start a compatible Kiln renderer on that device; its wider bind requires `RENDER_SERVICE_TOKEN` unless an authenticated proxy is explicitly configured. Manage the remote service on its own device. Verify the selected route with capabilities and require an actual `viewFidelity` receipt for material evidence.
diff --git a/.claude/skills/kiln-setup-workspace/references/renderer-setup.md b/.claude/skills/kiln-setup-workspace/references/renderer-setup.md
index 8cdd06cd..9dcbc2b5 100644
--- a/.claude/skills/kiln-setup-workspace/references/renderer-setup.md
+++ b/.claude/skills/kiln-setup-workspace/references/renderer-setup.md
@@ -6,6 +6,6 @@ The renderer code is included with Kiln; its native GPU dependency is optional a
Once dependencies are available, local CLI/MCP auto mode starts a managed service lazily for a view that needs PBR shading. Compatible clients share it; it survives the initiating session and exits after five minutes without admitted uploads, queued jobs or active renders. From the installation root, `node --import ./render-service/src/register-hooks.mjs render-service/src/server.mjs` starts a manual service that remains running while idle. It binds loopback; widening `HOST` requires `RENDER_SERVICE_TOKEN`.
-`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. After dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
+`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. Inside an MCP session, `kiln_renderer_status` is read-only, so call it freely: `activeRoute` (`gpu` or `cpu`), `ready` and `fallback` say what the next render uses, and an active `fallback` means CPU geometry views, not material evidence. Reprobe only after a repair: after dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
A `KILN_RENDER_PORT_URL` whose origin is exactly the shared local socket (`http://127.0.0.1:8000` by default) takes the local route: it starts on demand and restarts after an idle exit. For rendering on another device, configure the MCP server process's `KILN_RENDER_PORT_URL` and, when needed, `KILN_RENDER_TOKEN` through the chosen harness. CLI accepts `--render-port URL` and reads `KILN_RENDER_TOKEN`. Start a compatible Kiln renderer on that device; its wider bind requires `RENDER_SERVICE_TOKEN` unless an authenticated proxy is explicitly configured. Manage the remote service on its own device. Verify the selected route with capabilities and require an actual `viewFidelity` receipt for material evidence.
diff --git a/AGENTS.md b/AGENTS.md
index 20ba35f7..d652ce8c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -68,11 +68,11 @@ The stdio executable is a thin entry: `src/mcp-server.ts` bundles the protocol l
`src/mcp-core.ts`. Never import the engine statically from the entry or the core; an
engine-loading problem is a tool result naming the next step, never a dead server.
-`createKilnProgramToolRegistry` supplies the fourteen base MCP tools. The packaged local host
-also injects `kiln_project`, `kiln_material` and `kiln_review` (seventeen); embeddings
+`createKilnProgramToolRegistry` supplies the fifteen base MCP tools. The packaged local host
+also injects `kiln_project`, `kiln_material` and `kiln_review` (eighteen); embeddings
advertise these only when the host services exist, never as tools that always fail.
-`createKilnNativeToolRegistry` uses the same definitions and adds `kiln_finish`: ten tools
-by default, fifteen with an injected `assetLibrary` (the five delivery tools). A configured
+`createKilnNativeToolRegistry` uses the same definitions and adds `kiln_finish`: eleven tools
+by default, sixteen with an injected `assetLibrary` (the five delivery tools). A configured
skill-resource reader adds `kiln_skill_resource` to either native set.
Both skins use unified `kiln_render`: metrics, part paths, QA, images and fidelity share one
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d0359fd..e6d16628 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,15 @@ does not publish a package.
bare "Invalid input", and run only after the field checks pass. Tool input errors drop
a bare parent "Invalid input" line when an issue inside that record already explains
the failure.
+- Advertise renderer status separately from reprobe ([#206](https://github.com/instruktlabs/kiln/issues/206)).
+ The new read-only `kiln_renderer_status` (`readOnlyHint: true`) lets hosts that
+ auto-allow reads check status without a prompt; `kiln_renderer` stays stateful and
+ still accepts `action: "status"`. The packaged MCP server lists eighteen tools and the
+ native registry eleven (sixteen with delivery). In the named-operation presentation
+ `kiln_renderer_status` is now read-only and `kiln_renderer_reprobe` stays stateful.
+ Status and reprobe results add `ready`, `activeRoute` (`gpu` or `cpu`) and `fallback`
+ (`active`, with `materialFaithful: false` and a `reason` when views will be CPU
+ geometry). `kiln_discover({ capabilities: true })` is unchanged.
## 1.3.1 (2026-10-17)
diff --git a/dist/agent-run.mjs b/dist/agent-run.mjs
index db7e1d0c..ae910c2d 100644
--- a/dist/agent-run.mjs
+++ b/dist/agent-run.mjs
@@ -45413,6 +45413,33 @@ init_requirements_context();
init_evaluator();
init_material_resources();
+// src/render-route.ts
+var GPU_SERVES = new Set([
+ "available",
+ "on-demand",
+ "authentication-unverified"
+]);
+function nextRenderRoute(renderer) {
+ const fallback = (reason) => ({
+ active: true,
+ materialFaithful: false,
+ reason
+ });
+ if (!renderer.configured)
+ return {
+ ready: true,
+ activeRoute: "cpu",
+ fallback: fallback(renderer.reason ?? (renderer.mode === "cpu" ? "This host selected CPU rendering; views show geometry, not materials." : "No GPU renderer is attached to this session; views show geometry, not materials."))
+ };
+ if (GPU_SERVES.has(renderer.status))
+ return { ready: true, activeRoute: "gpu", fallback: { active: false } };
+ return {
+ ready: false,
+ activeRoute: "gpu",
+ fallback: renderer.required ? { active: false } : fallback(`GPU renderer ${renderer.status}${renderer.reason ? `: ${renderer.reason}` : ""}. Renders degrade to CPU geometry views.`)
+ };
+}
+
// src/edit-buffer.ts
class KilnDraftBuffer {
buf;
@@ -46817,6 +46844,28 @@ function withCaptureCache(context) {
var rendererInput = z23.strictObject({
action: z23.enum(["status", "reprobe"]).default("status")
});
+var rendererStatusInput = z23.strictObject({});
+async function runRenderer(context, action) {
+ if (action === "reprobe" && !context.reprobeRenderer)
+ return {
+ ok: false,
+ error: "Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true })."
+ };
+ if (!context.renderCapabilities)
+ return {
+ ok: false,
+ error: "Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true })."
+ };
+ try {
+ const renderer = await (action === "reprobe" ? context.reprobeRenderer() : context.renderCapabilities());
+ return { ok: true, renderer: { ...renderer, ...nextRenderRoute(renderer) } };
+ } catch (error) {
+ return {
+ ok: false,
+ error: error instanceof Error ? error.message : String(error)
+ };
+ }
+}
async function readSavedRevision(target, collection, assetId, revisionId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
try {
return await target.read(collection, assetId, revisionId);
@@ -46836,34 +46885,20 @@ function createProgramDefs(suppliedContext, presentation) {
return [
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.",
- inputSchema: rendererInput,
+ name: "kiln_renderer_status",
+ description: "Read renderer status: ready, activeRoute (gpu or cpu) and fallback say what the next render uses; an active fallback means CPU geometry views, not material evidence. Read-only: never reprobes, installs, starts or renders. Read viewFidelity after rendering.",
+ inputSchema: rendererStatusInput,
run: async (raw) => {
- const { action } = rendererInput.parse(raw);
- if (action === "reprobe" && !suppliedContext.reprobeRenderer)
- return {
- ok: false,
- error: "Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true })."
- };
- if (!suppliedContext.renderCapabilities)
- return {
- ok: false,
- error: "Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true })."
- };
- try {
- return {
- ok: true,
- renderer: await (action === "reprobe" ? suppliedContext.reprobeRenderer() : suppliedContext.renderCapabilities())
- };
- } catch (error) {
- return {
- ok: false,
- error: error instanceof Error ? error.message : String(error)
- };
- }
+ rendererStatusInput.parse(raw);
+ return runRenderer(suppliedContext, "status");
}
},
+ {
+ name: "kiln_renderer",
+ description: "Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.",
+ inputSchema: rendererInput,
+ run: async (raw) => runRenderer(suppliedContext, rendererInput.parse(raw).action)
+ },
...[
createKilnValidateDef(context),
createKilnRenderViewsDef(context),
@@ -46886,7 +46921,13 @@ function createProgramDefs(suppliedContext, presentation) {
].map((def) => withWorkspaceContext(def, context)).map((def) => ({
...def,
annotations: {
- readOnlyHint: ["kiln_source", "kiln_discover", "kiln_export", "kiln_present"].includes(def.name),
+ readOnlyHint: [
+ "kiln_source",
+ "kiln_discover",
+ "kiln_renderer_status",
+ "kiln_export",
+ "kiln_present"
+ ].includes(def.name),
destructiveHint: false,
idempotentHint: def.name !== "kiln_save",
openWorldHint: false,
diff --git a/dist/build.json b/dist/build.json
index 48bb9122..bca0efd2 100644
--- a/dist/build.json
+++ b/dist/build.json
@@ -2,10 +2,10 @@
"schemaVersion": 1,
"entries": {
"worker": {
- "identity": "sha256:c55e4770c4f6b08d2ef248aad2a565d8cf5a84fbab28844185f3b6a2517b58d6",
+ "identity": "sha256:ca2c37a68cba501909fa67cae3f6ee88127a35df8d3508102cf333fd5afc0bdf",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "839c118eca6d3c8267927a71715c5af5ffda22e14815e9c777985c23d9f50f1b",
+ "sourceHash": "dee8f1780b1e49feca7939dae14d72902d9781faad9784b5b4f3b2f2fdd3e76b",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -40,10 +40,10 @@
"bundleHash": "sha256:fde0385cddab538fe68c221db77dbc6b8944679a2e86a42ba213e6524ed33cce"
},
"agent-run": {
- "identity": "sha256:c55e4770c4f6b08d2ef248aad2a565d8cf5a84fbab28844185f3b6a2517b58d6",
+ "identity": "sha256:ca2c37a68cba501909fa67cae3f6ee88127a35df8d3508102cf333fd5afc0bdf",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "839c118eca6d3c8267927a71715c5af5ffda22e14815e9c777985c23d9f50f1b",
+ "sourceHash": "dee8f1780b1e49feca7939dae14d72902d9781faad9784b5b4f3b2f2fdd3e76b",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -75,13 +75,13 @@
},
"target": "node",
"file": "agent-run.mjs",
- "bundleHash": "sha256:0c22ff4c9e973855110098f05b87a151389a8ae93332af8e6e96b3c14689ed46"
+ "bundleHash": "sha256:f62ce5ffe1bb811eec81f982cdfa832e35f70d0a14cb6e7b9ba6ce7a2275c607"
},
"agent-providers": {
- "identity": "sha256:c55e4770c4f6b08d2ef248aad2a565d8cf5a84fbab28844185f3b6a2517b58d6",
+ "identity": "sha256:ca2c37a68cba501909fa67cae3f6ee88127a35df8d3508102cf333fd5afc0bdf",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "839c118eca6d3c8267927a71715c5af5ffda22e14815e9c777985c23d9f50f1b",
+ "sourceHash": "dee8f1780b1e49feca7939dae14d72902d9781faad9784b5b4f3b2f2fdd3e76b",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -116,10 +116,10 @@
"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"
},
"mcp": {
- "identity": "sha256:c55e4770c4f6b08d2ef248aad2a565d8cf5a84fbab28844185f3b6a2517b58d6",
+ "identity": "sha256:ca2c37a68cba501909fa67cae3f6ee88127a35df8d3508102cf333fd5afc0bdf",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "839c118eca6d3c8267927a71715c5af5ffda22e14815e9c777985c23d9f50f1b",
+ "sourceHash": "dee8f1780b1e49feca7939dae14d72902d9781faad9784b5b4f3b2f2fdd3e76b",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -151,13 +151,13 @@
},
"target": "node",
"file": "mcp-server.mjs",
- "bundleHash": "sha256:814d8ca81116501226d58e6f67c6ab2fe408c5ad08ae4995d6136b22ad024285"
+ "bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"
},
"cli": {
- "identity": "sha256:c55e4770c4f6b08d2ef248aad2a565d8cf5a84fbab28844185f3b6a2517b58d6",
+ "identity": "sha256:ca2c37a68cba501909fa67cae3f6ee88127a35df8d3508102cf333fd5afc0bdf",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "839c118eca6d3c8267927a71715c5af5ffda22e14815e9c777985c23d9f50f1b",
+ "sourceHash": "dee8f1780b1e49feca7939dae14d72902d9781faad9784b5b4f3b2f2fdd3e76b",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -189,13 +189,13 @@
},
"target": "node",
"file": "cli.mjs",
- "bundleHash": "sha256:10e7e9128a08023cfc8a4fcc89181e2d5a6bf482ca7d9a51184b80e727e2ae41"
+ "bundleHash": "sha256:fb0adc73d25acba5923a3d1234c637dca133cd326c42a47b60b2751e58e462a1"
},
"engine": {
- "identity": "sha256:c55e4770c4f6b08d2ef248aad2a565d8cf5a84fbab28844185f3b6a2517b58d6",
+ "identity": "sha256:ca2c37a68cba501909fa67cae3f6ee88127a35df8d3508102cf333fd5afc0bdf",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "839c118eca6d3c8267927a71715c5af5ffda22e14815e9c777985c23d9f50f1b",
+ "sourceHash": "dee8f1780b1e49feca7939dae14d72902d9781faad9784b5b4f3b2f2fdd3e76b",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -227,7 +227,7 @@
},
"target": "node",
"file": "mcp-engine.mjs",
- "bundleHash": "sha256:f4b71dcdfc203877f72031a1afbc78a5b5ee4f6fdcb51ea09066aaab03eac222"
+ "bundleHash": "sha256:cadfac179357407c9bd8d719c49125f56129050fa7eb7f9aeac50673fe743014"
}
}
}
diff --git a/dist/cli.mjs b/dist/cli.mjs
index e1f3b22a..f7dcd59a 100644
--- a/dist/cli.mjs
+++ b/dist/cli.mjs
@@ -48549,6 +48549,36 @@ var init_operations = __esm(() => {
init_operation_contract();
});
+// src/render-route.ts
+function nextRenderRoute(renderer) {
+ const fallback = (reason) => ({
+ active: true,
+ materialFaithful: false,
+ reason
+ });
+ if (!renderer.configured)
+ return {
+ ready: true,
+ activeRoute: "cpu",
+ fallback: fallback(renderer.reason ?? (renderer.mode === "cpu" ? "This host selected CPU rendering; views show geometry, not materials." : "No GPU renderer is attached to this session; views show geometry, not materials."))
+ };
+ if (GPU_SERVES.has(renderer.status))
+ return { ready: true, activeRoute: "gpu", fallback: { active: false } };
+ return {
+ ready: false,
+ activeRoute: "gpu",
+ fallback: renderer.required ? { active: false } : fallback(`GPU renderer ${renderer.status}${renderer.reason ? `: ${renderer.reason}` : ""}. Renders degrade to CPU geometry views.`)
+ };
+}
+var GPU_SERVES;
+var init_render_route = __esm(() => {
+ GPU_SERVES = new Set([
+ "available",
+ "on-demand",
+ "authentication-unverified"
+ ]);
+});
+
// src/edit-buffer.ts
class KilnDraftBuffer {
buf;
@@ -51231,6 +51261,27 @@ function withCaptureCache(context) {
} : {}
};
}
+async function runRenderer(context, action) {
+ if (action === "reprobe" && !context.reprobeRenderer)
+ return {
+ ok: false,
+ error: "Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true })."
+ };
+ if (!context.renderCapabilities)
+ return {
+ ok: false,
+ error: "Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true })."
+ };
+ try {
+ const renderer = await (action === "reprobe" ? context.reprobeRenderer() : context.renderCapabilities());
+ return { ok: true, renderer: { ...renderer, ...nextRenderRoute(renderer) } };
+ } catch (error) {
+ return {
+ ok: false,
+ error: error instanceof Error ? error.message : String(error)
+ };
+ }
+}
async function readSavedRevision(target, collection, assetId, revisionId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
try {
return await target.read(collection, assetId, revisionId);
@@ -51250,34 +51301,20 @@ function createProgramDefs(suppliedContext, presentation) {
return [
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.",
- inputSchema: rendererInput,
+ name: "kiln_renderer_status",
+ description: "Read renderer status: ready, activeRoute (gpu or cpu) and fallback say what the next render uses; an active fallback means CPU geometry views, not material evidence. Read-only: never reprobes, installs, starts or renders. Read viewFidelity after rendering.",
+ inputSchema: rendererStatusInput,
run: async (raw) => {
- const { action } = rendererInput.parse(raw);
- if (action === "reprobe" && !suppliedContext.reprobeRenderer)
- return {
- ok: false,
- error: "Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true })."
- };
- if (!suppliedContext.renderCapabilities)
- return {
- ok: false,
- error: "Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true })."
- };
- try {
- return {
- ok: true,
- renderer: await (action === "reprobe" ? suppliedContext.reprobeRenderer() : suppliedContext.renderCapabilities())
- };
- } catch (error) {
- return {
- ok: false,
- error: error instanceof Error ? error.message : String(error)
- };
- }
+ rendererStatusInput.parse(raw);
+ return runRenderer(suppliedContext, "status");
}
},
+ {
+ name: "kiln_renderer",
+ description: "Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.",
+ inputSchema: rendererInput,
+ run: async (raw) => runRenderer(suppliedContext, rendererInput.parse(raw).action)
+ },
...[
createKilnValidateDef(context),
createKilnRenderViewsDef(context),
@@ -51300,7 +51337,13 @@ function createProgramDefs(suppliedContext, presentation) {
].map((def) => withWorkspaceContext(def, context)).map((def) => ({
...def,
annotations: {
- readOnlyHint: ["kiln_source", "kiln_discover", "kiln_export", "kiln_present"].includes(def.name),
+ readOnlyHint: [
+ "kiln_source",
+ "kiln_discover",
+ "kiln_renderer_status",
+ "kiln_export",
+ "kiln_present"
+ ].includes(def.name),
destructiveHint: false,
idempotentHint: def.name !== "kiln_save",
openWorldHint: false,
@@ -51636,7 +51679,7 @@ var DEFAULT_INLOOP_VIEW_RENDER_TIMEOUT_MS = 6000, viewEvidenceHistoryByContext,
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, ASSET_CONTRACT;
+}), 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, rendererStatusInput, assetSelector, ASSET_CONTRACT;
var init_registry2 = __esm(() => {
init_capture_cache();
init_assets();
@@ -51659,6 +51702,7 @@ var init_registry2 = __esm(() => {
init_requirements_context();
init_evaluator();
init_material_resources();
+ init_render_route();
init_edit_buffer();
init_view_render_timeout();
init_evidence_history();
@@ -51761,6 +51805,7 @@ var init_registry2 = __esm(() => {
rendererInput = z24.strictObject({
action: z24.enum(["status", "reprobe"]).default("status")
});
+ rendererStatusInput = z24.strictObject({});
assetSelector = {
collection: z24.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: z24.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjs
index 02172d4f..dd95bab9 100644
--- a/dist/mcp-engine.mjs
+++ b/dist/mcp-engine.mjs
@@ -49317,6 +49317,8 @@ function projectOperationDefs(defs, context) {
return [];
if (def.name === "kiln_renderer")
return rendererOperations(def, context);
+ if (def.name === "kiln_renderer_status")
+ return context.renderCapabilities ? [def] : [];
if (def.name === "kiln_discover")
return discoveryOperations(def);
if (def.name === "kiln_material")
@@ -49414,20 +49416,21 @@ function materialOperations(def) {
return [search, tools.get, create, tools.import];
}
function rendererOperations(def, context) {
- if (!context.renderCapabilities)
+ if (!context.renderCapabilities || !context.reprobeRenderer)
return [];
- return ["status", ...context.reprobeRenderer ? ["reprobe"] : []].map((action) => {
- const inputSchema = z23.strictObject({});
- return {
+ const inputSchema = z23.strictObject({});
+ return [
+ {
...def,
- name: `kiln_renderer_${action}`,
+ name: "kiln_renderer_reprobe",
+ description: "Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.",
inputSchema,
run: async (raw) => {
inputSchema.parse(raw);
- return def.run({ action });
+ return def.run({ action: "reprobe" });
}
- };
- });
+ }
+ ];
}
function discoveryOperations(def) {
const original = def.inputSchema;
@@ -49463,6 +49466,33 @@ init_evaluator();
init_material_resources();
import * as THREE58 from "three";
+// src/render-route.ts
+var GPU_SERVES = new Set([
+ "available",
+ "on-demand",
+ "authentication-unverified"
+]);
+function nextRenderRoute(renderer) {
+ const fallback = (reason) => ({
+ active: true,
+ materialFaithful: false,
+ reason
+ });
+ if (!renderer.configured)
+ return {
+ ready: true,
+ activeRoute: "cpu",
+ fallback: fallback(renderer.reason ?? (renderer.mode === "cpu" ? "This host selected CPU rendering; views show geometry, not materials." : "No GPU renderer is attached to this session; views show geometry, not materials."))
+ };
+ if (GPU_SERVES.has(renderer.status))
+ return { ready: true, activeRoute: "gpu", fallback: { active: false } };
+ return {
+ ready: false,
+ activeRoute: "gpu",
+ fallback: renderer.required ? { active: false } : fallback(`GPU renderer ${renderer.status}${renderer.reason ? `: ${renderer.reason}` : ""}. Renders degrade to CPU geometry views.`)
+ };
+}
+
// src/edit-buffer.ts
class KilnDraftBuffer {
buf;
@@ -50863,6 +50893,28 @@ function withCaptureCache(context) {
var rendererInput = z24.strictObject({
action: z24.enum(["status", "reprobe"]).default("status")
});
+var rendererStatusInput = z24.strictObject({});
+async function runRenderer(context, action) {
+ if (action === "reprobe" && !context.reprobeRenderer)
+ return {
+ ok: false,
+ error: "Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true })."
+ };
+ if (!context.renderCapabilities)
+ return {
+ ok: false,
+ error: "Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true })."
+ };
+ try {
+ const renderer = await (action === "reprobe" ? context.reprobeRenderer() : context.renderCapabilities());
+ return { ok: true, renderer: { ...renderer, ...nextRenderRoute(renderer) } };
+ } catch (error) {
+ return {
+ ok: false,
+ error: error instanceof Error ? error.message : String(error)
+ };
+ }
+}
async function readSavedRevision(target, collection, assetId, revisionId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
try {
return await target.read(collection, assetId, revisionId);
@@ -50882,34 +50934,20 @@ function createProgramDefs(suppliedContext, presentation) {
return [
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.",
- inputSchema: rendererInput,
+ name: "kiln_renderer_status",
+ description: "Read renderer status: ready, activeRoute (gpu or cpu) and fallback say what the next render uses; an active fallback means CPU geometry views, not material evidence. Read-only: never reprobes, installs, starts or renders. Read viewFidelity after rendering.",
+ inputSchema: rendererStatusInput,
run: async (raw) => {
- const { action } = rendererInput.parse(raw);
- if (action === "reprobe" && !suppliedContext.reprobeRenderer)
- return {
- ok: false,
- error: "Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true })."
- };
- if (!suppliedContext.renderCapabilities)
- return {
- ok: false,
- error: "Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true })."
- };
- try {
- return {
- ok: true,
- renderer: await (action === "reprobe" ? suppliedContext.reprobeRenderer() : suppliedContext.renderCapabilities())
- };
- } catch (error) {
- return {
- ok: false,
- error: error instanceof Error ? error.message : String(error)
- };
- }
+ rendererStatusInput.parse(raw);
+ return runRenderer(suppliedContext, "status");
}
},
+ {
+ name: "kiln_renderer",
+ description: "Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.",
+ inputSchema: rendererInput,
+ run: async (raw) => runRenderer(suppliedContext, rendererInput.parse(raw).action)
+ },
...[
createKilnValidateDef(context),
createKilnRenderViewsDef(context),
@@ -50932,7 +50970,13 @@ function createProgramDefs(suppliedContext, presentation) {
].map((def) => withWorkspaceContext(def, context)).map((def) => ({
...def,
annotations: {
- readOnlyHint: ["kiln_source", "kiln_discover", "kiln_export", "kiln_present"].includes(def.name),
+ readOnlyHint: [
+ "kiln_source",
+ "kiln_discover",
+ "kiln_renderer_status",
+ "kiln_export",
+ "kiln_present"
+ ].includes(def.name),
destructiveHint: false,
idempotentHint: def.name !== "kiln_save",
openWorldHint: false,
diff --git a/dist/mcp-server.mjs b/dist/mcp-server.mjs
index 2dd0d9cd..cc63b740 100644
--- a/dist/mcp-server.mjs
+++ b/dist/mcp-server.mjs
@@ -90,9 +90,24 @@ var mcp_manifest_default = {
openWorldHint: false
}
},
+ {
+ name: "kiln_renderer_status",
+ description: "Read renderer status: ready, activeRoute (gpu or cpu) and fallback say what the next render uses; an active fallback means CPU geometry views, not material evidence. Read-only: never reprobes, installs, starts or renders. Read viewFidelity after rendering.",
+ inputSchema: {
+ type: "object",
+ properties: {},
+ additionalProperties: false
+ },
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false
+ }
+ },
{
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.",
+ description: "Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.",
inputSchema: {
type: "object",
properties: {
diff --git a/docs/architecture.md b/docs/architecture.md
index 1407e18c..21058ccf 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -34,8 +34,8 @@ See [package.json](../package.json) for all exports.
## Tool surfaces
[src/tools/registry.ts](../src/tools/registry.ts) owns the current tool definitions.
-`createKilnProgramToolRegistry` supplies fourteen MCP tools; the packaged local host
-adds `kiln_project`, `kiln_material` and `kiln_review`, for seventeen over stdio.
+`createKilnProgramToolRegistry` supplies fifteen MCP tools; the packaged local host
+adds `kiln_project`, `kiln_material` and `kiln_review`, for eighteen over stdio.
`createKilnNativeToolRegistry` reuses those definitions, removes unavailable delivery
services and adds exact-reference completion. The retired mutable-buffer factories
and separate `kiln_screenshot` are not the supported native workflow.
@@ -43,8 +43,8 @@ and separate `kiln_screenshot` are not the supported native workflow.
| Interface | Execution and feedback | Completion and host services |
| --- | --- | --- |
| CLI | Node commands call shared engine operations; render/inspection receipts accompany image files that the host agent must read. | The invoking agent controls delivery. CLI/MCP can share the same workspace, stores and requirements binding. |
-| MCP | Seventeen registry tools over stdio (fourteen program tools plus project, material and review); unified `kiln_render` returns metrics, QA, part paths and typed images with fidelity. Numeric-only inspection can omit images. | The host owns the agent loop; no terminal submit tool. Host media handling still needs qualification. |
-| Native Strands | Direct in-process registry adapters with injected stores, requirements and rendering; no CLI/MCP hop. Same source/reference/edit/inspection semantics. | Ten default tools including `kiln_finish`; five delivery tools when an asset library is injected. A configured skill-resource reader adds one tool. Finish selects a retained reviewed revision; it does not certify QA success. |
+| MCP | Eighteen registry tools over stdio (fifteen program tools plus project, material and review); unified `kiln_render` returns metrics, QA, part paths and typed images with fidelity. Numeric-only inspection can omit images. | The host owns the agent loop; no terminal submit tool. Host media handling still needs qualification. |
+| Native Strands | Direct in-process registry adapters with injected stores, requirements and rendering; no CLI/MCP hop. Same source/reference/edit/inspection semantics. | Eleven default tools including `kiln_finish`; five delivery tools when an asset library is injected. A configured skill-resource reader adds one tool. Finish selects a retained reviewed revision; it does not certify QA success. |
Discovery needs no inference service. Recipes are optional guidance; requirements
select checks independently of labels. The Strands SDK and provider adapters are
diff --git a/docs/chatgpt.md b/docs/chatgpt.md
index f3cbbf13..e3fe277a 100644
--- a/docs/chatgpt.md
+++ b/docs/chatgpt.md
@@ -13,7 +13,7 @@ optional OpenAI tunnel separately requires Platform access and a runtime API key
3. Obtain the client through the [official tunnel setup guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels#set-up-tunnel-client). Record the version you test. Keep credentials outside the plugin and source repository.
4. Configure the tunnel's stdio command to launch `node /absolute/path/dist/mcp-server.mjs` in a dedicated asset workspace. Set `KILN_PROGRAM_STORE` and `KILN_COLLECTIONS` explicitly. The server does not need provider keys. The tunnel control process needs its OpenAI key, which should not be inherited by the MCP child.
5. Run `tunnel-client doctor --profile NAME --explain`, then `tunnel-client run --profile NAME`. In ChatGPT Plugins, use the plus button, Add custom MCP server, then Tunnel. Select your tunnel, configure authentication, review the warning and create the plugin. Kiln's local stdio server has no separate OAuth; access is controlled by the private tunnel.
-6. Verify the seventeen-tool MCP surface appears, including `kiln_discover`, `kiln_renderer`, `kiln_present` and `kiln_project`. Test source submission, actual render-image visibility, save/list, copy, restore/edit, and exact revision export. Refresh connector metadata after changing tools.
+6. Verify the eighteen-tool MCP surface appears, including `kiln_discover`, `kiln_renderer_status`, `kiln_renderer`, `kiln_present` and `kiln_project`. Test source submission, actual render-image visibility, save/list, copy, restore/edit, and exact revision export. Refresh connector metadata after changing tools.
Local subprocess evaluation has deadlines and a sanitized environment; it is not the Linux isolated evaluator's OS security boundary. This setup is for an owner-controlled development test. A hosted multi-user deployment needs tenant-scoped storage, authentication, and the isolated evaluator posture.
diff --git a/docs/install.md b/docs/install.md
index 763fde19..a58b412d 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -155,9 +155,9 @@ For agent-assisted installation, give your agent the repository URL and ask:
## Release compatibility
-The packaged local MCP server lists the fourteen base tools in the
+The packaged local MCP server lists the fifteen base tools in the
[generated tool reference](tools.md), plus `kiln_project`, `kiln_material` and
-`kiln_review` from the packaged local host: seventeen in all. When installing an
+`kiln_review` from the packaged local host: eighteen in all. When installing an
older release, use the documentation and receipt attached to that release; newer
tools and migration changes are not retroactively available there.
diff --git a/docs/rendering.md b/docs/rendering.md
index c57dafd1..c5418d30 100644
--- a/docs/rendering.md
+++ b/docs/rendering.md
@@ -130,6 +130,17 @@ and survives the session that started it. It exits after five minutes with no ad
uploads, queued jobs or active renders. Health polling does not extend that timeout.
`RENDER_SERVICE_IDLE_MS` configures managed idle time from 1 to 3,600,000 milliseconds.
+`kiln_renderer_status` reads the session's renderer state and is advertised read-only, so
+hosts that auto-allow reads do not prompt for it. Besides the readiness fields below, it
+states what the next render uses: `activeRoute` is `gpu` or `cpu`, `ready` says that route
+can serve now, and `fallback` is `{ active: true, materialFaithful: false, reason }` when
+views will be CPU geometry (a CPU-only host, a session that selected CPU before a service
+became healthy, or an attached GPU that stopped answering), otherwise `{ active: false }`.
+A host that requires the GPU fails the render instead, with `ready: false` and no
+fallback. A scene that needs no PBR shading still renders on CPU over a GPU route, so the
+returned `viewFidelity` remains the evidence. `kiln_renderer` with `action:"status"`
+returns the same result for existing callers.
+
After renderer installation or repair, call `kiln_renderer({action:"reprobe"})` in
the existing MCP or native session. It refreshes the connection and resets a failed
local startup attempt; the next view starts the service if needed. Reprobe does not
diff --git a/docs/runtime.md b/docs/runtime.md
index 791c9f54..4d562fa7 100644
--- a/docs/runtime.md
+++ b/docs/runtime.md
@@ -2,7 +2,7 @@
Kiln stores source revisions separately from evaluated builds and rendered images. A reference saves the model from repeating source. A compatible build cache saves the engine from evaluating it again.
-The packaged local host also supplies optional project, material-library and review capabilities through the shared registry. These add `kiln_project`, `kiln_material` and `kiln_review` to the fourteen base MCP tools; custom embeddings only advertise capabilities they inject. Projects are optional: standalone calls can pin material dependencies directly, and omission does not infer project membership from nearby records. [Projects and Live Review](projects-and-live-review.md) describes explicit selection, shared CLI/MCP/dashboard records, exact-save delivery and portable resource closure. These host facilities do not change the native completion protocol.
+The packaged local host also supplies optional project, material-library and review capabilities through the shared registry. These add `kiln_project`, `kiln_material` and `kiln_review` to the fifteen base MCP tools; custom embeddings only advertise capabilities they inject. Projects are optional: standalone calls can pin material dependencies directly, and omission does not infer project membership from nearby records. [Projects and Live Review](projects-and-live-review.md) describes explicit selection, shared CLI/MCP/dashboard records, exact-save delivery and portable resource closure. These host facilities do not change the native completion protocol.
Compiled CLI/MCP commands share one Node compatibility check with workspace setup:
20.x from 20.15.0, or 22.2.0 and later. Optional Strands generation requires 22.2.0+;
diff --git a/docs/tools.md b/docs/tools.md
index 062170c2..ccc5d9f6 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -86,9 +86,27 @@ Discover Kiln operations, assemblies, recipes, tool-input shapes and current hos
</details>
+## kiln_renderer_status
+
+Read renderer status: ready, activeRoute (gpu or cpu) and fallback say what the next render uses; an active fallback means CPU geometry views, not material evidence. Read-only: never reprobes, installs, starts or renders. Read viewFidelity after rendering.
+
+<details>
+<summary>Input JSON Schema</summary>
+
+
+```json
+{
+ "type": "object",
+ "properties": {},
+ "additionalProperties": false
+}
+```
+
+</details>
+
## kiln_renderer
-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.
+Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.
<details>
<summary>Input JSON Schema</summary>
diff --git a/plugins/kiln-engine/package-provenance.json b/plugins/kiln-engine/package-provenance.json
index bc67be15..5e08248b 100644
--- a/plugins/kiln-engine/package-provenance.json
+++ b/plugins/kiln-engine/package-provenance.json
@@ -17,7 +17,7 @@
"runtime.json": "sha256:90a3e66998cc7f360a02f6d6910adb178b53cd24909505b1d2e46c2771e02679",
"SECURITY.md": "sha256:8e238d3985deff828efd71bc3354a5b0275613a4921f369fc971f760ca249606",
"skills/kiln-setup-workspace/references/plugin-install.md": "sha256:c338fb792e7fad0364c3e1a13c94c506afa1395489ec1b6e83b36d04728935fb",
- "skills/kiln-setup-workspace/references/renderer-setup.md": "sha256:b743b1b2827fa814385990e1e5b849391cb427413e9c016d273aa19cebd46031",
+ "skills/kiln-setup-workspace/references/renderer-setup.md": "sha256:a716a1e35c3ed69256c9f90ca7e08a3f0e66ccfc391c57a9454cad5d3c6f78dd",
"skills/kiln-setup-workspace/SKILL.md": "sha256:65ed926b3503a33f4fe793e84e4a045ce36e3967f0e6b340e456a15dd010ce54"
}
}
diff --git a/plugins/kiln-engine/skills/kiln-setup-workspace/references/renderer-setup.md b/plugins/kiln-engine/skills/kiln-setup-workspace/references/renderer-setup.md
index 8cdd06cd..9dcbc2b5 100644
--- a/plugins/kiln-engine/skills/kiln-setup-workspace/references/renderer-setup.md
+++ b/plugins/kiln-engine/skills/kiln-setup-workspace/references/renderer-setup.md
@@ -6,6 +6,6 @@ The renderer code is included with Kiln; its native GPU dependency is optional a
Once dependencies are available, local CLI/MCP auto mode starts a managed service lazily for a view that needs PBR shading. Compatible clients share it; it survives the initiating session and exits after five minutes without admitted uploads, queued jobs or active renders. From the installation root, `node --import ./render-service/src/register-hooks.mjs render-service/src/server.mjs` starts a manual service that remains running while idle. It binds loopback; widening `HOST` requires `RENDER_SERVICE_TOKEN`.
-`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. After dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
+`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. Inside an MCP session, `kiln_renderer_status` is read-only, so call it freely: `activeRoute` (`gpu` or `cpu`), `ready` and `fallback` say what the next render uses, and an active `fallback` means CPU geometry views, not material evidence. Reprobe only after a repair: after dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
A `KILN_RENDER_PORT_URL` whose origin is exactly the shared local socket (`http://127.0.0.1:8000` by default) takes the local route: it starts on demand and restarts after an idle exit. For rendering on another device, configure the MCP server process's `KILN_RENDER_PORT_URL` and, when needed, `KILN_RENDER_TOKEN` through the chosen harness. CLI accepts `--render-port URL` and reads `KILN_RENDER_TOKEN`. Start a compatible Kiln renderer on that device; its wider bind requires `RENDER_SERVICE_TOKEN` unless an authenticated proxy is explicitly configured. Manage the remote service on its own device. Verify the selected route with capabilities and require an actual `viewFidelity` receipt for material evidence.
diff --git a/plugins/kiln-hosted/README.md b/plugins/kiln-hosted/README.md
index 80b96643..70ae7a45 100644
--- a/plugins/kiln-hosted/README.md
+++ b/plugins/kiln-hosted/README.md
@@ -53,7 +53,7 @@ draft with `node scripts/package-hosted-plugin.mjs FRESH_OUTPUT_DIRECTORY`.
`tool-surface.json` records the 21-tool `kiln.hosted-tools.v2` presentation verified
in production with engine 1.2.1. Its skill and review cases use those operation
names. A parity test checks the snapshot against the shared engine registry to
-catch drift. The local package retains its seventeen-tool interface.
+catch drift. The local package retains its eighteen-tool interface.
The draft plugin version and deployed hosted engine version are recorded
separately; a new public package does not silently upgrade the hosted service.
diff --git a/scripts/create-workspace.mjs b/scripts/create-workspace.mjs
index c6995e22..4d90834c 100644
--- a/scripts/create-workspace.mjs
+++ b/scripts/create-workspace.mjs
@@ -354,7 +354,7 @@ Standalone work needs no project. Omitted project selection stays standalone unl
## Material-faithful views
-Render mode is auto: scenes with textures or metalness use a compatible GPU render service (render-service/ in the Kiln installation), started on demand when its dependencies are installed; flat scenes use CPU geometry views, which is not a failure. node kiln.mjs service status reports readiness; after repairing dependencies call kiln_renderer { action: "reprobe" } (CLI: node kiln.mjs service reprobe). For a renderer on another device, configure KILN_RENDER_PORT_URL and, when required, KILN_RENDER_TOKEN on the server, or pass --render-port URL to the CLI. When a task is about appearance and only CPU views exist, say so.
+Render mode is auto: scenes with textures or metalness use a compatible GPU render service (render-service/ in the Kiln installation), started on demand when its dependencies are installed; flat scenes use CPU geometry views, which is not a failure. node kiln.mjs service status reports readiness; kiln_renderer_status is read-only, so check the session's activeRoute and fallback with it freely (an active fallback means CPU geometry views); only after repairing dependencies call kiln_renderer { action: "reprobe" } (CLI: node kiln.mjs service reprobe). For a renderer on another device, configure KILN_RENDER_PORT_URL and, when required, KILN_RENDER_TOKEN on the server, or pass --render-port URL to the CLI. When a task is about appearance and only CPU views exist, say so.
## Context compaction
diff --git a/scripts/evaluation/server.test.ts b/scripts/evaluation/server.test.ts
index 2d04f5e9..99fa43ac 100644
--- a/scripts/evaluation/server.test.ts
+++ b/scripts/evaluation/server.test.ts
@@ -31,7 +31,7 @@ test('pilot host advertises a condition, delivers a real image and enforces the
await client.connect(transport);
try {
const listed = await client.listTools();
- expect(listed.tools).toHaveLength(9);
+ expect(listed.tools).toHaveLength(10);
const discovery = await client.callTool({
name: 'kiln_discover',
arguments: { category: 'geometry' },
diff --git a/scripts/sdk-host-contracts.test.mjs b/scripts/sdk-host-contracts.test.mjs
index 626ac190..c58ed1b2 100644
--- a/scripts/sdk-host-contracts.test.mjs
+++ b/scripts/sdk-host-contracts.test.mjs
@@ -17,7 +17,7 @@ test('a Node consumer embeds the shared MCP host through a public package import
import { createKilnMcpServer, createKilnToolHost, kilnMcpToolDefs } from '@instruktlabs/kiln/mcp';
const host = createKilnToolHost();
assert.deepEqual(host.defs.map(t => t.name), kilnMcpToolDefs().map(t => t.name));
- assert.equal(host.defs.length, 14);
+ assert.equal(host.defs.length, 15);
const result = await host.callTool('kiln_discover', { overview: true }, { signal: new AbortController().signal });
assert.notEqual(result.isError, true);
assert.ok(result.content.some(block => block.type === 'text' && block.text.includes('createRoot(name: string)')));
diff --git a/scripts/smoke-package-adoption.mjs b/scripts/smoke-package-adoption.mjs
index f7794282..3dd81de0 100644
--- a/scripts/smoke-package-adoption.mjs
+++ b/scripts/smoke-package-adoption.mjs
@@ -62,10 +62,16 @@ export async function smokePackageAdoption({ runtime, root, command, connect, te
"createPart('Body', boxGeo(1,1,1), gameMaterial(0x808080), {position:[0,0.5,0],parent:root});\n" +
'return root; }\n';
const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
- let programRef, asset, sourceUri, glbUri, glbHash;
+ let programRef, asset, sourceUri, glbUri, glbHash, toolNames;
+ // The registry matrix also runs this against older releases, whose tool count differs:
+ // require the host-injected tools and the same surface for both clients instead.
+ const names = async (session) =>
+ (await session.call('tools/list', {})).tools.map((t) => t.name).sort();
const first = await sessionFor(claude);
try {
- assert.equal((await first.call('tools/list', {})).tools.length, 17);
+ toolNames = await names(first);
+ for (const name of ['kiln_project', 'kiln_material', 'kiln_review', 'kiln_render'])
+ assert.ok(toolNames.includes(name), `adopted workspace serves ${name}`);
programRef = (await tool(first, 'kiln_validate', { code: source })).programRef;
assert.equal(typeof programRef, 'string');
await tool(first, 'kiln_render', { programRef, capture: { preset: '1x1' } });
@@ -85,7 +91,7 @@ export async function smokePackageAdoption({ runtime, root, command, connect, te
assert.equal(codex.env.KILN_PROGRAM_STORE, claude.env.KILN_PROGRAM_STORE);
const second = await sessionFor(codex);
try {
- assert.equal((await second.call('tools/list', {})).tools.length, 17);
+ assert.deepEqual(await names(second), toolNames);
assert.match(
(await tool(second, 'kiln_source', { programRef, query: 'ContractCube' })).code,
/ContractCube/,
diff --git a/skills/kiln-setup-workspace/references/renderer-setup.md b/skills/kiln-setup-workspace/references/renderer-setup.md
index 8cdd06cd..9dcbc2b5 100644
--- a/skills/kiln-setup-workspace/references/renderer-setup.md
+++ b/skills/kiln-setup-workspace/references/renderer-setup.md
@@ -6,6 +6,6 @@ The renderer code is included with Kiln; its native GPU dependency is optional a
Once dependencies are available, local CLI/MCP auto mode starts a managed service lazily for a view that needs PBR shading. Compatible clients share it; it survives the initiating session and exits after five minutes without admitted uploads, queued jobs or active renders. From the installation root, `node --import ./render-service/src/register-hooks.mjs render-service/src/server.mjs` starts a manual service that remains running while idle. It binds loopback; widening `HOST` requires `RENDER_SERVICE_TOKEN`.
-`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. After dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
+`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. Inside an MCP session, `kiln_renderer_status` is read-only, so call it freely: `activeRoute` (`gpu` or `cpu`), `ready` and `fallback` say what the next render uses, and an active `fallback` means CPU geometry views, not material evidence. Reprobe only after a repair: after dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
A `KILN_RENDER_PORT_URL` whose origin is exactly the shared local socket (`http://127.0.0.1:8000` by default) takes the local route: it starts on demand and restarts after an idle exit. For rendering on another device, configure the MCP server process's `KILN_RENDER_PORT_URL` and, when needed, `KILN_RENDER_TOKEN` through the chosen harness. CLI accepts `--render-port URL` and reads `KILN_RENDER_TOKEN`. Start a compatible Kiln renderer on that device; its wider bind requires `RENDER_SERVICE_TOKEN` unless an authenticated proxy is explicitly configured. Manage the remote service on its own device. Verify the selected route with capabilities and require an actual `viewFidelity` receipt for material evidence.
diff --git a/src/__tests__/mcp-conformance.test.ts b/src/__tests__/mcp-conformance.test.ts
index dc479556..41f920b3 100644
--- a/src/__tests__/mcp-conformance.test.ts
+++ b/src/__tests__/mcp-conformance.test.ts
@@ -58,6 +58,7 @@ const EXPECTED_TOOLS = [
'kiln_project',
'kiln_render',
'kiln_renderer',
+ 'kiln_renderer_status',
'kiln_review',
'kiln_save',
'kiln_screenshot_animation',
diff --git a/src/__tests__/mcp-manifest.test.ts b/src/__tests__/mcp-manifest.test.ts
index 10d93f6f..4f265e78 100644
--- a/src/__tests__/mcp-manifest.test.ts
+++ b/src/__tests__/mcp-manifest.test.ts
@@ -34,6 +34,7 @@ describe('generated MCP manifest', () => {
'kiln_project',
'kiln_render',
'kiln_renderer',
+ 'kiln_renderer_status',
'kiln_review',
'kiln_save',
'kiln_screenshot_animation',
diff --git a/src/__tests__/mcp-payload.test.ts b/src/__tests__/mcp-payload.test.ts
index ba1e9e53..a6940289 100644
--- a/src/__tests__/mcp-payload.test.ts
+++ b/src/__tests__/mcp-payload.test.ts
@@ -124,9 +124,10 @@ describe('always-on context cost', () => {
it('the tool schemas stay within the context budget', async () => {
const chars = schemaChars();
- // 32,455 serialized characters for fourteen tools, including bounded part
- // listing on inspect. This replaces guessed paths/repeated image calls for
- // scenes over the 80-part preview. No new tool or loaded helper catalog.
+ // Bounded part listing on inspect replaces guessed paths/repeated image calls
+ // for scenes over the 80-part preview, without a loaded helper catalog. The
+ // read-only kiln_renderer_status (#206) measured 24,512 -> 24,936 serialized
+ // characters for fifteen tools on 2026-10-22.
// Keep the new bound explicit; this is context cost, not a coverage gate.
expect(chars).toBeLessThan(32 * 1024);
});
diff --git a/src/__tests__/mcp-startup.test.ts b/src/__tests__/mcp-startup.test.ts
index 8c917957..aa7d6429 100644
--- a/src/__tests__/mcp-startup.test.ts
+++ b/src/__tests__/mcp-startup.test.ts
@@ -129,7 +129,7 @@ export function createPackagedKilnHost() { throw new Error('unused engine'); }
legacy.notify('notifications/initialized');
const listed = await legacy.request('tools/list', {});
expect(listed.error).toBeUndefined();
- expect((listed.result!['tools'] as unknown[]).length).toBe(17);
+ expect((listed.result!['tools'] as unknown[]).length).toBe(18);
// The first call that needs the engine reports the missing bundle as a
// tool result with the next step, and the process stays up.
const call = await legacy.request('tools/call', {
@@ -153,7 +153,7 @@ export function createPackagedKilnHost() { throw new Error('unused engine'); }
expect(discover.error, modern.stderr()).toBeUndefined();
expect(discover.result!['supportedVersions']).toContain('2026-07-28');
const tools = await modern.request('tools/list', { _meta: modernMeta() });
- expect((tools.result!['tools'] as unknown[]).length).toBe(17);
+ expect((tools.result!['tools'] as unknown[]).length).toBe(18);
await modern.close();
});
diff --git a/src/__tests__/renderer-refresh.test.ts b/src/__tests__/renderer-refresh.test.ts
index 4b4c52eb..bddf87ab 100644
--- a/src/__tests__/renderer-refresh.test.ts
+++ b/src/__tests__/renderer-refresh.test.ts
@@ -4,6 +4,8 @@ import type { AddressInfo } from 'node:net';
import sharp from 'sharp';
import { buildRenderPort } from '../cli-render-mode';
import { createLocalToolContext } from '../local-runtime';
+import type { RenderCapabilities } from '../render-capabilities';
+import { nextRenderRoute } from '../render-route';
import { createKilnProgramToolRegistry, type KilnRenderViewsResult } from '../tools/registry';
import { MemoryProgramStore } from '../program-store';
import { fakeRenderHealth } from './helpers/fake-render-service';
@@ -99,10 +101,31 @@ test('existing registry refreshes a recovered renderer and never reuses its CPU
ok: true,
renderer: { configured: false, reprobeRequired: true },
});
+ // #206: the read-only status names what the next render uses without reading prose.
+ const status = tools.find((t) => t.name === 'kiln_renderer_status')!;
+ expect(status.annotations?.readOnlyHint).toBe(true);
+ expect(await status.run({})).toMatchObject({
+ ok: true,
+ renderer: {
+ configured: false,
+ reprobeRequired: true,
+ ready: true,
+ activeRoute: 'cpu',
+ fallback: {
+ active: true,
+ materialFaithful: false,
+ reason: expect.stringContaining('reprobe'),
+ },
+ },
+ });
expect(await refresh!.run({ action: 'reprobe' })).toMatchObject({
ok: true,
renderer: { configured: true, status: 'available' },
});
+ expect(await status.run({})).toMatchObject({
+ ok: true,
+ renderer: { ready: true, activeRoute: 'gpu', fallback: { active: false } },
+ });
expect(state.renders).toBe(0);
const after = (await render.run({
programRef: before.programRef,
@@ -222,6 +245,89 @@ test('reprobe resets a failed lazy start without starting the service itself', a
expect(state.renders).toBe(0);
});
+test('status never reprobes, starts or renders, and names the on-demand GPU route', async () => {
+ const { state, url } = await service();
+ await new Promise<void>((r) => servers.at(-1)!.close(() => r()));
+ delete process.env.KILN_RENDER_PORT_URL;
+ process.env.KILN_RENDER_SERVICE_PORT = new URL(url).port;
+ let starts = 0;
+ const context = await buildRenderPort('auto', undefined, {
+ start: async () => {
+ starts++;
+ return url;
+ },
+ });
+ let reprobes = 0;
+ const reprobe = context.reprobeRenderer!;
+ context.reprobeRenderer = () => {
+ reprobes++;
+ return reprobe();
+ };
+ const tools = createKilnProgramToolRegistry(context);
+ const expected = {
+ ok: true,
+ renderer: {
+ status: 'on-demand',
+ ready: true,
+ activeRoute: 'gpu',
+ fallback: { active: false },
+ },
+ };
+ expect(await tools.find((t) => t.name === 'kiln_renderer_status')!.run({})).toMatchObject(
+ expected,
+ );
+ expect(
+ await tools.find((t) => t.name === 'kiln_renderer')!.run({ action: 'status' }),
+ ).toMatchObject(expected);
+ expect({ reprobes, starts, renders: state.renders, healthReads: state.healthReads }).toEqual({
+ reprobes: 0,
+ starts: 0,
+ renders: 0,
+ healthReads: 0,
+ });
+});
+
+test('a CPU-only host reports the CPU route as an active, non-material fallback', async () => {
+ const status = createKilnProgramToolRegistry(await buildRenderPort('cpu', undefined)).find(
+ (t) => t.name === 'kiln_renderer_status',
+ )!;
+ expect(await status.run({})).toMatchObject({
+ ok: true,
+ renderer: {
+ status: 'disabled',
+ ready: true,
+ activeRoute: 'cpu',
+ fallback: { active: true, materialFaithful: false, reason: expect.stringContaining('CPU') },
+ },
+ });
+});
+
+test('an attached GPU that stopped answering degrades, unless the host requires it', () => {
+ const attached: RenderCapabilities = {
+ mode: 'auto',
+ target: 'local',
+ configured: true,
+ required: false,
+ status: 'unavailable',
+ reason: 'No local service is listening and automatic startup is disabled.',
+ evidence: 'health-only',
+ };
+ expect(nextRenderRoute(attached)).toEqual({
+ ready: false,
+ activeRoute: 'gpu',
+ fallback: {
+ active: true,
+ materialFaithful: false,
+ reason: expect.stringContaining('No local service is listening'),
+ },
+ });
+ expect(nextRenderRoute({ ...attached, mode: 'gpu', required: true })).toEqual({
+ ready: false,
+ activeRoute: 'gpu',
+ fallback: { active: false },
+ });
+});
+
test('CPU refresh stays CPU; opaque injected hosts reject unsupported reprobe', async () => {
const { state, url } = await service();
const cpu = createKilnProgramToolRegistry(await buildRenderPort('cpu', url));
diff --git a/src/agent/tools-media.test.ts b/src/agent/tools-media.test.ts
index 5d29b337..f251e1aa 100644
--- a/src/agent/tools-media.test.ts
+++ b/src/agent/tools-media.test.ts
@@ -78,6 +78,7 @@ describe('makeKilnNativeTools media handling', () => {
test('exposes shared source tools and a native terminal action', () => {
expect(makeKilnNativeTools({}, {}).map((t) => t.name)).toEqual([
'kiln_discover',
+ 'kiln_renderer_status',
'kiln_renderer',
'kiln_validate',
'kiln_render',
diff --git a/src/generated/mcp-manifest.json b/src/generated/mcp-manifest.json
index b4e7c001..a9211fdb 100644
--- a/src/generated/mcp-manifest.json
+++ b/src/generated/mcp-manifest.json
@@ -74,9 +74,24 @@
"openWorldHint": false
}
},
+ {
+ "name": "kiln_renderer_status",
+ "description": "Read renderer status: ready, activeRoute (gpu or cpu) and fallback say what the next render uses; an active fallback means CPU geometry views, not material evidence. Read-only: never reprobes, installs, starts or renders. Read viewFidelity after rendering.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {},
+ "additionalProperties": false
+ },
+ "annotations": {
+ "readOnlyHint": true,
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": false
+ }
+ },
{
"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.",
+ "description": "Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.",
"inputSchema": {
"type": "object",
"properties": {
diff --git a/src/mcp-manifest.ts b/src/mcp-manifest.ts
index f22a06ff..a7ad86e1 100644
--- a/src/mcp-manifest.ts
+++ b/src/mcp-manifest.ts
@@ -7,7 +7,7 @@
* applies when it is handed a zod schema, so the manifest is what the library
* would have advertised -- minus the `$schema` keyword, because 2020-12 is the
* dialect MCP assumes when none is named, and the keyword costs 56 bytes in
- * every one of the seventeen definitions a harness sends with every request.
+ * every one of the eighteen definitions a harness sends with every request.
*/
import type { z } from 'zod';
diff --git a/src/mcp-parity.test.ts b/src/mcp-parity.test.ts
index e212b042..234988a1 100644
--- a/src/mcp-parity.test.ts
+++ b/src/mcp-parity.test.ts
@@ -10,7 +10,12 @@
import { describe, expect, it } from 'bun:test';
import { Client, InMemoryTransport } from '@modelcontextprotocol/client';
-import { createKilnNativeToolRegistry, createKilnProgramToolRegistry } from './tools/registry';
+import {
+ createKilnNativeToolRegistry,
+ createKilnOperationToolRegistry,
+ createKilnProgramToolRegistry,
+} from './tools/registry';
+import type { RenderCapabilities } from './render-capabilities';
import { makeKilnNativeTools } from './agent/tools';
import { runTool, kilnMcpToolDefs, createKilnMcpServer } from './mcp-engine';
@@ -51,6 +56,35 @@ describe('tool surface parity across transports', () => {
expect(tools.find((t) => t.name === name)?.annotations?.readOnlyHint).toBe(true);
expect(tools.find((t) => t.name === 'kiln_save')?.annotations?.readOnlyHint).toBe(false);
});
+ it('advertises renderer status as read-only and reprobe as stateful on every surface', async () => {
+ // #206: one kiln_renderer served both, advertised readOnlyHint false, so a host that
+ // auto-allows reads asked the user every time the agent checked status.
+ const renderer: RenderCapabilities = {
+ mode: 'cpu',
+ target: 'cpu',
+ configured: false,
+ required: false,
+ status: 'disabled',
+ evidence: 'configuration-only',
+ };
+ const host = {
+ renderCapabilities: async () => renderer,
+ reprobeRenderer: async () => renderer,
+ };
+ const readOnly = (defs: { name: string; annotations?: { readOnlyHint?: boolean } }[]) =>
+ Object.fromEntries(
+ defs
+ .filter((def) => def.name.startsWith('kiln_renderer'))
+ .map((def) => [def.name, def.annotations?.readOnlyHint]),
+ );
+ const grouped = { kiln_renderer_status: true, kiln_renderer: false };
+ expect(readOnly(await listToolsOverMcp())).toEqual(grouped);
+ expect(readOnly(createKilnNativeToolRegistry(host, {}))).toEqual(grouped);
+ expect(readOnly(createKilnOperationToolRegistry(host))).toEqual({
+ kiln_renderer_status: true,
+ kiln_renderer_reprobe: false,
+ });
+ });
it('the reference-based Strands skin shares every MCP definition plus terminal finish', () => {
expect(makeKilnNativeTools({}, { assetLibrary: {} as never }).map((t) => t.name)).toEqual([
...kilnMcpToolDefs().map((d) => d.name),
@@ -85,6 +119,7 @@ describe('tool surface parity across transports', () => {
it('the MCP surface carries one unified kiln_render and no native terminal', () => {
expect(kilnMcpToolDefs().map((d) => d.name)).toEqual([
'kiln_discover',
+ 'kiln_renderer_status',
'kiln_renderer',
'kiln_validate',
'kiln_render',
diff --git a/src/render-route.ts b/src/render-route.ts
new file mode 100644
index 00000000..279b12de
--- /dev/null
+++ b/src/render-route.ts
@@ -0,0 +1,53 @@
+/** Dependency-free reading of renderer status; the registry imports it without Node-only edges. */
+import type { RenderCapabilities } from './render-capabilities';
+
+/**
+ * What the next render uses, stated as fields (#206): agents inferred it from `configured`,
+ * `status` and prose. `activeRoute` is the route this session attempts; `ready` says that
+ * route can serve now; an active `fallback` means views will be CPU geometry, never material
+ * evidence. A scene that needs no PBR shading still renders on CPU over a GPU route, so each
+ * render's `viewFidelity` stays the authority.
+ */
+export interface NextRenderRoute {
+ ready: boolean;
+ activeRoute: 'gpu' | 'cpu';
+ fallback: { active: false } | { active: true; materialFaithful: false; reason: string };
+}
+
+/** GPU statuses a configured route can serve: verified, startable, or token not yet checked. */
+const GPU_SERVES = new Set<RenderCapabilities['status']>([
+ 'available',
+ 'on-demand',
+ 'authentication-unverified',
+]);
+
+export function nextRenderRoute(renderer: RenderCapabilities): NextRenderRoute {
+ const fallback = (reason: string): NextRenderRoute['fallback'] => ({
+ active: true,
+ materialFaithful: false,
+ reason,
+ });
+ if (!renderer.configured)
+ return {
+ ready: true,
+ activeRoute: 'cpu',
+ fallback: fallback(
+ renderer.reason ??
+ (renderer.mode === 'cpu'
+ ? 'This host selected CPU rendering; views show geometry, not materials.'
+ : 'No GPU renderer is attached to this session; views show geometry, not materials.'),
+ ),
+ };
+ if (GPU_SERVES.has(renderer.status))
+ return { ready: true, activeRoute: 'gpu', fallback: { active: false } };
+ // A required GPU fails the render instead of degrading.
+ return {
+ ready: false,
+ activeRoute: 'gpu',
+ fallback: renderer.required
+ ? { active: false }
+ : fallback(
+ `GPU renderer ${renderer.status}${renderer.reason ? `: ${renderer.reason}` : ''}. Renders degrade to CPU geometry views.`,
+ ),
+ };
+}
diff --git a/src/tools/operations.ts b/src/tools/operations.ts
index 597aebce..2305b921 100644
--- a/src/tools/operations.ts
+++ b/src/tools/operations.ts
@@ -14,6 +14,7 @@ export function projectOperationDefs(
)
return [];
if (def.name === 'kiln_renderer') return rendererOperations(def, context);
+ if (def.name === 'kiln_renderer_status') return context.renderCapabilities ? [def] : [];
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);
@@ -133,20 +134,23 @@ function materialOperations(def: KilnToolDef): KilnToolDef[] {
return [search, tools.get!, create, tools.import!];
}
+/** Status is the shared read-only `kiln_renderer_status`; only reprobe derives from here. */
function rendererOperations(def: KilnToolDef, context: KilnToolContext): KilnToolDef[] {
- if (!context.renderCapabilities) return [];
- return ['status', ...(context.reprobeRenderer ? ['reprobe'] : [])].map((action) => {
- const inputSchema = z.strictObject({});
- return {
+ if (!context.renderCapabilities || !context.reprobeRenderer) return [];
+ const inputSchema = z.strictObject({});
+ return [
+ {
...def,
- name: `kiln_renderer_${action}`,
+ name: 'kiln_renderer_reprobe',
+ description:
+ 'Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.',
inputSchema,
run: async (raw: unknown) => {
inputSchema.parse(raw);
- return def.run({ action });
+ return def.run({ action: 'reprobe' });
},
- };
- });
+ },
+ ];
}
function discoveryOperations(def: KilnToolDef): KilnToolDef[] {
diff --git a/src/tools/registry.ts b/src/tools/registry.ts
index 1231b7cf..35c36742 100644
--- a/src/tools/registry.ts
+++ b/src/tools/registry.ts
@@ -75,6 +75,7 @@ import type { ViewGridResult } from '../views';
import type { EvaluatorExecutionProfileV2, EvaluatorPortV2 } from '../evaluator';
import { resolveEvaluatorPortV2 } from '../evaluator';
import { sceneNeedsPbrShading } from '../material-resources';
+import { nextRenderRoute } from '../render-route';
import { KilnDraftBuffer } from '../edit-buffer';
// `agent/diff` has no imports of its own -- it is pure string work -- so this
// does not put an agent-SDK edge into the `kiln/tools` graph.
@@ -2500,6 +2501,40 @@ function withCaptureCache(context: KilnToolContext): KilnToolContext {
const rendererInput = z.strictObject({
action: z.enum(['status', 'reprobe']).default('status'),
});
+const rendererStatusInput = z.strictObject({});
+
+/**
+ * Renderer status or reprobe for one host. Status is a read; reprobe refreshes session state,
+ * so they are advertised as separate tools (#206). Every result states the next render's route.
+ */
+async function runRenderer(
+ context: KilnToolContext,
+ action: 'status' | 'reprobe',
+): Promise<Record<string, unknown>> {
+ if (action === 'reprobe' && !context.reprobeRenderer)
+ return {
+ ok: false,
+ error:
+ 'Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true }).',
+ };
+ if (!context.renderCapabilities)
+ return {
+ ok: false,
+ error:
+ 'Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true }).',
+ };
+ try {
+ const renderer = await (action === 'reprobe'
+ ? context.reprobeRenderer!()
+ : context.renderCapabilities());
+ return { ok: true, renderer: { ...renderer, ...nextRenderRoute(renderer) } };
+ } catch (error) {
+ return {
+ ok: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+}
/** A saved-revision read whose failure names the listing call instead of a filesystem path (rule 9). */
async function readSavedRevision(
@@ -2536,39 +2571,22 @@ function createProgramDefs(
return [
createKilnDiscoveryDef({ ...suppliedContext, programStore: store }, presentation),
{
- name: 'kiln_renderer',
+ name: 'kiln_renderer_status',
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.',
- inputSchema: rendererInput,
+ 'Read renderer status: ready, activeRoute (gpu or cpu) and fallback say what the next render uses; an active fallback means CPU geometry views, not material evidence. Read-only: never reprobes, installs, starts or renders. Read viewFidelity after rendering.',
+ inputSchema: rendererStatusInput,
run: async (raw: unknown) => {
- const { action } = rendererInput.parse(raw);
- if (action === 'reprobe' && !suppliedContext.reprobeRenderer)
- return {
- ok: false,
- error:
- 'Renderer reprobe is not provided by this host. Configure its render connection through the host, or read the declared configuration with kiln_discover({ capabilities: true }).',
- };
- if (!suppliedContext.renderCapabilities)
- return {
- ok: false,
- error:
- 'Renderer status is not provided by this host. Read the declared render configuration with kiln_discover({ capabilities: true }).',
- };
- try {
- return {
- ok: true,
- renderer: await (action === 'reprobe'
- ? suppliedContext.reprobeRenderer!()
- : suppliedContext.renderCapabilities()),
- };
- } catch (error) {
- return {
- ok: false,
- error: error instanceof Error ? error.message : String(error),
- };
- }
+ rendererStatusInput.parse(raw);
+ return runRenderer(suppliedContext, 'status');
},
},
+ {
+ name: 'kiln_renderer',
+ description:
+ 'Reprobe after renderer setup/repair to refresh this session and reset failed starts; check status with kiln_renderer_status. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart.',
+ inputSchema: rendererInput,
+ run: async (raw: unknown) => runRenderer(suppliedContext, rendererInput.parse(raw).action),
+ },
...[
createKilnValidateDef(context),
createKilnRenderViewsDef(context),
@@ -2599,9 +2617,13 @@ function createProgramDefs(
.map((def) => ({
...def,
annotations: {
- readOnlyHint: ['kiln_source', 'kiln_discover', 'kiln_export', 'kiln_present'].includes(
- def.name,
- ),
+ readOnlyHint: [
+ 'kiln_source',
+ 'kiln_discover',
+ 'kiln_renderer_status',
+ 'kiln_export',
+ 'kiln_present',
+ ].includes(def.name),
destructiveHint: false,
idempotentHint: def.name !== 'kiln_save',
openWorldHint: false,
diff --git a/src/workspace-mcp.test.ts b/src/workspace-mcp.test.ts
index d9d4d92d..01e72db1 100644
--- a/src/workspace-mcp.test.ts
+++ b/src/workspace-mcp.test.ts
@@ -46,7 +46,7 @@ test('real MCP creates project materials, renders their exact closure, and expos
throw new Error(`MCP startup failed: ${errors}`, { cause: error });
}
const names = (await client.listTools()).tools.map((tool) => tool.name);
- // The fourteen program tools plus the three packaged host services (AGENTS.md).
+ // The fifteen program tools plus the three packaged host services (AGENTS.md).
expect([...names].sort()).toEqual([
'kiln_assets',
'kiln_discover',
@@ -59,6 +59,7 @@ test('real MCP creates project materials, renders their exact closure, and expos
'kiln_project',
'kiln_render',
'kiln_renderer',
+ 'kiln_renderer_status',
'kiln_review',
'kiln_save',
'kiln_screenshot_animation',