@yolk-sdk/codemode 0.1.0-canary.96 → 0.1.0-canary.98

package/README.md

@@ -6,11 +6,11 @@ resolved tools, filters and aggregates their results, and returns only what matt
 ## Install
 
 ```bash
-pnpm add @yolk-sdk/codemode@canary @yolk-sdk/agent@canary effect@4.0.0-rc.115
+pnpm add @yolk-sdk/codemode@canary @yolk-sdk/agent@canary effect@4.0.0
 ```
 
 Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
-Use the SDK's matching Effect version (`4.0.0-rc.115`) in host code.
+Use the SDK's matching Effect version (`4.0.0`) in host code.
 Requires Node.js 22.19+ (the pi engine's minimum). `@yolk-sdk/codemode/node` is server-only.
 
 ## Subpaths
@@ -58,8 +58,20 @@ const program = Effect.gen(function* () {
   truncated error, and usage. Nested results never reach the model; only the script output and
   return value do.
 - A call resolves to `structuredContent` for tools with an output schema and to the text content
-  otherwise; error results reject with an `Error` carrying their text. Calls still running when
-  the script ends are cancelled and recorded as `cancelled`.
+  otherwise; error results, `beforeNestedCall` failures, and calls past `maxNestedCalls` reject
+  with an `Error` whose message is `tools.<id>: <text>`, or `tools["<name>"]: <text>` for a tool
+  whose identifier an earlier tool already uses (the nested-call record keeps the raw text). Calls
+  still running when the script ends are cancelled and recorded as `cancelled`.
+- Arguments make a JSON round trip: `undefined` keys and `null` optionals are absent, unknown keys
+  reject with a hint naming the allowed keys, and values JSON would silently change (`NaN`,
+  `Infinity`, invalid `Date`s, `undefined` array items, `Map`, `Set`, functions, class instances)
+  reject in the script before the call, with messages such as
+  `tools.search: argument at limit is NaN; pass a finite number or omit the key`. The pi executor
+  reads the argument once (getters and `toJSON` run once) into a checked JSON copy and sends that
+  copy; a valid `Date` passes as its ISO string. Arguments with more than 100,000 values or more
+  than 64 levels of nesting are rejected, never sent unchecked. Custom executors follow the same
+  rules (`CodeModeExecutorTool`) and label rejections with `CodeModeExecutorTool.callLabel`, which
+  `makeCodeModeTool` sets.
 - The tool description lists the globals and the nested tools by namespace, with the module's
   `ToolModule.description` under each heading. `codemode` + `listed` tools get TypeScript
   declarations within `inlineBudget` (default 3,000 estimated tokens, filled fairly across
@@ -80,9 +92,9 @@ const program = Effect.gen(function* () {
   keeps the 256 KiB-per-value and 1 MiB-total bounds by dropping offending writes. Transcript
   `ToolResultMessage`s carry no tool name: pair each with its assistant tool call's name.
 - `beforeNestedCall({ call, context })` runs before each nested call; a failure rejects that call in
-  the script with the message and records it as `error` without executing it.
-- A nested call that is interrupted rejects with `was cancelled`; a defect rejects with `failed
-unexpectedly`. If an executor misses its deadline, the tool returns a `timeout` failure
+  the script with `<label>: <message>` and records it as `error` without executing it.
+- A nested call that is interrupted rejects with `<label> was cancelled.`; a defect rejects with
+  `<label> failed unexpectedly.` (the same label as above). If an executor misses its deadline, the tool returns a `timeout` failure
   `timeoutMs` + 5 s after the start and aborts it.
 
 ## Limits

package/dist/catalog.d.mts

@@ -9,7 +9,13 @@ type CodeModeToolExposure = 'all' | 'listed' | 'search';
 /** One nested tool as scripts see it. */
 type CodeModeCatalogTool = {
   /** Raw tool name; scripts may call `tools["<name>"](args)`. */readonly name: string; /** Identifier for `tools.<identifier>(args)` (invalid identifier characters become `_`). */
-  readonly identifier: string; /** The tool's `ToolModule.id`. */
+  readonly identifier: string;
+  /**
+   * How scripts call this tool, used to prefix its rejections: `tools.<identifier>`, or
+   * `tools["<name>"]` when an earlier tool already has the identifier (see `codeModeCallLabels`;
+   * when the name is taken too, the tool is unreachable and the label only names it).
+   */
+  readonly callLabel: string; /** The tool's `ToolModule.id`. */
   readonly namespace: string; /** The module's `ToolModule.description`, when set. */
   readonly namespaceDescription?: string;
   readonly description: string;
@@ -18,6 +24,14 @@ type CodeModeCatalogTool = {
   readonly structured: boolean;
   readonly exposure: CodeModeToolExposure;
 };
+/**
+ * The call label of each tool name, in order, as pi binds `tools`: each tool takes
+ * `tools[<identifier>]` unless an earlier tool holds that key (first tool wins), then
+ * `tools[<name>]` if still free. The label is `tools.<identifier>` for the tool that holds its
+ * identifier, otherwise `tools["<name>"]`. The executor guard and the host rejection prefix share
+ * it, so both name a call the same way.
+ */
+declare const codeModeCallLabels: (names: ReadonlyArray<string>) => ReadonlyArray<string>;
 /** Catalog of nested tools in resolution order. */
 declare const codeModeCatalog: (tools: ReadonlyArray<NestedTool>) => ReadonlyArray<CodeModeCatalogTool>;
 /** Default inline budget of the nested tool listing, in estimated tokens. */
@@ -56,5 +70,5 @@ declare const describeCodeModeTool: (tool: CodeModeCatalogTool) => string;
 /** Finds a tool by identifier or raw name. */
 declare const findCodeModeTool: (catalog: ReadonlyArray<CodeModeCatalogTool>, name: string) => CodeModeCatalogTool | undefined;
 //#endregion
-export { CodeModeCatalogTool, CodeModeDescriptionInput, CodeModeListing, CodeModeToolExposure, codeModeCatalog, defaultCodeModeInlineBudget, describeCodeModeTool, estimateCodeModeTokens, findCodeModeTool, renderCodeModeDescription, selectCodeModeListing };
+export { CodeModeCatalogTool, CodeModeDescriptionInput, CodeModeListing, CodeModeToolExposure, codeModeCallLabels, codeModeCatalog, defaultCodeModeInlineBudget, describeCodeModeTool, estimateCodeModeTokens, findCodeModeTool, renderCodeModeDescription, selectCodeModeListing };
 //# sourceMappingURL=catalog.d.mts.map

package/dist/catalog.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.mts","names":[],"sources":["../src/catalog.ts"],"mappings":";;;;;;AAcA;KAAY,oBAAA;;KAGA,mBAAA;EAHoB,wEAKrB,IAAA,UAFoB;EAAA,SAIpB,UAAA,UAMa;EAAA,SAJb,SAAA,UASU;EAAA,SAPV,oBAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,EAAa,kBAAA,EANb;EAAA,SAQA,YAAA,EAAc,kBAAA,EAJd;EAAA,SAMA,UAAA;EAAA,SACA,QAAA,EAAU,oBAAA;AAAA;;cAMR,eAAA,GACX,KAAA,EAAO,aAAA,CAAc,UAAA,MACpB,aAAA,CAAc,mBAAA;;cAmBJ,2BAAA;;cAGA,sBAAA,GAA0B,IAAY;AAAA,KA4DvC,eAAA;EApFC;;;EAAA,SAwFF,MAAA,EAAQ,aAAA,CAAc,mBAAA,GAvFxB;EAAA,SAyFE,kBAAA,EAAoB,aAAA;AAAA;;;;;;;cASlB,qBAAA,GACX,OAAA,EAAS,aAAA,CAAc,mBAAA,GACvB,MAAA,aACC,eAAA;AAAA,KAuFS,wBAAA;EAAA,SACD,KAAA,EAAO,aAAa,CAAC,UAAA;EAAA,SACrB,YAAA,WA1K6B;EAAA,SA4K7B,KAAA;AAAA;AA5K6B;AAGxC;;;;AAAmD;AA4DnD;AA/DwC,cAsL3B,yBAAA,GAA6B,KAA+B,EAAxB,wBAAwB;;cAwB5D,oBAAA,GAAwB,IAAyB,EAAnB,mBAAmB;;cAIjD,gBAAA,GACX,OAAA,EAAS,aAAA,CAAc,mBAAA,GACvB,IAAA,aACC,mBAAA"}
+{"version":3,"file":"catalog.d.mts","names":[],"sources":["../src/catalog.ts"],"mappings":";;;;;;AAcA;KAAY,oBAAA;;KAGA,mBAAA;EAHoB,wEAKrB,IAAA,UAFoB;EAAA,SAIpB,UAAA;EAYa;;;;;EAAA,SANb,SAAA,UANA;EAAA,SAQA,SAAA;EAAA,SAEA,oBAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,EAAa,kBAAA,EAAA;EAAA,SAEb,YAAA,EAAc,kBAAA,EAAA;EAAA,SAEd,UAAA;EAAA,SACA,QAAA,EAAU,oBAAA;AAAA;;AAAoB;AAYzC;;;;;cAAa,kBAAA,GAAsB,KAAA,EAAO,aAAA,aAAwB,aAAa;;cAelE,eAAA,GACX,KAAA,EAAO,aAAA,CAAc,UAAA,MACpB,aAAA,CAAc,mBAAA;AAjB8D;AAAA,cAwClE,2BAAA;;cAGA,sBAAA,GAA0B,IAAY;AAAA,KA4DvC,eAAA;EAvFH;;;EAAA,SA2FE,MAAA,EAAQ,aAAA,CAAc,mBAAA,GA1FjB;EAAA,SA4FL,kBAAA,EAAoB,aAAA;AAAA;;;;;AA5FK;AAuBpC;cA8Ea,qBAAA,GACX,OAAA,EAAS,aAAA,CAAc,mBAAA,GACvB,MAAA,aACC,eAAA;AAAA,KAuFS,wBAAA;EAAA,SACD,KAAA,EAAO,aAAa,CAAC,UAAA;EAAA,SACrB,YAAA,WAvKE;EAAA,SAyKF,KAAA;AAAA;;AAzKwC;AA4DnD;;;;;cAuHa,yBAAA,GAA6B,KAA+B,EAAxB,wBAAwB;;cAwB5D,oBAAA,GAAwB,IAAyB,EAAnB,mBAAmB;;cAIjD,gBAAA,GACX,OAAA,EAAS,aAAA,CAAc,mBAAA,GACvB,IAAA,aACC,mBAAA"}

package/dist/catalog.mjs

@@ -3,23 +3,44 @@ import { renderDeclarations, renderToolOutputType, renderToolSample, toCodemodeI
 import { toolDiscovery } from "@yolk-sdk/agent/protocol";
 //#region src/catalog.ts
 const textOutputSchema = { type: "string" };
+/**
+* The call label of each tool name, in order, as pi binds `tools`: each tool takes
+* `tools[<identifier>]` unless an earlier tool holds that key (first tool wins), then
+* `tools[<name>]` if still free. The label is `tools.<identifier>` for the tool that holds its
+* identifier, otherwise `tools["<name>"]`. The executor guard and the host rejection prefix share
+* it, so both name a call the same way.
+*/
+const codeModeCallLabels = (names) => {
+	const bound = /* @__PURE__ */ new Set();
+	return names.map((name) => {
+		const identifier = toCodemodeIdentifier(name);
+		const ownsIdentifier = !bound.has(identifier);
+		bound.add(identifier);
+		bound.add(name);
+		return ownsIdentifier ? `tools.${identifier}` : `tools[${JSON.stringify(name)}]`;
+	});
+};
 /** Catalog of nested tools in resolution order. */
-const codeModeCatalog = (tools) => tools.map(({ def, moduleId, moduleDescription }) => {
-	const tool = {
-		name: def.name,
-		identifier: toCodemodeIdentifier(def.name),
-		namespace: moduleId,
-		description: def.description,
-		inputSchema: def.parameters,
-		outputSchema: def.outputSchema ?? textOutputSchema,
-		structured: def.outputSchema !== void 0,
-		exposure: toolDiscovery(def) ?? "all"
-	};
-	return moduleDescription === void 0 ? tool : {
-		...tool,
-		namespaceDescription: moduleDescription
-	};
-});
+const codeModeCatalog = (tools) => {
+	const labels = codeModeCallLabels(tools.map(({ def }) => def.name));
+	return tools.map(({ def, moduleId, moduleDescription }, index) => {
+		const tool = {
+			name: def.name,
+			identifier: toCodemodeIdentifier(def.name),
+			callLabel: labels[index] ?? `tools[${JSON.stringify(def.name)}]`,
+			namespace: moduleId,
+			description: def.description,
+			inputSchema: def.parameters,
+			outputSchema: def.outputSchema ?? textOutputSchema,
+			structured: def.outputSchema !== void 0,
+			exposure: toolDiscovery(def) ?? "all"
+		};
+		return moduleDescription === void 0 ? tool : {
+			...tool,
+			namespaceDescription: moduleDescription
+		};
+	});
+};
 /** Default inline budget of the nested tool listing, in estimated tokens. */
 const defaultCodeModeInlineBudget = 3e3;
 /** Estimated tokens of a text: four characters per token, rounded up. */
@@ -88,7 +109,7 @@ const selectCodeModeListing = (catalog, budget) => {
 const intro = [
 	"Run a JavaScript script that calls tools and returns only what matters.",
 	"`code` is the body of an async function: top-level `await` and `return` work. Write plain JavaScript; simple TypeScript annotations are stripped. There is no Node.js, network, filesystem, `require`, `fetch`, or timers.",
-	"Call tools as `await tools.<id>(args)`. A call resolves to the declared result type and rejects with an Error when the tool fails. Calls still running when the script ends are cancelled, so await every call (use `Promise.all` for parallel calls).",
+	"Call tools as `await tools.<id>(args)`. Arguments must be plain JSON (no `NaN`, `undefined` array items, `Map`, or functions). A call resolves to the declared result type and rejects with an Error whose message starts with `tools.<id>:` when the tool fails. Calls still running when the script ends are cancelled, so await every call (use `Promise.all` for parallel calls).",
 	"Only the script output and its return value come back to you: filter and aggregate inside the script and return a small JSON value."
 ].join("\n");
 const globalLines = (store) => [
@@ -138,6 +159,6 @@ const describeCodeModeTool = (tool) => renderToolSample(declarationTool(tool));
 /** Finds a tool by identifier or raw name. */
 const findCodeModeTool = (catalog, name) => catalog.find((tool) => tool.identifier === name) ?? catalog.find((tool) => tool.name === name);
 //#endregion
-export { codeModeCatalog, defaultCodeModeInlineBudget, describeCodeModeTool, estimateCodeModeTokens, findCodeModeTool, renderCodeModeDescription, selectCodeModeListing };
+export { codeModeCallLabels, codeModeCatalog, defaultCodeModeInlineBudget, describeCodeModeTool, estimateCodeModeTokens, findCodeModeTool, renderCodeModeDescription, selectCodeModeListing };
 
 //# sourceMappingURL=catalog.mjs.map

package/dist/catalog.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.mjs","names":[],"sources":["../src/catalog.ts"],"sourcesContent":["import { Predicate } from 'effect'\nimport {\n  renderDeclarations,\n  renderToolOutputType,\n  renderToolSample,\n  toCodemodeIdentifier\n} from '@earendil-works/pi-codemode/declarations'\nimport { toolDiscovery } from '@yolk-sdk/agent/protocol'\nimport type { NestedTool } from '@yolk-sdk/agent/tools'\nimport type { CodeModeJsonSchema } from './executor.ts'\n\n/** How a nested tool reaches scripts: `all` tools are also direct model tools; `listed` and\n * `search` are the two discovery modes of `codemode`-only tools.\n */\nexport type CodeModeToolExposure = 'all' | 'listed' | 'search'\n\n/** One nested tool as scripts see it. */\nexport type CodeModeCatalogTool = {\n  /** Raw tool name; scripts may call `tools[\"<name>\"](args)`. */\n  readonly name: string\n  /** Identifier for `tools.<identifier>(args)` (invalid identifier characters become `_`). */\n  readonly identifier: string\n  /** The tool's `ToolModule.id`. */\n  readonly namespace: string\n  /** The module's `ToolModule.description`, when set. */\n  readonly namespaceDescription?: string\n  readonly description: string\n  readonly inputSchema: CodeModeJsonSchema\n  /** The declared output schema, or `{ type: 'string' }` for text results. */\n  readonly outputSchema: CodeModeJsonSchema\n  /** True when the tool declares an output schema (calls resolve to `structuredContent`). */\n  readonly structured: boolean\n  readonly exposure: CodeModeToolExposure\n}\n\nconst textOutputSchema: CodeModeJsonSchema = { type: 'string' }\n\n/** Catalog of nested tools in resolution order. */\nexport const codeModeCatalog = (\n  tools: ReadonlyArray<NestedTool>\n): ReadonlyArray<CodeModeCatalogTool> =>\n  tools.map(({ def, moduleId, moduleDescription }) => {\n    const tool: CodeModeCatalogTool = {\n      name: def.name,\n      identifier: toCodemodeIdentifier(def.name),\n      namespace: moduleId,\n      description: def.description,\n      inputSchema: def.parameters,\n      outputSchema: def.outputSchema ?? textOutputSchema,\n      structured: def.outputSchema !== undefined,\n      exposure: toolDiscovery(def) ?? 'all'\n    }\n\n    return moduleDescription === undefined\n      ? tool\n      : { ...tool, namespaceDescription: moduleDescription }\n  })\n\n/** Default inline budget of the nested tool listing, in estimated tokens. */\nexport const defaultCodeModeInlineBudget = 3000\n\n/** Estimated tokens of a text: four characters per token, rounded up. */\nexport const estimateCodeModeTokens = (text: string): number => Math.ceil(text.length / 4)\n\nconst maxShortTypeChars = 60\n\nconst shortType = (schema: CodeModeJsonSchema): string => {\n  const rendered = renderToolOutputType(schema)\n\n  if (rendered.length <= maxShortTypeChars) return rendered\n\n  if (!Predicate.isBoolean(schema)) {\n    if (schema.type === 'array') return 'Array<unknown>'\n\n    if (schema.type === 'object') return 'object'\n  }\n\n  return 'unknown'\n}\n\n// Declarations only read names, descriptions, and schemas; `execute` is never called.\nconst declarationTool = (tool: CodeModeCatalogTool) => ({\n  name: tool.name,\n  description: tool.description,\n  inputSchema: tool.inputSchema,\n  outputSchema: tool.outputSchema,\n  execute: () => undefined\n})\n\nconst directToolLine = (tool: CodeModeCatalogTool) =>\n  `- \\`tools.${tool.identifier}(args)\\` takes the arguments of the \\`${tool.name}\\` tool and resolves to \\`${shortType(tool.outputSchema)}\\`.`\n\nconst declarationMembers = (tools: ReadonlyArray<CodeModeCatalogTool>) =>\n  renderDeclarations({ tools: tools.map(declarationTool) })\n\ntype Candidate = {\n  readonly tool: CodeModeCatalogTool\n  readonly index: number\n  readonly cost: number\n}\n\nconst candidateCost = (tool: CodeModeCatalogTool) =>\n  estimateCodeModeTokens(declarationMembers([tool]))\n\nconst groupByNamespace = <A extends { readonly tool: CodeModeCatalogTool }>(\n  items: ReadonlyArray<A>\n): ReadonlyMap<string, ReadonlyArray<A>> => {\n  const groups = new Map<string, Array<A>>()\n\n  for (const item of items) {\n    const group = groups.get(item.tool.namespace)\n\n    if (group === undefined) {\n      groups.set(item.tool.namespace, [item])\n    } else {\n      group.push(item)\n    }\n  }\n\n  return groups\n}\n\nexport type CodeModeListing = {\n  /** Tools placed in the description, in catalog order: every `all` tool, and the `listed` tools\n   * that fit the budget.\n   */\n  readonly listed: ReadonlyArray<CodeModeCatalogTool>\n  /** Namespaces (catalog order) with callable tools the description does not list. */\n  readonly unlistedNamespaces: ReadonlyArray<string>\n}\n\n/**\n * Chooses the tools the description lists. `all` tools are always placed, outside the budget\n * (the model already has their declarations). `listed` tools fill `budget` estimated tokens fairly\n * across namespaces: each round, every namespace still in play places its cheapest remaining tool;\n * a namespace whose next tool does not fit drops out. `search` tools are never candidates.\n */\nexport const selectCodeModeListing = (\n  catalog: ReadonlyArray<CodeModeCatalogTool>,\n  budget: number\n): CodeModeListing => {\n  const candidates = catalog.flatMap((tool, index): ReadonlyArray<Candidate> =>\n    tool.exposure === 'listed' ? [{ tool, index, cost: candidateCost(tool) }] : []\n  )\n\n  const queues = new Map(\n    [...groupByNamespace(candidates)].map(([namespace, group]) => [\n      namespace,\n      [...group].sort((left, right) => left.cost - right.cost || left.index - right.index)\n    ])\n  )\n\n  const placed = new Set(catalog.flatMap((tool, index) => (tool.exposure === 'all' ? [index] : [])))\n\n  const inPlay = new Set(queues.keys())\n  let remaining = budget\n\n  while (inPlay.size > 0) {\n    for (const [namespace, queue] of queues) {\n      if (!inPlay.has(namespace)) continue\n\n      const next = queue.shift()\n\n      if (next === undefined || next.cost > remaining) {\n        inPlay.delete(namespace)\n        continue\n      }\n\n      placed.add(next.index)\n      remaining -= next.cost\n    }\n  }\n\n  const unlisted = new Set(\n    catalog.flatMap((tool, index) => (placed.has(index) ? [] : [tool.namespace]))\n  )\n\n  return {\n    listed: catalog.filter((_, index) => placed.has(index)),\n    unlistedNamespaces: [...new Set(catalog.map(tool => tool.namespace))].filter(namespace =>\n      unlisted.has(namespace)\n    )\n  }\n}\n\nconst intro = [\n  'Run a JavaScript script that calls tools and returns only what matters.',\n  '`code` is the body of an async function: top-level `await` and `return` work. Write plain JavaScript; simple TypeScript annotations are stripped. There is no Node.js, network, filesystem, `require`, `fetch`, or timers.',\n  'Call tools as `await tools.<id>(args)`. A call resolves to the declared result type and rejects with an Error when the tool fails. Calls still running when the script ends are cancelled, so await every call (use `Promise.all` for parallel calls).',\n  'Only the script output and its return value come back to you: filter and aggregate inside the script and return a small JSON value.'\n].join('\\n')\n\nconst globalLines = (store: boolean) => [\n  '- `text(value)` and `console.log(...values)`: append text to the output.',\n  '- `image(dataUrl)`: append a base64 image (a `data:` URL or `{ type: \"image\", data, mimeType }`).',\n  '- `exit()`: end the script successfully.',\n  '- `ALL_TOOLS`: `{ name, description }` of every callable tool.',\n  '- `await searchTools(query, { limit?, namespace? })`: find tools by topic; resolves to `Array<{ name: string; description: string }>` (default limit 8).',\n  '- `await describeTool(name)`: the description and TypeScript declaration of a tool, or `undefined`.',\n  '- `await describeNamespace(name)`: `{ name, description?, tools: Array<{ name, description }> }` for a namespace, or `undefined`.',\n  ...(store\n    ? [\n        '- `store(key, value)` and `load(key)`: keep small JSON values for later scripts; writes are saved only when the script succeeds.'\n      ]\n    : [])\n]\n\nconst namespaceSection = (namespace: string, tools: ReadonlyArray<CodeModeCatalogTool>) => {\n  const declared = tools.filter(tool => tool.exposure !== 'all')\n  const direct = tools.filter(tool => tool.exposure === 'all')\n\n  const description = tools.find(\n    tool => tool.namespaceDescription !== undefined\n  )?.namespaceDescription\n\n  return [\n    `### ${namespace}`,\n    ...(description === undefined ? [] : [description]),\n    ...(declared.length > 0 ? ['```ts', declarationMembers(declared), '```'] : []),\n    ...direct.map(directToolLine)\n  ].join('\\n')\n}\n\n// Fixed text: never derived from `search` tools or from which tools did not fit the budget.\nconst unlistedToolsLine =\n  'More tools may be callable than are listed here: find them with `await searchTools(query, { namespace? })` and read one with `await describeTool(name)` or `await describeNamespace(name)` before calling it.'\n\nexport type CodeModeDescriptionInput = {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly inlineBudget?: number\n  /** Mention `store()`/`load()` persistence. */\n  readonly store?: boolean\n}\n\n/**\n * The code mode tool description: intro, globals one per line, then nested tools grouped by\n * namespace, then one fixed line pointing to `searchTools`/`describeTool`/`describeNamespace`.\n * `all` tools get one line each outside the budget; `listed` tools are declared within the inline\n * budget; `search` tools never contribute, so adding or removing them (even whole namespaces of\n * them) leaves the text byte-identical.\n */\nexport const renderCodeModeDescription = (input: CodeModeDescriptionInput): string => {\n  const catalog = codeModeCatalog(input.tools)\n\n  const listing = selectCodeModeListing(catalog, input.inlineBudget ?? defaultCodeModeInlineBudget)\n\n  const sections = [...groupByNamespace(listing.listed.map(tool => ({ tool })))].map(\n    ([namespace, items]) =>\n      namespaceSection(\n        namespace,\n        items.map(item => item.tool)\n      )\n  )\n\n  return [\n    intro,\n    ['Globals:', ...globalLines(input.store === true)].join('\\n'),\n    sections.length === 0\n      ? 'Nested tools: none are listed here.'\n      : ['## Nested tools by namespace', ...sections].join('\\n\\n'),\n    unlistedToolsLine\n  ].join('\\n\\n')\n}\n\n/** `describeTool` text: the description and TypeScript declaration of one tool. */\nexport const describeCodeModeTool = (tool: CodeModeCatalogTool): string =>\n  renderToolSample(declarationTool(tool))\n\n/** Finds a tool by identifier or raw name. */\nexport const findCodeModeTool = (\n  catalog: ReadonlyArray<CodeModeCatalogTool>,\n  name: string\n): CodeModeCatalogTool | undefined =>\n  catalog.find(tool => tool.identifier === name) ?? catalog.find(tool => tool.name === name)\n"],"mappings":"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"}
+{"version":3,"file":"catalog.mjs","names":[],"sources":["../src/catalog.ts"],"sourcesContent":["import { Predicate } from 'effect'\nimport {\n  renderDeclarations,\n  renderToolOutputType,\n  renderToolSample,\n  toCodemodeIdentifier\n} from '@earendil-works/pi-codemode/declarations'\nimport { toolDiscovery } from '@yolk-sdk/agent/protocol'\nimport type { NestedTool } from '@yolk-sdk/agent/tools'\nimport type { CodeModeJsonSchema } from './executor.ts'\n\n/** How a nested tool reaches scripts: `all` tools are also direct model tools; `listed` and\n * `search` are the two discovery modes of `codemode`-only tools.\n */\nexport type CodeModeToolExposure = 'all' | 'listed' | 'search'\n\n/** One nested tool as scripts see it. */\nexport type CodeModeCatalogTool = {\n  /** Raw tool name; scripts may call `tools[\"<name>\"](args)`. */\n  readonly name: string\n  /** Identifier for `tools.<identifier>(args)` (invalid identifier characters become `_`). */\n  readonly identifier: string\n  /**\n   * How scripts call this tool, used to prefix its rejections: `tools.<identifier>`, or\n   * `tools[\"<name>\"]` when an earlier tool already has the identifier (see `codeModeCallLabels`;\n   * when the name is taken too, the tool is unreachable and the label only names it).\n   */\n  readonly callLabel: string\n  /** The tool's `ToolModule.id`. */\n  readonly namespace: string\n  /** The module's `ToolModule.description`, when set. */\n  readonly namespaceDescription?: string\n  readonly description: string\n  readonly inputSchema: CodeModeJsonSchema\n  /** The declared output schema, or `{ type: 'string' }` for text results. */\n  readonly outputSchema: CodeModeJsonSchema\n  /** True when the tool declares an output schema (calls resolve to `structuredContent`). */\n  readonly structured: boolean\n  readonly exposure: CodeModeToolExposure\n}\n\nconst textOutputSchema: CodeModeJsonSchema = { type: 'string' }\n\n/**\n * The call label of each tool name, in order, as pi binds `tools`: each tool takes\n * `tools[<identifier>]` unless an earlier tool holds that key (first tool wins), then\n * `tools[<name>]` if still free. The label is `tools.<identifier>` for the tool that holds its\n * identifier, otherwise `tools[\"<name>\"]`. The executor guard and the host rejection prefix share\n * it, so both name a call the same way.\n */\nexport const codeModeCallLabels = (names: ReadonlyArray<string>): ReadonlyArray<string> => {\n  const bound = new Set<string>()\n\n  return names.map(name => {\n    const identifier = toCodemodeIdentifier(name)\n    const ownsIdentifier = !bound.has(identifier)\n\n    bound.add(identifier)\n    bound.add(name)\n\n    return ownsIdentifier ? `tools.${identifier}` : `tools[${JSON.stringify(name)}]`\n  })\n}\n\n/** Catalog of nested tools in resolution order. */\nexport const codeModeCatalog = (\n  tools: ReadonlyArray<NestedTool>\n): ReadonlyArray<CodeModeCatalogTool> => {\n  const labels = codeModeCallLabels(tools.map(({ def }) => def.name))\n\n  return tools.map(({ def, moduleId, moduleDescription }, index) => {\n    const tool: CodeModeCatalogTool = {\n      name: def.name,\n      identifier: toCodemodeIdentifier(def.name),\n      callLabel: labels[index] ?? `tools[${JSON.stringify(def.name)}]`,\n      namespace: moduleId,\n      description: def.description,\n      inputSchema: def.parameters,\n      outputSchema: def.outputSchema ?? textOutputSchema,\n      structured: def.outputSchema !== undefined,\n      exposure: toolDiscovery(def) ?? 'all'\n    }\n\n    return moduleDescription === undefined\n      ? tool\n      : { ...tool, namespaceDescription: moduleDescription }\n  })\n}\n\n/** Default inline budget of the nested tool listing, in estimated tokens. */\nexport const defaultCodeModeInlineBudget = 3000\n\n/** Estimated tokens of a text: four characters per token, rounded up. */\nexport const estimateCodeModeTokens = (text: string): number => Math.ceil(text.length / 4)\n\nconst maxShortTypeChars = 60\n\nconst shortType = (schema: CodeModeJsonSchema): string => {\n  const rendered = renderToolOutputType(schema)\n\n  if (rendered.length <= maxShortTypeChars) return rendered\n\n  if (!Predicate.isBoolean(schema)) {\n    if (schema.type === 'array') return 'Array<unknown>'\n\n    if (schema.type === 'object') return 'object'\n  }\n\n  return 'unknown'\n}\n\n// Declarations only read names, descriptions, and schemas; `execute` is never called.\nconst declarationTool = (tool: CodeModeCatalogTool) => ({\n  name: tool.name,\n  description: tool.description,\n  inputSchema: tool.inputSchema,\n  outputSchema: tool.outputSchema,\n  execute: () => undefined\n})\n\nconst directToolLine = (tool: CodeModeCatalogTool) =>\n  `- \\`tools.${tool.identifier}(args)\\` takes the arguments of the \\`${tool.name}\\` tool and resolves to \\`${shortType(tool.outputSchema)}\\`.`\n\nconst declarationMembers = (tools: ReadonlyArray<CodeModeCatalogTool>) =>\n  renderDeclarations({ tools: tools.map(declarationTool) })\n\ntype Candidate = {\n  readonly tool: CodeModeCatalogTool\n  readonly index: number\n  readonly cost: number\n}\n\nconst candidateCost = (tool: CodeModeCatalogTool) =>\n  estimateCodeModeTokens(declarationMembers([tool]))\n\nconst groupByNamespace = <A extends { readonly tool: CodeModeCatalogTool }>(\n  items: ReadonlyArray<A>\n): ReadonlyMap<string, ReadonlyArray<A>> => {\n  const groups = new Map<string, Array<A>>()\n\n  for (const item of items) {\n    const group = groups.get(item.tool.namespace)\n\n    if (group === undefined) {\n      groups.set(item.tool.namespace, [item])\n    } else {\n      group.push(item)\n    }\n  }\n\n  return groups\n}\n\nexport type CodeModeListing = {\n  /** Tools placed in the description, in catalog order: every `all` tool, and the `listed` tools\n   * that fit the budget.\n   */\n  readonly listed: ReadonlyArray<CodeModeCatalogTool>\n  /** Namespaces (catalog order) with callable tools the description does not list. */\n  readonly unlistedNamespaces: ReadonlyArray<string>\n}\n\n/**\n * Chooses the tools the description lists. `all` tools are always placed, outside the budget\n * (the model already has their declarations). `listed` tools fill `budget` estimated tokens fairly\n * across namespaces: each round, every namespace still in play places its cheapest remaining tool;\n * a namespace whose next tool does not fit drops out. `search` tools are never candidates.\n */\nexport const selectCodeModeListing = (\n  catalog: ReadonlyArray<CodeModeCatalogTool>,\n  budget: number\n): CodeModeListing => {\n  const candidates = catalog.flatMap((tool, index): ReadonlyArray<Candidate> =>\n    tool.exposure === 'listed' ? [{ tool, index, cost: candidateCost(tool) }] : []\n  )\n\n  const queues = new Map(\n    [...groupByNamespace(candidates)].map(([namespace, group]) => [\n      namespace,\n      [...group].sort((left, right) => left.cost - right.cost || left.index - right.index)\n    ])\n  )\n\n  const placed = new Set(catalog.flatMap((tool, index) => (tool.exposure === 'all' ? [index] : [])))\n\n  const inPlay = new Set(queues.keys())\n  let remaining = budget\n\n  while (inPlay.size > 0) {\n    for (const [namespace, queue] of queues) {\n      if (!inPlay.has(namespace)) continue\n\n      const next = queue.shift()\n\n      if (next === undefined || next.cost > remaining) {\n        inPlay.delete(namespace)\n        continue\n      }\n\n      placed.add(next.index)\n      remaining -= next.cost\n    }\n  }\n\n  const unlisted = new Set(\n    catalog.flatMap((tool, index) => (placed.has(index) ? [] : [tool.namespace]))\n  )\n\n  return {\n    listed: catalog.filter((_, index) => placed.has(index)),\n    unlistedNamespaces: [...new Set(catalog.map(tool => tool.namespace))].filter(namespace =>\n      unlisted.has(namespace)\n    )\n  }\n}\n\nconst intro = [\n  'Run a JavaScript script that calls tools and returns only what matters.',\n  '`code` is the body of an async function: top-level `await` and `return` work. Write plain JavaScript; simple TypeScript annotations are stripped. There is no Node.js, network, filesystem, `require`, `fetch`, or timers.',\n  'Call tools as `await tools.<id>(args)`. Arguments must be plain JSON (no `NaN`, `undefined` array items, `Map`, or functions). A call resolves to the declared result type and rejects with an Error whose message starts with `tools.<id>:` when the tool fails. Calls still running when the script ends are cancelled, so await every call (use `Promise.all` for parallel calls).',\n  'Only the script output and its return value come back to you: filter and aggregate inside the script and return a small JSON value.'\n].join('\\n')\n\nconst globalLines = (store: boolean) => [\n  '- `text(value)` and `console.log(...values)`: append text to the output.',\n  '- `image(dataUrl)`: append a base64 image (a `data:` URL or `{ type: \"image\", data, mimeType }`).',\n  '- `exit()`: end the script successfully.',\n  '- `ALL_TOOLS`: `{ name, description }` of every callable tool.',\n  '- `await searchTools(query, { limit?, namespace? })`: find tools by topic; resolves to `Array<{ name: string; description: string }>` (default limit 8).',\n  '- `await describeTool(name)`: the description and TypeScript declaration of a tool, or `undefined`.',\n  '- `await describeNamespace(name)`: `{ name, description?, tools: Array<{ name, description }> }` for a namespace, or `undefined`.',\n  ...(store\n    ? [\n        '- `store(key, value)` and `load(key)`: keep small JSON values for later scripts; writes are saved only when the script succeeds.'\n      ]\n    : [])\n]\n\nconst namespaceSection = (namespace: string, tools: ReadonlyArray<CodeModeCatalogTool>) => {\n  const declared = tools.filter(tool => tool.exposure !== 'all')\n  const direct = tools.filter(tool => tool.exposure === 'all')\n\n  const description = tools.find(\n    tool => tool.namespaceDescription !== undefined\n  )?.namespaceDescription\n\n  return [\n    `### ${namespace}`,\n    ...(description === undefined ? [] : [description]),\n    ...(declared.length > 0 ? ['```ts', declarationMembers(declared), '```'] : []),\n    ...direct.map(directToolLine)\n  ].join('\\n')\n}\n\n// Fixed text: never derived from `search` tools or from which tools did not fit the budget.\nconst unlistedToolsLine =\n  'More tools may be callable than are listed here: find them with `await searchTools(query, { namespace? })` and read one with `await describeTool(name)` or `await describeNamespace(name)` before calling it.'\n\nexport type CodeModeDescriptionInput = {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly inlineBudget?: number\n  /** Mention `store()`/`load()` persistence. */\n  readonly store?: boolean\n}\n\n/**\n * The code mode tool description: intro, globals one per line, then nested tools grouped by\n * namespace, then one fixed line pointing to `searchTools`/`describeTool`/`describeNamespace`.\n * `all` tools get one line each outside the budget; `listed` tools are declared within the inline\n * budget; `search` tools never contribute, so adding or removing them (even whole namespaces of\n * them) leaves the text byte-identical.\n */\nexport const renderCodeModeDescription = (input: CodeModeDescriptionInput): string => {\n  const catalog = codeModeCatalog(input.tools)\n\n  const listing = selectCodeModeListing(catalog, input.inlineBudget ?? defaultCodeModeInlineBudget)\n\n  const sections = [...groupByNamespace(listing.listed.map(tool => ({ tool })))].map(\n    ([namespace, items]) =>\n      namespaceSection(\n        namespace,\n        items.map(item => item.tool)\n      )\n  )\n\n  return [\n    intro,\n    ['Globals:', ...globalLines(input.store === true)].join('\\n'),\n    sections.length === 0\n      ? 'Nested tools: none are listed here.'\n      : ['## Nested tools by namespace', ...sections].join('\\n\\n'),\n    unlistedToolsLine\n  ].join('\\n\\n')\n}\n\n/** `describeTool` text: the description and TypeScript declaration of one tool. */\nexport const describeCodeModeTool = (tool: CodeModeCatalogTool): string =>\n  renderToolSample(declarationTool(tool))\n\n/** Finds a tool by identifier or raw name. */\nexport const findCodeModeTool = (\n  catalog: ReadonlyArray<CodeModeCatalogTool>,\n  name: string\n): CodeModeCatalogTool | undefined =>\n  catalog.find(tool => tool.identifier === name) ?? catalog.find(tool => tool.name === name)\n"],"mappings":"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"}

package/dist/executor.d.mts

@@ -13,20 +13,38 @@ type CodeModeToolContext = {
  * A function a script can call. Tools are called as `tools.<identifier>(args)` and
  * `tools["<name>"](args)`; the identifier replaces characters that are not valid in a JavaScript
  * identifier with `_`. Arguments and results make a JSON round trip; a rejection surfaces in the
- * script as an `Error` with the same message.
+ * script as an `Error` with the same message (`makeCodeModeTool` rejects with
+ * `<call label>: <message>`, the label being `tools.<identifier>` or `tools["<name>"]`).
+ *
+ * `args` is the JSON value of the script's first argument (`undefined` when there is none), read
+ * once the way `JSON.stringify` reads it (getters and `toJSON` run once); the checked value is the
+ * one sent. Executors reject, inside the script and without calling `execute`, values that JSON
+ * would silently change instead of coercing them: non-finite numbers, invalid `Date`s,
+ * `undefined`/function/symbol array items and holes, function/symbol/bigint values, cycles, and
+ * non-plain objects without `toJSON` (`Map`, `Set`, `RegExp`, `Error`, class instances), including
+ * inside `toJSON` results. `undefined`-valued object keys count as absent, as JSON drops them; a
+ * valid `Date` passes as its ISO string. An argument too large or deep to check completely is
+ * rejected, never sent unchecked (the pi executor: more than 100000 values or 64 levels). A
+ * rejection names the call the way scripts reach it, as `makeCodeModeTool` does: the first tool
+ * with an identifier is `tools.<identifier>`, a later one `tools["<name>"]`.
  */
 type CodeModeExecutorTool = {
   readonly name: string;
   readonly description?: string;
   readonly inputSchema?: CodeModeJsonSchema;
   readonly outputSchema?: CodeModeJsonSchema;
+  /** Diagnostic call label for rejection messages: `tools.<identifier>`, or `tools["<name>"]`
+   * when an earlier tool holds the identifier (a tool whose name is taken too is unreachable and
+   * the label only names it). `makeCodeModeTool` sets it; executors fall back to pi's binding rule.
+   */
+  readonly callLabel?: string;
   readonly execute: (args: unknown, context: CodeModeToolContext) => Promise<unknown>;
 };
 /**
  * A top-level function (`name`) or namespace member (`namespace.member`) for scripts. Globals are
  * host helpers: they are not tools and are not recorded as nested calls.
  */
-type CodeModeExecutorGlobal = CodeModeExecutorTool & {
+type CodeModeExecutorGlobal = Omit<CodeModeExecutorTool, 'callLabel'> & {
   /** `execute` receives every call argument as an array instead of the first one. */readonly spread?: boolean; /** TypeScript parameter list and return type for declarations. */
   readonly signature?: string;
 };
@@ -76,7 +94,8 @@ type CodeModeExecuteOptions = {
  * may carry TypeScript annotations: executors strip them or report a `script` error. The promise
  * resolves for every script outcome, including failures, timeouts, and aborts; a rejection is
  * treated as a `sandbox` failure. Running tool calls must be cancelled through their signal when
- * the script ends.
+ * the script ends. Tool arguments follow the JSON rules of `CodeModeExecutorTool`: pass their JSON
+ * value and reject what JSON would silently change.
  *
  * `@yolk-sdk/codemode/node` provides `makePiCodeModeExecutor`; hosts on other runtimes supply their
  * own engine behind this interface.

package/dist/executor.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.mts","names":[],"sources":["../src/executor.ts"],"mappings":";;;;;KAIY,kBAAA,GAAqB,cAAc;AAA/C;AAAA,KAGY,aAAA,GAAgB,QAAA,CAAS,MAAA,SAAe,MAAA,CAAO,IAAA;AAAA,KAE/C,mBAAA;EALmC,uGAOpC,MAAA,EAAQ,WAAW;AAAA;;;;;;;KASlB,oBAAA;EAAA,SACD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,GAAc,kBAAA;EAAA,SACd,YAAA,GAAe,kBAAA;EAAA,SACf,OAAA,GAAU,IAAA,WAAe,OAAA,EAAS,mBAAA,KAAwB,OAAA;AAAA;AAhBrE;;;;AAAA,KAuBY,sBAAA,GAAyB,oBAAoB;EAZ7C,4FAcD,MAAA;WAEA,SAAA;AAAA;;KAIC,kBAAA;EAAA,SACG,IAAA;EAAA,SAAuB,IAAA;AAAA;EAAA,SACvB,IAAA;EAAA,SAAwB,IAAA;EAAA,SAAuB,QAAA;AAAA;;;;;;;KAQlD,iBAAA;AAAA,KAEA,aAAA;EAAA,SACD,IAAA,EAAM,iBAAiB;EAAA,SACvB,OAAA;EAAA,SACA,KAAA;AAAA;;KAIC,mBAAA;EAAA,SACD,GAAA,EAAK,aAAA;EAAA,SACL,MAAA,EAAQ,aAAa;AAAA;AAAA,KAGpB,uBAAA;EAAA,SACD,EAAA;WAEA,KAAA;EAAA,SACA,KAAA,GAAQ,aAAA,EA3BmB;EAAA,SA6B3B,MAAA,EAAQ,aAAA,CAAc,kBAAA,GA5BM;EAAA,SA8B5B,WAAA,GAAc,mBAAA;AAAA;AAAA,KAGb,sBAAA;EAAA,SACD,KAAA,EAAO,aAAA,CAAc,oBAAA;EAAA,SACrB,OAAA,EAAS,aAAA,CAAc,sBAAA;WAEvB,SAAA,UA7BkB;EAAA,SA+BlB,gBAAA,UA7Bc;EAAA,SA+Bd,KAAA,EAAO,aAAA;EAAA,SACP,MAAA,EAAQ,WAAA;AAAA;;;;;AA7BH;AAIhB;;;;;KAsCY,gBAAA;EAAA,SACD,OAAA,GACP,IAAA,UACA,OAAA,EAAS,sBAAA,KACN,OAAA,CAAQ,uBAAA;AAAA"}
+{"version":3,"file":"executor.d.mts","names":[],"sources":["../src/executor.ts"],"mappings":";;;;;KAIY,kBAAA,GAAqB,cAAc;AAA/C;AAAA,KAGY,aAAA,GAAgB,QAAA,CAAS,MAAA,SAAe,MAAA,CAAO,IAAA;AAAA,KAE/C,mBAAA;EALmC,uGAOpC,MAAA,EAAQ,WAAW;AAAA;;;;;;;;;;;;;AAJiC;AAE/D;;;;AAE8B;AAsB9B;KAAY,oBAAA;EAAA,SACD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,GAAc,kBAAA;EAAA,SACd,YAAA,GAAe,kBAAA;EAM2C;;;;EAAA,SAD1D,SAAA;EAAA,SACA,OAAA,GAAU,IAAA,WAAe,OAAA,EAAS,mBAAA,KAAwB,OAAA;AAAA;;;;;KAOzD,sBAAA,GAAyB,IAAI,CAAC,oBAAA;EAPG,4FASlC,MAAA,YAT0D;EAAA,SAW1D,SAAA;AAAA;AAJX;AAAA,KAQY,kBAAA;EAAA,SACG,IAAA;EAAA,SAAuB,IAAA;AAAA;EAAA,SACvB,IAAA;EAAA,SAAwB,IAAA;EAAA,SAAuB,QAAA;AAAA;AAN1C;AAIpB;;;;;AAJoB,KAcR,iBAAA;AAAA,KAEA,aAAA;EAAA,SACD,IAAA,EAAM,iBAAiB;EAAA,SACvB,OAAA;EAAA,SACA,KAAA;AAAA;AALX;AAAA,KASY,mBAAA;EAAA,SACD,GAAA,EAAK,aAAA;EAAA,SACL,MAAA,EAAQ,aAAa;AAAA;AAAA,KAGpB,uBAAA;EAAA,SACD,EAAA;WAEA,KAAA;EAAA,SACA,KAAA,GAAQ,aAAA,EAfF;EAAA,SAiBN,MAAA,EAAQ,aAAA,CAAc,kBAAA,GAftB;EAAA,SAiBA,WAAA,GAAc,mBAAA;AAAA;AAAA,KAGb,sBAAA;EAAA,SACD,KAAA,EAAO,aAAA,CAAc,oBAAA;EAAA,SACrB,OAAA,EAAS,aAAA,CAAc,sBAAA,GAhBF;EAAA,SAkBrB,SAAA,UAnBK;EAAA,SAqBL,gBAAA,UApBQ;EAAA,SAsBR,KAAA,EAAO,aAAA;EAAA,SACP,MAAA,EAAQ,WAAA;AAAA;;;;;;;;;;;;KAcP,gBAAA;EAAA,SACD,OAAA,GACP,IAAA,UACA,OAAA,EAAS,sBAAA,KACN,OAAA,CAAQ,uBAAA;AAAA"}

package/dist/node.d.mts

@@ -20,7 +20,8 @@ type PiCodeModeExecutorOptions = {
 /**
  * A `CodeModeExecutor` on `@earendil-works/pi-codemode`: every execution gets a fresh QuickJS VM
  * (WebAssembly) in a fresh worker thread, closed when the execution ends. Applies the timeout,
- * heap cap, abort signal, and store, strips TypeScript annotations first, and caps concurrent
+ * heap cap, abort signal, and store, strips TypeScript annotations first, rejects tool arguments
+ * that JSON would silently change inside the script (see `CodeModeExecutorTool`), and caps concurrent
  * executions per executor; create one executor per process (module scope) so the cap is
  * per process.
  *

package/dist/node.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.mts","names":[],"sources":["../src/node.ts"],"mappings":";;;;;cAqBa,8BAAA;AAAA,KAED,yBAAA;EAF+B;;;AAAA;EAAA,SAOhC,IAAA,GAAO,kBAAA,GAAqB,OAAA,CAAQ,kBAAA;EALV;;;;EAAA,SAU1B,SAAA,YAAqB,GAAA,EAAA;EAAA,SAErB,uBAAA;AAAA;;;;;;;;;AAAuB;AA4NlC;;cAAa,sBAAA,GACX,OAAA,GAAS,yBAAA,KACR,gBA4EF"}
+{"version":3,"file":"node.d.mts","names":[],"sources":["../src/node.ts"],"mappings":";;;;;cAsBa,8BAAA;AAAA,KAED,yBAAA;EAF+B;;;AAAA;EAAA,SAOhC,IAAA,GAAO,kBAAA,GAAqB,OAAA,CAAQ,kBAAA;EALV;;;;EAAA,SAU1B,SAAA,YAAqB,GAAA,EAAA;EAAA,SAErB,uBAAA;AAAA;;;;;;;;;AAAuB;AA8alC;;;cAAa,sBAAA,GACX,OAAA,GAAS,yBAAA,KACR,gBA6EF"}

package/dist/node.mjs

@@ -1,3 +1,4 @@
+import { codeModeCallLabels } from "./catalog.mjs";
 import * as nodeModule from "node:module";
 import { Option, Predicate } from "effect";
 import * as Schema from "effect/Schema";
@@ -42,6 +43,182 @@ const makeExecutionSlots = (max) => {
 };
 const wrapperPrefix = "async function __yolkCodeMode() {\n";
 const wrapperSuffix = "\n}";
+/**
+* Evaluated in the VM before the script runs: `(tools, labels) => guardedTools`, with `labels` the
+* `[name, callLabel]` pairs of the tools in order (`codeModeCallLabels`). Each call walks its first
+* argument once, the way `JSON.stringify` reads it (each own enumerable string key and each array
+* index read once, so getters run once; a callable `toJSON` is called once with the key, `''` at
+* the root, and its result is walked at the same path), and builds a fresh copy (null-prototype
+* objects and arrays) that is what the call sends. It rejects with a `TypeError` naming the call
+* label and path when JSON would change the value instead of carrying it: non-finite numbers,
+* invalid `Date`s, `undefined`/function/symbol array items and holes, function/symbol/bigint
+* values, cycles, and objects that are neither plain (prototype `Object.prototype` or `null`) nor
+* arrays and have no `toJSON`. An argument with more than `maxArgumentValues` values or nested more
+* than `maxArgumentDepth` levels is rejected too, never sent unchecked. `undefined`-valued keys are
+* left out (absent, as JSON drops them); the same object twice (not a cycle) is copied twice. An
+* error thrown by a getter or `toJSON` rejects the call with that error. A rejected call never
+* reaches the host. Every member of pi's `tools` is wrapped; unknown members fall through to pi's
+* proxy (close-match suggestions). Not a security boundary (`globalThis.tools` is unguarded):
+* arguments are still decoded by the host.
+*/
+const toolsGuardSource = `(function (tools, labels) {
+  // Captured before the script runs, so a script that changes built-ins cannot change the checks.
+  const { apply, getPrototypeOf, setPrototypeOf } = Reflect
+  const isFinite = Number.isFinite
+  const isArray = Array.isArray
+  const { keys, create, defineProperty } = Object
+  const getTime = Date.prototype.getTime
+  const TypeErrorCtor = TypeError
+  const SetCtor = Set
+  const setAdd = Set.prototype.add
+  const setHas = Set.prototype.has
+  const setDelete = Set.prototype.delete
+  const ObjectProto = Object.prototype
+  const { trunc, min } = Math
+  const stringify = JSON.stringify
+  const plainJson = 'pass plain JSON (objects, arrays, strings, finite numbers, booleans, null)'
+  const maxValues = 100000
+  const maxDepth = 64
+  class Rejected {
+    constructor(message) {
+      defineProperty(this, 'message', { value: message })
+    }
+  }
+  const keyPath = (path, key) =>
+    /^[A-Za-z_$][\\w$]*$/.test(key)
+      ? (path === '' ? key : path + '.' + key)
+      : path + '[' + stringify(key) + ']'
+  const typeName = value => {
+    const proto = getPrototypeOf(value)
+    const name = proto && typeof proto.constructor === 'function' ? proto.constructor.name : ''
+    return name ? (/^[AEIOU]/.test(name) ? 'an ' : 'a ') + name : 'a non-plain object'
+  }
+  // The JSON copy of a value already read from its holder at key (undefined: absent), or throws
+  // Rejected with why JSON would not carry it unchanged.
+  const snapshot = (read, key, path, slot, walk) => {
+    const at = path === '' ? 'is ' : 'at ' + path + ' is '
+    if (++walk.values > maxValues) {
+      throw new Rejected('has more than ' + maxValues + ' values; split the work across calls')
+    }
+    let value = read
+    const kind = typeof value
+    if ((kind === 'object' && value !== null) || kind === 'function' || kind === 'bigint') {
+      // The intrinsic getTime reads a Date's internal time (and throws for anything else).
+      let time
+      try {
+        time = apply(getTime, value, [])
+      } catch {
+        time = undefined
+      }
+      if (time !== undefined && !isFinite(time)) {
+        throw new Rejected(at + 'an invalid Date; pass a valid Date or an ISO string')
+      }
+      const toJSON = value.toJSON
+      if (typeof toJSON === 'function') value = apply(toJSON, value, [key])
+    }
+    switch (typeof value) {
+      case 'string':
+      case 'boolean':
+        return value
+      case 'number':
+        if (isFinite(value)) return value
+        throw new Rejected(
+          at + value + '; pass a finite number' + (slot === 'key' ? ' or omit the key' : '')
+        )
+      case 'undefined':
+        if (slot === 'item') throw new Rejected(at + 'undefined; arrays cannot hold undefined')
+        return undefined
+      case 'bigint':
+      case 'function':
+      case 'symbol':
+        throw new Rejected(at + 'a ' + typeof value + '; ' + plainJson)
+    }
+    if (value === null) return null
+    if (apply(setHas, walk.ancestors, [value])) {
+      throw new Rejected(at + 'a circular reference; ' + plainJson)
+    }
+    if (walk.depth >= maxDepth) {
+      throw new Rejected('at ' + path + ' is nested more than ' + maxDepth + ' levels deep')
+    }
+    const array = isArray(value)
+    if (!array) {
+      const proto = getPrototypeOf(value)
+      if (proto !== ObjectProto && proto !== null) {
+        throw new Rejected(at + typeName(value) + '; ' + plainJson)
+      }
+    }
+    apply(setAdd, walk.ancestors, [value])
+    walk.depth++
+    let copy
+    if (array) {
+      // LengthOfArrayLike, read once, as JSON.stringify does.
+      // Unary plus is ToNumber: one coercion, and it throws for a bigint as JSON.stringify does.
+      const raw = +value.length
+      const length = raw > 0 ? min(trunc(raw), 9007199254740991) : 0
+      // No prototype: no inherited toJSON or index setter can change the checked copy when pi
+      // serializes it (still an array to JSON.stringify).
+      copy = []
+      setPrototypeOf(copy, null)
+      for (let i = 0; i < length; i++) {
+        copy[i] = snapshot(value[i], '' + i, path + '[' + i + ']', 'item', walk)
+      }
+    } else {
+      copy = create(null)
+      // Indexed over the fresh key array: no iterator a script could replace.
+      const names = keys(value)
+      for (let i = 0; i < names.length; i++) {
+        const name = names[i]
+        const item = snapshot(value[name], name, keyPath(path, name), 'key', walk)
+        if (item !== undefined) copy[name] = item
+      }
+    }
+    walk.depth--
+    apply(setDelete, walk.ancestors, [value])
+    return copy
+  }
+  const wrap = (label, call) => async (...args) => {
+    let json
+    try {
+      json = snapshot(args[0], '', '', 'root', { values: 0, depth: 0, ancestors: new SetCtor() })
+    } catch (error) {
+      if (error instanceof Rejected) throw new TypeErrorCtor(label + ': argument ' + error.message)
+      throw error
+    }
+    return call(json)
+  }
+  // Each tool's function sits at tools[name] unless an earlier tool holds that key, in which case
+  // that earlier function is already wrapped.
+  const wrappers = new Map()
+  for (const [name, label] of labels) {
+    const call = name in tools ? tools[name] : undefined
+    if (typeof call === 'function' && !wrappers.has(call)) wrappers.set(call, wrap(label, call))
+  }
+  const guarded = Object.create(null)
+  for (const key of Object.keys(tools)) {
+    const call = tools[key]
+    if (!wrappers.has(call)) wrappers.set(call, wrap('tools[' + JSON.stringify(key) + ']', call))
+    guarded[key] = wrappers.get(call)
+  }
+  return new Proxy(Object.freeze(guarded), {
+    get: (target, key) => (key in target ? target[key] : tools[key])
+  })
+})`;
+const guardPrefix = "return (async (tools, console) => {";
+/** JSON as a JavaScript expression (U+2028/U+2029 escaped for older parsers). */
+const jsonSource = (value) => JSON.stringify(value).replace(/[\u2028\u2029]/g, (char) => char === "\u2028" ? "\\u2028" : "\\u2029");
+const guardSuffix = (tools) => {
+	const labels = codeModeCallLabels(tools.map((tool) => tool.name));
+	return `\n})(${toolsGuardSource}(tools, ${jsonSource(tools.map((tool, index) => [tool.name, tool.callLabel ?? labels[index] ?? `tools[${JSON.stringify(tool.name)}]`]))}), console)`;
+};
+const lineTerminators = /\r\n?|[\n\u2028\u2029]/g;
+/** Lines of the script as QuickJS counts them (at least; never fewer). */
+const scriptLineCount = (code) => (code.match(lineTerminators)?.length ?? 0) + 1;
+const scriptFrame = /codemode\.js:(\d+):\d+/;
+/** Drops stack frames of the wrapper and guard, which sit below the script's last line. */
+const withoutWrapperFrames = (stack, scriptLines) => stack.split("\n").filter((line) => {
+	const frame = scriptFrame.exec(line);
+	return frame === null || Number(frame[1]) <= scriptLines;
+}).join("\n");
 const ErrorWithCode = Schema.Struct({ code: Schema.String });
 const errorCode = (error) => Option.getOrUndefined(Option.map(Schema.decodeUnknownOption(ErrorWithCode)(error), (e) => e.code));
 const syntaxLocation = (error) => {
@@ -114,7 +291,7 @@ const StoreWrites = Schema.Struct({
 	delete: Schema.Array(Schema.String)
 });
 const decodeStoreWrites = Schema.decodeUnknownOption(StoreWrites);
-const fromPiResult = (result) => {
+const fromPiResult = (result, scriptLines) => {
 	if (result.ok) {
 		const storeWrites = decodeStoreWrites(result.storeWrites);
 		if (Option.isNone(storeWrites)) return failure({
@@ -134,7 +311,7 @@ const fromPiResult = (result) => {
 		kind,
 		message: name !== void 0 && name.length > 0 && !message.startsWith(name) ? `${name}: ${message}` : message
 	};
-	if (stack !== void 0) error.stack = stack;
+	if (stack !== void 0) error.stack = withoutWrapperFrames(stack, scriptLines);
 	return {
 		ok: false,
 		error,
@@ -145,7 +322,8 @@ const describeError = (error) => error instanceof Error ? error.message : String
 /**
 * A `CodeModeExecutor` on `@earendil-works/pi-codemode`: every execution gets a fresh QuickJS VM
 * (WebAssembly) in a fresh worker thread, closed when the execution ends. Applies the timeout,
-* heap cap, abort signal, and store, strips TypeScript annotations first, and caps concurrent
+* heap cap, abort signal, and store, strips TypeScript annotations first, rejects tool arguments
+* that JSON would silently change inside the script (see `CodeModeExecutorTool`), and caps concurrent
 * executions per executor; create one executor per process (module scope) so the cap is
 * per process.
 *
@@ -182,11 +360,11 @@ const makePiCodeModeExecutor = (options = {}) => {
 			});
 		}
 		try {
-			return fromPiResult(await sandbox.execute(stripped.code, {
+			return fromPiResult(await sandbox.execute(`${guardPrefix}${stripped.code}${guardSuffix(execution.tools)}`, {
 				signal: execution.signal,
 				store: execution.store,
 				timeoutMs
-			}));
+			}), scriptLineCount(stripped.code));
 		} finally {
 			await sandbox.close();
 		}