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.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(discovery): return known contracts beside unknown IDs (#218) (#232)
Matthew Kissinger8faa8ade014e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e7e6efea..59e70f94 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -83,6 +83,10 @@ does not publish a package.note naming the part and count, leaving the authored geometry and unit normals untouched.A zero-length normal fails naming the part and vertex, with `lathe`, `revolveGeo` or`creaseNormals` as the remedy.+- Discovery: when some exact IDs are unknown, the known contracts are returned in request order+ beside the `UNKNOWN_ID` error, which names only the unknown IDs; no substitution is made and+ a request with no known ID still returns no entries. `pbrMaterial` now ranks first for+ roughness-map queries (#218).## 1.3.1 (2026-10-17)diff --git a/dist/agent-run.mjs b/dist/agent-run.mjsindex 7f38e767..cded262c 100644--- a/dist/agent-run.mjs+++ b/dist/agent-run.mjs@@ -41988,7 +41988,12 @@ define2("pbrMaterial", {...materialMetadata,references: ["src/textures.ts"],aliases: ["textured PBR", "metallic roughness material"],- intents: ["bind portable material textures and scalar factors"],+ intents: [+ "bind portable material textures and scalar factors",+ "roughness map",+ "packed roughness and metalness texture",+ "apply albedo normal and roughness maps"+ ],limitations: ["CPU views do not prove texture/metalness appearance."]});define2("foliageMaterial", {@@ -44561,6 +44566,7 @@ ${JSON.stringify(current)}`}if (input.mode === "detail") {const selected = input.ids.map(select);+ let unresolved = {};const unknown = input.ids.filter((_, offset) => !selected[offset]);if (unknown.length) {const removed = unknown.flatMap((id) => {@@ -44572,12 +44578,12 @@ ${JSON.stringify(current)}`${removed.join(``)}`));const suggestions = (await ranked(unknown[0])).slice(0, 3).map(({ entry }) => entry.id);- return finish({- ...error(input.mode, "UNKNOWN_ID", `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`),- suggestions- });+ const message = `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`;+ if (selected.every((entry) => !entry))+ return finish({ ...error(input.mode, "UNKNOWN_ID", message), suggestions });+ unresolved = { error: { code: "UNKNOWN_ID", message }, suggestions };}- const requested = selected;+ const requested = selected.filter((entry) => !!entry);if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {return error(input.mode, "DUPLICATE_ID", "Each exact selector must identify a different catalog entry. A name or unprefixed slug and its canonical ID refer to the same entry.");}@@ -44598,7 +44604,9 @@ ${removed.join(`total: requested.length,nextOffset: null,...omitted.length ? { omittedIds: omitted } : {},- text: JSON.stringify(details) + (omitted.length ? `+ ...unresolved,+ text: (unresolved.error ? `${unresolved.error.message}+` : "") + JSON.stringify(details) + (omitted.length ? `Not returned, over the result size: ${omitted.join(", ")}. Fetch them with another kiln_discover ids call.` : "")});}diff --git a/dist/build.json b/dist/build.jsonindex 371581f8..135ec36e 100644--- a/dist/build.json+++ b/dist/build.json@@ -2,10 +2,10 @@"schemaVersion": 1,"entries": {"worker": {- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -40,10 +40,10 @@"bundleHash": "sha256:eb4c421782d3d96e7f4ba04072ecdca10af471d17299bc42a1e0e2fc4c54c421"},"agent-run": {- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -75,13 +75,13 @@},"target": "node","file": "agent-run.mjs",- "bundleHash": "sha256:463f1803f3cf6cbe1c33e0eba1651b012dc5b39d7afa762a7ef155780a0b31f4"+ "bundleHash": "sha256:c12f6fdb2e30e1f8694047341588c3b155ef49986322b71c9df7a9535111ae89"},"agent-providers": {- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -116,10 +116,10 @@"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"},"mcp": {- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -154,10 +154,10 @@"bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"},"cli": {- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -189,13 +189,13 @@},"target": "node","file": "cli.mjs",- "bundleHash": "sha256:75e9b3dae1ad7bfcb0bc9ce07d18d005e6720d0ee2f3fc5bbffe2bb4d364981c"+ "bundleHash": "sha256:9960552936452073bc433f715c4c032a9777a65aa4e02cb92b6ea5c45e2b62d7"},"engine": {- "identity": "sha256:87db6a4bebbd23ff45c63007ed94737db002c806798867672bc36a3932d705e5",+ "identity": "sha256:f1936abb73114537073d9061b79c903987853d21562cbc6cf0496e12ff8acb43","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "933586256ec90971162f278942bc4e5ccb37de7b4eedad01b3631a505d70cf28",+ "sourceHash": "96210a83ce55f04135f19d0ab051aadbf25f6bac5734cd783ec8e48420fd05b1","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -227,7 +227,7 @@},"target": "node","file": "mcp-engine.mjs",- "bundleHash": "sha256:00469f2fe9953b0dfb942f62d27cab9a2c0e2a5363456592ba0d1f849fd1214c"+ "bundleHash": "sha256:d80eb0c40aa1e063377c4d1a8e52753af7fb483cc2f9d09129d04bd6a288a379"}}}diff --git a/dist/cli.mjs b/dist/cli.mjsindex d2a632f0..d67c74b5 100644--- a/dist/cli.mjs+++ b/dist/cli.mjs@@ -45317,7 +45317,12 @@ var init_helper_contracts = __esm(() => {...materialMetadata,references: ["src/textures.ts"],aliases: ["textured PBR", "metallic roughness material"],- intents: ["bind portable material textures and scalar factors"],+ intents: [+ "bind portable material textures and scalar factors",+ "roughness map",+ "packed roughness and metalness texture",+ "apply albedo normal and roughness maps"+ ],limitations: ["CPU views do not prove texture/metalness appearance."]});define2("foliageMaterial", {@@ -47918,6 +47923,7 @@ ${JSON.stringify(current)}`}if (input.mode === "detail") {const selected = input.ids.map(select);+ let unresolved = {};const unknown = input.ids.filter((_, offset) => !selected[offset]);if (unknown.length) {const removed = unknown.flatMap((id) => {@@ -47929,12 +47935,12 @@ ${JSON.stringify(current)}`${removed.join(``)}`));const suggestions = (await ranked(unknown[0])).slice(0, 3).map(({ entry }) => entry.id);- return finish({- ...error(input.mode, "UNKNOWN_ID", `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`),- suggestions- });+ const message = `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`;+ if (selected.every((entry) => !entry))+ return finish({ ...error(input.mode, "UNKNOWN_ID", message), suggestions });+ unresolved = { error: { code: "UNKNOWN_ID", message }, suggestions };}- const requested = selected;+ const requested = selected.filter((entry) => !!entry);if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {return error(input.mode, "DUPLICATE_ID", "Each exact selector must identify a different catalog entry. A name or unprefixed slug and its canonical ID refer to the same entry.");}@@ -47955,7 +47961,9 @@ ${removed.join(`total: requested.length,nextOffset: null,...omitted.length ? { omittedIds: omitted } : {},- text: JSON.stringify(details) + (omitted.length ? `+ ...unresolved,+ text: (unresolved.error ? `${unresolved.error.message}+` : "") + JSON.stringify(details) + (omitted.length ? `Not returned, over the result size: ${omitted.join(", ")}. Fetch them with another kiln_discover ids call.` : "")});}diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjsindex be34a5c3..053cc5c9 100644--- a/dist/mcp-engine.mjs+++ b/dist/mcp-engine.mjs@@ -46103,7 +46103,12 @@ define2("pbrMaterial", {...materialMetadata,references: ["src/textures.ts"],aliases: ["textured PBR", "metallic roughness material"],- intents: ["bind portable material textures and scalar factors"],+ intents: [+ "bind portable material textures and scalar factors",+ "roughness map",+ "packed roughness and metalness texture",+ "apply albedo normal and roughness maps"+ ],limitations: ["CPU views do not prove texture/metalness appearance."]});define2("foliageMaterial", {@@ -48676,6 +48681,7 @@ ${JSON.stringify(current)}`}if (input.mode === "detail") {const selected = input.ids.map(select);+ let unresolved = {};const unknown = input.ids.filter((_, offset) => !selected[offset]);if (unknown.length) {const removed = unknown.flatMap((id) => {@@ -48687,12 +48693,12 @@ ${JSON.stringify(current)}`${removed.join(``)}`));const suggestions = (await ranked(unknown[0])).slice(0, 3).map(({ entry }) => entry.id);- return finish({- ...error(input.mode, "UNKNOWN_ID", `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`),- suggestions- });+ const message = `Unknown exact Discovery IDs: ${unknown.join(", ")}. Use query for suggestions; no substitutions were made.`;+ if (selected.every((entry) => !entry))+ return finish({ ...error(input.mode, "UNKNOWN_ID", message), suggestions });+ unresolved = { error: { code: "UNKNOWN_ID", message }, suggestions };}- const requested = selected;+ const requested = selected.filter((entry) => !!entry);if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {return error(input.mode, "DUPLICATE_ID", "Each exact selector must identify a different catalog entry. A name or unprefixed slug and its canonical ID refer to the same entry.");}@@ -48713,7 +48719,9 @@ ${removed.join(`total: requested.length,nextOffset: null,...omitted.length ? { omittedIds: omitted } : {},- text: JSON.stringify(details) + (omitted.length ? `+ ...unresolved,+ text: (unresolved.error ? `${unresolved.error.message}+` : "") + JSON.stringify(details) + (omitted.length ? `Not returned, over the result size: ${omitted.join(", ")}. Fetch them with another kiln_discover ids call.` : "")});}diff --git a/src/__tests__/cli-discovery.test.ts b/src/__tests__/cli-discovery.test.tsindex f30fb825..1ca03445 100644--- a/src/__tests__/cli-discovery.test.ts+++ b/src/__tests__/cli-discovery.test.ts@@ -91,7 +91,7 @@ test('CLI capabilities report the collections and program store the MCP host inj}});-test('CLI exact details preserve ordering and unknown IDs fail atomically', async () => {+test('CLI exact details preserve ordering and report unknown IDs beside known ones', async () => {const detail = await command(['--id', 'copyGeometry', '--id', 'operation:boxGeo', '--json']);expect(detail.status).toBe(0);expect(JSON.parse(detail.stdout).entries.map((entry: { name: string }) => entry.name)).toEqual([@@ -101,6 +101,11 @@ test('CLI exact details preserve ordering and unknown IDs fail atomically', asynconst unknown = await command(['--id', 'copyGeomtry', '--json']);expect(unknown.status).toBe(1);expect(JSON.parse(unknown.stdout).error.code).toBe('UNKNOWN_ID');+ const partial = await command(['--id', 'boxGeo', '--id', 'copyGeomtry', '--json']);+ expect(partial.status).toBe(1);+ const body = JSON.parse(partial.stdout);+ expect(body.error.code).toBe('UNKNOWN_ID');+ expect(body.entries.map((entry: { name: string }) => entry.name)).toEqual(['boxGeo']);});test('CLI rejects retired or contradictory selectors and exposes bounded human overview', async () => {diff --git a/src/__tests__/discovery.test.ts b/src/__tests__/discovery.test.tsindex a4c93b08..2b0af52e 100644--- a/src/__tests__/discovery.test.ts+++ b/src/__tests__/discovery.test.ts@@ -99,7 +99,8 @@ describe('progressive capability discovery', () => {})) as Result;expect(missing.error?.message).toContain('inventedMesh');expect(missing.error?.message).toContain('unknownSurface');- expect(missing.entries).toHaveLength(0);+ expect(missing.error?.message).not.toContain('boxGeo,');+ expect(missing.entries.map((entry) => entry.name)).toEqual(['boxGeo']);await expect(tool.run({ ids: ['boxGeo'], family: 'geometry' })).rejects.toThrow('alone');await expect(tool.run({ ids: Array(7).fill('boxGeo') })).rejects.toThrow();});diff --git a/src/discovery/helper-contracts.ts b/src/discovery/helper-contracts.tsindex fed0b665..978779b5 100644--- a/src/discovery/helper-contracts.ts+++ b/src/discovery/helper-contracts.ts@@ -1782,7 +1782,12 @@ define(...materialMetadata,references: ['src/textures.ts'],aliases: ['textured PBR', 'metallic roughness material'],- intents: ['bind portable material textures and scalar factors'],+ intents: [+ 'bind portable material textures and scalar factors',+ 'roughness map',+ 'packed roughness and metalness texture',+ 'apply albedo normal and roughness maps',+ ],limitations: ['CPU views do not prove texture/metalness appearance.'],},);diff --git a/src/discovery/lexical-index.test.ts b/src/discovery/lexical-index.test.tsindex 86875749..1ba82f64 100644--- a/src/discovery/lexical-index.test.ts+++ b/src/discovery/lexical-index.test.ts@@ -119,3 +119,18 @@ test('everyday object words reach the reviewed structure and material entries',?.expandedTerms ?? [],).not.toContain('cost');});++test('Cove authoring words reach welding, crease, packed-roughness and V3 shape contracts', async () => {+ // Cove quality pass (#218): each of these took several queries.+ const run = createDiscoveryService(+ entries,+ createLexicalDiscoveryIndex(entries),+ async () => ({}),+ );+ const first = async (query: string) => (await run({ query })).entries[0]?.id;+ expect(await first('weld duplicate vertices')).toBe('operation:mergeVertices');+ expect(await first('crease normals hard edges')).toBe('operation:creaseNormals');+ expect(await first('roughness map')).toBe('operation:pbrMaterial');+ expect(await first('packed roughness metalness texture')).toBe('operation:pbrMaterial');+ expect(await first('V3 texture ellipse polygon shape')).toBe('operation:proceduralTexture');+});diff --git a/src/discovery/service.test.ts b/src/discovery/service.test.tsindex 107046d4..0ff555fc 100644--- a/src/discovery/service.test.ts+++ b/src/discovery/service.test.ts@@ -83,11 +83,18 @@ test('detail resolves exact IDs and names in requested order and returns detacheexpect((await run({ ids: ['sweepProfile'] })).entries[0]!.tags).not.toContain('mutation');});-test('unknown exact names fail as a whole without silently substituting a related function', async () => {- const result = await make()({ ids: ['sweepProfile', 'sweepProfle'] });+test('unknown exact names are reported beside the known entries, never substituted', async () => {+ const result = await make()({ ids: ['copyGeometry', 'sweepProfle', 'sweepProfile'] });expect(result.error?.code).toBe('UNKNOWN_ID');- expect(result.entries).toHaveLength(0);+ expect(result.error?.message).toContain('sweepProfle');+ expect(result.error?.message).not.toContain('copyGeometry');+ expect(result.entries.map((entry) => entry.name)).toEqual(['copyGeometry', 'sweepProfile']);+ expect(result.total).toBe(2);expect(result.suggestions?.length).toBeGreaterThan(0);+ expect(result.text).toStartWith('Unknown exact Discovery IDs: sweepProfle.');+ const none = await make()({ ids: ['sweepProfle'] });+ expect(none.error?.code).toBe('UNKNOWN_ID');+ expect(none.entries).toHaveLength(0);});test('ranked search filters then paginates and never exposes numeric confidence', async () => {diff --git a/src/discovery/service.ts b/src/discovery/service.tsindex 99a00c4f..753fc296 100644--- a/src/discovery/service.ts+++ b/src/discovery/service.ts@@ -169,6 +169,7 @@ export function createDiscoveryService(}if (input.mode === 'detail') {const selected = input.ids.map(select);+ let unresolved: Pick<DiscoveryResponse, 'error' | 'suggestions'> = {};const unknown = input.ids.filter((_, offset) => !selected[offset]);if (unknown.length) {const removed = unknown.flatMap((id) => {@@ -184,16 +185,13 @@ export function createDiscoveryService(),);const suggestions = (await ranked(unknown[0]!)).slice(0, 3).map(({ entry }) => entry.id);- return finish({- ...error(- input.mode,- 'UNKNOWN_ID',- `Unknown exact Discovery IDs: ${unknown.join(', ')}. Use query for suggestions; no substitutions were made.`,- ),- suggestions,- });+ const message = `Unknown exact Discovery IDs: ${unknown.join(', ')}. Use query for suggestions; no substitutions were made.`;+ // One typo must not hide the contracts that did resolve: report it beside them.+ if (selected.every((entry) => !entry))+ return finish({ ...error(input.mode, 'UNKNOWN_ID', message), suggestions });+ unresolved = { error: { code: 'UNKNOWN_ID', message }, suggestions };}- const requested = selected as DiscoveryEntry[];+ const requested = selected.filter((entry): entry is DiscoveryEntry => !!entry);if (new Set(requested.map((entry) => entry.id)).size !== requested.length) {return error(input.mode,@@ -220,9 +218,11 @@ export function createDiscoveryService(total: requested.length,nextOffset: null,...(omitted.length ? { omittedIds: omitted } : {}),+ ...unresolved,// One JSON line: a contract is read whole, and one-line JSON costs// about a quarter fewer tokens than the indented form.text:+ (unresolved.error ? `${unresolved.error.message}\n` : '') +JSON.stringify(details) +(omitted.length? `\nNot returned, over the result size: ${omitted.join(', ')}. Fetch them with another kiln_discover ids call.`