@yolk-sdk/codemode 0.1.0-canary.100

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,174 @@
+# @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
+```
+
+Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+Use the SDK's matching Effect version (`4.0.0`) in host code.
+Requires Node.js 22.19+ (the pi engine's minimum). `@yolk-sdk/codemode/node` is server-only.
+
+## Subpaths
+
+| 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. The record keeps up to `maxNestedCalls` calls, at most 4096
+  (`nestedToolCallMaxRecordedCalls`; argument byte budgets still apply), and per-status `counts`
+  over every call. 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, `beforeNestedCall` failures, and calls past `maxNestedCalls` reject
+  with an `Error` whose message is `tools.<id>: <text>`, or `tools["<name>"]: <text>` for a tool
+  whose identifier an earlier tool already uses (the nested-call record keeps the raw text). Calls
+  still running when the script ends are cancelled and recorded as `cancelled`.
+- Arguments make a JSON round trip: `undefined` keys and `null` optionals are absent, unknown keys
+  reject with a hint naming the allowed keys, and values JSON would silently change (`NaN`,
+  `Infinity`, invalid `Date`s, `undefined` array items, `Map`, `Set`, functions, class instances)
+  reject in the script before the call, with messages such as
+  `tools.search: argument at limit is NaN; pass a finite number or omit the key`. The pi executor
+  reads the argument once (getters and `toJSON` run once) into a checked JSON copy and sends that
+  copy; a valid `Date` passes as its ISO string. Arguments with more than 100,000 values or more
+  than 64 levels of nesting are rejected, never sent unchecked. Custom executors follow the same
+  rules (`CodeModeExecutorTool`) and label rejections with `CodeModeExecutorTool.callLabel`, which
+  `makeCodeModeTool` sets.
+- The tool description lists the globals and the nested tools by namespace, with the module's
+  `ToolModule.description` under each heading. `codemode` + `listed` tools get TypeScript
+  declarations within `inlineBudget` (default 3,000 estimated tokens, filled fairly across
+  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 `<label>: <message>` and records it as `error` without executing it.
+- `afterNestedCall({ call, outcome, durationMs, context, result? })` runs after each admitted
+  nested call with `success`, `failure` (error result or unexpected failure), or `interrupted`
+  (cancelled, for example still running when the script ended). Calls rejected before running are
+  not reported. A failing hook (a failure, a defect, or a synchronous throw) is logged and never
+  changes the call's result.
+- A nested call that is interrupted rejects with `<label> was cancelled.`; a defect rejects with
+  `<label> failed unexpectedly.` (the same label as above). If an executor misses its deadline, the tool returns a `timeout` failure
+  `timeoutMs` + 5 s after the start and aborts it.
+
+## Re-execution and the tool ledger
+
+Hosts that re-execute steps (Vercel Workflow's queue is at-least-once) pass a durable ledger to
+`resolveTools(modules, context, { ledger: { store } })` (see `@yolk-sdk/agent/tools`). The
+`codemode` call is itself ledgered, so a re-executed call never runs its script again:
+
+- completed: the stored result is returned;
+- still running elsewhere: the call waits for it (up to `maxWaitMs`/`deadline`);
+- abandoned (the earlier execution crashed): an interrupted error result lists that script's
+  ledgered nested calls as applied, failed, or unknown (started, no recorded result), states that
+  they were not undone, and asks the model to verify. Hosts get the same entries in
+  `structuredContent.codemode` without calling the store again:
+  `{ ok: false, interrupted: true, interruptedCalls: { calls, complete, counts } }`, where each call
+  is `{ key, toolName, args, status: 'applied' | 'failed' | 'unknown' }` (`args` compact JSON cut
+  with a trailing `…`), bounded like `nestedCalls` (`maxNestedCalls` calls, 8 KiB of arguments per
+  call, 32 KiB in total; `complete: false` when cut, here or by the ledger), and `counts` covers
+  every entry. Types: `CodeModeInterruptedCalls`, `CodeModeInterruptedCall`,
+  `CodeModeInterruptedCallStatus`. When the ledger cannot list the nested calls, the result stays
+  interrupted, says they may already have been applied, and sets
+  `interruptedCallsUnavailable: true` instead of `interruptedCalls`.
+
+Nested write calls are ledgered under `<toolCallId>/<seq>` and receive a stable `idempotencyKey`.
+Calls the ledger policy skips (by default read-only calls) are not listed.
+
+## 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; also sizes the `nestedCalls` record (at most 4096) |
+| `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, and supply a durable tool ledger: steps are at-least-once.
+
+## 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,74 @@
+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;
+  /**
+   * How scripts call this tool, used to prefix its rejections: `tools.<identifier>`, or
+   * `tools["<name>"]` when an earlier tool already has the identifier (see `codeModeCallLabels`;
+   * when the name is taken too, the tool is unreachable and the label only names it).
+   */
+  readonly callLabel: string; /** The tool's `ToolModule.id`. */
+  readonly namespace: string; /** The module's `ToolModule.description`, when set. */
+  readonly namespaceDescription?: string;
+  readonly description: string;
+  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;
+};
+/**
+ * The call label of each tool name, in order, as pi binds `tools`: each tool takes
+ * `tools[<identifier>]` unless an earlier tool holds that key (first tool wins), then
+ * `tools[<name>]` if still free. The label is `tools.<identifier>` for the tool that holds its
+ * identifier, otherwise `tools["<name>"]`. The executor guard and the host rejection prefix share
+ * it, so both name a call the same way.
+ */
+declare const codeModeCallLabels: (names: ReadonlyArray<string>) => ReadonlyArray<string>;
+/** Catalog of nested tools in resolution order. */
+declare const codeModeCatalog: (tools: ReadonlyArray<NestedTool>) => ReadonlyArray<CodeModeCatalogTool>;
+/** Default inline budget of the nested tool listing, in estimated tokens. */
+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, codeModeCallLabels, 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;EAYa;;;;;EAAA,SANb,SAAA,UANA;EAAA,SAQA,SAAA;EAAA,SAEA,oBAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,EAAa,kBAAA,EAAA;EAAA,SAEb,YAAA,EAAc,kBAAA,EAAA;EAAA,SAEd,UAAA;EAAA,SACA,QAAA,EAAU,oBAAA;AAAA;;AAAoB;AAYzC;;;;;cAAa,kBAAA,GAAsB,KAAA,EAAO,aAAA,aAAwB,aAAa;;cAelE,eAAA,GACX,KAAA,EAAO,aAAA,CAAc,UAAA,MACpB,aAAA,CAAc,mBAAA;AAjB8D;AAAA,cAwClE,2BAAA;;cAGA,sBAAA,GAA0B,IAAY;AAAA,KA4DvC,eAAA;EAvFH;;;EAAA,SA2FE,MAAA,EAAQ,aAAA,CAAc,mBAAA,GA1FjB;EAAA,SA4FL,kBAAA,EAAoB,aAAA;AAAA;;;;;AA5FK;AAuBpC;cA8Ea,qBAAA,GACX,OAAA,EAAS,aAAA,CAAc,mBAAA,GACvB,MAAA,aACC,eAAA;AAAA,KAuFS,wBAAA;EAAA,SACD,KAAA,EAAO,aAAa,CAAC,UAAA;EAAA,SACrB,YAAA,WAvKE;EAAA,SAyKF,KAAA;AAAA;;AAzKwC;AA4DnD;;;;;cAuHa,yBAAA,GAA6B,KAA+B,EAAxB,wBAAwB;;cAwB5D,oBAAA,GAAwB,IAAyB,EAAnB,mBAAmB;;cAIjD,gBAAA,GACX,OAAA,EAAS,aAAA,CAAc,mBAAA,GACvB,IAAA,aACC,mBAAA"}

package/dist/catalog.mjs

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

package/dist/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"}