Release v0.3.0

lib/tool-registry.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const {
@@ -22,9 +23,24 @@ const {
   searchProjectLogs,
 } = require('./logs');
 const { resolveProjectPath } = require('./path-safety');
+const {
+  createProjectSkill,
+  listProjectInstructions,
+  readProjectInstruction,
+  writeProjectInstruction,
+} = require('./project-instructions');
+const {
+  applyPrefabInstance,
+  duplicatePrefab,
+  editPrefabJson,
+  inspectPrefab,
+  revertPrefabInstance,
+  validatePrefabReferences,
+} = require('./prefabs');
 const { captureDesktopScreenshot, captureEditorWindowScreenshot, capturePanelScreenshot } = require('./screenshots');
 const { checkForUpdate } = require('./update-checker');
 const { safeStringify } = require('./utils');
+const IMAGE_DATA_URI_PREFIX = 'data:image/png;base64,';
 
 const TOOL_CATEGORY_RULES = [
   ['updates', /update/],
@@ -35,6 +51,7 @@ const TOOL_CATEGORY_RULES = [
   ['files', /file|directory|exists|refresh_assets/],
   ['assets', /asset|scene$|scenes|open_scene|run_scene_asset/],
   ['prefabs', /prefab/],
+  ['instructions', /instruction|skill/],
   ['selection', /selection|select_/],
   ['components', /component/],
   ['ui', /canvas|label|button|sprite/],
@@ -57,6 +74,34 @@ function createSchema(properties, required) {
   return schema;
 }
 
+function createOutputSchema(dataSchema = {}) {
+  return {
+    type: 'object',
+    properties: {
+      ok: { type: 'boolean', description: 'Whether the tool call completed successfully.' },
+      tool: { type: 'string', description: 'Tool name that produced this result.' },
+      callId: { type: 'string', description: 'Stable identifier for this tool call result.' },
+      timestamp: { type: 'string', description: 'ISO timestamp when the result envelope was produced.' },
+      summary: { type: 'string', description: 'Short human-readable result summary.' },
+      data: dataSchema,
+      refs: {
+        type: 'array',
+        description: 'Stable references discovered in the result for follow-up tool calls.',
+        items: {
+          type: 'object',
+          properties: {
+            type: { type: 'string' },
+            id: { type: 'string' },
+            path: { type: 'string' },
+            name: { type: 'string' },
+          },
+        },
+      },
+    },
+    required: ['ok', 'tool', 'callId', 'timestamp', 'data'],
+  };
+}
+
 function inferToolCategory(toolName) {
   for (const [category, pattern] of TOOL_CATEGORY_RULES) {
     if (pattern.test(toolName)) {
@@ -86,6 +131,26 @@ function toolCategory(tool) {
   return tool.category || inferToolCategory(tool.name);
 }
 
+function inferToolAnnotations(tool) {
+  const name = tool.name;
+  const category = toolCategory(tool);
+  const readOnly = /^(get|list|inspect|find|read|search|check|validate|exists|capture)/.test(name);
+  const destructive = /(delete|remove|clear|replace|write|reset|set_|execute|run_scene|invoke|emit|simulate)/.test(name);
+  const idempotent = readOnly || /^(set|select|open|pause|resume|stop|refresh)/.test(name);
+
+  return {
+    title: name
+      .split('_')
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join(' '),
+    readOnlyHint: readOnly,
+    destructiveHint: readOnly ? false : destructive,
+    idempotentHint: idempotent,
+    openWorldHint: category === 'updates',
+    ...(tool.annotations || {}),
+  };
+}
+
 function isToolExposed(config, tool) {
   const profile = config && config.toolProfile === 'full'
     ? 'full'
@@ -112,6 +177,115 @@ function isToolExposed(config, tool) {
   return exposed;
 }
 
+function hashObject(value) {
+  return crypto
+    .createHash('sha256')
+    .update(safeStringify(value))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function summarizeResult(result) {
+  if (typeof result === 'string') {
+    if (result.startsWith(IMAGE_DATA_URI_PREFIX)) {
+      return 'Image payload returned.';
+    }
+    return result.length > 160 ? `${result.slice(0, 160)}...` : result;
+  }
+  if (!result || typeof result !== 'object') {
+    return String(result);
+  }
+  if (typeof result.summary === 'string') {
+    return result.summary;
+  }
+  for (const key of ['message', 'path', 'url', 'sceneName', 'projectName']) {
+    if (typeof result[key] === 'string' && result[key]) {
+      return `${key}: ${result[key]}`;
+    }
+  }
+  if (Number.isFinite(result.count)) {
+    return `count: ${result.count}`;
+  }
+  return 'Structured result returned.';
+}
+
+function normalizeEnvelopeData(result) {
+  if (typeof result === 'string' && result.startsWith(IMAGE_DATA_URI_PREFIX)) {
+    return {
+      image: true,
+      mimeType: 'image/png',
+      byteLength: Buffer.byteLength(result.slice(IMAGE_DATA_URI_PREFIX.length), 'base64'),
+    };
+  }
+  return result;
+}
+
+function addRef(refs, type, id, extra = {}) {
+  if (!id) {
+    return;
+  }
+  const key = `${type}:${id}`;
+  if (refs.some((ref) => ref.key === key)) {
+    return;
+  }
+  refs.push({ key, type, id: String(id), ...extra });
+}
+
+function collectRefs(value, refs = [], depth = 0, seen = new WeakSet()) {
+  if (!value || depth > 5) {
+    return refs;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectRefs(item, refs, depth + 1, seen);
+    }
+    return refs;
+  }
+  if (typeof value !== 'object') {
+    return refs;
+  }
+  if (seen.has(value)) {
+    return refs;
+  }
+  seen.add(value);
+
+  const uuid = value.uuid || value.prefabUuid || value.sceneUuid || value.assetUuid;
+  const pathValue = value.path || value.node || value.url;
+  if (uuid) {
+    addRef(refs, pathValue && String(pathValue).startsWith('db://') ? 'asset' : 'uuid', uuid, {
+      path: pathValue ? String(pathValue) : undefined,
+      name: value.name ? String(value.name) : undefined,
+    });
+  }
+  if (typeof pathValue === 'string' && pathValue) {
+    addRef(refs, pathValue.startsWith('db://') ? 'asset' : 'path', pathValue, {
+      name: value.name ? String(value.name) : undefined,
+    });
+  }
+
+  for (const item of Object.values(value)) {
+    collectRefs(item, refs, depth + 1, seen);
+  }
+  return refs;
+}
+
+function createResultEnvelope(tool, args, result, options = {}) {
+  const data = normalizeEnvelopeData(result);
+  const refs = collectRefs(data).map(({ key, ...ref }) => ref);
+  const timestamp = new Date().toISOString();
+  const summary = options.summary || summarizeResult(result);
+  const callId = `fp_${hashObject({ tool: tool.name, args: args || {}, result: data })}`;
+  return {
+    ok: options.ok !== false,
+    tool: tool.name,
+    callId,
+    timestamp,
+    summary,
+    data,
+    refs,
+  };
+}
+
 function summarizeDiagnostics(result) {
   if (!result) {
     return null;
@@ -217,6 +391,17 @@ async function refreshAssets(projectPath, targetPath) {
   return 'File written outside assets directory; no asset-db refresh was needed.';
 }
 
+async function resolveNodeUuid(sceneBridge, args) {
+  if (args && args.uuid) {
+    return String(args.uuid);
+  }
+  const inspected = await sceneBridge.call('inspectNode', args || {});
+  if (!inspected || !inspected.uuid) {
+    throw new Error('Target node uuid could not be resolved.');
+  }
+  return inspected.uuid;
+}
+
 function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runtimeLog, sceneBridge, editorExecutor }) {
   const tools = [
     {
@@ -351,6 +536,67 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
       inputSchema: createSchema({}, []),
       handler: async () => getCurrentSelection(),
     },
+    {
+      name: 'list_project_instructions',
+      profile: 'core',
+      description: '[specialist] List project AI instruction files and local Codex project skills.',
+      inputSchema: createSchema({}, []),
+      handler: async () => {
+        const { projectPath } = getRuntimeContext();
+        return listProjectInstructions(projectPath);
+      },
+    },
+    {
+      name: 'read_project_instruction',
+      profile: 'core',
+      description: '[specialist] Read a project AI instruction file such as AGENTS.md, CLAUDE.md, or a .codex skill SKILL.md.',
+      inputSchema: createSchema(
+        {
+          target: { type: 'string', description: 'Project-relative instruction path.' },
+        },
+        ['target']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        return readProjectInstruction(projectPath, args.target);
+      },
+    },
+    {
+      name: 'write_project_instruction',
+      profile: 'full',
+      description: '[core] Create or update a project AI instruction file inside the Cocos project.',
+      inputSchema: createSchema(
+        {
+          target: { type: 'string', description: 'Project-relative instruction path.' },
+          content: { type: 'string', description: 'Instruction file content.' },
+          overwrite: { type: 'boolean', description: 'Allow overwriting an existing file. Defaults to true.' },
+        },
+        ['target', 'content']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        return writeProjectInstruction(projectPath, args);
+      },
+    },
+    {
+      name: 'create_project_skill',
+      profile: 'full',
+      description: '[core] Create a local Codex project skill under .codex/skills/{skillName}/SKILL.md.',
+      inputSchema: createSchema(
+        {
+          skillName: { type: 'string', description: 'Filesystem-safe project skill name.' },
+          title: { type: 'string', description: 'Human-readable skill title.' },
+          description: { type: 'string', description: 'Skill trigger description.' },
+          instructions: { type: 'string', description: 'Skill instructions body.' },
+          overwrite: { type: 'boolean', description: 'Allow overwriting an existing skill. Defaults to true.' },
+        },
+        ['skillName']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        return createProjectSkill(projectPath, args);
+      },
+    },
     {
       name: 'set_selection',
       profile: 'core',
@@ -537,6 +783,166 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
         return { count: assets.length, prefabs: assets.slice(0, 200) };
       },
     },
+    {
+      name: 'inspect_prefab',
+      profile: 'core',
+      description: '[specialist] Inspect a prefab asset, its metadata, serialized file path, and UUID-like asset references.',
+      inputSchema: createSchema(
+        {
+          target: { type: 'string', description: 'Prefab uuid, db url, or project path.' },
+        },
+        ['target']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        return await inspectPrefab(projectPath, args.target);
+      },
+    },
+    {
+      name: 'validate_prefab_references',
+      profile: 'core',
+      description: '[specialist] Validate prefab asset references by checking serialized UUID references against asset-db.',
+      inputSchema: createSchema(
+        {
+          target: { type: 'string', description: 'Optional prefab uuid, db url, or path. When omitted, scans prefab assets.' },
+          pattern: { type: 'string', description: 'Optional asset-db pattern used when scanning prefabs.' },
+          limit: { type: 'number', description: 'Maximum prefab assets to scan when target is omitted.' },
+        },
+        []
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        return await validatePrefabReferences(projectPath, args);
+      },
+    },
+    {
+      name: 'duplicate_prefab',
+      profile: 'full',
+      description: '[core] Create a new prefab asset by duplicating an existing prefab file without copying its .meta UUID.',
+      inputSchema: createSchema(
+        {
+          source: { type: 'string', description: 'Source prefab uuid, db url, or project path.' },
+          target: { type: 'string', description: 'Project-relative target path under assets, with or without .prefab.' },
+          overwrite: { type: 'boolean', description: 'Overwrite target prefab if it already exists.' },
+        },
+        ['source', 'target']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const result = await duplicatePrefab(projectPath, args);
+        return { ...result, refresh: await refreshAssets(projectPath, resolveProjectPath(projectPath, result.target)) };
+      },
+    },
+    {
+      name: 'edit_prefab_json',
+      profile: 'full',
+      description: '[core] Edit a prefab JSON file by JSON path assignment or literal search/replace, then validate references.',
+      inputSchema: createSchema(
+        {
+          target: { type: 'string', description: 'Prefab uuid, db url, or project path.' },
+          jsonPath: { type: 'string', description: 'JSON path such as /0/_name or 0._name when assigning valueJson.' },
+          valueJson: { type: 'string', description: 'JSON encoded value to assign at jsonPath.' },
+          search: { type: 'string', description: 'Literal text to search for instead of jsonPath assignment.' },
+          replace: { type: 'string', description: 'Replacement text for literal search.' },
+          replaceAll: { type: 'boolean', description: 'Replace all literal matches.' },
+          createBackup: { type: 'boolean', description: 'Create a .bak file before writing.' },
+        },
+        ['target']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const result = await editPrefabJson(projectPath, args);
+        return { ...result, refresh: await refreshAssets(projectPath, resolveProjectPath(projectPath, result.path)) };
+      },
+    },
+    {
+      name: 'create_prefab_instance',
+      profile: 'full',
+      description: '[core] Create a linked prefab instance in the editor hierarchy using Cocos scene create-node when available.',
+      inputSchema: createSchema(
+        {
+          prefabUuid: { type: 'string', description: 'Prefab asset uuid, db url, or path.' },
+          parentPath: { type: 'string', description: 'Optional parent node path.' },
+          name: { type: 'string', description: 'Optional override node name.' },
+          position: { type: 'object', description: 'Optional position {x,y,z}; fallback runtime path only.' },
+        },
+        ['prefabUuid']
+      ),
+      handler: async (args) => {
+        const info = await queryAssetInfo(args.prefabUuid);
+        const payload = {
+          assetUuid: info.uuid || args.prefabUuid,
+          unlinkPrefab: false,
+        };
+        if (args.parentPath) {
+          payload.parent = await resolveNodeUuid(sceneBridge, { path: args.parentPath });
+        }
+        if (args.name) {
+          payload.name = args.name;
+        }
+
+        if (global.Editor && Editor.Message && typeof Editor.Message.request === 'function') {
+          try {
+            const createdUuid = await Editor.Message.request('scene', 'create-node', payload);
+            return {
+              created: true,
+              linkedPrefab: true,
+              prefabUuid: payload.assetUuid,
+              uuid: createdUuid,
+            };
+          } catch (error) {
+            runtimeLog && runtimeLog.add('warn', `Linked prefab create-node failed: ${error.message}`);
+          }
+        }
+
+        return await sceneBridge.call('instantiatePrefab', {
+          ...args,
+          prefabUuid: info.uuid || args.prefabUuid,
+        });
+      },
+    },
+    {
+      name: 'inspect_prefab_instance',
+      profile: 'core',
+      description: '[specialist] Inspect whether a scene node is linked to a prefab instance and return prefab metadata when available.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Node hierarchy path.' },
+          uuid: { type: 'string', description: 'Node uuid.' },
+          name: { type: 'string', description: 'Fallback exact node name.' },
+        },
+        []
+      ),
+      handler: async (args) => sceneBridge.call('getPrefabInstanceInfo', args),
+    },
+    {
+      name: 'apply_prefab_instance',
+      profile: 'full',
+      description: '[core] Apply a scene prefab instance back to its associated prefab asset using the Cocos editor scene apply-prefab message.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Node hierarchy path.' },
+          uuid: { type: 'string', description: 'Node uuid.' },
+          name: { type: 'string', description: 'Fallback exact node name.' },
+        },
+        []
+      ),
+      handler: async (args) => await applyPrefabInstance(await resolveNodeUuid(sceneBridge, args)),
+    },
+    {
+      name: 'revert_prefab_instance',
+      profile: 'full',
+      description: '[core] Revert a scene prefab instance from its associated prefab asset using available Cocos editor prefab revert messages.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Node hierarchy path.' },
+          uuid: { type: 'string', description: 'Node uuid.' },
+          name: { type: 'string', description: 'Fallback exact node name.' },
+        },
+        []
+      ),
+      handler: async (args) => await revertPrefabInstance(await resolveNodeUuid(sceneBridge, args)),
+    },
     {
       name: 'instantiate_prefab',
       profile: 'full',
@@ -1242,6 +1648,7 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
           includeComponents: true,
         }).catch((error) => ({ ok: false, error: error.message }));
         const runtime = await sceneBridge.call('getRuntimeState', {}).catch((error) => ({ ok: false, error: error.message }));
+        const performance = await sceneBridge.call('getPerformanceSnapshot', {}).catch((error) => ({ ok: false, error: error.message }));
         const diagnostics = args.includeScriptDiagnostics === false
           ? null
           : summarizeDiagnostics(await runScriptDiagnostics(projectPath, args).catch((error) => ({ ok: false, summary: error.message, diagnostics: [] })));
@@ -1250,14 +1657,22 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
           : searchProjectLogs(projectPath, { query: 'error', limit: 20 }).matches;
 
         return {
-          ok: !scene.error && !runtime.error && (!diagnostics || diagnostics.ok) && (!logErrors || logErrors.length === 0),
+          ok: !scene.error && !runtime.error && !performance.error && (!diagnostics || diagnostics.ok) && (!logErrors || logErrors.length === 0),
           scene,
           runtime,
+          performance,
           diagnostics,
           logErrors,
         };
       },
     },
+    {
+      name: 'get_performance_snapshot',
+      profile: 'core',
+      description: '[specialist] Return scene scale and runtime performance-oriented counters such as node/component counts, UI counts, depth, memory, and warnings.',
+      inputSchema: createSchema({}, []),
+      handler: async (args) => sceneBridge.call('getPerformanceSnapshot', args),
+    },
     {
       name: 'get_runtime_state',
       profile: 'core',
@@ -1580,6 +1995,8 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
           name: tool.name,
           description: tool.description,
           inputSchema: tool.inputSchema,
+          outputSchema: tool.outputSchema || createOutputSchema(tool.dataSchema),
+          annotations: inferToolAnnotations(tool),
         }));
     },
     listToolCatalog() {
@@ -1589,6 +2006,8 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
         description: tool.description,
         profile: tool.profile,
         category: toolCategory(tool),
+        annotations: inferToolAnnotations(tool),
+        outputSchema: tool.outputSchema || createOutputSchema(tool.dataSchema),
         enabled: isToolExposed(config || {}, tool),
       }));
     },
@@ -1604,14 +2023,21 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
 
       try {
         const result = await tool.handler(args || {});
-        const output = toOutput(result);
-        interactionLog.add(name, 'success', output.slice(0, 500));
+        const envelope = createResultEnvelope(tool, args || {}, result);
+        const output = typeof result === 'string' && result.startsWith(IMAGE_DATA_URI_PREFIX)
+          ? result
+          : toOutput(envelope);
+        interactionLog.add(name, 'success', envelope.summary.slice(0, 500));
         return {
-          value: result,
+          value: envelope,
           text: output,
         };
       } catch (error) {
         interactionLog.add(name, 'error', error.message);
+        error.toolEnvelope = createResultEnvelope(tool, args || {}, { message: error.message }, {
+          ok: false,
+          summary: error.message,
+        });
         throw error;
       }
     },