@yolk-sdk/codemode 0.1.0-canary.96

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yolk SDK contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @yolk-sdk/codemode
+
+Code mode for Yolk agents: one tool whose input is a short JavaScript program that calls the host's
+resolved tools, filters and aggregates their results, and returns only what matters.
+
+## Install
+
+```bash
+pnpm add @yolk-sdk/codemode@canary @yolk-sdk/agent@canary effect@4.0.0-rc.115
+```
+
+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.
+Requires Node.js 22.19+ (the pi engine's minimum). `@yolk-sdk/codemode/node` is server-only.
+
+## Subpaths
+
+| Subpath                   | Purpose                                                                                                                  |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `@yolk-sdk/codemode`      | Runtime-neutral: `makeCodeModeTool`, the `CodeModeExecutor` interface, catalog/discovery, store rebuild, classifier tool |
+| `@yolk-sdk/codemode/node` | `makePiCodeModeExecutor`: QuickJS (WebAssembly) in a worker thread per script, on `@earendil-works/pi-codemode` 1.0.0    |
+
+## Example
+
+```ts
+import { Effect } from 'effect'
+import { resolveTools } from '@yolk-sdk/agent/tools'
+import { codeModeStoreFromToolResults, makeCodeModeTool } from '@yolk-sdk/codemode'
+import { makePiCodeModeExecutor } from '@yolk-sdk/codemode/node'
+
+// One executor per process: its concurrency cap is per executor.
+const executor = makePiCodeModeExecutor({ maxConcurrentExecutions: 4 })
+
+const codemode = makeCodeModeTool<HostContext>({
+  executor,
+  deadline: context => context.stepDeadlineMs,
+  // Prior results paired with their tool names, oldest first (host-owned lookup).
+  loadStore: context => Effect.succeed(codeModeStoreFromToolResults(context.priorToolResults))
+})
+
+const program = Effect.gen(function* () {
+  const toolSet = yield* resolveTools(
+    [{ id: 'codemode', tools: [codemode] }, ...hostModules],
+    hostContext
+  )
+
+  return toolSet
+})
+```
+
+`HostContext`, `hostModules`, and `hostContext` are host-owned placeholders.
+
+## How it works
+
+- Scripts call tools as `await tools.<id>(args)`. Every nested call runs through the resolution's
+  normal execute path (input decoding, enablement, registration wrappers, same host context), gets
+  the id `<toolCallId>/<seq>`, and is recorded on the result's `nestedCalls` with status, duration,
+  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`.
+- 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
+  namespaces); `callableBy: 'all'` tools get one line each outside the budget; `codemode` +
+  `search` tools contribute nothing (no headings or hints), so the description stays
+  byte-identical when they, or whole namespaces of them, change. One fixed line tells scripts to
+  find unlisted tools with `searchTools(query, { limit?, namespace? })` (BM25 over names,
+  descriptions, namespaces, and module descriptions), `describeTool(name)`, and
+  `describeNamespace(name)`.
+- 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
+  `maxImageBytes` are dropped with a note. Failed scripts keep partial output and list the tool
+  calls already made (they are not undone).
+- `store(key, value)` writes of successful scripts are returned in
+  `structuredContent.codemode.storeWrites`. `codeModeStoreFromToolResults(entries, { toolName? })`
+  rebuilds the store for `loadStore` from `{ toolName, result }` entries, oldest first; it applies
+  only results of the code mode tool (default `codemode`), so other tools cannot spoof writes, and
+  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
+  `timeoutMs` + 5 s after the start and aborts it.
+
+## Limits
+
+| Limit              | Default | Notes                                                     |
+| ------------------ | ------- | --------------------------------------------------------- |
+| `timeoutMs`        | 120000  | Clamped to `deadline(context)` minus 5 s, never below 1 s |
+| `memoryLimitBytes` | 64 MiB  | QuickJS heap cap                                          |
+| `maxNestedCalls`   | 256     | Further calls reject with an `Error`                      |
+| `maxOutputChars`   | 40000   | Head-and-tail cut with an omission marker                 |
+| `maxImages`        | 8       | Later images are dropped with a note                      |
+| `maxImageBytes`    | 4 MiB   | Base64 characters of images in total                      |
+
+## Classifier tool
+
+`makeClassifierTool({ classify })` wraps a `ClassifierModel` from `@yolk-sdk/agent/classification`
+as a `codemode` + `listed` read tool (default name `classify`). Scripts classify one item per call;
+calls beyond `maxConcurrency` (default 100 per script, keyed by the parent tool call id) queue.
+Each call then takes a permit from `processLimiter`, shared across scripts and registrations:
+`defaultClassifierProcessLimiter` (200 per process) unless you pass one built with
+`makeClassifierConcurrencyLimiter(max)` or `false`. An interrupted waiting call releases its
+permits. Nested-call records carry token usage; cost stays in the result's
+`structuredContent.usage`.
+
+## Host responsibilities
+
+- Which tools are callable from scripts (`callableBy`, `discovery`), approvals, and policy.
+- Run authority for nested calls: decorators around the `ToolExecutor` (outside
+  `ResolvedToolSet.execute`) do not see nested calls. Use `beforeNestedCall` or registration-level
+  wrappers for per-call checks.
+  Approval, input, interaction, background, `question`, and `subagent` tools never run from code
+  mode.
+- Where the tool is advertised (voice sessions do not get it in v1), deadlines, and limits.
+- Next.js: `serverExternalPackages: ['@yolk-sdk/codemode', '@earendil-works/pi-codemode', 'quickjs-wasi']`.
+- Vercel Workflow: run the code mode call inside the tool-batch step (`'use step'`), never inside a
+  `'use workflow'` function.
+
+## Boundaries
+
+- The root is runtime-neutral (no Node builtins) and depends only on `@yolk-sdk/agent` and the pure
+  declaration renderer of `@earendil-works/pi-codemode`; the worker-thread engine lives behind
+  `./node`. `@yolk-sdk/agent` never imports code mode.
+- The pi worker inherits a copy of `process.env`; scripts cannot read it (the VM has no `process`).
+- pi buffers script text and image output on the host thread without a limit while the script
+  runs; only the timeout bounds it. Results are bounded afterwards (`maxOutputChars`,
+  `maxImages`, `maxImageBytes`).
+- `stripTypeScriptTypes` is experimental in Node and prints one `ExperimentalWarning` per process.

package/dist/catalog.d.mts

@@ -0,0 +1,60 @@
+import { CodeModeJsonSchema } from "./executor.mjs";
+import { NestedTool } from "@yolk-sdk/agent/tools";
+
+//#region src/catalog.d.ts
+/** How a nested tool reaches scripts: `all` tools are also direct model tools; `listed` and
+ * `search` are the two discovery modes of `codemode`-only tools.
+ */
+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 namespace: string; /** The module's `ToolModule.description`, when set. */
+  readonly namespaceDescription?: string;
+  readonly description: string;
+  readonly inputSchema: CodeModeJsonSchema; /** The declared output schema, or `{ type: 'string' }` for text results. */
+  readonly outputSchema: CodeModeJsonSchema; /** True when the tool declares an output schema (calls resolve to `structuredContent`). */
+  readonly structured: boolean;
+  readonly exposure: CodeModeToolExposure;
+};
+/** 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. */
+declare const defaultCodeModeInlineBudget = 3000;
+/** Estimated tokens of a text: four characters per token, rounded up. */
+declare const estimateCodeModeTokens: (text: string) => number;
+type CodeModeListing = {
+  /** Tools placed in the description, in catalog order: every `all` tool, and the `listed` tools
+   * that fit the budget.
+   */
+  readonly listed: ReadonlyArray<CodeModeCatalogTool>; /** Namespaces (catalog order) with callable tools the description does not list. */
+  readonly unlistedNamespaces: ReadonlyArray<string>;
+};
+/**
+ * Chooses the tools the description lists. `all` tools are always placed, outside the budget
+ * (the model already has their declarations). `listed` tools fill `budget` estimated tokens fairly
+ * across namespaces: each round, every namespace still in play places its cheapest remaining tool;
+ * a namespace whose next tool does not fit drops out. `search` tools are never candidates.
+ */
+declare const selectCodeModeListing: (catalog: ReadonlyArray<CodeModeCatalogTool>, budget: number) => CodeModeListing;
+type CodeModeDescriptionInput = {
+  readonly tools: ReadonlyArray<NestedTool>;
+  readonly inlineBudget?: number; /** Mention `store()`/`load()` persistence. */
+  readonly store?: boolean;
+};
+/**
+ * The code mode tool description: intro, globals one per line, then nested tools grouped by
+ * namespace, then one fixed line pointing to `searchTools`/`describeTool`/`describeNamespace`.
+ * `all` tools get one line each outside the budget; `listed` tools are declared within the inline
+ * budget; `search` tools never contribute, so adding or removing them (even whole namespaces of
+ * them) leaves the text byte-identical.
+ */
+declare const renderCodeModeDescription: (input: CodeModeDescriptionInput) => string;
+/** `describeTool` text: the description and TypeScript declaration of one tool. */
+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 };
+//# sourceMappingURL=catalog.d.mts.map

package/dist/catalog.d.mts.map

@@ -0,0 +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"}

package/dist/catalog.mjs

@@ -0,0 +1,143 @@
+import { Predicate } from "effect";
+import { renderDeclarations, renderToolOutputType, renderToolSample, toCodemodeIdentifier } from "@earendil-works/pi-codemode/declarations";
+import { toolDiscovery } from "@yolk-sdk/agent/protocol";
+//#region src/catalog.ts
+const textOutputSchema = { type: "string" };
+/** 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
+	};
+});
+/** 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. */
+const estimateCodeModeTokens = (text) => Math.ceil(text.length / 4);
+const maxShortTypeChars = 60;
+const shortType = (schema) => {
+	const rendered = renderToolOutputType(schema);
+	if (rendered.length <= maxShortTypeChars) return rendered;
+	if (!Predicate.isBoolean(schema)) {
+		if (schema.type === "array") return "Array<unknown>";
+		if (schema.type === "object") return "object";
+	}
+	return "unknown";
+};
+const declarationTool = (tool) => ({
+	name: tool.name,
+	description: tool.description,
+	inputSchema: tool.inputSchema,
+	outputSchema: tool.outputSchema,
+	execute: () => void 0
+});
+const directToolLine = (tool) => `- \`tools.${tool.identifier}(args)\` takes the arguments of the \`${tool.name}\` tool and resolves to \`${shortType(tool.outputSchema)}\`.`;
+const declarationMembers = (tools) => renderDeclarations({ tools: tools.map(declarationTool) });
+const candidateCost = (tool) => estimateCodeModeTokens(declarationMembers([tool]));
+const groupByNamespace = (items) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const group = groups.get(item.tool.namespace);
+		if (group === void 0) groups.set(item.tool.namespace, [item]);
+		else group.push(item);
+	}
+	return groups;
+};
+/**
+* Chooses the tools the description lists. `all` tools are always placed, outside the budget
+* (the model already has their declarations). `listed` tools fill `budget` estimated tokens fairly
+* across namespaces: each round, every namespace still in play places its cheapest remaining tool;
+* a namespace whose next tool does not fit drops out. `search` tools are never candidates.
+*/
+const selectCodeModeListing = (catalog, budget) => {
+	const candidates = catalog.flatMap((tool, index) => tool.exposure === "listed" ? [{
+		tool,
+		index,
+		cost: candidateCost(tool)
+	}] : []);
+	const queues = new Map([...groupByNamespace(candidates)].map(([namespace, group]) => [namespace, [...group].sort((left, right) => left.cost - right.cost || left.index - right.index)]));
+	const placed = new Set(catalog.flatMap((tool, index) => tool.exposure === "all" ? [index] : []));
+	const inPlay = new Set(queues.keys());
+	let remaining = budget;
+	while (inPlay.size > 0) for (const [namespace, queue] of queues) {
+		if (!inPlay.has(namespace)) continue;
+		const next = queue.shift();
+		if (next === void 0 || next.cost > remaining) {
+			inPlay.delete(namespace);
+			continue;
+		}
+		placed.add(next.index);
+		remaining -= next.cost;
+	}
+	const unlisted = new Set(catalog.flatMap((tool, index) => placed.has(index) ? [] : [tool.namespace]));
+	return {
+		listed: catalog.filter((_, index) => placed.has(index)),
+		unlistedNamespaces: [...new Set(catalog.map((tool) => tool.namespace))].filter((namespace) => unlisted.has(namespace))
+	};
+};
+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).",
+	"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) => [
+	"- `text(value)` and `console.log(...values)`: append text to the output.",
+	"- `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 }>` (default limit 8).",
+	"- `await describeTool(name)`: the description and TypeScript declaration of a tool, or `undefined`.",
+	"- `await describeNamespace(name)`: `{ name, description?, tools: Array<{ name, description }> }` for a namespace, or `undefined`.",
+	...store ? ["- `store(key, value)` and `load(key)`: keep small JSON values for later scripts; writes are saved only when the script succeeds."] : []
+];
+const namespaceSection = (namespace, tools) => {
+	const declared = tools.filter((tool) => tool.exposure !== "all");
+	const direct = tools.filter((tool) => tool.exposure === "all");
+	const description = tools.find((tool) => tool.namespaceDescription !== void 0)?.namespaceDescription;
+	return [
+		`### ${namespace}`,
+		...description === void 0 ? [] : [description],
+		...declared.length > 0 ? [
+			"```ts",
+			declarationMembers(declared),
+			"```"
+		] : [],
+		...direct.map(directToolLine)
+	].join("\n");
+};
+const unlistedToolsLine = "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.";
+/**
+* The code mode tool description: intro, globals one per line, then nested tools grouped by
+* namespace, then one fixed line pointing to `searchTools`/`describeTool`/`describeNamespace`.
+* `all` tools get one line each outside the budget; `listed` tools are declared within the inline
+* budget; `search` tools never contribute, so adding or removing them (even whole namespaces of
+* them) leaves the text byte-identical.
+*/
+const renderCodeModeDescription = (input) => {
+	const sections = [...groupByNamespace(selectCodeModeListing(codeModeCatalog(input.tools), input.inlineBudget ?? 3e3).listed.map((tool) => ({ tool })))].map(([namespace, items]) => namespaceSection(namespace, items.map((item) => item.tool)));
+	return [
+		intro,
+		["Globals:", ...globalLines(input.store === true)].join("\n"),
+		sections.length === 0 ? "Nested tools: none are listed here." : ["## Nested tools by namespace", ...sections].join("\n\n"),
+		unlistedToolsLine
+	].join("\n\n");
+};
+/** `describeTool` text: the description and TypeScript declaration of one tool. */
+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 };
+
+//# sourceMappingURL=catalog.mjs.map

package/dist/catalog.mjs.map

@@ -0,0 +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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"}

package/dist/classifier-tool.d.mts

@@ -0,0 +1,78 @@
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import { ClassifierModel } from "@yolk-sdk/agent/classification";
+import { ToolRegistration } from "@yolk-sdk/agent/tools";
+
+//#region src/classifier-tool.d.ts
+/** Default name of the classifier tool. */
+declare const classifierToolName = "classify";
+/** Default cap of concurrent classifications per script. */
+declare const defaultClassifierToolMaxConcurrency = 100;
+/** Default cap of concurrent classifications per process, across scripts and registrations. */
+declare const defaultClassifierProcessMaxConcurrency = 200;
+/** A concurrency cap shared by every classifier tool registration that uses it. */
+type ClassifierConcurrencyLimiter = {
+  /** Maximum concurrent classifications. */readonly max: number;
+  /** Runs `effect` holding one permit. Waiting is interruptible and never leaks a permit; the
+   * permit is released when `effect` ends, however it ends.
+   */
+  readonly withPermit: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+};
+/** A classifier concurrency limiter allowing `max` (at least 1) classifications at once. */
+declare const makeClassifierConcurrencyLimiter: (max: number) => ClassifierConcurrencyLimiter;
+/** The process-wide limiter every classifier tool uses unless given `processLimiter`. Default
+ * 200 concurrent classifications (200 concurrent AI Gateway classifications finished in about
+ * 1.2 s without rate-limit errors in a live probe).
+ */
+declare const defaultClassifierProcessLimiter: ClassifierConcurrencyLimiter;
+type ClassifierModelService = (typeof ClassifierModel)['Service'];
+type Classify = ClassifierModelService['classify'];
+type MakeClassifierToolOptions = {
+  /** `ClassifierModel`'s `classify`, or the service value itself. */readonly classify: Classify | ClassifierModelService; /** Default `classify`. */
+  readonly name?: string;
+  /** Concurrent classifications per script (keyed by the parent tool call id of the nested call
+   * id `<parentToolCallId>/<seq>`, or the call id itself); default 100.
+   */
+  readonly maxConcurrency?: number;
+  /** Limiter shared across scripts and registrations; default `defaultClassifierProcessLimiter`
+   * (200 per process). `false` disables the process cap (the per-script cap still applies).
+   */
+  readonly processLimiter?: ClassifierConcurrencyLimiter | false;
+  readonly description?: string;
+};
+/** The classifier tool's input: one state and its named questions. Provider options stay
+ * host-owned and are never taken from scripts.
+ */
+declare const ClassifierToolParams: Schema.Struct<{
+  readonly state: Schema.Union<readonly [Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+  readonly questions: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"boolean">;
+    readonly instructions: Schema.NonEmptyString;
+    readonly criteria: Schema.optionalKey<Schema.Struct<{
+      readonly true: Schema.String;
+      readonly false: Schema.String;
+    }>>;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"choice">;
+    readonly instructions: Schema.NonEmptyString;
+    readonly criteria: Schema.$Record<Schema.NonEmptyString, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"score">;
+    readonly instructions: Schema.NonEmptyString;
+    readonly criteria: Schema.NonEmptyArray<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+  }>]>>;
+}>;
+/**
+ * A code-mode-only (`callableBy: 'codemode'`, `discovery: 'listed'`) read tool that classifies one
+ * item per call with a classifier model. Its content is the compact JSON of the answers, its
+ * `structuredContent` the full `ClassificationResult` (which nested calls resolve to), and its
+ * token usage is reported on `ToolResult.usage`. Classifier errors become model-visible error
+ * results; usage billed before a response error is kept.
+ *
+ * Each call takes a per-script permit (`maxConcurrency`) and then a process permit
+ * (`processLimiter`), so one script's queue never holds process permits it cannot use.
+ */
+declare const makeClassifierTool: <Context>(options: MakeClassifierToolOptions) => ToolRegistration<Context>;
+//#endregion
+export { ClassifierConcurrencyLimiter, ClassifierToolParams, MakeClassifierToolOptions, classifierToolName, defaultClassifierProcessLimiter, defaultClassifierProcessMaxConcurrency, defaultClassifierToolMaxConcurrency, makeClassifierConcurrencyLimiter, makeClassifierTool };
+//# sourceMappingURL=classifier-tool.d.mts.map

package/dist/classifier-tool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier-tool.d.mts","names":[],"sources":["../src/classifier-tool.ts"],"mappings":";;;;;;;cA2Ba,kBAAA;AAAb;AAAA,cAGa,mCAAA;;cAGA,sCAAA;AANkB;AAAA,KASnB,4BAAA;EANoC,mDAQrC,GAAA;EARqC;AAAA;AAGhD;EAHgD,SAYrC,UAAA,YAAsB,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,CAAA,MAAO,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,CAAA;AAAA;;cAM3E,gCAAA,GAAoC,GAAA,aAAc,4BAK9D;AAjBD;;;;AAAA,cAuBa,+BAAA,EAA+B,4BAE3C;AAAA,KAEI,sBAAA,WAAiC,eAAe;AAAA,KAEhD,QAAA,GAAW,sBAAsB;AAAA,KAE1B,yBAAA;EAzByE,4EA2B1E,QAAA,EAAU,QAAA,GAAW,sBAAA,EA3BoC;EAAA,SA6BzD,IAAA;EA7BsE;;;EAAA,SAiCtE,cAAA;EAjCgB;;;EAAA,SAqChB,cAAA,GAAiB,4BAAA;EAAA,SACjB,WAAA;AAAA;;;;cAME,oBAAA,EAAoB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;AAvBoB;AAAA;;;;AAEf;AAEtC;;;cAkGa,kBAAA,YACX,OAAA,EAAS,yBAAA,KACR,gBAAA,CAAiB,OAAA"}

package/dist/classifier-tool.mjs

@@ -0,0 +1,125 @@
+import { Effect, Predicate, Semaphore } from "effect";
+import { AgentInputUsage, AgentOutputUsage, AgentUsage, ToolResult } from "@yolk-sdk/agent/protocol";
+import * as Schema from "effect/Schema";
+import { ClassificationResult, ClassifierQuestions, ClassifierState } from "@yolk-sdk/agent/classification";
+import { makeTool, modelVisibleToolError, modelVisibleToolErrorStructuredContent } from "@yolk-sdk/agent/tools";
+//#region src/classifier-tool.ts
+/** Default name of the classifier tool. */
+const classifierToolName = "classify";
+/** Default cap of concurrent classifications per script. */
+const defaultClassifierToolMaxConcurrency = 100;
+/** Default cap of concurrent classifications per process, across scripts and registrations. */
+const defaultClassifierProcessMaxConcurrency = 200;
+const permitCount = (max) => Math.max(1, Math.floor(max));
+/** A classifier concurrency limiter allowing `max` (at least 1) classifications at once. */
+const makeClassifierConcurrencyLimiter = (max) => {
+	const permits = permitCount(max);
+	const semaphore = Semaphore.makeUnsafe(permits);
+	return {
+		max: permits,
+		withPermit: (effect) => semaphore.withPermits(1)(effect)
+	};
+};
+/** The process-wide limiter every classifier tool uses unless given `processLimiter`. Default
+* 200 concurrent classifications (200 concurrent AI Gateway classifications finished in about
+* 1.2 s without rate-limit errors in a live probe).
+*/
+const defaultClassifierProcessLimiter = makeClassifierConcurrencyLimiter(200);
+/** The classifier tool's input: one state and its named questions. Provider options stay
+* host-owned and are never taken from scripts.
+*/
+const ClassifierToolParams = Schema.Struct({
+	state: ClassifierState,
+	questions: ClassifierQuestions
+});
+const defaultDescription = (maxConcurrency) => [
+	"Classify one item with a classifier model: answer named typed questions about one `state` (a string, JSON object, or JSON array) with probabilities.",
+	"Question types: `boolean` (`probability` of true), `choice` (one of the `criteria` keys, with `probabilities`), and `score` (an ordinal level from the `criteria` list, lowest first).",
+	`Call it once per item; at most ${maxConcurrency} classifications of one script run at once and further calls queue.`
+].join(" ");
+/** Token usage of a classification as agent usage. `costUsd` has no agent usage field; it stays
+* in the result's `structuredContent.usage`, so nested-call records carry token usage only.
+*/
+const agentUsage = (usage) => AgentUsage.make({
+	input: AgentInputUsage.make({ total: usage.inputTokens }),
+	output: AgentOutputUsage.make({ total: usage.outputTokens })
+});
+const errorReason = (error) => Predicate.isTagged(error, "ClassificationRequestInvalid") ? "invalid_input" : "unavailable";
+const billedUsage = (error) => Predicate.isTagged(error, "ClassificationResponseInvalid") ? error.usage : void 0;
+/** The parent tool call id of a nested call id `<parentToolCallId>/<seq>`, else the id itself. */
+const scriptKey = (call) => {
+	const separator = call.id.lastIndexOf("/");
+	return separator > 0 ? call.id.slice(0, separator) : call.id;
+};
+const withUsage = (fields, usage) => {
+	if (usage !== void 0) fields.usage = agentUsage(usage);
+	return ToolResult.make(fields);
+};
+const successResult = (call, result) => withUsage({
+	toolCallId: call.id,
+	content: JSON.stringify(result.answers),
+	structuredContent: result
+}, result.usage);
+const errorResult = (call, name, error) => withUsage({
+	toolCallId: call.id,
+	content: error.message,
+	isError: true,
+	structuredContent: modelVisibleToolErrorStructuredContent(modelVisibleToolError({
+		tool: name,
+		reason: errorReason(error),
+		message: error.message
+	}))
+}, billedUsage(error));
+/**
+* A code-mode-only (`callableBy: 'codemode'`, `discovery: 'listed'`) read tool that classifies one
+* item per call with a classifier model. Its content is the compact JSON of the answers, its
+* `structuredContent` the full `ClassificationResult` (which nested calls resolve to), and its
+* token usage is reported on `ToolResult.usage`. Classifier errors become model-visible error
+* results; usage billed before a response error is kept.
+*
+* Each call takes a per-script permit (`maxConcurrency`) and then a process permit
+* (`processLimiter`), so one script's queue never holds process permits it cannot use.
+*/
+const makeClassifierTool = (options) => {
+	const name = options.name ?? "classify";
+	const maxConcurrency = permitCount(options.maxConcurrency ?? 100);
+	const processLimiter = options.processLimiter === void 0 ? defaultClassifierProcessLimiter : options.processLimiter;
+	const withProcessPermit = (effect) => processLimiter === false ? effect : processLimiter.withPermit(effect);
+	const classify = Predicate.isFunction(options.classify) ? options.classify : options.classify.classify;
+	const scripts = /* @__PURE__ */ new Map();
+	const withScriptPermit = (call, effect) => Effect.acquireUseRelease(Effect.sync(() => {
+		const key = scriptKey(call);
+		const entry = scripts.get(key) ?? {
+			semaphore: Semaphore.makeUnsafe(maxConcurrency),
+			users: 0
+		};
+		entry.users++;
+		scripts.set(key, entry);
+		return {
+			key,
+			entry
+		};
+	}), ({ entry }) => entry.semaphore.withPermits(1)(withProcessPermit(effect)), ({ key, entry }) => Effect.sync(() => {
+		entry.users--;
+		if (entry.users === 0 && scripts.get(key) === entry) scripts.delete(key);
+	}));
+	return makeTool({
+		name,
+		description: options.description ?? defaultDescription(maxConcurrency),
+		parameters: ClassifierToolParams,
+		output: ClassificationResult,
+		access: "read",
+		callableBy: "codemode",
+		discovery: "listed",
+		execute: ({ call, params }) => {
+			return withScriptPermit(call, classify({
+				state: params.state,
+				questions: params.questions
+			})).pipe(Effect.map((result) => successResult(call, result)), Effect.catch((error) => Effect.succeed(errorResult(call, name, error))));
+		}
+	});
+};
+//#endregion
+export { ClassifierToolParams, classifierToolName, defaultClassifierProcessLimiter, defaultClassifierProcessMaxConcurrency, defaultClassifierToolMaxConcurrency, makeClassifierConcurrencyLimiter, makeClassifierTool };
+
+//# sourceMappingURL=classifier-tool.mjs.map

package/dist/classifier-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier-tool.mjs","names":[],"sources":["../src/classifier-tool.ts"],"sourcesContent":["import { Effect, Predicate, Semaphore } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport {\n  ClassificationResult,\n  ClassifierQuestions,\n  ClassifierState,\n  type ClassificationError,\n  type ClassificationRequest,\n  type ClassificationUsage,\n  type ClassifierModel\n} from '@yolk-sdk/agent/classification'\nimport {\n  AgentInputUsage,\n  AgentOutputUsage,\n  AgentUsage,\n  ToolResult,\n  type ToolCall\n} from '@yolk-sdk/agent/protocol'\nimport {\n  makeTool,\n  modelVisibleToolError,\n  modelVisibleToolErrorStructuredContent,\n  type ModelVisibleToolErrorReason,\n  type ToolRegistration\n} from '@yolk-sdk/agent/tools'\n\n/** Default name of the classifier tool. */\nexport const classifierToolName = 'classify'\n\n/** Default cap of concurrent classifications per script. */\nexport const defaultClassifierToolMaxConcurrency = 100\n\n/** Default cap of concurrent classifications per process, across scripts and registrations. */\nexport const defaultClassifierProcessMaxConcurrency = 200\n\n/** A concurrency cap shared by every classifier tool registration that uses it. */\nexport type ClassifierConcurrencyLimiter = {\n  /** Maximum concurrent classifications. */\n  readonly max: number\n  /** Runs `effect` holding one permit. Waiting is interruptible and never leaks a permit; the\n   * permit is released when `effect` ends, however it ends.\n   */\n  readonly withPermit: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>\n}\n\nconst permitCount = (max: number) => Math.max(1, Math.floor(max))\n\n/** A classifier concurrency limiter allowing `max` (at least 1) classifications at once. */\nexport const makeClassifierConcurrencyLimiter = (max: number): ClassifierConcurrencyLimiter => {\n  const permits = permitCount(max)\n  const semaphore = Semaphore.makeUnsafe(permits)\n\n  return { max: permits, withPermit: effect => semaphore.withPermits(1)(effect) }\n}\n\n/** The process-wide limiter every classifier tool uses unless given `processLimiter`. Default\n * 200 concurrent classifications (200 concurrent AI Gateway classifications finished in about\n * 1.2 s without rate-limit errors in a live probe).\n */\nexport const defaultClassifierProcessLimiter = makeClassifierConcurrencyLimiter(\n  defaultClassifierProcessMaxConcurrency\n)\n\ntype ClassifierModelService = (typeof ClassifierModel)['Service']\n\ntype Classify = ClassifierModelService['classify']\n\nexport type MakeClassifierToolOptions = {\n  /** `ClassifierModel`'s `classify`, or the service value itself. */\n  readonly classify: Classify | ClassifierModelService\n  /** Default `classify`. */\n  readonly name?: string\n  /** Concurrent classifications per script (keyed by the parent tool call id of the nested call\n   * id `<parentToolCallId>/<seq>`, or the call id itself); default 100.\n   */\n  readonly maxConcurrency?: number\n  /** Limiter shared across scripts and registrations; default `defaultClassifierProcessLimiter`\n   * (200 per process). `false` disables the process cap (the per-script cap still applies).\n   */\n  readonly processLimiter?: ClassifierConcurrencyLimiter | false\n  readonly description?: string\n}\n\n/** The classifier tool's input: one state and its named questions. Provider options stay\n * host-owned and are never taken from scripts.\n */\nexport const ClassifierToolParams = Schema.Struct({\n  state: ClassifierState,\n  questions: ClassifierQuestions\n})\n\nconst defaultDescription = (maxConcurrency: number) =>\n  [\n    'Classify one item with a classifier model: answer named typed questions about one `state` (a string, JSON object, or JSON array) with probabilities.',\n    'Question types: `boolean` (`probability` of true), `choice` (one of the `criteria` keys, with `probabilities`), and `score` (an ordinal level from the `criteria` list, lowest first).',\n    `Call it once per item; at most ${maxConcurrency} classifications of one script run at once and further calls queue.`\n  ].join(' ')\n\n/** Token usage of a classification as agent usage. `costUsd` has no agent usage field; it stays\n * in the result's `structuredContent.usage`, so nested-call records carry token usage only.\n */\nconst agentUsage = (usage: ClassificationUsage): AgentUsage =>\n  AgentUsage.make({\n    input: AgentInputUsage.make({ total: usage.inputTokens }),\n    output: AgentOutputUsage.make({ total: usage.outputTokens })\n  })\n\nconst errorReason = (error: ClassificationError): ModelVisibleToolErrorReason =>\n  Predicate.isTagged(error, 'ClassificationRequestInvalid') ? 'invalid_input' : 'unavailable'\n\nconst billedUsage = (error: ClassificationError) =>\n  Predicate.isTagged(error, 'ClassificationResponseInvalid') ? error.usage : undefined\n\n/** The parent tool call id of a nested call id `<parentToolCallId>/<seq>`, else the id itself. */\nconst scriptKey = (call: ToolCall) => {\n  const separator = call.id.lastIndexOf('/')\n\n  return separator > 0 ? call.id.slice(0, separator) : call.id\n}\n\ntype ResultFields = {\n  toolCallId: string\n  content: string\n  isError?: boolean\n  structuredContent: unknown\n  usage?: AgentUsage\n}\n\nconst withUsage = (fields: ResultFields, usage: ClassificationUsage | undefined) => {\n  if (usage !== undefined) {\n    fields.usage = agentUsage(usage)\n  }\n\n  return ToolResult.make(fields)\n}\n\nconst successResult = (call: ToolCall, result: ClassificationResult) =>\n  withUsage(\n    { toolCallId: call.id, content: JSON.stringify(result.answers), structuredContent: result },\n    result.usage\n  )\n\nconst errorResult = (call: ToolCall, name: string, error: ClassificationError) =>\n  withUsage(\n    {\n      toolCallId: call.id,\n      content: error.message,\n      isError: true,\n      structuredContent: modelVisibleToolErrorStructuredContent(\n        modelVisibleToolError({ tool: name, reason: errorReason(error), message: error.message })\n      )\n    },\n    billedUsage(error)\n  )\n\n/**\n * A code-mode-only (`callableBy: 'codemode'`, `discovery: 'listed'`) read tool that classifies one\n * item per call with a classifier model. Its content is the compact JSON of the answers, its\n * `structuredContent` the full `ClassificationResult` (which nested calls resolve to), and its\n * token usage is reported on `ToolResult.usage`. Classifier errors become model-visible error\n * results; usage billed before a response error is kept.\n *\n * Each call takes a per-script permit (`maxConcurrency`) and then a process permit\n * (`processLimiter`), so one script's queue never holds process permits it cannot use.\n */\nexport const makeClassifierTool = <Context>(\n  options: MakeClassifierToolOptions\n): ToolRegistration<Context> => {\n  const name = options.name ?? classifierToolName\n\n  const maxConcurrency = permitCount(options.maxConcurrency ?? defaultClassifierToolMaxConcurrency)\n\n  const processLimiter =\n    options.processLimiter === undefined ? defaultClassifierProcessLimiter : options.processLimiter\n\n  const withProcessPermit = <A, E>(effect: Effect.Effect<A, E>) =>\n    processLimiter === false ? effect : processLimiter.withPermit(effect)\n\n  const classify = Predicate.isFunction(options.classify)\n    ? options.classify\n    : options.classify.classify\n\n  // One semaphore per script (parent tool call), removed when its last classification ends.\n  const scripts = new Map<string, { readonly semaphore: Semaphore.Semaphore; users: number }>()\n\n  const withScriptPermit = <A, E>(call: ToolCall, effect: Effect.Effect<A, E>) =>\n    Effect.acquireUseRelease(\n      Effect.sync(() => {\n        const key = scriptKey(call)\n\n        const entry = scripts.get(key) ?? {\n          semaphore: Semaphore.makeUnsafe(maxConcurrency),\n          users: 0\n        }\n\n        entry.users++\n        scripts.set(key, entry)\n\n        return { key, entry }\n      }),\n      ({ entry }) => entry.semaphore.withPermits(1)(withProcessPermit(effect)),\n      ({ key, entry }) =>\n        Effect.sync(() => {\n          entry.users--\n\n          if (entry.users === 0 && scripts.get(key) === entry) scripts.delete(key)\n        })\n    )\n\n  return makeTool<Context, typeof ClassifierToolParams>({\n    name,\n    description: options.description ?? defaultDescription(maxConcurrency),\n    parameters: ClassifierToolParams,\n    output: ClassificationResult,\n    access: 'read',\n    callableBy: 'codemode',\n    discovery: 'listed',\n    execute: ({ call, params }) => {\n      const request: ClassificationRequest = { state: params.state, questions: params.questions }\n\n      return withScriptPermit(call, classify(request)).pipe(\n        Effect.map(result => successResult(call, result)),\n        Effect.catch(error => Effect.succeed(errorResult(call, name, error)))\n      )\n    }\n  })\n}\n"],"mappings":"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"}