@yolk-sdk/codemode 0.1.0-canary.110 → 0.1.0-canary.111

package/README.md

@@ -80,11 +80,14 @@ const program = Effect.gen(function* () {
   `search` tools contribute nothing (no headings or hints), so the description stays
   byte-identical when they, or whole namespaces of them, change. `codemode` + `pinned` tools are
   always declared, outside the budget, and deferred (`loading: 'deferred'`) `all` tools count as
-  `search` tools. One fixed line tells scripts to
-  find unlisted tools with `searchTools(query, { limit?, namespace? })` (BM25 over names,
-  descriptions, namespaces, and module descriptions) and call them in the next script: each hit
-  has a one-line `signature` with the argument and result types (`codeModeToolSignature`; past
-  800 characters it is cut with a `describeTool` pointer). `describeTool(name)` gives the full documented declaration and
+  `search` tools. One fixed line tells scripts to find unlisted tools with
+  `searchTools(query, { limit?, namespace? })` (BM25 over names, descriptions, namespaces, and
+  module descriptions): each hit has a one-line `signature` with the argument and result types
+  (`codeModeToolSignature`; past 800 characters it is cut with a `describeTool` pointer). The
+  description tells the model to call a tool whose exact name it already knows (listed, returned
+  by an earlier search, or called before) without searching, and never to call a tool in the same
+  script that found it: ranking is lexical and hits carry no access metadata, so an unseen hit
+  could be a write. `describeTool(name)` gives the full documented declaration and
   `describeNamespace(name)` a namespace's tools.
 - Results start with `Script completed` or `Script failed`, include the wall time, output, and the
   JSON return value, and are cut head and tail at `maxOutputChars`. Images beyond `maxImages` or

package/dist/catalog.mjs

@@ -164,7 +164,7 @@ const globalLines = (store) => [
 	"- `image(dataUrl)`: append a base64 image (a `data:` URL or `{ type: \"image\", data, mimeType }`).",
 	"- `exit()`: end the script successfully.",
 	"- `ALL_TOOLS`: `{ name, description }` of every callable tool.",
-	"- `await searchTools(query, { limit?, namespace? })`: find tools by topic; resolves to `Array<{ name: string; description: string; signature: string }>` (default limit 8). `signature` is the call with its argument and result types: enough to call the tool in your next script.",
+	"- `await searchTools(query, { limit?, namespace? })`: find tools by topic; resolves to `Array<{ name: string; description: string; signature: string }>` (default limit 8). `signature` is the call with its argument and result types. When you already know the exact name of a tool (listed in this description or the catalog, returned by an earlier `searchTools`, or called earlier in this conversation), call it as `tools.<id>(args)` without searching. Otherwise search, return the hits, and call the tool you choose in your next script. Never call a tool in the same script that found it. If a call fails on its arguments, read its `signature` (or `describeTool`) and retry.",
 	"- `await describeTool(name)`: the full description and documented TypeScript declaration of a tool, or `undefined`; needed only when a signature is cut or unclear.",
 	"- `await describeNamespace(name)`: `{ name, description?, tools: Array<{ name, description }> }` for a namespace, or `undefined`.",
 	...store ? ["- `store(key, value)` and `load(key)`: keep JSON values (up to 256 KiB each) for later scripts; writes are saved only when the script succeeds. When fetched data is large, store it and return a summary, then filter it with `load()` in a later script instead of calling the tools again."] : []
@@ -184,7 +184,7 @@ const namespaceSection = (namespace, tools) => {
 		...direct.map(directToolLine)
 	].join("\n");
 };
-const unlistedToolsLine = "More tools may be callable than are listed here: find them with `await searchTools(query, { namespace? })` (each hit has its call signature) or `await describeNamespace(name)`, then call them in your next script.";
+const unlistedToolsLine = "More tools may be callable than are listed here: find them with `await searchTools(query, { namespace? })` (each hit has its call signature) or `await describeNamespace(name)`; call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.";
 /**
 * The code mode tool description: intro, globals one per line, then nested tools grouped by
 * namespace, then one fixed line pointing to `searchTools` and `describeNamespace`.
@@ -322,7 +322,7 @@ const namespaceLine = (namespace) => {
 /** The full catalog text of an instruction message. */
 const renderCodeModeCatalog = (summary) => [
 	"# Code mode catalog",
-	"Tools `codemode` scripts can call, by namespace; the latest catalog in the conversation replaces any earlier one. Call a listed tool as `await tools.<id>(args)`; find the others with `await searchTools(query, { namespace })` (each hit has its call signature) and call them in your next script.",
+	"Tools `codemode` scripts can call, by namespace; the latest catalog in the conversation replaces any earlier one. Call a listed tool as `await tools.<id>(args)`; find the others with `await searchTools(query, { namespace })` (each hit has its call signature); call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.",
 	["## Namespaces", ...summary.namespaces.map(namespaceLine)].join("\n"),
 	...summary.namespaces.flatMap((namespace) => namespace.listing.length === 0 ? [] : [`### ${namespace.name}\n${namespace.listing}`]),
 	...hasStageableNames(summary.stageable) ? [stageableSection(summary.stageable)] : []
@@ -353,7 +353,7 @@ const renderCodeModeInstructedDescription = (input) => [
 		...globalLines(input.store === true),
 		...input.staging === void 0 ? [] : [stageLine(input.staging.reviewToolName)]
 	].join("\n"),
-	"The tools scripts can call are in the \"Code mode catalog\" (namespaces, tool counts and listed tools; the latest one applies). Find the others with `await searchTools(query, { namespace? })` (each hit has its call signature) and call them in your next script."
+	"The tools scripts can call are in the \"Code mode catalog\" (namespaces, tool counts and listed tools; the latest one applies). Find the others with `await searchTools(query, { namespace? })` (each hit has its call signature); call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching."
 ].join("\n\n");
 //#endregion
 export { CodeModeCatalogSummary, codeModeCallLabels, codeModeCatalog, codeModeCatalogInstruction, codeModeCatalogInstructionKey, codeModeStageOnlyCatalog, codeModeToolSignature, defaultCodeModeInlineBudget, describeCodeModeTool, estimateCodeModeTokens, findCodeModeTool, maxCodeModeSearchSignatureChars, renderCodeModeCatalog, renderCodeModeDescription, renderCodeModeInstructedDescription, selectCodeModeListing, summarizeCodeModeCatalog };

package/dist/catalog.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.mjs","names":[],"sources":["../src/catalog.ts"],"sourcesContent":["import { Option, Predicate } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport {\n  renderDeclarations,\n  renderToolOutputType,\n  renderToolSample,\n  schemaToType,\n  toCodemodeIdentifier\n} from '@earendil-works/pi-codemode/declarations'\nimport { isDeferredTool, toolDiscovery } from '@yolk-sdk/agent/protocol'\nimport type { RunInstruction } from '@yolk-sdk/agent/loop'\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; `stage` marks a stageable tool\n * (approval-gated, ADR 0007): found by search, never callable, only passed to `stage()`.\n */\nexport type CodeModeToolExposure = 'all' | 'listed' | 'search' | 'pinned' | 'stage'\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      // A deferred tool's declaration is not in model context until activated: scripts find it\n      // by search like a codemode-only `search` tool (ADR 0007).\n      exposure: toolDiscovery(def) ?? (isDeferredTool(def) ? 'search' : 'all')\n    }\n\n    return moduleDescription === undefined\n      ? tool\n      : { ...tool, namespaceDescription: moduleDescription }\n  })\n}\n\n/**\n * Catalog entries of the stageable tools (ADR 0007). Stageable tools are approval-gated, so scripts\n * can only `stage()` them whatever their `callableBy` (stage-only `codemode` ones are also never\n * declared to the model): searchable and describable, never callable (no `tools` binding), so\n * their call label is the `stage()` call that records them.\n */\nexport const codeModeStageOnlyCatalog = (\n  stageable: ReadonlyArray<NestedTool>\n): ReadonlyArray<CodeModeCatalogTool> =>\n  stageable.map(({ def, moduleId, moduleDescription }) => {\n    const tool: CodeModeCatalogTool = {\n      name: def.name,\n      identifier: toCodemodeIdentifier(def.name),\n      callLabel: `stage(${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: 'stage'\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), and so are `pinned` tools. `listed` tools fill\n * `budget` estimated tokens fairly across namespaces: each round, every namespace still in play\n * places its cheapest remaining tool; a namespace whose next tool does not fit drops out. `search`\n * 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(\n    catalog.flatMap((tool, index) =>\n      tool.exposure === 'all' || tool.exposure === 'pinned' ? [index] : []\n    )\n  )\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 stageLine = (reviewToolName: string) =>\n  `- \\`await stage(name, args)\\`: record a call of a stageable tool for review instead of running it; resolves to \\`{ staged: true, key, index }\\`. Nothing runs until a person approves the plan through the \\`${reviewToolName}\\` tool, which the result tells you how to call. Once a script stages, it may only run read tools; a script that already ran a write tool cannot stage. \\`searchTools\\` marks approval-gated tools \\`stageOnly: true\\`: they have no \\`tools\\` binding, only \\`stage()\\` them.`\n\n/** Stageable tool names listed in the description; the rest are summarized with a count. */\nconst maxListedStageableTools = 20\n\n/**\n * Stageable tools the description names: `pinned` ones first, never `search` or deferred ones\n * (whose declaration is not in model context; scripts find them by search, ADR 0007).\n */\ntype StageableNames = {\n  readonly pinned: ReadonlyArray<string>\n  readonly listed: ReadonlyArray<string>\n}\n\nconst listedStageableNames = (staging: CodeModeStagingDescription): StageableNames => ({\n  pinned: staging.tools.flatMap(({ def }) => (toolDiscovery(def) === 'pinned' ? [def.name] : [])),\n  listed: staging.tools.flatMap(({ def }) => {\n    const discovery = toolDiscovery(def)\n\n    return discovery === 'search' || discovery === 'pinned' || isDeferredTool(def) ? [] : [def.name]\n  })\n})\n\nconst hasStageableNames = (names: StageableNames) =>\n  names.pinned.length > 0 || names.listed.length > 0\n\n/** `pinned` names are always shown; the cap applies to the others. */\nconst stageableSection = (names: StageableNames) => {\n  const room = Math.max(0, maxListedStageableTools - names.pinned.length)\n  const hidden = names.listed.length - room\n\n  return [\n    '## Stageable tools',\n    'Approval-gated tools a script cannot call through `tools`, only stage with `await stage(\"<name>\", args)` (arguments as for the tool of the same name):',\n    ...[...names.pinned, ...names.listed.slice(0, room)].map(name => `- \\`${name}\\``),\n    ...(hidden > 0 ? [`- … and ${hidden} more (find them with \\`searchTools\\`).`] : [])\n  ].join('\\n')\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; signature: string }>` (default limit 8). `signature` is the call with its argument and result types: enough to call the tool in your next script.',\n  '- `await describeTool(name)`: the full description and documented TypeScript declaration of a tool, or `undefined`; needed only when a signature is cut or unclear.',\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 JSON values (up to 256 KiB each) for later scripts; writes are saved only when the script succeeds. When fetched data is large, store it and return a summary, then filter it with `load()` in a later script instead of calling the tools again.'\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? })` (each hit has its call signature) or `await describeNamespace(name)`, then call them in your next script.'\n\n/** Staged tool plans as the description shows them (`NestedToolStagingDescription`). */\nexport type CodeModeStagingDescription = {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly reviewToolName: string\n}\n\nexport type CodeModeDescriptionInput = {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly inlineBudget?: number\n  /** Mention `store()`/`load()` persistence. */\n  readonly store?: boolean\n  /** Document `stage()` and list the stageable tools that are neither `search` nor deferred. */\n  readonly staging?: CodeModeStagingDescription\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` and `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. With `staging` (and stageable tools), `stage()` is listed\n * with the globals and the stageable tool names follow the nested tools; `search` and deferred\n * stageable tools are never named, so they leave the text byte-identical too once any stageable\n * tool exists.\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  const staging =\n    input.staging !== undefined && input.staging.tools.length > 0 ? input.staging : undefined\n\n  const stageableNames =\n    staging === undefined ? { pinned: [], listed: [] } : listedStageableNames(staging)\n\n  return [\n    intro,\n    [\n      'Globals:',\n      ...globalLines(input.store === true),\n      ...(staging === undefined ? [] : [stageLine(staging.reviewToolName)])\n    ].join('\\n'),\n    sections.length === 0\n      ? 'Nested tools: none are listed here.'\n      : ['## Nested tools by namespace', ...sections].join('\\n\\n'),\n    ...(hasStageableNames(stageableNames) ? [stageableSection(stageableNames)] : []),\n    unlistedToolsLine\n  ].join('\\n\\n')\n}\n\n/** Longest `searchTools` signature, cut marker included (`describeTool` has the whole declaration). */\nexport const maxCodeModeSearchSignatureChars = 800\n\nconst signatureCutMarker = '… (describeTool for the full declaration)'\n\n// A rendered type on one line, without its description comments (`describeTool` keeps them). pi\n// puts every description line on its own `//` line and JSON-quotes keys and literals, so no other\n// line starts with `//`.\nconst compactText = (rendered: string) =>\n  rendered\n    .split('\\n')\n    .map(line => line.trim())\n    .filter(line => !line.startsWith('//'))\n    .join(' ')\n\nconst compactResultType = (schema: CodeModeJsonSchema) => {\n  const rendered = compactText(renderToolOutputType(schema))\n\n  return rendered.length <= maxShortTypeChars ? rendered : shortType(schema)\n}\n\n// Cuts at a code point boundary: never leaves half of a surrogate pair.\nconst cutSignature = (signature: string) => {\n  const end = maxCodeModeSearchSignatureChars - signatureCutMarker.length\n  const kept = signature.slice(0, end)\n  const last = kept.charCodeAt(kept.length - 1)\n\n  return `${last >= 0xd800 && last <= 0xdbff ? kept.slice(0, -1) : kept}${signatureCutMarker}`\n}\n\n/**\n * The call a `searchTools` hit shows, enough to call the tool without `describeTool`:\n * `tools.<id>(args): Promise<result>`, or `stage(\"<name>\", args)` for a stageable tool. Bounded:\n * a long one ends with a pointer to `describeTool`.\n */\nexport const codeModeToolSignature = (tool: CodeModeCatalogTool): string => {\n  const signature =\n    tool.exposure === 'stage'\n      ? `stage(${JSON.stringify(tool.name)}, ${compactText(schemaToType(tool.inputSchema))})`\n      : `${tool.callLabel}(${compactText(schemaToType(tool.inputSchema))}): Promise<${compactResultType(tool.outputSchema)}>`\n\n  return signature.length <= maxCodeModeSearchSignatureChars ? signature : cutSignature(signature)\n}\n\n/**\n * `describeTool` text: the description and TypeScript declaration of one tool. A stage-only tool\n * has no `tools` binding, so it is described as the `stage()` call that records it.\n */\nexport const describeCodeModeTool = (tool: CodeModeCatalogTool): string =>\n  tool.exposure === 'stage'\n    ? [\n        tool.description,\n        `Stage-only (approval-gated): record a call with \\`await stage(${JSON.stringify(tool.name)}, args)\\`; it runs only after a person approves the plan.`,\n        `args: ${schemaToType(tool.inputSchema)}`\n      ].join('\\n\\n')\n    : renderToolSample(declarationTool(tool))\n\n/**\n * Finds a tool by identifier or raw name. A stageable tool's exact raw name wins first: it has no\n * binding, so a callable tool sharing its identifier (`archive-resource` vs `archive_resource`)\n * must not answer for it; callable lookups keep identifier precedence, as their bindings do.\n */\nexport const findCodeModeTool = (\n  catalog: ReadonlyArray<CodeModeCatalogTool>,\n  name: string\n): CodeModeCatalogTool | undefined =>\n  catalog.find(tool => tool.exposure === 'stage' && tool.name === name) ??\n  catalog.find(tool => tool.identifier === name) ??\n  catalog.find(tool => tool.name === name)\n\n/** The instruction key of the code mode catalog (`catalog: 'instructions'`, ADR 0007). */\nexport const codeModeCatalogInstructionKey = 'yolk.codemode.catalog'\n\nconst CodeModeCatalogNamespace = Schema.Struct({\n  name: Schema.String,\n  description: Schema.optional(Schema.String),\n  /** Every tool scripts reach in the namespace: callable and stage-only. */\n  count: Schema.Number,\n  /** Tools the listing shows. */\n  shown: Schema.Number,\n  /** The rendered declarations and direct tool lines of the shown tools. */\n  listing: Schema.String\n})\n\n/** The catalog an instruction message records as its state (JSON, never model-visible). */\nexport const CodeModeCatalogSummary = Schema.Struct({\n  namespaces: Schema.Array(CodeModeCatalogNamespace),\n  /** Stageable tool names the catalog lists: `pinned` ones, then the others (never `search` or\n   * deferred ones). */\n  stageable: Schema.Struct({\n    pinned: Schema.Array(Schema.String),\n    listed: Schema.Array(Schema.String)\n  })\n})\n\nexport type CodeModeCatalogSummary = typeof CodeModeCatalogSummary.Type\n\nconst decodeCatalogSummary = Schema.decodeUnknownOption(CodeModeCatalogSummary)\n\nconst encodeCatalogSummary = Schema.encodeOption(CodeModeCatalogSummary)\n\nconst namespaceListing = (tools: ReadonlyArray<CodeModeCatalogTool>) => {\n  const declared = tools.filter(tool => tool.exposure !== 'all')\n  const direct = tools.filter(tool => tool.exposure === 'all')\n\n  return [\n    ...(declared.length > 0 ? ['```ts', declarationMembers(declared), '```'] : []),\n    ...direct.map(directToolLine)\n  ].join('\\n')\n}\n\n/**\n * The catalog of one resolution: every namespace with its tool count and description, and the\n * listing of the tools the inline budget (or `pinned`) places. `search` and stage-only tools are\n * counted, never listed.\n */\nexport const summarizeCodeModeCatalog = (input: {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly staging?: CodeModeStagingDescription\n  readonly inlineBudget?: number\n}): CodeModeCatalogSummary => {\n  const catalog = codeModeCatalog(input.tools)\n  const stageOnly = input.staging === undefined ? [] : codeModeStageOnlyCatalog(input.staging.tools)\n  const listing = selectCodeModeListing(catalog, input.inlineBudget ?? defaultCodeModeInlineBudget)\n  const listedByNamespace = groupByNamespace(listing.listed.map(tool => ({ tool })))\n\n  const namespaces = [...groupByNamespace([...catalog, ...stageOnly].map(tool => ({ tool })))].map(\n    ([name, items]) => {\n      const shown = (listedByNamespace.get(name) ?? []).map(item => item.tool)\n\n      const description = items.find(item => item.tool.namespaceDescription !== undefined)?.tool\n        .namespaceDescription\n\n      const namespace = {\n        name,\n        count: items.length,\n        shown: shown.length,\n        listing: namespaceListing(shown)\n      }\n\n      return description === undefined ? namespace : { ...namespace, description }\n    }\n  )\n\n  return {\n    namespaces,\n    stageable:\n      input.staging === undefined ? { pinned: [], listed: [] } : listedStageableNames(input.staging)\n  }\n}\n\nconst namespaceLine = (namespace: CodeModeCatalogSummary['namespaces'][number]) => {\n  const count = namespace.count === 1 ? '1 tool' : `${namespace.count} tools`\n\n  const label =\n    namespace.shown === namespace.count\n      ? count\n      : namespace.shown === 0\n        ? `${count}, none listed`\n        : `${count}, ${namespace.shown} listed`\n\n  return `- \\`${namespace.name}\\` (${label})${namespace.description === undefined ? '' : `: ${namespace.description}`}`\n}\n\n/** The full catalog text of an instruction message. */\nexport const renderCodeModeCatalog = (summary: CodeModeCatalogSummary): string =>\n  [\n    '# Code mode catalog',\n    'Tools `codemode` scripts can call, by namespace; the latest catalog in the conversation replaces any earlier one. Call a listed tool as `await tools.<id>(args)`; find the others with `await searchTools(query, { namespace })` (each hit has its call signature) and call them in your next script.',\n    ['## Namespaces', ...summary.namespaces.map(namespaceLine)].join('\\n'),\n    ...summary.namespaces.flatMap(namespace =>\n      namespace.listing.length === 0 ? [] : [`### ${namespace.name}\\n${namespace.listing}`]\n    ),\n    ...(hasStageableNames(summary.stageable) ? [stageableSection(summary.stageable)] : [])\n  ].join('\\n\\n')\n\n/**\n * The host instruction of the code mode catalog: its state is the encoded summary, and its render\n * the full catalog (every change renders it whole, see `RunInstruction.render`) or a removal notice.\n */\nexport const codeModeCatalogInstruction = (input: {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly staging?: CodeModeStagingDescription\n  readonly inlineBudget?: number\n}): RunInstruction => {\n  const summary = summarizeCodeModeCatalog(input)\n\n  return {\n    key: codeModeCatalogInstructionKey,\n    state:\n      summary.namespaces.length === 0\n        ? undefined\n        : Option.getOrUndefined(encodeCatalogSummary(summary)),\n    render: current => {\n      const decoded = current === undefined ? Option.none() : decodeCatalogSummary(current)\n\n      return Option.isNone(decoded)\n        ? 'Code mode tools are no longer available: do not call previously listed code mode tools.'\n        : renderCodeModeCatalog(decoded.value)\n    }\n  }\n}\n\n/**\n * The code mode description when the catalog is delivered as an instruction: invariant across\n * catalog changes (only staging availability adds the `stage()` line).\n */\nexport const renderCodeModeInstructedDescription = (input: {\n  readonly store?: boolean\n  readonly staging?: CodeModeStagingDescription\n}): string =>\n  [\n    intro,\n    [\n      'Globals:',\n      ...globalLines(input.store === true),\n      ...(input.staging === undefined ? [] : [stageLine(input.staging.reviewToolName)])\n    ].join('\\n'),\n    'The tools scripts can call are in the \"Code mode catalog\" (namespaces, tool counts and listed tools; the latest one applies). Find the others with `await searchTools(query, { namespace? })` (each hit has its call signature) and call them in your next script.'\n  ].join('\\n\\n')\n"],"mappings":"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"}
+{"version":3,"file":"catalog.mjs","names":[],"sources":["../src/catalog.ts"],"sourcesContent":["import { Option, Predicate } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport {\n  renderDeclarations,\n  renderToolOutputType,\n  renderToolSample,\n  schemaToType,\n  toCodemodeIdentifier\n} from '@earendil-works/pi-codemode/declarations'\nimport { isDeferredTool, toolDiscovery } from '@yolk-sdk/agent/protocol'\nimport type { RunInstruction } from '@yolk-sdk/agent/loop'\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; `stage` marks a stageable tool\n * (approval-gated, ADR 0007): found by search, never callable, only passed to `stage()`.\n */\nexport type CodeModeToolExposure = 'all' | 'listed' | 'search' | 'pinned' | 'stage'\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      // A deferred tool's declaration is not in model context until activated: scripts find it\n      // by search like a codemode-only `search` tool (ADR 0007).\n      exposure: toolDiscovery(def) ?? (isDeferredTool(def) ? 'search' : 'all')\n    }\n\n    return moduleDescription === undefined\n      ? tool\n      : { ...tool, namespaceDescription: moduleDescription }\n  })\n}\n\n/**\n * Catalog entries of the stageable tools (ADR 0007). Stageable tools are approval-gated, so scripts\n * can only `stage()` them whatever their `callableBy` (stage-only `codemode` ones are also never\n * declared to the model): searchable and describable, never callable (no `tools` binding), so\n * their call label is the `stage()` call that records them.\n */\nexport const codeModeStageOnlyCatalog = (\n  stageable: ReadonlyArray<NestedTool>\n): ReadonlyArray<CodeModeCatalogTool> =>\n  stageable.map(({ def, moduleId, moduleDescription }) => {\n    const tool: CodeModeCatalogTool = {\n      name: def.name,\n      identifier: toCodemodeIdentifier(def.name),\n      callLabel: `stage(${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: 'stage'\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), and so are `pinned` tools. `listed` tools fill\n * `budget` estimated tokens fairly across namespaces: each round, every namespace still in play\n * places its cheapest remaining tool; a namespace whose next tool does not fit drops out. `search`\n * 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(\n    catalog.flatMap((tool, index) =>\n      tool.exposure === 'all' || tool.exposure === 'pinned' ? [index] : []\n    )\n  )\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 stageLine = (reviewToolName: string) =>\n  `- \\`await stage(name, args)\\`: record a call of a stageable tool for review instead of running it; resolves to \\`{ staged: true, key, index }\\`. Nothing runs until a person approves the plan through the \\`${reviewToolName}\\` tool, which the result tells you how to call. Once a script stages, it may only run read tools; a script that already ran a write tool cannot stage. \\`searchTools\\` marks approval-gated tools \\`stageOnly: true\\`: they have no \\`tools\\` binding, only \\`stage()\\` them.`\n\n/** Stageable tool names listed in the description; the rest are summarized with a count. */\nconst maxListedStageableTools = 20\n\n/**\n * Stageable tools the description names: `pinned` ones first, never `search` or deferred ones\n * (whose declaration is not in model context; scripts find them by search, ADR 0007).\n */\ntype StageableNames = {\n  readonly pinned: ReadonlyArray<string>\n  readonly listed: ReadonlyArray<string>\n}\n\nconst listedStageableNames = (staging: CodeModeStagingDescription): StageableNames => ({\n  pinned: staging.tools.flatMap(({ def }) => (toolDiscovery(def) === 'pinned' ? [def.name] : [])),\n  listed: staging.tools.flatMap(({ def }) => {\n    const discovery = toolDiscovery(def)\n\n    return discovery === 'search' || discovery === 'pinned' || isDeferredTool(def) ? [] : [def.name]\n  })\n})\n\nconst hasStageableNames = (names: StageableNames) =>\n  names.pinned.length > 0 || names.listed.length > 0\n\n/** `pinned` names are always shown; the cap applies to the others. */\nconst stageableSection = (names: StageableNames) => {\n  const room = Math.max(0, maxListedStageableTools - names.pinned.length)\n  const hidden = names.listed.length - room\n\n  return [\n    '## Stageable tools',\n    'Approval-gated tools a script cannot call through `tools`, only stage with `await stage(\"<name>\", args)` (arguments as for the tool of the same name):',\n    ...[...names.pinned, ...names.listed.slice(0, room)].map(name => `- \\`${name}\\``),\n    ...(hidden > 0 ? [`- … and ${hidden} more (find them with \\`searchTools\\`).`] : [])\n  ].join('\\n')\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; signature: string }>` (default limit 8). `signature` is the call with its argument and result types. When you already know the exact name of a tool (listed in this description or the catalog, returned by an earlier `searchTools`, or called earlier in this conversation), call it as `tools.<id>(args)` without searching. Otherwise search, return the hits, and call the tool you choose in your next script. Never call a tool in the same script that found it. If a call fails on its arguments, read its `signature` (or `describeTool`) and retry.',\n  '- `await describeTool(name)`: the full description and documented TypeScript declaration of a tool, or `undefined`; needed only when a signature is cut or unclear.',\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 JSON values (up to 256 KiB each) for later scripts; writes are saved only when the script succeeds. When fetched data is large, store it and return a summary, then filter it with `load()` in a later script instead of calling the tools again.'\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? })` (each hit has its call signature) or `await describeNamespace(name)`; call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.'\n\n/** Staged tool plans as the description shows them (`NestedToolStagingDescription`). */\nexport type CodeModeStagingDescription = {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly reviewToolName: string\n}\n\nexport type CodeModeDescriptionInput = {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly inlineBudget?: number\n  /** Mention `store()`/`load()` persistence. */\n  readonly store?: boolean\n  /** Document `stage()` and list the stageable tools that are neither `search` nor deferred. */\n  readonly staging?: CodeModeStagingDescription\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` and `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. With `staging` (and stageable tools), `stage()` is listed\n * with the globals and the stageable tool names follow the nested tools; `search` and deferred\n * stageable tools are never named, so they leave the text byte-identical too once any stageable\n * tool exists.\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  const staging =\n    input.staging !== undefined && input.staging.tools.length > 0 ? input.staging : undefined\n\n  const stageableNames =\n    staging === undefined ? { pinned: [], listed: [] } : listedStageableNames(staging)\n\n  return [\n    intro,\n    [\n      'Globals:',\n      ...globalLines(input.store === true),\n      ...(staging === undefined ? [] : [stageLine(staging.reviewToolName)])\n    ].join('\\n'),\n    sections.length === 0\n      ? 'Nested tools: none are listed here.'\n      : ['## Nested tools by namespace', ...sections].join('\\n\\n'),\n    ...(hasStageableNames(stageableNames) ? [stageableSection(stageableNames)] : []),\n    unlistedToolsLine\n  ].join('\\n\\n')\n}\n\n/** Longest `searchTools` signature, cut marker included (`describeTool` has the whole declaration). */\nexport const maxCodeModeSearchSignatureChars = 800\n\nconst signatureCutMarker = '… (describeTool for the full declaration)'\n\n// A rendered type on one line, without its description comments (`describeTool` keeps them). pi\n// puts every description line on its own `//` line and JSON-quotes keys and literals, so no other\n// line starts with `//`.\nconst compactText = (rendered: string) =>\n  rendered\n    .split('\\n')\n    .map(line => line.trim())\n    .filter(line => !line.startsWith('//'))\n    .join(' ')\n\nconst compactResultType = (schema: CodeModeJsonSchema) => {\n  const rendered = compactText(renderToolOutputType(schema))\n\n  return rendered.length <= maxShortTypeChars ? rendered : shortType(schema)\n}\n\n// Cuts at a code point boundary: never leaves half of a surrogate pair.\nconst cutSignature = (signature: string) => {\n  const end = maxCodeModeSearchSignatureChars - signatureCutMarker.length\n  const kept = signature.slice(0, end)\n  const last = kept.charCodeAt(kept.length - 1)\n\n  return `${last >= 0xd800 && last <= 0xdbff ? kept.slice(0, -1) : kept}${signatureCutMarker}`\n}\n\n/**\n * The call a `searchTools` hit shows, enough to call the tool without `describeTool`:\n * `tools.<id>(args): Promise<result>`, or `stage(\"<name>\", args)` for a stageable tool. Bounded:\n * a long one ends with a pointer to `describeTool`.\n */\nexport const codeModeToolSignature = (tool: CodeModeCatalogTool): string => {\n  const signature =\n    tool.exposure === 'stage'\n      ? `stage(${JSON.stringify(tool.name)}, ${compactText(schemaToType(tool.inputSchema))})`\n      : `${tool.callLabel}(${compactText(schemaToType(tool.inputSchema))}): Promise<${compactResultType(tool.outputSchema)}>`\n\n  return signature.length <= maxCodeModeSearchSignatureChars ? signature : cutSignature(signature)\n}\n\n/**\n * `describeTool` text: the description and TypeScript declaration of one tool. A stage-only tool\n * has no `tools` binding, so it is described as the `stage()` call that records it.\n */\nexport const describeCodeModeTool = (tool: CodeModeCatalogTool): string =>\n  tool.exposure === 'stage'\n    ? [\n        tool.description,\n        `Stage-only (approval-gated): record a call with \\`await stage(${JSON.stringify(tool.name)}, args)\\`; it runs only after a person approves the plan.`,\n        `args: ${schemaToType(tool.inputSchema)}`\n      ].join('\\n\\n')\n    : renderToolSample(declarationTool(tool))\n\n/**\n * Finds a tool by identifier or raw name. A stageable tool's exact raw name wins first: it has no\n * binding, so a callable tool sharing its identifier (`archive-resource` vs `archive_resource`)\n * must not answer for it; callable lookups keep identifier precedence, as their bindings do.\n */\nexport const findCodeModeTool = (\n  catalog: ReadonlyArray<CodeModeCatalogTool>,\n  name: string\n): CodeModeCatalogTool | undefined =>\n  catalog.find(tool => tool.exposure === 'stage' && tool.name === name) ??\n  catalog.find(tool => tool.identifier === name) ??\n  catalog.find(tool => tool.name === name)\n\n/** The instruction key of the code mode catalog (`catalog: 'instructions'`, ADR 0007). */\nexport const codeModeCatalogInstructionKey = 'yolk.codemode.catalog'\n\nconst CodeModeCatalogNamespace = Schema.Struct({\n  name: Schema.String,\n  description: Schema.optional(Schema.String),\n  /** Every tool scripts reach in the namespace: callable and stage-only. */\n  count: Schema.Number,\n  /** Tools the listing shows. */\n  shown: Schema.Number,\n  /** The rendered declarations and direct tool lines of the shown tools. */\n  listing: Schema.String\n})\n\n/** The catalog an instruction message records as its state (JSON, never model-visible). */\nexport const CodeModeCatalogSummary = Schema.Struct({\n  namespaces: Schema.Array(CodeModeCatalogNamespace),\n  /** Stageable tool names the catalog lists: `pinned` ones, then the others (never `search` or\n   * deferred ones). */\n  stageable: Schema.Struct({\n    pinned: Schema.Array(Schema.String),\n    listed: Schema.Array(Schema.String)\n  })\n})\n\nexport type CodeModeCatalogSummary = typeof CodeModeCatalogSummary.Type\n\nconst decodeCatalogSummary = Schema.decodeUnknownOption(CodeModeCatalogSummary)\n\nconst encodeCatalogSummary = Schema.encodeOption(CodeModeCatalogSummary)\n\nconst namespaceListing = (tools: ReadonlyArray<CodeModeCatalogTool>) => {\n  const declared = tools.filter(tool => tool.exposure !== 'all')\n  const direct = tools.filter(tool => tool.exposure === 'all')\n\n  return [\n    ...(declared.length > 0 ? ['```ts', declarationMembers(declared), '```'] : []),\n    ...direct.map(directToolLine)\n  ].join('\\n')\n}\n\n/**\n * The catalog of one resolution: every namespace with its tool count and description, and the\n * listing of the tools the inline budget (or `pinned`) places. `search` and stage-only tools are\n * counted, never listed.\n */\nexport const summarizeCodeModeCatalog = (input: {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly staging?: CodeModeStagingDescription\n  readonly inlineBudget?: number\n}): CodeModeCatalogSummary => {\n  const catalog = codeModeCatalog(input.tools)\n  const stageOnly = input.staging === undefined ? [] : codeModeStageOnlyCatalog(input.staging.tools)\n  const listing = selectCodeModeListing(catalog, input.inlineBudget ?? defaultCodeModeInlineBudget)\n  const listedByNamespace = groupByNamespace(listing.listed.map(tool => ({ tool })))\n\n  const namespaces = [...groupByNamespace([...catalog, ...stageOnly].map(tool => ({ tool })))].map(\n    ([name, items]) => {\n      const shown = (listedByNamespace.get(name) ?? []).map(item => item.tool)\n\n      const description = items.find(item => item.tool.namespaceDescription !== undefined)?.tool\n        .namespaceDescription\n\n      const namespace = {\n        name,\n        count: items.length,\n        shown: shown.length,\n        listing: namespaceListing(shown)\n      }\n\n      return description === undefined ? namespace : { ...namespace, description }\n    }\n  )\n\n  return {\n    namespaces,\n    stageable:\n      input.staging === undefined ? { pinned: [], listed: [] } : listedStageableNames(input.staging)\n  }\n}\n\nconst namespaceLine = (namespace: CodeModeCatalogSummary['namespaces'][number]) => {\n  const count = namespace.count === 1 ? '1 tool' : `${namespace.count} tools`\n\n  const label =\n    namespace.shown === namespace.count\n      ? count\n      : namespace.shown === 0\n        ? `${count}, none listed`\n        : `${count}, ${namespace.shown} listed`\n\n  return `- \\`${namespace.name}\\` (${label})${namespace.description === undefined ? '' : `: ${namespace.description}`}`\n}\n\n/** The full catalog text of an instruction message. */\nexport const renderCodeModeCatalog = (summary: CodeModeCatalogSummary): string =>\n  [\n    '# Code mode catalog',\n    'Tools `codemode` scripts can call, by namespace; the latest catalog in the conversation replaces any earlier one. Call a listed tool as `await tools.<id>(args)`; find the others with `await searchTools(query, { namespace })` (each hit has its call signature); call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.',\n    ['## Namespaces', ...summary.namespaces.map(namespaceLine)].join('\\n'),\n    ...summary.namespaces.flatMap(namespace =>\n      namespace.listing.length === 0 ? [] : [`### ${namespace.name}\\n${namespace.listing}`]\n    ),\n    ...(hasStageableNames(summary.stageable) ? [stageableSection(summary.stageable)] : [])\n  ].join('\\n\\n')\n\n/**\n * The host instruction of the code mode catalog: its state is the encoded summary, and its render\n * the full catalog (every change renders it whole, see `RunInstruction.render`) or a removal notice.\n */\nexport const codeModeCatalogInstruction = (input: {\n  readonly tools: ReadonlyArray<NestedTool>\n  readonly staging?: CodeModeStagingDescription\n  readonly inlineBudget?: number\n}): RunInstruction => {\n  const summary = summarizeCodeModeCatalog(input)\n\n  return {\n    key: codeModeCatalogInstructionKey,\n    state:\n      summary.namespaces.length === 0\n        ? undefined\n        : Option.getOrUndefined(encodeCatalogSummary(summary)),\n    render: current => {\n      const decoded = current === undefined ? Option.none() : decodeCatalogSummary(current)\n\n      return Option.isNone(decoded)\n        ? 'Code mode tools are no longer available: do not call previously listed code mode tools.'\n        : renderCodeModeCatalog(decoded.value)\n    }\n  }\n}\n\n/**\n * The code mode description when the catalog is delivered as an instruction: invariant across\n * catalog changes (only staging availability adds the `stage()` line).\n */\nexport const renderCodeModeInstructedDescription = (input: {\n  readonly store?: boolean\n  readonly staging?: CodeModeStagingDescription\n}): string =>\n  [\n    intro,\n    [\n      'Globals:',\n      ...globalLines(input.store === true),\n      ...(input.staging === undefined ? [] : [stageLine(input.staging.reviewToolName)])\n    ].join('\\n'),\n    'The tools scripts can call are in the \"Code mode catalog\" (namespaces, tool counts and listed tools; the latest one applies). Find the others with `await searchTools(query, { namespace? })` (each hit has its call signature); call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.'\n  ].join('\\n\\n')\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk-sdk/codemode",
-  "version": "0.1.0-canary.110",
+  "version": "0.1.0-canary.111",
   "description": "Code mode for Yolk agents: one tool that runs model-written JavaScript calling the host's resolved tools, plus a Node executor on a confined QuickJS sandbox.",
   "license": "MIT",
   "type": "module",
@@ -52,7 +52,7 @@
   "dependencies": {
     "@earendil-works/pi-codemode": "1.0.0",
     "effect": "4.0.0",
-    "@yolk-sdk/agent": "^0.1.0-canary.110"
+    "@yolk-sdk/agent": "^0.1.0-canary.111"
   },
   "scripts": {
     "build": "tsdown",

package/src/catalog.ts

@@ -304,7 +304,7 @@ const globalLines = (store: boolean) => [
   '- `image(dataUrl)`: append a base64 image (a `data:` URL or `{ type: "image", data, mimeType }`).',
   '- `exit()`: end the script successfully.',
   '- `ALL_TOOLS`: `{ name, description }` of every callable tool.',
-  '- `await searchTools(query, { limit?, namespace? })`: find tools by topic; resolves to `Array<{ name: string; description: string; signature: string }>` (default limit 8). `signature` is the call with its argument and result types: enough to call the tool in your next script.',
+  '- `await searchTools(query, { limit?, namespace? })`: find tools by topic; resolves to `Array<{ name: string; description: string; signature: string }>` (default limit 8). `signature` is the call with its argument and result types. When you already know the exact name of a tool (listed in this description or the catalog, returned by an earlier `searchTools`, or called earlier in this conversation), call it as `tools.<id>(args)` without searching. Otherwise search, return the hits, and call the tool you choose in your next script. Never call a tool in the same script that found it. If a call fails on its arguments, read its `signature` (or `describeTool`) and retry.',
   '- `await describeTool(name)`: the full description and documented TypeScript declaration of a tool, or `undefined`; needed only when a signature is cut or unclear.',
   '- `await describeNamespace(name)`: `{ name, description?, tools: Array<{ name, description }> }` for a namespace, or `undefined`.',
   ...(store
@@ -332,7 +332,7 @@ const namespaceSection = (namespace: string, tools: ReadonlyArray<CodeModeCatalo
 
 // Fixed text: never derived from `search` tools or from which tools did not fit the budget.
 const unlistedToolsLine =
-  'More tools may be callable than are listed here: find them with `await searchTools(query, { namespace? })` (each hit has its call signature) or `await describeNamespace(name)`, then call them in your next script.'
+  'More tools may be callable than are listed here: find them with `await searchTools(query, { namespace? })` (each hit has its call signature) or `await describeNamespace(name)`; call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.'
 
 /** Staged tool plans as the description shows them (`NestedToolStagingDescription`). */
 export type CodeModeStagingDescription = {
@@ -561,7 +561,7 @@ const namespaceLine = (namespace: CodeModeCatalogSummary['namespaces'][number])
 export const renderCodeModeCatalog = (summary: CodeModeCatalogSummary): string =>
   [
     '# Code mode catalog',
-    'Tools `codemode` scripts can call, by namespace; the latest catalog in the conversation replaces any earlier one. Call a listed tool as `await tools.<id>(args)`; find the others with `await searchTools(query, { namespace })` (each hit has its call signature) and call them in your next script.',
+    'Tools `codemode` scripts can call, by namespace; the latest catalog in the conversation replaces any earlier one. Call a listed tool as `await tools.<id>(args)`; find the others with `await searchTools(query, { namespace })` (each hit has its call signature); call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.',
     ['## Namespaces', ...summary.namespaces.map(namespaceLine)].join('\n'),
     ...summary.namespaces.flatMap(namespace =>
       namespace.listing.length === 0 ? [] : [`### ${namespace.name}\n${namespace.listing}`]
@@ -611,5 +611,5 @@ export const renderCodeModeInstructedDescription = (input: {
       ...globalLines(input.store === true),
       ...(input.staging === undefined ? [] : [stageLine(input.staging.reviewToolName)])
     ].join('\n'),
-    'The tools scripts can call are in the "Code mode catalog" (namespaces, tool counts and listed tools; the latest one applies). Find the others with `await searchTools(query, { namespace? })` (each hit has its call signature) and call them in your next script.'
+    'The tools scripts can call are in the "Code mode catalog" (namespaces, tool counts and listed tools; the latest one applies). Find the others with `await searchTools(query, { namespace? })` (each hit has its call signature); call the tool you choose in your next script, and call a tool whose exact name you already know directly, without searching.'
   ].join('\n\n')