@imgly/codesign-mcp 0.1.5 → 0.1.6

package/dist/test/vitest.config.js

@@ -1,7 +1,7 @@
 import { defineConfig } from 'vitest/config';
 export default defineConfig({
     test: {
-        include: ['test/**/*.test.ts'],
+        include: ['test/**/*.test.ts', 'scripts/**/*.test.ts'],
         typecheck: { tsconfig: './tsconfig.test.json' }
     }
 });

package/dist/test/vitest.config.js.map

@@ -1 +1 @@
-{"version":3,"file":"vitest.config.js","sourceRoot":"","sources":["../../vitest.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE;QACJ,OAAO,EAAE,CAAC,mBAAmB,CAAC;QAC9B,SAAS,EAAE,EAAE,QAAQ,EAAE,sBAAsB,EAAE;KAChD;CACF,CAAC,CAAC","sourcesContent":["import { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n  test: {\n    include: ['test/**/*.test.ts'],\n    typecheck: { tsconfig: './tsconfig.test.json' }\n  }\n});\n"]}
+{"version":3,"file":"vitest.config.js","sourceRoot":"","sources":["../../vitest.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE;QACJ,OAAO,EAAE,CAAC,mBAAmB,EAAE,sBAAsB,CAAC;QACtD,SAAS,EAAE,EAAE,QAAQ,EAAE,sBAAsB,EAAE;KAChD;CACF,CAAC,CAAC","sourcesContent":["import { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n  test: {\n    include: ['test/**/*.test.ts', 'scripts/**/*.test.ts'],\n    typecheck: { tsconfig: './tsconfig.test.json' }\n  }\n});\n"]}

package/dist/tools/asset-generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asset-generate.d.ts","sourceRoot":"","sources":["../../src/tools/asset-generate.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AA+BzD,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,aAAa,CAAC;IACvB,EAAE,EAAE,WAAW,CAAC;IAChB,sEAAsE;IACtE,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAgBD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,8BAA8B,GACnC,2BAA2B,CAkE7B"}
+{"version":3,"file":"asset-generate.d.ts","sourceRoot":"","sources":["../../src/tools/asset-generate.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAgCzD,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,aAAa,CAAC;IACvB,EAAE,EAAE,WAAW,CAAC;IAChB,sEAAsE;IACtE,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAQD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,8BAA8B,GACnC,2BAA2B,CAkE7B"}

package/dist/tools/asset-generate.js

@@ -7,6 +7,7 @@
 //
 // Phase 1 supports `kind: 'image'` only.
 import { GatewayDisabledError } from '../gateway/types.js';
+import { shortHash } from '../workspace/content-hash.js';
 const DESCRIPTION = [
     'Generate an image asset via the IMG.LY gateway. Writes the asset into the workspace at `assets/<sha>.png`.',
     '',
@@ -27,14 +28,6 @@ const ASSET_INPUT_SCHEMA = {
     required: ['kind', 'prompt'],
     additionalProperties: false
 };
-async function shortHash(bytes) {
-    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
-    const view = new Uint8Array(digest);
-    let hex = '';
-    for (let i = 0; i < 6; i++)
-        hex += view[i].toString(16).padStart(2, '0');
-    return hex;
-}
 function extFor(mime) {
     if (mime === 'image/jpeg')
         return 'jpg';

package/dist/tools/asset-generate.js.map

@@ -1 +1 @@
-{"version":3,"file":"asset-generate.js","sourceRoot":"","sources":["../../src/tools/asset-generate.ts"],"names":[],"mappings":"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","sourcesContent":["//\n// `asset_generate` — calls the gateway, persists the asset bytes into the\n// workspace at `assets/<sha>.<ext>`, and returns `{ uri, httpUrl, mimeType,\n// bytes }`. `uri` is the durable `workspace://` handle to embed in subsequent\n// `edit` calls (CE.SDK resolves it via the `/r/` route at fetch time);\n// `httpUrl` is a fetch link for opening the asset directly.\n//\n// Phase 1 supports `kind: 'image'` only.\n\nimport { type GatewayClient, GatewayDisabledError } from '../gateway/types.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\n\ninterface AssetGenerateArgs {\n  kind: 'image' | 'video' | 'audio';\n  prompt: string;\n  width?: number;\n  height?: number;\n}\n\nconst DESCRIPTION = [\n  'Generate an image asset via the IMG.LY gateway. Writes the asset into the workspace at `assets/<sha>.png`.',\n  '',\n  'Returns JSON: `{ uri, httpUrl, mimeType, bytes }`. `uri` (a `workspace://` URI) is the durable handle — embed it in subsequent `edit` calls. `httpUrl` is a fetch link for opening the asset now.',\n  '',\n  \"Phase 1 supports `kind: 'image'` only; video/audio land in Phase 4.\",\n  '',\n  \"On Local: requires `API_KEY` env. On Hosted: cost-gated via Clerk; an actionable error tells you when it's disabled for your workspace.\"\n].join('\\n');\n\nconst ASSET_INPUT_SCHEMA = {\n  type: 'object' as const,\n  properties: {\n    kind: { enum: ['image', 'video', 'audio'] },\n    prompt: { type: 'string' as const },\n    width: { type: 'integer' as const, minimum: 64 },\n    height: { type: 'integer' as const, minimum: 64 }\n  },\n  required: ['kind', 'prompt'],\n  additionalProperties: false\n};\n\nexport interface CreateAssetGenerateToolOptions {\n  gateway: GatewayClient;\n  fs: WorkspaceFS;\n  /** Builds the `httpUrl` for the generated asset (the `/r/` route). */\n  urlBuilder: ViewerUrlBuilder;\n}\n\nasync function shortHash(bytes: Uint8Array): Promise<string> {\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);\n  const view = new Uint8Array(digest);\n  let hex = '';\n  for (let i = 0; i < 6; i++) hex += view[i].toString(16).padStart(2, '0');\n  return hex;\n}\n\nfunction extFor(mime: string): string {\n  if (mime === 'image/jpeg') return 'jpg';\n  if (mime === 'image/webp') return 'webp';\n  return 'png';\n}\n\nexport function createAssetGenerateTool(\n  opts: CreateAssetGenerateToolOptions\n): CodesignMcpToolRegistration {\n  return {\n    name: 'asset_generate',\n    description: DESCRIPTION,\n    inputSchema: ASSET_INPUT_SCHEMA,\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as Partial<AssetGenerateArgs>;\n      if (typeof args.prompt !== 'string' || !args.prompt) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'asset_generate: `prompt` (string) is required.'\n            }\n          ]\n        };\n      }\n      if (args.kind !== 'image') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: `asset_generate: kind=${args.kind} is deferred to Phase 4.`\n            }\n          ]\n        };\n      }\n      try {\n        const out = await opts.gateway.generateImage({\n          prompt: args.prompt,\n          width: args.width,\n          height: args.height\n        });\n        const sha = await shortHash(out.bytes);\n        const ext = extFor(out.mimeType);\n        const relPath = `assets/${sha}.${ext}`;\n        await opts.fs.writeFile(relPath, out.bytes);\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                uri: `workspace://${relPath}`,\n                httpUrl: await opts.urlBuilder.forDownload(relPath),\n                mimeType: out.mimeType,\n                bytes: out.bytes.byteLength\n              })\n            }\n          ]\n        };\n      } catch (err) {\n        const msg =\n          err instanceof GatewayDisabledError\n            ? err.message\n            : err instanceof Error\n              ? err.message\n              : String(err);\n        return {\n          isError: true,\n          content: [{ type: 'text' as const, text: `asset_generate: ${msg}` }]\n        };\n      }\n    }\n  };\n}\n"]}
+{"version":3,"file":"asset-generate.js","sourceRoot":"","sources":["../../src/tools/asset-generate.ts"],"names":[],"mappings":"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","sourcesContent":["//\n// `asset_generate` — calls the gateway, persists the asset bytes into the\n// workspace at `assets/<sha>.<ext>`, and returns `{ uri, httpUrl, mimeType,\n// bytes }`. `uri` is the durable `workspace://` handle to embed in subsequent\n// `edit` calls (CE.SDK resolves it via the `/r/` route at fetch time);\n// `httpUrl` is a fetch link for opening the asset directly.\n//\n// Phase 1 supports `kind: 'image'` only.\n\nimport { type GatewayClient, GatewayDisabledError } from '../gateway/types.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport { shortHash } from '../workspace/content-hash.js';\n\ninterface AssetGenerateArgs {\n  kind: 'image' | 'video' | 'audio';\n  prompt: string;\n  width?: number;\n  height?: number;\n}\n\nconst DESCRIPTION = [\n  'Generate an image asset via the IMG.LY gateway. Writes the asset into the workspace at `assets/<sha>.png`.',\n  '',\n  'Returns JSON: `{ uri, httpUrl, mimeType, bytes }`. `uri` (a `workspace://` URI) is the durable handle — embed it in subsequent `edit` calls. `httpUrl` is a fetch link for opening the asset now.',\n  '',\n  \"Phase 1 supports `kind: 'image'` only; video/audio land in Phase 4.\",\n  '',\n  \"On Local: requires `API_KEY` env. On Hosted: cost-gated via Clerk; an actionable error tells you when it's disabled for your workspace.\"\n].join('\\n');\n\nconst ASSET_INPUT_SCHEMA = {\n  type: 'object' as const,\n  properties: {\n    kind: { enum: ['image', 'video', 'audio'] },\n    prompt: { type: 'string' as const },\n    width: { type: 'integer' as const, minimum: 64 },\n    height: { type: 'integer' as const, minimum: 64 }\n  },\n  required: ['kind', 'prompt'],\n  additionalProperties: false\n};\n\nexport interface CreateAssetGenerateToolOptions {\n  gateway: GatewayClient;\n  fs: WorkspaceFS;\n  /** Builds the `httpUrl` for the generated asset (the `/r/` route). */\n  urlBuilder: ViewerUrlBuilder;\n}\n\nfunction extFor(mime: string): string {\n  if (mime === 'image/jpeg') return 'jpg';\n  if (mime === 'image/webp') return 'webp';\n  return 'png';\n}\n\nexport function createAssetGenerateTool(\n  opts: CreateAssetGenerateToolOptions\n): CodesignMcpToolRegistration {\n  return {\n    name: 'asset_generate',\n    description: DESCRIPTION,\n    inputSchema: ASSET_INPUT_SCHEMA,\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as Partial<AssetGenerateArgs>;\n      if (typeof args.prompt !== 'string' || !args.prompt) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'asset_generate: `prompt` (string) is required.'\n            }\n          ]\n        };\n      }\n      if (args.kind !== 'image') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: `asset_generate: kind=${args.kind} is deferred to Phase 4.`\n            }\n          ]\n        };\n      }\n      try {\n        const out = await opts.gateway.generateImage({\n          prompt: args.prompt,\n          width: args.width,\n          height: args.height\n        });\n        const sha = await shortHash(out.bytes);\n        const ext = extFor(out.mimeType);\n        const relPath = `assets/${sha}.${ext}`;\n        await opts.fs.writeFile(relPath, out.bytes);\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                uri: `workspace://${relPath}`,\n                httpUrl: await opts.urlBuilder.forDownload(relPath),\n                mimeType: out.mimeType,\n                bytes: out.bytes.byteLength\n              })\n            }\n          ]\n        };\n      } catch (err) {\n        const msg =\n          err instanceof GatewayDisabledError\n            ? err.message\n            : err instanceof Error\n              ? err.message\n              : String(err);\n        return {\n          isError: true,\n          content: [{ type: 'text' as const, text: `asset_generate: ${msg}` }]\n        };\n      }\n    }\n  };\n}\n"]}

package/dist/tools/edit.d.ts

@@ -3,6 +3,7 @@ import type { EngineSession } from '../engine/session.js';
 import type { RevisionStore } from '../revisions/store.js';
 import type { CodesignMcpToolRegistration } from '../server.js';
 import type { WorkspaceFS } from '../workspace/types.js';
+import { type TelemetrySink } from './spans.js';
 export interface CreateEditToolOptions<E = unknown> {
     store: RevisionStore;
     session: EngineSession<E>;
@@ -24,6 +25,8 @@ export interface CreateEditToolOptions<E = unknown> {
     }) => Promise<Uint8Array>;
     /** Workspace FS for persisting the thumbnail (required if renderThumbnail is supplied). */
     fs?: WorkspaceFS;
+    /** Diagnostics telemetry port. Absent → no-op (no timing overhead beyond a few clocks). */
+    telemetry?: TelemetrySink;
 }
 export declare function createEditTool<E = unknown>(opts: CreateEditToolOptions<E>): CodesignMcpToolRegistration;
 //# sourceMappingURL=edit.d.ts.map

package/dist/tools/edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO;IAChD,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC;IAClB,iEAAiE;IACjE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,gGAAgG;IAChG,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC;KACX,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1B,2FAA2F;IAC3F,EAAE,CAAC,EAAE,WAAW,CAAC;CAClB;AAiDD,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,2BAA2B,CAoH7B"}
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO;IAChD,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC;IAClB,iEAAiE;IACjE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,gGAAgG;IAChG,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC;KACX,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1B,2FAA2F;IAC3F,EAAE,CAAC,EAAE,WAAW,CAAC;IACjB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAqDD,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,2BAA2B,CA6K7B"}

package/dist/tools/edit.js

@@ -11,7 +11,9 @@
 //
 // `onLeafWritten` is the viewer hook: called after a successful write so the
 // SSE broadcaster can fan out the new revision id to subscribed viewers.
+import { performance } from 'node:perf_hooks';
 import { normalizeResult } from './result.js';
+import { SpanRecorder, NOOP_TELEMETRY_SINK, summarizeResult, toErrorShape } from './spans.js';
 const DESCRIPTION = [
     'Edit the CE.SDK canvas by running JavaScript against the live CreativeEngine, then commit the result as a new revision.',
     '',
@@ -27,7 +29,11 @@ const EDIT_INPUT_SCHEMA = {
     type: 'object',
     properties: {
         parent: {
-            oneOf: [{ type: 'string' }, { type: 'null' }],
+            // `type: ['string','null']` — NOT `oneOf: [{string},{null}]`. The
+            // type-array nullable idiom is honoured by strict tool-calling; `oneOf`
+            // is not (OpenAI bans it, weaker models stringify the value). See
+            // test/tools/schema-best-practices.test.ts.
+            type: ['string', 'null'],
             description: 'Parent revision id from a previous edit (a string). To start a new design root, use the JSON null literal. REQUIRED — there is no implicit default.'
         },
         code: {
@@ -48,110 +54,153 @@ const EDIT_INPUT_SCHEMA = {
 };
 export function createEditTool(opts) {
     const { store, session, onLeafWritten, renderThumbnail, fs, engineLock } = opts;
+    const telemetry = opts.telemetry ?? NOOP_TELEMETRY_SINK;
     return {
         name: 'edit',
         description: DESCRIPTION,
         inputSchema: EDIT_INPUT_SCHEMA,
         call: async (rawArgs) => {
-            const args = (rawArgs ?? {});
-            if (!Object.hasOwn(args, 'parent')) {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'edit: `parent` is required. Pass the revision id from a previous edit, or the JSON null literal (no quotes) for a new design root. See `handbook` for the rewind-recovery flow.'
+            const rec = new SpanRecorder();
+            const startedAt = performance.now();
+            let result;
+            let threw;
+            let revision;
+            let codeError;
+            try {
+                result = await (async () => {
+                    const args = (rawArgs ?? {});
+                    if (!Object.hasOwn(args, 'parent')) {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'edit: `parent` is required. Pass the revision id from a previous edit, or the JSON null literal (no quotes) for a new design root. See `handbook` for the rewind-recovery flow.'
+                                }
+                            ]
+                        };
+                    }
+                    if (args.parent === 'null') {
+                        // Some LLMs / MCP clients emit the JSON string "null" instead of the
+                        // bare null literal — a quoting slip, not a real revision id. Coerce it
+                        // rather than reject: this quoting nuance must never block creating a
+                        // new design root. (Stochastic, model-dependent; see edit.test.ts.)
+                        args.parent = null;
+                    }
+                    if (typeof args.code !== 'string') {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'edit: `code` (string) is required.'
+                                }
+                            ]
+                        };
+                    }
+                    // The shared engine is loaded, mutated by user code, then saved across
+                    // several awaits below. Serialize the whole sequence so a concurrent
+                    // session sharing this engine can't swap the scene out mid-edit.
+                    const beforeLock = performance.now();
+                    return engineLock.runExclusive(async () => {
+                        rec.add('lock_wait', performance.now() - beforeLock);
+                        // Pre-stage scene bytes for the session if parent is non-null.
+                        if (args.parent !== null) {
+                            const parentRev = await rec.time('workspace_read', () => store.read(args.parent));
+                            await rec.time('engine_scene_load', async () => {
+                                await session.populate(args.parent, parentRev.scene);
+                            });
                         }
-                    ]
-                };
-            }
-            if (args.parent === 'null') {
-                // Some LLMs / MCP clients emit the JSON string "null" instead of the
-                // bare null literal — a quoting slip, not a real revision id. Coerce it
-                // rather than reject: this quoting nuance must never block creating a
-                // new design root. (Stochastic, model-dependent; see edit.test.ts.)
-                args.parent = null;
-            }
-            if (typeof args.code !== 'string') {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'edit: `code` (string) is required.'
+                        const slot = await rec.time('engine_scene_load', () => session.acquire(args.parent ?? null));
+                        let codeResult;
+                        try {
+                            const AsyncFunction = Object.getPrototypeOf(async () => { }).constructor;
+                            const fn = new AsyncFunction('engine', args.code);
+                            codeResult = await rec.time('engine_execute', () => fn(slot.engine));
+                        }
+                        catch (err) {
+                            codeError = err;
+                            session.markDirty(slot);
+                            return {
+                                isError: true,
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: `edit: code threw — engine slot marked dirty (next edit pays one reload). ${err instanceof Error
+                                            ? (err.stack ?? err.message)
+                                            : String(err)}`
+                                    }
+                                ]
+                            };
+                        }
+                        const adapter = session.opts.adapter;
+                        const sceneBytes = await rec.time('engine_scene_save', () => adapter.saveToString(slot.engine));
+                        const written = await rec.time('workspace_write', () => store.write({
+                            scene: sceneBytes,
+                            parent: args.parent ?? null,
+                            title: args.title,
+                            note: args.note,
+                            code: args.code
+                        }));
+                        revision = written.id;
+                        session.commit(slot, written.id);
+                        if (renderThumbnail && fs) {
+                            await rec.time('engine_scene_thumbnail', async () => {
+                                try {
+                                    const bytes = await renderThumbnail({
+                                        revision: written.id,
+                                        engine: slot.engine
+                                    });
+                                    const shard = written.id.slice(0, 2);
+                                    const rest = written.id.slice(2);
+                                    await fs.writeFile(`exports/${shard}/${rest}/preview.webp`, bytes);
+                                }
+                                catch {
+                                    // best-effort; thumbnail failure must not poison the edit success path
+                                }
+                            });
                         }
-                    ]
-                };
+                        if (onLeafWritten) {
+                            const rootRevision = args.parent === null
+                                ? written.id
+                                : (await store.historyOf(written.id))[0].id;
+                            await onLeafWritten({ revision: written.id, rootRevision });
+                        }
+                        const envelope = {
+                            revision: written.id,
+                            parent: args.parent ?? null
+                        };
+                        const codeParts = normalizeResult(codeResult);
+                        return {
+                            content: [
+                                { type: 'text', text: JSON.stringify(envelope) },
+                                ...codeParts
+                            ]
+                        };
+                    });
+                })();
+                return result;
             }
-            // The shared engine is loaded, mutated by user code, then saved across
-            // several awaits below. Serialize the whole sequence so a concurrent
-            // session sharing this engine can't swap the scene out mid-edit.
-            return engineLock.runExclusive(async () => {
-                // Pre-stage scene bytes for the session if parent is non-null.
-                if (args.parent !== null) {
-                    const parentRev = await store.read(args.parent);
-                    await session.populate(args.parent, parentRev.scene);
-                }
-                const slot = await session.acquire(args.parent ?? null);
-                let codeResult;
-                try {
-                    const AsyncFunction = Object.getPrototypeOf(async () => { }).constructor;
-                    const fn = new AsyncFunction('engine', args.code);
-                    codeResult = await fn(slot.engine);
-                }
-                catch (err) {
-                    session.markDirty(slot);
-                    return {
-                        isError: true,
-                        content: [
-                            {
-                                type: 'text',
-                                text: `edit: code threw — engine slot marked dirty (next edit pays one reload). ${err instanceof Error
-                                    ? (err.stack ?? err.message)
-                                    : String(err)}`
-                            }
-                        ]
-                    };
-                }
-                const adapter = session.opts.adapter;
-                const sceneBytes = await adapter.saveToString(slot.engine);
-                const written = await store.write({
-                    scene: sceneBytes,
-                    parent: args.parent ?? null,
-                    title: args.title,
-                    note: args.note,
-                    code: args.code
+            catch (err) {
+                threw = err;
+                throw err;
+            }
+            finally {
+                telemetry.record({
+                    tool: 'edit',
+                    succeeded: threw === undefined && result?.isError !== true,
+                    totalMs: performance.now() - startedAt,
+                    spans: rec.list(),
+                    args: rawArgs,
+                    ...(result !== undefined ? { result: summarizeResult(result) } : {}),
+                    ...(revision ? { revision } : {}),
+                    ...(threw
+                        ? { error: toErrorShape(threw) }
+                        : codeError
+                            ? { error: toErrorShape(codeError) }
+                            : {})
                 });
-                session.commit(slot, written.id);
-                if (renderThumbnail && fs) {
-                    try {
-                        const bytes = await renderThumbnail({
-                            revision: written.id,
-                            engine: slot.engine
-                        });
-                        const shard = written.id.slice(0, 2);
-                        const rest = written.id.slice(2);
-                        await fs.writeFile(`exports/${shard}/${rest}/preview.webp`, bytes);
-                    }
-                    catch {
-                        // best-effort; thumbnail failure must not poison the edit success path
-                    }
-                }
-                if (onLeafWritten) {
-                    const rootRevision = args.parent === null
-                        ? written.id
-                        : (await store.historyOf(written.id))[0].id;
-                    await onLeafWritten({ revision: written.id, rootRevision });
-                }
-                const envelope = { revision: written.id, parent: args.parent ?? null };
-                const codeParts = normalizeResult(codeResult);
-                return {
-                    content: [
-                        { type: 'text', text: JSON.stringify(envelope) },
-                        ...codeParts
-                    ]
-                };
-            });
+            }
         }
     };
 }

package/dist/tools/edit.js.map

@@ -1 +1 @@
-{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/edit.ts\n//\n// `edit` — the spec's central tool (§6.1). Replaces `exec.ts`. Differences\n// from the POC `exec`:\n//   - `parent` is mandatory (null = new design root).\n//   - `title?` set on root creation; `note?` annotates this revision.\n//   - Writes a new revision via RevisionStore after `code` returns.\n//   - Reloads engine if session slot's currentRevision !== parent.\n//   - Dirty-on-throw: failed code marks the slot dirty.\n//   - Returns {revision, parent} JSON as the first MessagePart (text).\n//\n// `onLeafWritten` is the viewer hook: called after a successful write so the\n// SSE broadcaster can fan out the new revision id to subscribed viewers.\n\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport { normalizeResult } from './result.js';\n\nexport interface CreateEditToolOptions<E = unknown> {\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /**\n   * Guards the shared engine. The acquire → run code → save → thumbnail\n   * sequence below mutates one engine across several awaits; this serializes\n   * it against any other engine-touching tool call (see engine/mutex.ts).\n   */\n  engineLock: Mutex;\n  /** Called after a successful edit writes a new leaf revision. */\n  onLeafWritten?: (event: {\n    revision: string;\n    rootRevision: string;\n  }) => void | Promise<void>;\n  /** Render a thumbnail for the newly committed revision. Best-effort: failures are swallowed. */\n  renderThumbnail?: (event: {\n    revision: string;\n    engine: E;\n  }) => Promise<Uint8Array>;\n  /** Workspace FS for persisting the thumbnail (required if renderThumbnail is supplied). */\n  fs?: WorkspaceFS;\n}\n\nconst DESCRIPTION = [\n  'Edit the CE.SDK canvas by running JavaScript against the live CreativeEngine, then commit the result as a new revision.',\n  '',\n  '⚠ Call `handbook` BEFORE your first `edit`. It documents the mandatory `parent` argument, the dirty-on-throw safety contract, the typeface schema, and the runtime quirks.',\n  '',\n  \"REQUIRED: `parent` is a revision id (returned by a previous edit), or the JSON null literal (no quotes) to start a new design. Omitting it is an error — there is no implicit 'continue from wherever'.\",\n  '',\n  'Returns: the first content part is JSON `{ revision, parent }` — store `revision` so you can pass it as `parent` on the next edit.',\n  '',\n  \"Optional: `title` (set on parent=null only — the design's display name) and `note` (a one-liner describing what this edit accomplished — purely descriptive, helps you re-ground after a rewind).\"\n].join('\\n');\n\ninterface EditArgs {\n  parent: string | null;\n  code: string;\n  title?: string;\n  note?: string;\n}\n\nconst EDIT_INPUT_SCHEMA = {\n  type: 'object' as const,\n  properties: {\n    parent: {\n      oneOf: [{ type: 'string' as const }, { type: 'null' as const }],\n      description:\n        'Parent revision id from a previous edit (a string). To start a new design root, use the JSON null literal. REQUIRED — there is no implicit default.'\n    },\n    code: {\n      type: 'string' as const,\n      description:\n        'Async JS body. `engine` is in scope. Strict return contract per the handbook.'\n    },\n    title: {\n      type: 'string' as const,\n      description:\n        'Display name for the design. Set only when parent=null (creating a new design). For mid-chain renames use the `rename` tool.'\n    },\n    note: {\n      type: 'string' as const,\n      description:\n        'Freeform descriptive text — what this edit accomplished. Metadata only; never load-bearing.'\n    }\n  },\n  required: ['parent', 'code'],\n  additionalProperties: false\n};\n\nexport function createEditTool<E = unknown>(\n  opts: CreateEditToolOptions<E>\n): CodesignMcpToolRegistration {\n  const { store, session, onLeafWritten, renderThumbnail, fs, engineLock } =\n    opts;\n  return {\n    name: 'edit',\n    description: DESCRIPTION,\n    inputSchema: EDIT_INPUT_SCHEMA,\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as Partial<EditArgs>;\n      if (!Object.hasOwn(args, 'parent')) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'edit: `parent` is required. Pass the revision id from a previous edit, or the JSON null literal (no quotes) for a new design root. See `handbook` for the rewind-recovery flow.'\n            }\n          ]\n        };\n      }\n      if (args.parent === 'null') {\n        // Some LLMs / MCP clients emit the JSON string \"null\" instead of the\n        // bare null literal — a quoting slip, not a real revision id. Coerce it\n        // rather than reject: this quoting nuance must never block creating a\n        // new design root. (Stochastic, model-dependent; see edit.test.ts.)\n        args.parent = null;\n      }\n      if (typeof args.code !== 'string') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'edit: `code` (string) is required.'\n            }\n          ]\n        };\n      }\n      // The shared engine is loaded, mutated by user code, then saved across\n      // several awaits below. Serialize the whole sequence so a concurrent\n      // session sharing this engine can't swap the scene out mid-edit.\n      return engineLock.runExclusive(async () => {\n        // Pre-stage scene bytes for the session if parent is non-null.\n        if (args.parent !== null) {\n          const parentRev = await store.read(args.parent as string);\n          await session.populate(args.parent as string, parentRev.scene);\n        }\n        const slot = await session.acquire(args.parent ?? null);\n        let codeResult: unknown;\n        try {\n          const AsyncFunction = Object.getPrototypeOf(\n            async () => {}\n          ).constructor;\n          const fn = new AsyncFunction('engine', args.code);\n          codeResult = await fn(slot.engine);\n        } catch (err) {\n          session.markDirty(slot);\n          return {\n            isError: true,\n            content: [\n              {\n                type: 'text' as const,\n                text: `edit: code threw — engine slot marked dirty (next edit pays one reload). ${\n                  err instanceof Error\n                    ? (err.stack ?? err.message)\n                    : String(err)\n                }`\n              }\n            ]\n          };\n        }\n        const adapter = (\n          session as unknown as {\n            opts: { adapter: { saveToString(e: E): Promise<string> } };\n          }\n        ).opts.adapter;\n        const sceneBytes = await adapter.saveToString(slot.engine);\n        const written = await store.write({\n          scene: sceneBytes,\n          parent: args.parent ?? null,\n          title: args.title,\n          note: args.note,\n          code: args.code\n        });\n        session.commit(slot, written.id);\n        if (renderThumbnail && fs) {\n          try {\n            const bytes = await renderThumbnail({\n              revision: written.id,\n              engine: slot.engine\n            });\n            const shard = written.id.slice(0, 2);\n            const rest = written.id.slice(2);\n            await fs.writeFile(`exports/${shard}/${rest}/preview.webp`, bytes);\n          } catch {\n            // best-effort; thumbnail failure must not poison the edit success path\n          }\n        }\n        if (onLeafWritten) {\n          const rootRevision =\n            args.parent === null\n              ? written.id\n              : (await store.historyOf(written.id))[0].id;\n          await onLeafWritten({ revision: written.id, rootRevision });\n        }\n        const envelope = { revision: written.id, parent: args.parent ?? null };\n        const codeParts = normalizeResult(codeResult);\n        return {\n          content: [\n            { type: 'text' as const, text: JSON.stringify(envelope) },\n            ...codeParts\n          ]\n        };\n      });\n    }\n  };\n}\n"]}
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/edit.ts\n//\n// `edit` — the spec's central tool (§6.1). Replaces `exec.ts`. Differences\n// from the POC `exec`:\n//   - `parent` is mandatory (null = new design root).\n//   - `title?` set on root creation; `note?` annotates this revision.\n//   - Writes a new revision via RevisionStore after `code` returns.\n//   - Reloads engine if session slot's currentRevision !== parent.\n//   - Dirty-on-throw: failed code marks the slot dirty.\n//   - Returns {revision, parent} JSON as the first MessagePart (text).\n//\n// `onLeafWritten` is the viewer hook: called after a successful write so the\n// SSE broadcaster can fan out the new revision id to subscribed viewers.\n\nimport { performance } from 'node:perf_hooks';\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport { normalizeResult } from './result.js';\nimport {\n  SpanRecorder,\n  NOOP_TELEMETRY_SINK,\n  summarizeResult,\n  toErrorShape,\n  type TelemetrySink\n} from './spans.js';\n\nexport interface CreateEditToolOptions<E = unknown> {\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /**\n   * Guards the shared engine. The acquire → run code → save → thumbnail\n   * sequence below mutates one engine across several awaits; this serializes\n   * it against any other engine-touching tool call (see engine/mutex.ts).\n   */\n  engineLock: Mutex;\n  /** Called after a successful edit writes a new leaf revision. */\n  onLeafWritten?: (event: {\n    revision: string;\n    rootRevision: string;\n  }) => void | Promise<void>;\n  /** Render a thumbnail for the newly committed revision. Best-effort: failures are swallowed. */\n  renderThumbnail?: (event: {\n    revision: string;\n    engine: E;\n  }) => Promise<Uint8Array>;\n  /** Workspace FS for persisting the thumbnail (required if renderThumbnail is supplied). */\n  fs?: WorkspaceFS;\n  /** Diagnostics telemetry port. Absent → no-op (no timing overhead beyond a few clocks). */\n  telemetry?: TelemetrySink;\n}\n\nconst DESCRIPTION = [\n  'Edit the CE.SDK canvas by running JavaScript against the live CreativeEngine, then commit the result as a new revision.',\n  '',\n  '⚠ Call `handbook` BEFORE your first `edit`. It documents the mandatory `parent` argument, the dirty-on-throw safety contract, the typeface schema, and the runtime quirks.',\n  '',\n  \"REQUIRED: `parent` is a revision id (returned by a previous edit), or the JSON null literal (no quotes) to start a new design. Omitting it is an error — there is no implicit 'continue from wherever'.\",\n  '',\n  'Returns: the first content part is JSON `{ revision, parent }` — store `revision` so you can pass it as `parent` on the next edit.',\n  '',\n  \"Optional: `title` (set on parent=null only — the design's display name) and `note` (a one-liner describing what this edit accomplished — purely descriptive, helps you re-ground after a rewind).\"\n].join('\\n');\n\ninterface EditArgs {\n  parent: string | null;\n  code: string;\n  title?: string;\n  note?: string;\n}\n\nconst EDIT_INPUT_SCHEMA = {\n  type: 'object' as const,\n  properties: {\n    parent: {\n      // `type: ['string','null']` — NOT `oneOf: [{string},{null}]`. The\n      // type-array nullable idiom is honoured by strict tool-calling; `oneOf`\n      // is not (OpenAI bans it, weaker models stringify the value). See\n      // test/tools/schema-best-practices.test.ts.\n      type: ['string', 'null'] as const,\n      description:\n        'Parent revision id from a previous edit (a string). To start a new design root, use the JSON null literal. REQUIRED — there is no implicit default.'\n    },\n    code: {\n      type: 'string' as const,\n      description:\n        'Async JS body. `engine` is in scope. Strict return contract per the handbook.'\n    },\n    title: {\n      type: 'string' as const,\n      description:\n        'Display name for the design. Set only when parent=null (creating a new design). For mid-chain renames use the `rename` tool.'\n    },\n    note: {\n      type: 'string' as const,\n      description:\n        'Freeform descriptive text — what this edit accomplished. Metadata only; never load-bearing.'\n    }\n  },\n  required: ['parent', 'code'],\n  additionalProperties: false\n};\n\nexport function createEditTool<E = unknown>(\n  opts: CreateEditToolOptions<E>\n): CodesignMcpToolRegistration {\n  const { store, session, onLeafWritten, renderThumbnail, fs, engineLock } =\n    opts;\n  const telemetry = opts.telemetry ?? NOOP_TELEMETRY_SINK;\n  return {\n    name: 'edit',\n    description: DESCRIPTION,\n    inputSchema: EDIT_INPUT_SCHEMA,\n    call: async (rawArgs) => {\n      const rec = new SpanRecorder();\n      const startedAt = performance.now();\n      type CallResult = Awaited<\n        ReturnType<CodesignMcpToolRegistration['call']>\n      >;\n      let result: CallResult | undefined;\n      let threw: unknown;\n      let revision: string | undefined;\n      let codeError: unknown;\n      try {\n        result = await (async (): Promise<CallResult> => {\n          const args = (rawArgs ?? {}) as Partial<EditArgs>;\n          if (!Object.hasOwn(args, 'parent')) {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'edit: `parent` is required. Pass the revision id from a previous edit, or the JSON null literal (no quotes) for a new design root. See `handbook` for the rewind-recovery flow.'\n                }\n              ]\n            };\n          }\n          if (args.parent === 'null') {\n            // Some LLMs / MCP clients emit the JSON string \"null\" instead of the\n            // bare null literal — a quoting slip, not a real revision id. Coerce it\n            // rather than reject: this quoting nuance must never block creating a\n            // new design root. (Stochastic, model-dependent; see edit.test.ts.)\n            args.parent = null;\n          }\n          if (typeof args.code !== 'string') {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'edit: `code` (string) is required.'\n                }\n              ]\n            };\n          }\n          // The shared engine is loaded, mutated by user code, then saved across\n          // several awaits below. Serialize the whole sequence so a concurrent\n          // session sharing this engine can't swap the scene out mid-edit.\n          const beforeLock = performance.now();\n          return engineLock.runExclusive(async () => {\n            rec.add('lock_wait', performance.now() - beforeLock);\n            // Pre-stage scene bytes for the session if parent is non-null.\n            if (args.parent !== null) {\n              const parentRev = await rec.time('workspace_read', () =>\n                store.read(args.parent as string)\n              );\n              await rec.time('engine_scene_load', async () => {\n                await session.populate(args.parent as string, parentRev.scene);\n              });\n            }\n            const slot = await rec.time('engine_scene_load', () =>\n              session.acquire(args.parent ?? null)\n            );\n            let codeResult: unknown;\n            try {\n              const AsyncFunction = Object.getPrototypeOf(\n                async () => {}\n              ).constructor;\n              const fn = new AsyncFunction('engine', args.code);\n              codeResult = await rec.time('engine_execute', () =>\n                fn(slot.engine)\n              );\n            } catch (err) {\n              codeError = err;\n              session.markDirty(slot);\n              return {\n                isError: true,\n                content: [\n                  {\n                    type: 'text' as const,\n                    text: `edit: code threw — engine slot marked dirty (next edit pays one reload). ${\n                      err instanceof Error\n                        ? (err.stack ?? err.message)\n                        : String(err)\n                    }`\n                  }\n                ]\n              };\n            }\n            const adapter = (\n              session as unknown as {\n                opts: { adapter: { saveToString(e: E): Promise<string> } };\n              }\n            ).opts.adapter;\n            const sceneBytes = await rec.time('engine_scene_save', () =>\n              adapter.saveToString(slot.engine)\n            );\n            const written = await rec.time('workspace_write', () =>\n              store.write({\n                scene: sceneBytes,\n                parent: args.parent ?? null,\n                title: args.title,\n                note: args.note,\n                code: args.code\n              })\n            );\n            revision = written.id;\n            session.commit(slot, written.id);\n            if (renderThumbnail && fs) {\n              await rec.time('engine_scene_thumbnail', async () => {\n                try {\n                  const bytes = await renderThumbnail({\n                    revision: written.id,\n                    engine: slot.engine\n                  });\n                  const shard = written.id.slice(0, 2);\n                  const rest = written.id.slice(2);\n                  await fs.writeFile(\n                    `exports/${shard}/${rest}/preview.webp`,\n                    bytes\n                  );\n                } catch {\n                  // best-effort; thumbnail failure must not poison the edit success path\n                }\n              });\n            }\n            if (onLeafWritten) {\n              const rootRevision =\n                args.parent === null\n                  ? written.id\n                  : (await store.historyOf(written.id))[0].id;\n              await onLeafWritten({ revision: written.id, rootRevision });\n            }\n            const envelope = {\n              revision: written.id,\n              parent: args.parent ?? null\n            };\n            const codeParts = normalizeResult(codeResult);\n            return {\n              content: [\n                { type: 'text' as const, text: JSON.stringify(envelope) },\n                ...codeParts\n              ]\n            };\n          });\n        })();\n        return result;\n      } catch (err) {\n        threw = err;\n        throw err;\n      } finally {\n        telemetry.record({\n          tool: 'edit',\n          succeeded: threw === undefined && result?.isError !== true,\n          totalMs: performance.now() - startedAt,\n          spans: rec.list(),\n          args: rawArgs,\n          ...(result !== undefined ? { result: summarizeResult(result) } : {}),\n          ...(revision ? { revision } : {}),\n          ...(threw\n            ? { error: toErrorShape(threw) }\n            : codeError\n              ? { error: toErrorShape(codeError) }\n              : {})\n        });\n      }\n    }\n  };\n}\n"]}

package/dist/tools/export.d.ts

@@ -4,6 +4,7 @@ import type { RevisionStore } from '../revisions/store.js';
 import type { CodesignMcpToolRegistration } from '../server.js';
 import type { ViewerUrlBuilder } from '../viewer/url-builder.js';
 import type { WorkspaceFS } from '../workspace/types.js';
+import { type TelemetrySink } from './spans.js';
 export interface CreateExportToolOptions<E = unknown> {
     fs: WorkspaceFS;
     store: RevisionStore;
@@ -14,6 +15,8 @@ export interface CreateExportToolOptions<E = unknown> {
     allowOutPath?: boolean;
     /** Guards the shared engine — load-then-export must not interleave with another session's edit (see engine/mutex.ts). */
     engineLock: Mutex;
+    /** Diagnostics telemetry port. Absent → no-op (no timing overhead beyond a few clocks). */
+    telemetry?: TelemetrySink;
 }
 export declare function createExportTool<E = unknown>(opts: CreateExportToolOptions<E>): CodesignMcpToolRegistration;
 //# sourceMappingURL=export.d.ts.map

package/dist/tools/export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAoEzD,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAClD,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yHAAyH;IACzH,UAAU,EAAE,KAAK,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,2BAA2B,CAgI7B"}
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAoEpB,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAClD,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yHAAyH;IACzH,UAAU,EAAE,KAAK,CAAC;IAClB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,2BAA2B,CAyK7B"}