@instruktlabs/kiln 1.1.0 → 1.2.0

package/src/tools/operation-contract.ts

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

package/src/tools/operations.ts

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

package/src/tools/registry.ts

@@ -24,6 +24,8 @@ import { createKilnMaterialDef } from './materials';
 import { createKilnReviewDef, type ReviewStore } from './review';
 import { withWorkspaceContext } from './workspace';
 import { describeInputError } from './actions';
+import { projectOperationDefs } from './operations';
+import type { KilnActionContract } from './operation-contract';
 import {
   advancedCaptureInput,
   cameraShotInput,
@@ -94,6 +96,8 @@ import type { TextureUsage } from '../textures';
 
 export const KILN_ASSET_WIDGET_URI = 'ui://kiln/asset-v5.html';
 export interface KilnToolDef {
+  /** Shared action ownership and requirements; never hand-maintained by transports. */
+  actionContract?: Readonly<Record<string, import('./operation-contract').KilnActionContract>>;
   outputSchema?: z.ZodType;
   /** Optional MCP App presentation; metadata is hidden from the language model. */
   ui?: {
@@ -2498,13 +2502,14 @@ async function readSavedRevision(
   collection: string,
   assetId: string,
   revisionId: string,
+  listCall = `kiln_assets { action: 'list', collection: '${collection}' }`,
 ) {
   try {
     return await target.read(collection, assetId, revisionId);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT')
       throw new Error(
-        `Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. kiln_assets { action: 'list', collection: '${collection}' } lists the saved revisions.`,
+        `Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. ${listCall} lists the saved revisions.`,
       );
     throw error;
   }
@@ -2512,12 +2517,19 @@ async function readSavedRevision(
 
 export function createKilnProgramToolRegistry(
   suppliedContext: KilnToolContext = {},
+): KilnToolDef[] {
+  return createProgramDefs(suppliedContext, 'grouped');
+}
+
+function createProgramDefs(
+  suppliedContext: KilnToolContext,
+  presentation: 'grouped' | 'operations',
 ): KilnToolDef[] {
   toolRequirements(suppliedContext);
   const store = suppliedContext.programStore ?? new MemoryProgramStore();
   const context = withCaptureCache(withBuildCache({ ...suppliedContext, programStore: store }));
   return [
-    createKilnDiscoveryDef({ ...suppliedContext, programStore: store }),
+    createKilnDiscoveryDef({ ...suppliedContext, programStore: store }, presentation),
     {
       name: 'kiln_renderer',
       description:
@@ -2564,7 +2576,9 @@ export function createKilnProgramToolRegistry(
     ...(context.projectStore
       ? [createKilnProjectDef(context.projectStore, context.projectBundleReader)]
       : []),
-    ...(context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary)] : []),
+    ...(context.materialLibrary
+      ? [createKilnMaterialDef(context.materialLibrary, presentation)]
+      : []),
     ...(context.reviewStore && context.assetLibrary
       ? [
           createKilnReviewDef({
@@ -2574,7 +2588,7 @@ export function createKilnProgramToolRegistry(
           }),
         ]
       : []),
-    ...createKilnAssetDefs({ ...context, programStore: store }),
+    ...createKilnAssetDefs({ ...context, programStore: store }, presentation),
   ]
     .map((def) => withWorkspaceContext(def, context))
     .map((def) => ({
@@ -2591,6 +2605,11 @@ export function createKilnProgramToolRegistry(
     }));
 }
 
+/** Opt-in named domain operations; grouped local/native contracts remain unchanged. */
+export function createKilnOperationToolRegistry(context: KilnToolContext = {}): KilnToolDef[] {
+  return projectOperationDefs(createProgramDefs(context, 'operations'), context);
+}
+
 /** Canonical native workflow: shared definitions plus one host-owned terminal. */
 export function createKilnNativeToolRegistry(
   suppliedContext: KilnToolContext,
@@ -2686,6 +2705,36 @@ const assetSelector = {
   revisionId: z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
 };
 
+const ASSET_CONTRACT = {
+  collections: {
+    fields: [],
+    required: [],
+    description: 'List configured asset storage collections. Collection is not project membership.',
+  },
+  catalog: {
+    fields: ['assetId', 'query', 'offset', 'limit'],
+    required: [],
+    description: 'Search saved assets across configured collections with pagination.',
+  },
+  list: {
+    fields: ['collection', 'assetId', 'query', 'offset', 'limit'],
+    required: [],
+    description: 'Search saved assets in one collection with pagination.',
+  },
+  get: {
+    fields: ['collection', 'assetId', 'revisionId'],
+    required: ['assetId'],
+    description:
+      'Read a saved revision and its download descriptors. Omit revisionId for the newest revision.',
+  },
+  restore: {
+    fields: ['collection', 'assetId', 'revisionId'],
+    required: ['assetId'],
+    description:
+      'Restore exact saved source as programRef for editing or rendering. Omit revisionId for the newest revision. Does not overwrite the saved revision. Binary-only assets have no source.',
+  },
+} satisfies Record<string, KilnActionContract>;
+
 /**
  * The revision a get or restore without `revisionId` means: the newest, the
  * one no later revision names as its parent, ties to the latest `createdAt`
@@ -2701,12 +2750,11 @@ export async function newestRevision(
   },
   collection: string,
   assetId: string,
+  listCall = `kiln_assets { action: 'list', collection: '${collection}' }`,
 ): Promise<string> {
   const revisions = (await target.list(collection)).filter((a) => a.assetId === assetId);
   if (!revisions.length)
-    throw new Error(
-      `Unknown asset ${assetId} in ${collection}; kiln_assets { action: 'list', collection: '${collection}' } lists them.`,
-    );
+    throw new Error(`Unknown asset ${assetId} in ${collection}; ${listCall} lists them.`);
   const parents = new Set(revisions.map((a) => a.parentRevision).filter(Boolean));
   const heads = revisions.filter((a) => !parents.has(a.revisionId));
   const newest = (heads.length ? heads : revisions).sort((a, b) =>
@@ -2797,7 +2845,23 @@ export async function buildProgramAssetDraft(
 }
 
 /** All asset operation schemas live here, alongside the existing tool definitions. */
-export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
+export function createKilnAssetDefs(
+  context: KilnToolContext,
+  presentation: 'grouped' | 'operations' = 'grouped',
+): KilnToolDef[] {
+  const listCall = (collection: string) =>
+    presentation === 'operations'
+      ? `kiln_assets_search({ collection: '${collection}' })`
+      : `kiln_assets { action: 'list', collection: '${collection}' }`;
+  const selector =
+    presentation === 'operations'
+      ? {
+          ...assetSelector,
+          collection: assetSelector.collection.describe(
+            'Collection ID from kiln_assets_collections; default project.',
+          ),
+        }
+      : assetSelector;
   const library = () => {
     if (!context.assetLibrary)
       throw new Error(
@@ -2828,11 +2892,11 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
     downloadUrls: await context.assetDownloadUrls?.(collection, asset.assetId, asset.revisionId),
   });
   const saveInput = z.object({
-    collection: assetSelector.collection,
+    collection: selector.collection,
     programRef: z.string(),
     name: z.string().min(1).max(200),
-    assetId: assetSelector.assetId.optional(),
-    parentRevision: assetSelector.revisionId.optional(),
+    assetId: selector.assetId.optional(),
+    parentRevision: selector.revisionId.optional(),
     tags: z.array(z.string().max(80)).max(30).optional(),
     brief: z.string().max(8000).optional(),
     description: z.string().max(4000).optional(),
@@ -2850,16 +2914,16 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
   });
   const assetsInput = z.object({
     action: z.enum(['collections', 'catalog', 'list', 'get', 'restore']).default('list'),
-    collection: assetSelector.collection,
-    assetId: assetSelector.assetId.optional(),
-    revisionId: assetSelector.revisionId
+    collection: selector.collection,
+    assetId: selector.assetId.optional(),
+    revisionId: selector.revisionId
       .optional()
       .describe('get, restore: the saved revision; omitted, the newest.'),
     query: z.string().max(200).optional(),
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(50).default(20),
   });
-  const exportInput = z.object(assetSelector);
+  const exportInput = z.object(selector);
   const profileExportInput = exportInput.extend({
     profile: z
       .enum(['editable', 'runtime'])
@@ -2869,8 +2933,8 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
       ),
   });
   const importInput = z.object({
-    ...assetSelector,
-    sourceCollection: assetSelector.collection,
+    ...selector,
+    sourceCollection: selector.collection,
   });
   return [
     {
@@ -2892,6 +2956,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
             input.collection,
             input.assetId,
             input.parentRevision,
+            listCall(input.collection),
           );
           assertSavedRequirementsAuthorized(previous.manifest, activeRequirements);
         }
@@ -2908,6 +2973,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
       description:
         'Browse saved assets: collections discovers storage; catalog searches all configured collections; list searches one. Both searches paginate. get returns a build record/downloads; restore loads exact source for kiln_source/kiln_edit. Collection is not project membership. Binary-only assets cannot restore source.',
       inputSchema: assetsInput,
+      actionContract: ASSET_CONTRACT,
       run: async (raw) => {
         const input = assetsInput.parse(raw);
         const activeRequirements = toolRequirements(context);
@@ -2961,13 +3027,25 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
             })),
           };
         }
-        if (!input.assetId)
+        if (ASSET_CONTRACT[input.action].required.some((field) => !input[field as 'assetId']))
           throw new Error(
             `kiln_assets ${input.action} requires assetId; kiln_assets { action: 'list', collection: '${input.collection}' } lists them.`,
           );
         const revisionId =
-          input.revisionId ?? (await newestRevision(target, input.collection, input.assetId));
-        const record = await readSavedRevision(target, input.collection, input.assetId, revisionId);
+          input.revisionId ??
+          (await newestRevision(
+            target,
+            input.collection,
+            input.assetId!,
+            listCall(input.collection),
+          ));
+        const record = await readSavedRevision(
+          target,
+          input.collection,
+          input.assetId!,
+          revisionId,
+          listCall(input.collection),
+        );
         if (input.action === 'get') return links(input.collection, record.manifest);
         const saved = assertSavedRequirementsAuthorized(record.manifest, activeRequirements);
         const code = record.files['source.kiln.js'];
@@ -3059,6 +3137,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
           input.collection,
           input.assetId,
           input.revisionId,
+          listCall(input.collection),
         );
         const { inspectDrawDiagnostics } = await import('../draw-diagnostics');
         if (input.profile === 'runtime') {
@@ -3102,6 +3181,7 @@ export function createKilnAssetDefs(context: KilnToolContext): KilnToolDef[] {
           input.sourceCollection,
           input.assetId,
           input.revisionId,
+          listCall(input.sourceCollection),
         );
         await target.import(input.collection, [record]);
         return links(input.collection, record.manifest);