@execbox/core 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,8 @@
 # @execbox/core
 
-Core execution contract for execbox. Use it to resolve host tools into callable guest namespaces, validate tool boundaries, and bridge MCP servers or clients into the same execution model.
+Provider, schema, and MCP adapter contracts for execbox. Use it to resolve host
+tools into callable guest namespaces before running code with an executor such
+as `@execbox/quickjs`.
 
 [![npm version](https://img.shields.io/npm/v/%40execbox%2Fcore?style=flat-square)](https://www.npmjs.com/package/@execbox/core)
 [![License](https://img.shields.io/github/license/aallam/execbox?style=flat-square)](https://github.com/aallam/execbox/blob/main/LICENSE)
@@ -9,18 +11,17 @@ Core execution contract for execbox. Use it to resolve host tools into callable
 ## Use `@execbox/core` When
 
 - you want to expose host capabilities to guest code through explicit tool providers
-- you want one execution contract across QuickJS, remote, or `isolated-vm` runtimes
-- you want to wrap MCP servers or clients into callable namespaces instead of exposing raw tool loops
+- you want one execution contract across inline and worker-hosted QuickJS
+- you want to wrap MCP servers or clients into callable namespaces
 
 ## Pair It With an Executor
 
-`@execbox/core` defines the provider and tool boundary, but it does not execute guest code on its own.
+`@execbox/core` defines the provider and tool boundary. Guest execution happens
+in an executor package.
 
-| Package                                                                      | Start here when                                                                |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| [`@execbox/quickjs`](https://www.npmjs.com/package/@execbox/quickjs)         | You want the default path with inline, worker, or process-hosted QuickJS.      |
-| [`@execbox/remote`](https://www.npmjs.com/package/@execbox/remote)           | Your runtime already lives behind an application-owned transport boundary.     |
-| [`@execbox/isolated-vm`](https://www.npmjs.com/package/@execbox/isolated-vm) | You explicitly want the `isolated-vm` runtime and can support its constraints. |
+| Package                                                              | Start here when                                                 |
+| -------------------------------------------------------------------- | --------------------------------------------------------------- |
+| [`@execbox/quickjs`](https://www.npmjs.com/package/@execbox/quickjs) | You want the default path with inline or worker-hosted QuickJS. |
 
 ## Install
 
@@ -30,12 +31,28 @@ Most users start with QuickJS:
 npm install @execbox/core @execbox/quickjs
 ```
 
-Swap in `@execbox/remote` or `@execbox/isolated-vm` when you need a different runtime boundary.
+## Provider Boundary
+
+Providers are explicit capability grants. `resolveProvider()` validates the
+namespace, normalizes tool schemas, creates guest-safe tool names, wraps tool
+execution with schema checks, and keeps original-to-safe name maps for callers
+that need to explain MCP or generated tool names.
+
+Tool inputs and results should be JSON-compatible data. Keep host-only values
+such as clients, handles, secrets, and tenant routing inside the tool
+implementation.
 
 ## Runtime Implementer Surface
 
-Application code should usually import from `@execbox/core`, `@execbox/core/mcp`, or `@execbox/core/protocol`.
-Executor and runner packages should import shared runtime helpers from `@execbox/core/runtime` instead. That subpath contains the manifest dispatcher, runtime option defaults, timeout helpers, log formatting, code normalization, and error normalization used to keep runtime implementations aligned.
+Most application code can skip this section.
+
+Application code should usually import from `@execbox/core` or `@execbox/core/mcp`.
+The `@execbox/core/protocol` and `@execbox/core/runtime` subpaths exist for
+execbox-owned runtime packages. `@execbox/core/protocol` carries the
+worker-hosted QuickJS message contract, while `@execbox/core/runtime` contains
+the manifest dispatcher, runtime option defaults, timeout helpers, log
+formatting, code normalization, and error normalization used to keep runtime
+implementations aligned.
 
 ## Smallest Working Usage
 
@@ -71,7 +88,8 @@ console.log(result);
 
 ## MCP Support
 
-Use `@execbox/core/mcp` when you want MCP on either side of the boundary:
+Use `@execbox/core/mcp` when you want MCP on either side of the provider
+boundary:
 
 - wrap an upstream MCP server or client into a provider with `createMcpToolProvider()` or `openMcpToolProvider()`
 - expose execbox code execution back out through an MCP server with `codeMcpServer()`
@@ -86,8 +104,9 @@ Use `@execbox/core/mcp` when you want MCP on either side of the boundary:
 ## Read Next
 
 - [Getting Started](https://execbox.aallam.com/getting-started)
+- [Providers & Tools](https://execbox.aallam.com/providers-and-tools)
+- [Runtime Choices](https://execbox.aallam.com/runtime-choices)
+- [MCP Integration](https://execbox.aallam.com/mcp-integration)
 - [Examples](https://execbox.aallam.com/examples)
 - [Security & Boundaries](https://execbox.aallam.com/security)
 - [Architecture Overview](https://execbox.aallam.com/architecture/)
-- [Core Architecture](https://execbox.aallam.com/architecture/execbox-core)
-- [MCP And Protocol](https://execbox.aallam.com/architecture/execbox-mcp-and-protocol)

package/dist/{errors-DlbJQYs7.d.ts → errors-BIWv-QIC.d.ts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { u as ExecuteErrorCode } from "./runner-ClFrFnz9.js";
+import { u as ExecuteErrorCode } from "./runner-DXLu0eJV.js";
 
 //#region src/errors.d.ts
 
@@ -26,4 +26,4 @@ declare function isExecuteFailure(value: unknown): value is ExecuteFailure;
 declare function isJsonSerializable(value: unknown, active?: Set<object>, memo?: WeakSet<object>): boolean;
 //#endregion
 export { isExecuteFailure as n, isJsonSerializable as r, ExecuteFailure as t };
-//# sourceMappingURL=errors-DlbJQYs7.d.ts.map
+//# sourceMappingURL=errors-BIWv-QIC.d.ts.map

package/dist/{errors-DlbJQYs7.d.ts.map → errors-BIWv-QIC.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"errors-DlbJQYs7.d.ts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}
+{"version":3,"file":"errors-BIWv-QIC.d.ts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}

package/dist/{errors-wS8yjQhS.js → errors-DdWVEGU8.js}

@@ -58,4 +58,4 @@ function isJsonSerializable(value, active = /* @__PURE__ */ new Set(), memo = /*
 
 //#endregion
 export { isExecuteFailure as n, isJsonSerializable as r, ExecuteFailure as t };
-//# sourceMappingURL=errors-wS8yjQhS.js.map
+//# sourceMappingURL=errors-DdWVEGU8.js.map

package/dist/{errors-wS8yjQhS.js.map → errors-DdWVEGU8.js.map}

@@ -1 +1 @@
-{"version":3,"file":"errors-wS8yjQhS.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import type { ExecuteErrorCode } from \"./types\";\n\n/**\n * Structured failure used internally to propagate executor and tool errors.\n */\nexport class ExecuteFailure extends Error {\n  code: ExecuteErrorCode;\n\n  /**\n   * Creates a structured failure with a trusted executor or tool error code.\n   */\n  constructor(code: ExecuteErrorCode, message: string) {\n    super(message);\n    this.code = code;\n    this.name = \"ExecuteFailure\";\n  }\n}\n\n/**\n * Returns whether a thrown value is an {@link ExecuteFailure}.\n */\nexport function isExecuteFailure(value: unknown): value is ExecuteFailure {\n  return value instanceof ExecuteFailure;\n}\n\n/**\n * Returns whether a value can be serialized through the JSON-only host/guest boundary.\n */\nexport function isJsonSerializable(\n  value: unknown,\n  active = new Set<object>(),\n  memo = new WeakSet<object>(),\n): boolean {\n  if (value === null) {\n    return true;\n  }\n\n  switch (typeof value) {\n    case \"string\":\n    case \"boolean\":\n      return true;\n    case \"number\":\n      return Number.isFinite(value);\n    case \"bigint\":\n    case \"function\":\n    case \"symbol\":\n    case \"undefined\":\n      return false;\n    case \"object\": {\n      const objectValue = value as object;\n\n      if (memo.has(objectValue)) {\n        return true;\n      }\n\n      if (active.has(objectValue)) {\n        return false;\n      }\n\n      active.add(objectValue);\n      let isSerializable = false;\n\n      try {\n        if (Array.isArray(value)) {\n          isSerializable = value.every((item) =>\n            isJsonSerializable(item, active, memo),\n          );\n          return isSerializable;\n        }\n\n        const prototype = Object.getPrototypeOf(value);\n        if (prototype !== Object.prototype && prototype !== null) {\n          return false;\n        }\n\n        isSerializable = Object.values(value).every((item) =>\n          isJsonSerializable(item, active, memo),\n        );\n        return isSerializable;\n      } finally {\n        active.delete(objectValue);\n        if (isSerializable) {\n          memo.add(objectValue);\n        }\n      }\n    }\n  }\n\n  return false;\n}\n"],"mappings":";;;;AAKA,IAAa,iBAAb,cAAoC,MAAM;CACxC;;;;CAKA,YAAY,MAAwB,SAAiB;AACnD,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,OAAO;;;;;;AAOhB,SAAgB,iBAAiB,OAAyC;AACxE,QAAO,iBAAiB;;;;;AAM1B,SAAgB,mBACd,OACA,yBAAS,IAAI,KAAa,EAC1B,uBAAO,IAAI,SAAiB,EACnB;AACT,KAAI,UAAU,KACZ,QAAO;AAGT,SAAQ,OAAO,OAAf;EACE,KAAK;EACL,KAAK,UACH,QAAO;EACT,KAAK,SACH,QAAO,OAAO,SAAS,MAAM;EAC/B,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,YACH,QAAO;EACT,KAAK,UAAU;GACb,MAAM,cAAc;AAEpB,OAAI,KAAK,IAAI,YAAY,CACvB,QAAO;AAGT,OAAI,OAAO,IAAI,YAAY,CACzB,QAAO;AAGT,UAAO,IAAI,YAAY;GACvB,IAAI,iBAAiB;AAErB,OAAI;AACF,QAAI,MAAM,QAAQ,MAAM,EAAE;AACxB,sBAAiB,MAAM,OAAO,SAC5B,mBAAmB,MAAM,QAAQ,KAAK,CACvC;AACD,YAAO;;IAGT,MAAM,YAAY,OAAO,eAAe,MAAM;AAC9C,QAAI,cAAc,OAAO,aAAa,cAAc,KAClD,QAAO;AAGT,qBAAiB,OAAO,OAAO,MAAM,CAAC,OAAO,SAC3C,mBAAmB,MAAM,QAAQ,KAAK,CACvC;AACD,WAAO;aACC;AACR,WAAO,OAAO,YAAY;AAC1B,QAAI,eACF,MAAK,IAAI,YAAY;;;;AAM7B,QAAO"}
+{"version":3,"file":"errors-DdWVEGU8.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import type { ExecuteErrorCode } from \"./types\";\n\n/**\n * Structured failure used internally to propagate executor and tool errors.\n */\nexport class ExecuteFailure extends Error {\n  code: ExecuteErrorCode;\n\n  /**\n   * Creates a structured failure with a trusted executor or tool error code.\n   */\n  constructor(code: ExecuteErrorCode, message: string) {\n    super(message);\n    this.code = code;\n    this.name = \"ExecuteFailure\";\n  }\n}\n\n/**\n * Returns whether a thrown value is an {@link ExecuteFailure}.\n */\nexport function isExecuteFailure(value: unknown): value is ExecuteFailure {\n  return value instanceof ExecuteFailure;\n}\n\n/**\n * Returns whether a value can be serialized through the JSON-only host/guest boundary.\n */\nexport function isJsonSerializable(\n  value: unknown,\n  active = new Set<object>(),\n  memo = new WeakSet<object>(),\n): boolean {\n  if (value === null) {\n    return true;\n  }\n\n  switch (typeof value) {\n    case \"string\":\n    case \"boolean\":\n      return true;\n    case \"number\":\n      return Number.isFinite(value);\n    case \"bigint\":\n    case \"function\":\n    case \"symbol\":\n    case \"undefined\":\n      return false;\n    case \"object\": {\n      const objectValue = value as object;\n\n      if (memo.has(objectValue)) {\n        return true;\n      }\n\n      if (active.has(objectValue)) {\n        return false;\n      }\n\n      active.add(objectValue);\n      let isSerializable = false;\n\n      try {\n        if (Array.isArray(value)) {\n          isSerializable = value.every((item) =>\n            isJsonSerializable(item, active, memo),\n          );\n          return isSerializable;\n        }\n\n        const prototype = Object.getPrototypeOf(value);\n        if (prototype !== Object.prototype && prototype !== null) {\n          return false;\n        }\n\n        isSerializable = Object.values(value).every((item) =>\n          isJsonSerializable(item, active, memo),\n        );\n        return isSerializable;\n      } finally {\n        active.delete(objectValue);\n        if (isSerializable) {\n          memo.add(objectValue);\n        }\n      }\n    }\n  }\n\n  return false;\n}\n"],"mappings":";;;;AAKA,IAAa,iBAAb,cAAoC,MAAM;CACxC;;;;CAKA,YAAY,MAAwB,SAAiB;AACnD,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,OAAO;;;;;;AAOhB,SAAgB,iBAAiB,OAAyC;AACxE,QAAO,iBAAiB;;;;;AAM1B,SAAgB,mBACd,OACA,yBAAS,IAAI,KAAa,EAC1B,uBAAO,IAAI,SAAiB,EACnB;AACT,KAAI,UAAU,KACZ,QAAO;AAGT,SAAQ,OAAO,OAAf;EACE,KAAK;EACL,KAAK,UACH,QAAO;EACT,KAAK,SACH,QAAO,OAAO,SAAS,MAAM;EAC/B,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,YACH,QAAO;EACT,KAAK,UAAU;GACb,MAAM,cAAc;AAEpB,OAAI,KAAK,IAAI,YAAY,CACvB,QAAO;AAGT,OAAI,OAAO,IAAI,YAAY,CACzB,QAAO;AAGT,UAAO,IAAI,YAAY;GACvB,IAAI,iBAAiB;AAErB,OAAI;AACF,QAAI,MAAM,QAAQ,MAAM,EAAE;AACxB,sBAAiB,MAAM,OAAO,SAC5B,mBAAmB,MAAM,QAAQ,KAAK,CACvC;AACD,YAAO;;IAGT,MAAM,YAAY,OAAO,eAAe,MAAM;AAC9C,QAAI,cAAc,OAAO,aAAa,cAAc,KAClD,QAAO;AAGT,qBAAiB,OAAO,OAAO,MAAM,CAAC,OAAO,SAC3C,mBAAmB,MAAM,QAAQ,KAAK,CACvC;AACD,WAAO;aACC;AACR,WAAO,OAAO,YAAY;AAC1B,QAAI,eACF,MAAK,IAAI,YAAY;;;;AAM7B,QAAO"}

package/dist/{errors-B9ADBuDH.d.cts → errors-y4C-EIWT.d.cts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { u as ExecuteErrorCode } from "./runner-DSgvu6Ad.cjs";
+import { u as ExecuteErrorCode } from "./runner-Cy18Z0u0.cjs";
 
 //#region src/errors.d.ts
 
@@ -26,4 +26,4 @@ declare function isExecuteFailure(value: unknown): value is ExecuteFailure;
 declare function isJsonSerializable(value: unknown, active?: Set<object>, memo?: WeakSet<object>): boolean;
 //#endregion
 export { isExecuteFailure as n, isJsonSerializable as r, ExecuteFailure as t };
-//# sourceMappingURL=errors-B9ADBuDH.d.cts.map
+//# sourceMappingURL=errors-y4C-EIWT.d.cts.map

package/dist/{errors-B9ADBuDH.d.cts.map → errors-y4C-EIWT.d.cts.map}

@@ -1 +1 @@
-{"version":3,"file":"errors-B9ADBuDH.d.cts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}
+{"version":3,"file":"errors-y4C-EIWT.d.cts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}

package/dist/{executor-B7q7K_27.d.ts → executor-BOTd9xNK.d.ts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-ClFrFnz9.js";
+import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-DXLu0eJV.js";
 
 //#region src/executor/executor.d.ts
 
@@ -26,4 +26,4 @@ interface Executor {
 }
 //#endregion
 export { ExecutorPoolOptions as n, Executor as t };
-//# sourceMappingURL=executor-B7q7K_27.d.ts.map
+//# sourceMappingURL=executor-BOTd9xNK.d.ts.map

package/dist/{executor-B7q7K_27.d.ts.map → executor-BOTd9xNK.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"executor-B7q7K_27.d.ts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}
+{"version":3,"file":"executor-BOTd9xNK.d.ts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}

package/dist/{executor-BsE5nF-j.d.cts → executor-CtbrvTQ_.d.cts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-DSgvu6Ad.cjs";
+import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-Cy18Z0u0.cjs";
 
 //#region src/executor/executor.d.ts
 
@@ -26,4 +26,4 @@ interface Executor {
 }
 //#endregion
 export { ExecutorPoolOptions as n, Executor as t };
-//# sourceMappingURL=executor-BsE5nF-j.d.cts.map
+//# sourceMappingURL=executor-CtbrvTQ_.d.cts.map

package/dist/{executor-BsE5nF-j.d.cts.map → executor-CtbrvTQ_.d.cts.map}

@@ -1 +1 @@
-{"version":3,"file":"executor-BsE5nF-j.d.cts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}
+{"version":3,"file":"executor-CtbrvTQ_.d.cts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}

package/dist/index.cjs

@@ -1,14 +1,6 @@
-const require_resolveProvider = require('./resolveProvider-BZYSw8Qk.cjs');
+const require_resolveProvider = require('./resolveProvider-DFAg6No5.cjs');
 const require_errors = require('./errors-xD8r6fCf.cjs');
 
 exports.ExecuteFailure = require_errors.ExecuteFailure;
-exports.assertValidIdentifier = require_resolveProvider.assertValidIdentifier;
-exports.generateTypesFromJsonSchema = require_resolveProvider.generateTypesFromJsonSchema;
 exports.isExecuteFailure = require_errors.isExecuteFailure;
-exports.isJsonSerializable = require_errors.isJsonSerializable;
-exports.isReservedWord = require_resolveProvider.isReservedWord;
-exports.isValidIdentifier = require_resolveProvider.isValidIdentifier;
-exports.resolveProvider = require_resolveProvider.resolveProvider;
-exports.sanitizeIdentifier = require_resolveProvider.sanitizeIdentifier;
-exports.sanitizeToolName = require_resolveProvider.sanitizeToolName;
-exports.serializePropertyName = require_resolveProvider.serializePropertyName;
+exports.resolveProvider = require_resolveProvider.resolveProvider;

package/dist/index.d.cts

@@ -2,49 +2,15 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { _ as ToolProvider, a as ToolCall, d as ExecuteResult, f as JsonSchema, g as ToolExecutionContext, h as ToolDescriptor, i as ProviderToolManifest, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, o as ToolCallResult, p as ResolvedToolDescriptor, r as ProviderManifest, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolSchema, y as TypegenToolDescriptor } from "./runner-DSgvu6Ad.cjs";
-import { n as ExecutorPoolOptions, t as Executor } from "./executor-BsE5nF-j.cjs";
-import { n as isExecuteFailure, r as isJsonSerializable, t as ExecuteFailure } from "./errors-B9ADBuDH.cjs";
+import { _ as ToolExecutionContext, d as ExecuteResult, f as JsonSchema, g as ToolDescriptor, h as ToolAnnotations, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, p as ResolvedToolDescriptor, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolProvider, y as ToolSchema } from "./runner-Cy18Z0u0.cjs";
+import { n as ExecutorPoolOptions, t as Executor } from "./executor-CtbrvTQ_.cjs";
+import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-y4C-EIWT.cjs";
 
-//#region src/identifier.d.ts
-/**
- * Returns whether the value is a valid JavaScript identifier.
- */
-declare function isValidIdentifier(value: string): boolean;
-/**
- * Returns whether the identifier is reserved in JavaScript source.
- */
-declare function isReservedWord(value: string): boolean;
-/**
- * Throws when the value cannot be used as a bare JavaScript identifier.
- */
-declare function assertValidIdentifier(value: string, label?: string): void;
-/**
- * Converts a raw identifier-like value into a safe JavaScript identifier.
- */
-declare function sanitizeIdentifier(value: string): string;
-/**
- * Renders the name as a bare identifier when possible, otherwise as a string literal.
- */
-declare function serializePropertyName(name: string): string;
-//#endregion
-//#region src/sanitize.d.ts
-/**
- * Converts a raw tool name into a safe JavaScript identifier.
- */
-declare function sanitizeToolName(name: string): string;
-//#endregion
 //#region src/provider/resolveProvider.d.ts
 /**
  * Resolves a tool provider into the validated, sanitized shape consumed by executors.
  */
 declare function resolveProvider(provider: ToolProvider): ResolvedToolProvider;
 //#endregion
-//#region src/typegen/jsonSchema.d.ts
-/**
- * Generates a namespace declaration for a provider's tool schemas.
- */
-declare function generateTypesFromJsonSchema(providerName: string, tools: Record<string, TypegenToolDescriptor>): string;
-//#endregion
-export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ProviderManifest, type ProviderToolManifest, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolCall, type ToolCallResult, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, type TypegenToolDescriptor, assertValidIdentifier, generateTypesFromJsonSchema, isExecuteFailure, isJsonSerializable, isReservedWord, isValidIdentifier, resolveProvider, sanitizeIdentifier, sanitizeToolName, serializePropertyName };
+export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolAnnotations, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, isExecuteFailure, resolveProvider };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/identifier.ts","../src/sanitize.ts","../src/provider/resolveProvider.ts","../src/typegen/jsonSchema.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBA6DgB,iBAAA;;AAAhB,CAAA,CAAA,CAAA,OAAA,CAAA,OAAA,CAAA,GAAA,CAAA,UAAA,CAAA,EAAA,CAAA,QAAA,CAAA,EAAA,CAAA,UAAA,CAAA,MAAA;AAOA,CAAA,CAAA;AAOgB,OAAA,CAAA,QAAA,CAPA,cAAA,CAOqB,KAAA,CAAA,CAAA,MAAA,CAAA,CAAA,CAAA,OAAA;AAYrC,CAAA,CAAA;AAqBA,CAAA,CAAA,CAAA,MAAA,CAAA,IAAA,CAAA,GAAA,CAAA,KAAA,CAAA,MAAA,CAAA,EAAA,CAAA,IAAA,CAAA,EAAA,CAAA,CAAA,CAAA,IAAA,CAAA,UAAA,CAAA,UAAA;;iBAjCgB,qBAAA;;ACtEhB,CAAA,CAAA,CAAA,QAAA,CAAA,CAAA,CAAA,GAAA,CAAA,UAAA,CAAA,IAAA,CAAA,KAAA,CAAA,IAAA,CAAA,CAAA,CAAA,IAAA,CAAA,UAAA,CAAA,UAAA;;iBDkFgB,kBAAA;;AE3ChB,CAAA,CAAA,CAAA,OAAA,CAAA,GAAA,CAAA,IAAA,CAAA,EAAA,CAAA,CAAA,CAAA,IAAA,CAAA,UAAA,CAAA,IAAA,CAAA,QAAA,CAAA,CAAA,SAAA,CAAA,EAAA,CAAA,CAAA,CAAA,MAAA,CAAA,OAAA;;iBFgEgB,qBAAA;;;;;;iBCvGA,gBAAA;;;;;;iBCuCA,eAAA,WAA0B,eAAe;;;AFwBzD,CAAA,CAAA;AAOA,CAAA,CAAA,CAAA,SAAA,CAAA,CAAA,CAAA,SAAA,CAAA,WAAA,CAAA,GAAA,CAAA,CAAA,CAAA,QAAA,CAAA,CAAA,CAAA,IAAA,CAAA,OAAA;AAYA,CAAA,CAAA;AAqBgB,OAAA,CAAA,QAAA,CGJA,2BAAA,CHIqB,YAAA,CAAA,CAAA,MAAA,CAAA,CAAA,KAAA,CAAA,CGF5B,MHE4B,CAAA,MAAA,CAAA,CGFb,qBHEa,CAAA,CAAA,CAAA,CAAA,MAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/provider/resolveProvider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBAgFgB,eAAA,WAA0B,eAAe"}

package/dist/index.d.ts

@@ -2,49 +2,15 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { _ as ToolProvider, a as ToolCall, d as ExecuteResult, f as JsonSchema, g as ToolExecutionContext, h as ToolDescriptor, i as ProviderToolManifest, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, o as ToolCallResult, p as ResolvedToolDescriptor, r as ProviderManifest, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolSchema, y as TypegenToolDescriptor } from "./runner-ClFrFnz9.js";
-import { n as ExecutorPoolOptions, t as Executor } from "./executor-B7q7K_27.js";
-import { n as isExecuteFailure, r as isJsonSerializable, t as ExecuteFailure } from "./errors-DlbJQYs7.js";
+import { _ as ToolExecutionContext, d as ExecuteResult, f as JsonSchema, g as ToolDescriptor, h as ToolAnnotations, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, p as ResolvedToolDescriptor, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolProvider, y as ToolSchema } from "./runner-DXLu0eJV.js";
+import { n as ExecutorPoolOptions, t as Executor } from "./executor-BOTd9xNK.js";
+import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-BIWv-QIC.js";
 
-//#region src/identifier.d.ts
-/**
- * Returns whether the value is a valid JavaScript identifier.
- */
-declare function isValidIdentifier(value: string): boolean;
-/**
- * Returns whether the identifier is reserved in JavaScript source.
- */
-declare function isReservedWord(value: string): boolean;
-/**
- * Throws when the value cannot be used as a bare JavaScript identifier.
- */
-declare function assertValidIdentifier(value: string, label?: string): void;
-/**
- * Converts a raw identifier-like value into a safe JavaScript identifier.
- */
-declare function sanitizeIdentifier(value: string): string;
-/**
- * Renders the name as a bare identifier when possible, otherwise as a string literal.
- */
-declare function serializePropertyName(name: string): string;
-//#endregion
-//#region src/sanitize.d.ts
-/**
- * Converts a raw tool name into a safe JavaScript identifier.
- */
-declare function sanitizeToolName(name: string): string;
-//#endregion
 //#region src/provider/resolveProvider.d.ts
 /**
  * Resolves a tool provider into the validated, sanitized shape consumed by executors.
  */
 declare function resolveProvider(provider: ToolProvider): ResolvedToolProvider;
 //#endregion
-//#region src/typegen/jsonSchema.d.ts
-/**
- * Generates a namespace declaration for a provider's tool schemas.
- */
-declare function generateTypesFromJsonSchema(providerName: string, tools: Record<string, TypegenToolDescriptor>): string;
-//#endregion
-export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ProviderManifest, type ProviderToolManifest, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolCall, type ToolCallResult, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, type TypegenToolDescriptor, assertValidIdentifier, generateTypesFromJsonSchema, isExecuteFailure, isJsonSerializable, isReservedWord, isValidIdentifier, resolveProvider, sanitizeIdentifier, sanitizeToolName, serializePropertyName };
+export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolAnnotations, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, isExecuteFailure, resolveProvider };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/identifier.ts","../src/sanitize.ts","../src/provider/resolveProvider.ts","../src/typegen/jsonSchema.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBA6DgB,iBAAA;;AAAhB,CAAA,CAAA,CAAA,OAAA,CAAA,OAAA,CAAA,GAAA,CAAA,UAAA,CAAA,EAAA,CAAA,QAAA,CAAA,EAAA,CAAA,UAAA,CAAA,MAAA;AAOA,CAAA,CAAA;AAOgB,OAAA,CAAA,QAAA,CAPA,cAAA,CAOqB,KAAA,CAAA,CAAA,MAAA,CAAA,CAAA,CAAA,OAAA;AAYrC,CAAA,CAAA;AAqBA,CAAA,CAAA,CAAA,MAAA,CAAA,IAAA,CAAA,GAAA,CAAA,KAAA,CAAA,MAAA,CAAA,EAAA,CAAA,IAAA,CAAA,EAAA,CAAA,CAAA,CAAA,IAAA,CAAA,UAAA,CAAA,UAAA;;iBAjCgB,qBAAA;;ACtEhB,CAAA,CAAA,CAAA,QAAA,CAAA,CAAA,CAAA,GAAA,CAAA,UAAA,CAAA,IAAA,CAAA,KAAA,CAAA,IAAA,CAAA,CAAA,CAAA,IAAA,CAAA,UAAA,CAAA,UAAA;;iBDkFgB,kBAAA;;AE3ChB,CAAA,CAAA,CAAA,OAAA,CAAA,GAAA,CAAA,IAAA,CAAA,EAAA,CAAA,CAAA,CAAA,IAAA,CAAA,UAAA,CAAA,IAAA,CAAA,QAAA,CAAA,CAAA,SAAA,CAAA,EAAA,CAAA,CAAA,CAAA,MAAA,CAAA,OAAA;;iBFgEgB,qBAAA;;;;;;iBCvGA,gBAAA;;;;;;iBCuCA,eAAA,WAA0B,eAAe;;;AFwBzD,CAAA,CAAA;AAOA,CAAA,CAAA,CAAA,SAAA,CAAA,CAAA,CAAA,SAAA,CAAA,WAAA,CAAA,GAAA,CAAA,CAAA,CAAA,QAAA,CAAA,CAAA,CAAA,IAAA,CAAA,OAAA;AAYA,CAAA,CAAA;AAqBgB,OAAA,CAAA,QAAA,CGJA,2BAAA,CHIqB,YAAA,CAAA,CAAA,MAAA,CAAA,CAAA,KAAA,CAAA,CGF5B,MHE4B,CAAA,MAAA,CAAA,CGFb,qBHEa,CAAA,CAAA,CAAA,CAAA,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/provider/resolveProvider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBAgFgB,eAAA,WAA0B,eAAe"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { c as isReservedWord, d as serializePropertyName, l as isValidIdentifier, n as generateTypesFromJsonSchema, o as sanitizeToolName, s as assertValidIdentifier, t as resolveProvider, u as sanitizeIdentifier } from "./resolveProvider-UqQxdF4j.js";
-import { n as isExecuteFailure, r as isJsonSerializable, t as ExecuteFailure } from "./errors-wS8yjQhS.js";
+import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-DdWVEGU8.js";
+import { t as resolveProvider } from "./resolveProvider-CMrXPuTx.js";
 
-export { ExecuteFailure, assertValidIdentifier, generateTypesFromJsonSchema, isExecuteFailure, isJsonSerializable, isReservedWord, isValidIdentifier, resolveProvider, sanitizeIdentifier, sanitizeToolName, serializePropertyName };
+export { ExecuteFailure, isExecuteFailure, resolveProvider };

package/dist/mcp/index.cjs

@@ -1,4 +1,4 @@
-const require_resolveProvider = require('../resolveProvider-BZYSw8Qk.cjs');
+const require_resolveProvider = require('../resolveProvider-DFAg6No5.cjs');
 require('../errors-xD8r6fCf.cjs');
 let zod = require("zod");
 zod = require_resolveProvider.__toESM(zod);
@@ -25,16 +25,26 @@ const MCP_CALL_TOOL_RESULT_TYPE = [
 	"};"
 ].join("\n");
 /**
+* Generates one wrapped MCP tool declaration exposed to guest code.
+*/
+function generateMcpWrappedToolType(provider, safeName) {
+	const tool = provider.tools[safeName];
+	if (!tool) throw new Error(`Unknown wrapped MCP tool: ${safeName}`);
+	return [require_resolveProvider.renderDocComment([...tool.description ? [tool.description, ""] : [], "Wrapped MCP tool. Inspect structuredContent first, then fall back to content text items."]), `function ${safeName}(input: ${require_resolveProvider.schemaToType(tool.inputSchema)}): Promise<McpCallToolResult>;`].filter(Boolean).join("\n");
+}
+/**
 * Generates the wrapped MCP tool namespace declarations exposed to guest code.
 */
 function generateMcpWrappedToolTypes(provider) {
-	const declarations = [MCP_CALL_TOOL_RESULT_TYPE];
-	for (const [safeName, tool] of Object.entries(provider.tools)) {
-		const comment = require_resolveProvider.renderDocComment([...tool.description ? [tool.description, ""] : [], "Wrapped MCP tool. Inspect structuredContent first, then fall back to content text items."]);
-		declarations.push([comment, `function ${safeName}(input: ${require_resolveProvider.schemaToType(tool.inputSchema)}): Promise<McpCallToolResult>;`].filter(Boolean).join("\n"));
-	}
+	const declarations = [MCP_CALL_TOOL_RESULT_TYPE, ...Object.keys(provider.tools).map((safeName) => generateMcpWrappedToolType(provider, safeName))];
 	return require_resolveProvider.renderNamespaceDeclaration(provider.name, declarations);
 }
+/**
+* Generates the wrapped MCP tool namespace declaration for one selected tool.
+*/
+function generateMcpWrappedSingleToolTypes(provider, safeName) {
+	return require_resolveProvider.renderNamespaceDeclaration(provider.name, [MCP_CALL_TOOL_RESULT_TYPE, generateMcpWrappedToolType(provider, safeName)]);
+}
 
 //#endregion
 //#region src/mcp/createMcpToolProvider.ts
@@ -53,6 +63,9 @@ async function closeAll(closers) {
 	const rejected = (await Promise.allSettled(closers.map((close) => close()))).find((result) => result.status === "rejected");
 	if (rejected) throw rejected.reason;
 }
+function asJsonSchema(schema) {
+	return typeof schema === "object" && schema !== null ? schema : void 0;
+}
 async function openMcpToolClient(source, clientInfo) {
 	if ("client" in source) return {
 		client: source.client,
@@ -86,11 +99,13 @@ async function openMcpToolProvider(source, options = {}) {
 	const connection = await openMcpToolClient(source, options.clientInfo ?? DEFAULT_MCP_TOOL_CLIENT_INFO);
 	try {
 		const toolsResponse = await connection.client.listTools();
+		const toolsByOriginalName = new Map(toolsResponse.tools.map((tool) => [tool.name, tool]));
 		const provider = {
 			name: options.namespace ?? "mcp",
 			tools: {}
 		};
 		for (const tool of toolsResponse.tools) provider.tools[tool.name] = {
+			annotations: tool.annotations,
 			description: tool.description,
 			execute: async (input, context) => {
 				const argumentsObject = typeof input === "object" && input !== null ? input : void 0;
@@ -102,13 +117,25 @@ async function openMcpToolProvider(source, options = {}) {
 			inputSchema: tool.inputSchema
 		};
 		const resolvedProvider = require_resolveProvider.resolveProvider(provider);
+		const toolDefinitions = Object.fromEntries(Object.entries(resolvedProvider.tools).map(([safeName, descriptor]) => {
+			const upstreamTool = toolsByOriginalName.get(descriptor.originalName);
+			return [safeName, {
+				annotations: descriptor.annotations,
+				description: descriptor.description,
+				inputSchema: descriptor.inputSchema,
+				originalName: descriptor.originalName,
+				outputSchema: asJsonSchema(upstreamTool?.outputSchema),
+				safeName: descriptor.safeName
+			}];
+		}));
 		return {
 			close: connection.close,
 			provider: {
 				...resolvedProvider,
 				types: generateMcpWrappedToolTypes(resolvedProvider)
 			},
-			serverInfo: getMcpToolSourceServerInfo(source)
+			serverInfo: getMcpToolSourceServerInfo(source),
+			toolDefinitions
 		};
 	} catch (error) {
 		await connection.close().catch(() => {});
@@ -126,6 +153,18 @@ async function createMcpToolProvider(source, options = {}) {
 //#endregion
 //#region src/mcp/codeMcpServer.ts
 const DEFAULT_MAX_TEXT_CHARS = 24e3;
+const CODE_EXECUTION_TOOL_ANNOTATIONS = {
+	destructiveHint: true,
+	idempotentHint: false,
+	openWorldHint: true,
+	readOnlyHint: false
+};
+const READ_ONLY_TOOL_ANNOTATIONS = {
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false,
+	readOnlyHint: true
+};
 const DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO = {
 	name: "mcp-code-wrapper",
 	version: "0.0.0"
@@ -136,32 +175,41 @@ function truncateText(text, maxTextChars) {
 function renderText(value, maxTextChars) {
 	return truncateText(JSON.stringify(value, null, 2), maxTextChars);
 }
-function searchTools(provider, query, limit) {
+function searchTools(toolDefinitions, namespace, query, limit) {
 	const normalizedQuery = query?.toLowerCase().trim();
-	const matches = Object.entries(provider.tools).map(([safeName, descriptor]) => ({
-		description: descriptor.description,
-		inputSchema: descriptor.inputSchema,
-		originalName: descriptor.originalName,
-		outputSchema: descriptor.outputSchema,
-		safeName
-	})).filter((tool) => {
-		if (!normalizedQuery) return true;
-		return [
-			tool.originalName,
-			tool.safeName,
-			tool.description ?? ""
-		].some((field) => field.toLowerCase().includes(normalizedQuery));
-	}).slice(0, limit);
 	return {
-		namespace: provider.name,
-		originalToSafeName: provider.originalToSafeName,
-		safeToOriginalName: provider.safeToOriginalName,
-		tools: matches,
-		types: provider.types
+		namespace,
+		tools: Object.values(toolDefinitions).filter((tool) => {
+			if (!normalizedQuery) return true;
+			return [
+				tool.originalName,
+				tool.safeName,
+				tool.description ?? ""
+			].some((field) => field.toLowerCase().includes(normalizedQuery));
+		}).slice(0, limit).map((tool) => ({
+			annotations: tool.annotations,
+			description: tool.description,
+			originalName: tool.originalName,
+			safeName: tool.safeName
+		}))
+	};
+}
+function getToolDetails(provider, toolDefinitions, safeName) {
+	const tool = toolDefinitions[safeName];
+	if (!tool) throw new Error(`Unknown wrapped MCP tool: ${safeName}`);
+	return {
+		annotations: tool.annotations,
+		description: tool.description,
+		inputSchema: tool.inputSchema,
+		originalName: tool.originalName,
+		outputSchema: tool.outputSchema,
+		safeName: tool.safeName,
+		types: generateMcpWrappedSingleToolTypes(provider, safeName)
 	};
 }
 function registerExecuteTool(server, name, provider, executor, maxTextChars, description) {
 	server.registerTool.bind(server)(name, {
+		annotations: CODE_EXECUTION_TOOL_ANNOTATIONS,
 		description,
 		inputSchema: { code: zod.string() }
 	}, async (args) => {
@@ -176,15 +224,32 @@ function registerExecuteTool(server, name, provider, executor, maxTextChars, des
 		};
 	});
 }
-function registerSearchTool(server, name, provider, maxTextChars) {
+function registerSearchTool(server, name, namespace, toolDefinitions, maxTextChars) {
 	server.registerTool.bind(server)(name, {
-		description: `Search wrapped MCP tools exposed under the ${provider.name} namespace.`,
+		annotations: READ_ONLY_TOOL_ANNOTATIONS,
+		description: `Search wrapped MCP tools exposed under the ${namespace} namespace. Returns concise catalog entries only; call the details tool for schemas.`,
 		inputSchema: {
 			limit: zod.number().int().optional(),
 			query: zod.string().optional()
 		}
 	}, async (args) => {
-		const structuredContent = searchTools(provider, args.query, args.limit ?? 20);
+		const structuredContent = searchTools(toolDefinitions, namespace, args.query, args.limit ?? 20);
+		return {
+			content: [{
+				text: renderText(structuredContent, maxTextChars),
+				type: "text"
+			}],
+			structuredContent
+		};
+	});
+}
+function registerDetailsTool(server, name, provider, toolDefinitions, maxTextChars) {
+	server.registerTool.bind(server)(name, {
+		annotations: READ_ONLY_TOOL_ANNOTATIONS,
+		description: `Return the full schema and generated TypeScript declaration for one wrapped ${provider.name} MCP tool.`,
+		inputSchema: { safeName: zod.string() }
+	}, async (args) => {
+		const structuredContent = getToolDetails(provider, toolDefinitions, args.safeName);
 		return {
 			content: [{
 				text: renderText(structuredContent, maxTextChars),
@@ -211,8 +276,9 @@ function attachOwnedClose(server, closeOwnedResources) {
 */
 async function codeMcpServer(source, options) {
 	const maxTextChars = options.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS;
-	const mode = options.mode ?? "both";
+	const mode = options.mode ?? "progressive";
 	const names = {
+		details: options.names?.details ?? "mcp_get_tool_details",
 		execute: options.names?.execute ?? "mcp_execute_code",
 		search: options.names?.search ?? "mcp_search_tools",
 		single: options.names?.single ?? "mcp_code"
@@ -224,9 +290,10 @@ async function codeMcpServer(source, options) {
 	const provider = handle.provider;
 	const server = new __modelcontextprotocol_sdk_server_mcp_js.McpServer(options.serverInfo ?? handle.serverInfo ?? DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO);
 	try {
-		if (mode === "both" || mode === "split") {
-			registerSearchTool(server, names.search, provider, maxTextChars);
-			registerExecuteTool(server, names.execute, provider, options.executor, maxTextChars, `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace.`);
+		if (mode === "both" || mode === "progressive") {
+			registerSearchTool(server, names.search, provider.name, handle.toolDefinitions, maxTextChars);
+			registerDetailsTool(server, names.details, provider, handle.toolDefinitions, maxTextChars);
+			registerExecuteTool(server, names.execute, provider, options.executor, maxTextChars, `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace. Use the search and details tools before writing code.`);
 		}
 		if (mode === "both" || mode === "single") registerExecuteTool(server, names.single, provider, options.executor, maxTextChars, `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace.\n\n${provider.types}`);
 		return attachOwnedClose(server, handle.close);