@nhtio/adk 0.1.0-master-f0aa531d

package/spooled_artifact-Cm9Te22K.js

@@ -0,0 +1,568 @@
+require("./chunk-KmRHZBOW.js");
+const require_exceptions = require("./exceptions-D5YrO9Vm.js");
+const require_tool_registry = require("./tool_registry-Dkfprsck.js");
+const require_runtime = require("./runtime-BJVkrGQe.js");
+const require_tool = require("./tool-COSeH8I6.js");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/lib/classes/artifact_tool.ts
+/**
+* Validator schema for a {@link RawArtifactTool}.
+*
+* @remarks
+* Mirrors the base tool schema but explicitly forbids `artifactConstructor` — the entire
+* point of `ArtifactTool` is to opt out of `SpooledArtifact` wrapping.
+*/
+var rawArtifactToolSchema = _nhtio_validation.validator.object({
+	name: _nhtio_validation.validator.string().required(),
+	description: _nhtio_validation.validator.string().required(),
+	inputSchema: _nhtio_validation.validator.any().custom((value, helpers) => {
+		if (_nhtio_validation.validator.isSchema(value) && value.type === "object") return value;
+		return helpers.error("any.invalid");
+	}).required(),
+	handler: _nhtio_validation.validator.function().required(),
+	meta: _nhtio_validation.validator.object().pattern(_nhtio_validation.validator.string(), _nhtio_validation.validator.any()).default({}),
+	ephemeral: _nhtio_validation.validator.boolean().default(false),
+	trusted: _nhtio_validation.validator.boolean().default(false),
+	onCollision: _nhtio_validation.validator.string().valid("throw", "replace", "keep").default("throw"),
+	artifactConstructor: _nhtio_validation.validator.any().forbidden()
+});
+/**
+* A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a
+* {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it
+* lands on `ToolCall.results`.
+*
+* @remarks
+* `ArtifactTool` is the canonical producer for **forged artifact-query tools** — the tools
+* `SpooledArtifact.forgeTools(ctx)` emits so the model can `head`, `tail`, `grep`, `json_get`,
+* `md_headings` (etc.) an artifact that is already in `ctx.turnToolCalls`.
+*
+* The difference from {@link @nhtio/adk!Tool} is structural, not stylistic:
+*
+* - A normal `Tool`'s handler returns bytes the ADK wraps in a fresh `SpooledArtifact`.
+*   The artifact lands in `ToolCall.results`, joins `ctx.turnToolCalls`, and is itself a
+*   first-class queryable artifact in the turn.
+* - An `ArtifactTool`'s handler returns a string that is **already the model-visible answer**
+*   to a query against an existing artifact. The ADK wraps it in a `Tokenizable` rather
+*   than a `SpooledArtifact`; nothing new is queryable on its own. Subsequent
+*   `forgeTools(ctx)` calls exclude `ToolCall`s produced by an `ArtifactTool` from the
+*   `callId` enum (via the `ToolCall.fromArtifactTool` marker) — this is the structural fix
+*   that breaks the otherwise-recursive grep-on-the-grep-result loop.
+*
+* Consumers who want to build their own artifact-query tools (e.g. for a domain-specific
+* spooled subclass not shipped by the ADK) should extend or instantiate this class.
+*/
+var ArtifactTool = class ArtifactTool extends require_tool.Tool {
+	/**
+	* Validator schema that accepts a {@link RawArtifactTool} object.
+	*
+	* @remarks
+	* Differs from {@link @nhtio/adk!Tool.schema} by forbidding `artifactConstructor` — wrapping is
+	* exactly the thing this class opts out of. Typed identically to {@link @nhtio/adk!Tool.schema} so the
+	* subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the
+	* runtime validation rules still differ as declared by `rawArtifactToolSchema`.
+	*/
+	static schema = rawArtifactToolSchema;
+	/**
+	* Returns `true` if `value` is an {@link ArtifactTool} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances
+	* created in a different module copy or VM context.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is an {@link ArtifactTool} instance.
+	*/
+	static isArtifactTool(value) {
+		return require_tool_registry.isInstanceOf(value, "ArtifactTool", ArtifactTool);
+	}
+	/**
+	* @param raw - Raw tool input validated against {@link ArtifactTool.schema}.
+	*
+	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy
+	*   {@link ArtifactTool.schema} (most commonly, when `artifactConstructor` is supplied — it is
+	*   explicitly forbidden on this class) or when the base {@link @nhtio/adk!Tool} constructor rejects the
+	*   input for any reason.
+	*/
+	constructor(raw) {
+		try {
+			require_exceptions.validateOrThrow(rawArtifactToolSchema, raw, true);
+		} catch (err) {
+			if (require_tool_registry.isInstanceOf(err, "ValidationException", require_exceptions.ValidationException)) throw new require_runtime.E_INVALID_INITIAL_TOOL_VALUE({ cause: err });
+			throw err;
+		}
+		super(raw);
+	}
+};
+//#endregion
+//#region src/lib/contracts/spool_reader.ts
+/**
+* Validator schema used to validate a {@link SpoolReader} value.
+*
+* @remarks
+* Because `SpoolReader` is a structural interface with no associated constructor, validation is
+* duck-typed: the value must be an object, class instance, or function with `line`, `byteLength`,
+* and `lineCount` present as callable properties. Arity is not enforced — implementations may add
+* optional parameters beyond the contract.
+*/
+var spoolReaderSchema = _nhtio_validation.validator.any().custom((value, helpers) => {
+	if (value !== null && value !== void 0 && typeof value.line === "function" && typeof value.byteLength === "function" && typeof value.lineCount === "function" && typeof value.readAll === "function") return value;
+	return helpers.error("any.invalid");
+});
+/**
+* Returns `true` if `value` implements the {@link SpoolReader} interface.
+*
+* @remarks
+* Duck-typed: checks that `value` is non-null with `line`, `byteLength`, `lineCount`, and
+* `readAll` as callable functions. Does not use `instanceof` — there is no `SpoolReader`
+* constructor.
+*
+* @param value - The value to test.
+* @returns `true` when `value` conforms to the {@link SpoolReader} interface.
+*/
+var implementsSpoolReader = (value) => {
+	return require_exceptions.passesSchema(spoolReaderSchema, value);
+};
+//#endregion
+//#region src/lib/classes/spooled_artifact.ts
+var noArgsSchema = _nhtio_validation.validator.object({});
+/**
+* Default serialiser for {@link @nhtio/adk!ArtifactTool} handler return values when a descriptor does not
+* provide its own. Exported for reuse by subclass `forgeTools` overrides.
+*
+* @param result - The artifact-method return value.
+* @returns A string suitable for inclusion in an LLM tool-call response.
+*/
+var defaultSerialise = (result) => {
+	if (result === void 0) return "(undefined)";
+	if (result === null) return "null";
+	if (typeof result === "string") return result;
+	if (Array.isArray(result) && result.every((r) => typeof r === "string")) {
+		if (result.length === 0) return "(empty list)";
+		return result.join("\n");
+	}
+	if (typeof result === "number") return String(result);
+	return JSON.stringify(result, null, 2);
+};
+var baseToolMethods = Object.freeze([
+	{
+		name: "artifact_head",
+		method: "head",
+		description: "Return the first n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.",
+		argsSchema: _nhtio_validation.validator.object({ n: _nhtio_validation.validator.number().integer().min(1).default(10).description("Number of lines to return.") })
+	},
+	{
+		name: "artifact_tail",
+		method: "tail",
+		description: "Return the last n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.",
+		argsSchema: _nhtio_validation.validator.object({ n: _nhtio_validation.validator.number().integer().min(1).default(10).description("Number of lines to return.") })
+	},
+	{
+		name: "artifact_grep",
+		method: "grep",
+		description: "Return all lines matching a regular expression pattern from a spooled artifact produced earlier in this turn.",
+		argsSchema: _nhtio_validation.validator.object({
+			pattern: _nhtio_validation.validator.string().required().description("Regular expression pattern, applied via JavaScript RegExp."),
+			flags: _nhtio_validation.validator.string().pattern(/^[imsu]*$/).optional().description("Optional RegExp flags. Allowed: 'i' (case-insensitive), 'm' (multiline), 's' (dotAll), 'u' (unicode). 'g' and 'y' are disallowed because per-line matching is stateless.")
+		})
+	},
+	{
+		name: "artifact_cat",
+		method: "cat",
+		description: "Return lines from a spooled artifact produced earlier in this turn, optionally bounded to a range.",
+		argsSchema: _nhtio_validation.validator.object({
+			start: _nhtio_validation.validator.number().integer().min(0).optional().description("Start line (inclusive)."),
+			end: _nhtio_validation.validator.number().integer().min(0).optional().description("End line (exclusive).")
+		})
+	},
+	{
+		name: "artifact_byte_length",
+		method: "byteLength",
+		description: "Return the total byte length of a spooled artifact produced earlier in this turn.",
+		argsSchema: noArgsSchema
+	},
+	{
+		name: "artifact_line_count",
+		method: "lineCount",
+		description: "Return the total line count of a spooled artifact produced earlier in this turn.",
+		argsSchema: noArgsSchema
+	},
+	{
+		name: "artifact_estimate_tokens",
+		method: "estimateTokens",
+		description: "Estimate the total token count of a spooled artifact produced earlier in this turn under a named encoding.",
+		argsSchema: _nhtio_validation.validator.object({ encoding: _nhtio_validation.validator.string().valid(...require_tool_registry.TokenEncoding).required().description("Token encoding identifier.") })
+	}
+]);
+/**
+* A lazy, line-oriented view over an arbitrary backing store.
+*
+* @remarks
+* All I/O methods are async to remain compatible with both in-memory and streaming
+* {@link @nhtio/adk!SpoolReader} implementations. Token estimation delegates to
+* {@link @nhtio/adk!Tokenizable.estimateTokens} — the same backends used elsewhere in the ADK.
+*
+* The class is read-only by design: mutation of the underlying data is the responsibility of the
+* producer that created the {@link @nhtio/adk!SpoolReader}, not the consumer reading from this artifact.
+*/
+var SpooledArtifact = class SpooledArtifact {
+	/**
+	* The set of artifact-query methods this class surfaces via {@link SpooledArtifact.forgeTools}.
+	*
+	* @remarks
+	* The base set covers the generic line-oriented operations every artifact supports:
+	* `artifact_head`, `artifact_tail`, `artifact_grep`, `artifact_cat`, `artifact_byte_length`,
+	* `artifact_line_count`, `artifact_estimate_tokens`. Each `toolMethods` array lists **only**
+	* its own class's descriptors — subclasses do not concatenate inherited descriptors. The
+	* subclass instead overrides {@link SpooledArtifact.forgeTools} to merge the base registry
+	* (produced by `SpooledArtifact.forgeTools(ctx)`) with its own — see
+	* {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for
+	* the canonical shape and the pattern downstream consumers should follow when building
+	* their own `SpooledArtifact` subclasses.
+	*
+	* Tool names are absolute (not subclass-prefixed). Forged tools carry
+	* `Tool.onCollision = 'replace'` so merging multiple subclasses' `forgeTools()` outputs is
+	* silent — every same-named tool dispatches the same method on whatever artifact the
+	* `callId` resolves to, so the overlap is behaviourally interchangeable.
+	*
+	* Frozen at module load.
+	*/
+	static toolMethods = baseToolMethods;
+	#reader;
+	/**
+	* @param reader - The backing store to read from.
+	* @throws {@link @nhtio/adk!E_NOT_A_SPOOL_READER} when `reader` does not implement {@link @nhtio/adk!SpoolReader}.
+	*/
+	constructor(reader) {
+		if (!implementsSpoolReader(reader)) throw new require_runtime.E_NOT_A_SPOOL_READER();
+		this.#reader = reader;
+	}
+	/**
+	* Returns the line at the given 0-based index, or `undefined` when out of range.
+	*
+	* @remarks
+	* Protected so subclasses can scan the backing store line-by-line without allocating
+	* intermediate arrays. Delegates directly to the {@link @nhtio/adk!SpoolReader}.
+	*
+	* @param index - 0-based line index.
+	* @returns The raw line string, or `undefined` when out of range.
+	*/
+	async line(index) {
+		return this.#reader.line(index);
+	}
+	/**
+	* Returns `true` if `value` is a {@link SpooledArtifact} instance (including any subclass).
+	*
+	* @remarks
+	* Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then
+	* `Symbol.hasInstance`, then a `constructor.name` fallback. Subclass instances (e.g.
+	* {@link @nhtio/adk!SpooledJsonArtifact}) satisfy this guard because `instanceof` walks the prototype
+	* chain. The fallbacks handle the dual-module-copy case where two distinct `SpooledArtifact`
+	* classes coexist in the same realm (e.g. one bundled into a downstream library, one in the
+	* consumer's `node_modules`).
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link SpooledArtifact} instance.
+	*/
+	static isSpooledArtifact(value) {
+		return require_tool_registry.isInstanceOf(value, "SpooledArtifact", SpooledArtifact);
+	}
+	/**
+	* Returns `true` if `value` is a constructor function whose prototype chain includes
+	* {@link SpooledArtifact} (including `SpooledArtifact` itself).
+	*
+	* @remarks
+	* Used by {@link @nhtio/adk!Tool} to validate the optional `artifactConstructor` field. Performs an
+	* `instanceof`-based check on the prototype chain; falls back to a duck-type test that looks
+	* for the canonical SpooledArtifact instance methods on `value.prototype` for cross-realm
+	* safety (constructors passed from a different module copy or VM context).
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a constructor for `SpooledArtifact` or a subclass.
+	*/
+	static isSpooledArtifactConstructor(value) {
+		if (typeof value !== "function") return false;
+		if (value === SpooledArtifact) return true;
+		const proto = value.prototype;
+		if (proto === void 0 || proto === null) return false;
+		if (require_tool_registry.isInstanceOf(proto, "SpooledArtifact", SpooledArtifact)) return true;
+		return [
+			"head",
+			"tail",
+			"grep",
+			"cat",
+			"byteLength",
+			"lineCount",
+			"estimateTokens"
+		].every((m) => typeof proto[m] === "function");
+	}
+	/**
+	* Returns the first `n` lines of the artifact.
+	*
+	* @remarks
+	* If the artifact contains fewer than `n` lines, all available lines are returned. Matches the
+	* behaviour of POSIX `head -n`.
+	*
+	* @param n - Number of lines to return. Defaults to 10.
+	* @returns Array of line strings, without trailing newlines.
+	*/
+	async head(n = 10) {
+		const count = await this.#reader.lineCount();
+		const limit = Math.min(n, count);
+		const lines = [];
+		for (let i = 0; i < limit; i++) {
+			const line = await this.#reader.line(i);
+			if (line !== void 0) lines.push(line);
+		}
+		return lines;
+	}
+	/**
+	* Returns the last `n` lines of the artifact.
+	*
+	* @remarks
+	* If the artifact contains fewer than `n` lines, all available lines are returned. Matches the
+	* behaviour of POSIX `tail -n`.
+	*
+	* @param n - Number of lines to return. Defaults to 10.
+	* @returns Array of line strings, without trailing newlines.
+	*/
+	async tail(n = 10) {
+		const count = await this.#reader.lineCount();
+		const start = Math.max(0, count - n);
+		const lines = [];
+		for (let i = start; i < count; i++) {
+			const line = await this.#reader.line(i);
+			if (line !== void 0) lines.push(line);
+		}
+		return lines;
+	}
+	/**
+	* Returns all lines that match `pattern`.
+	*
+	* @remarks
+	* Behaves like POSIX `grep`: each line is tested against the pattern and included in the result
+	* when it matches. The pattern is applied as a JavaScript `RegExp`; flags (e.g. case-
+	* insensitivity) should be encoded in the expression itself.
+	*
+	* Stateful flags (`g`, `y`) on the supplied `RegExp` would normally cause `pattern.test()` to
+	* advance `lastIndex` across calls, producing skipped matches and order-dependent results. To
+	* keep the per-line semantics stateless, `grep` resets `pattern.lastIndex` to `0` before each
+	* line test. The forged `artifact_grep` tool also rejects `g` and `y` flags up-front at schema
+	* validation time.
+	*
+	* @param pattern - The regular expression to test each line against.
+	* @returns Array of matching line strings, in order.
+	*/
+	async grep(pattern) {
+		const count = await this.#reader.lineCount();
+		const matches = [];
+		for (let i = 0; i < count; i++) {
+			const line = await this.#reader.line(i);
+			if (line !== void 0) {
+				pattern.lastIndex = 0;
+				if (pattern.test(line)) matches.push(line);
+			}
+		}
+		return matches;
+	}
+	/**
+	* Returns lines from the artifact, optionally bounded to a range.
+	*
+	* @remarks
+	* Without arguments, returns all lines — equivalent to POSIX `cat`. With `start` and/or `end`,
+	* behaves like `Array.prototype.slice`: `start` defaults to `0`, `end` defaults to the total
+	* line count, and only lines in `[start, end)` are fetched from the backing store. For large
+	* artifacts, prefer a bounded range or {@link SpooledArtifact.head} / {@link SpooledArtifact.tail}.
+	*
+	* @param start - 0-based start line index (inclusive). Defaults to `0`.
+	* @param end - 0-based end line index (exclusive). Defaults to `lineCount()`.
+	* @returns Array of line strings in the requested range.
+	*/
+	async cat(start, end) {
+		const count = await this.#reader.lineCount();
+		const from = Math.max(0, start ?? 0);
+		const to = Math.min(count, end ?? count);
+		const lines = [];
+		for (let i = from; i < to; i++) {
+			const line = await this.#reader.line(i);
+			if (line !== void 0) lines.push(line);
+		}
+		return lines;
+	}
+	/**
+	* Returns the total byte length of the underlying data.
+	*
+	* @returns The byte length as reported by the {@link @nhtio/adk!SpoolReader}.
+	*/
+	async byteLength() {
+		return this.#reader.byteLength();
+	}
+	/**
+	* Returns the total number of lines in the artifact.
+	*
+	* @returns The line count as reported by the {@link @nhtio/adk!SpoolReader}.
+	*/
+	async lineCount() {
+		return this.#reader.lineCount();
+	}
+	/**
+	* Estimates the total token count of the artifact under `encoding`.
+	*
+	* @remarks
+	* Reads the full byte-faithful content via {@link SpooledArtifact.asString} (which delegates to
+	* {@link @nhtio/adk!SpoolReader.readAll}) and delegates to {@link @nhtio/adk!Tokenizable.estimateTokens}. The estimate
+	* therefore reflects the actual source bytes — including trailing newlines and non-`\n` line
+	* terminators that the line-based {@link SpooledArtifact.cat} view would otherwise discard or
+	* misrepresent.
+	*
+	* @param encoding - The encoding identifier to use for counting.
+	* @returns The estimated number of tokens.
+	*/
+	async estimateTokens(encoding) {
+		const content = await this.#reader.readAll();
+		return require_tool_registry.Tokenizable.estimateTokens(content, encoding);
+	}
+	/**
+	* Returns the full artifact body as a single byte-faithful string.
+	*
+	* @remarks
+	* Round-trip faithful to whatever bytes the {@link @nhtio/adk!SpoolReader} was constructed over —
+	* preserves trailing newlines and non-`\n` line terminators that {@link SpooledArtifact.cat}
+	* discards via its line-based view. This is the canonical primitive for "inline the artifact
+	* content directly into a message" use cases.
+	*
+	* `asString()` and the static `forgeTools(ctx)` factory on each subclass are independent
+	* alternatives — a consumer chooses per turn whether to inline the body in a message
+	* (`await tc.results.asString()`) or hand the model query tools
+	* (`SpooledArtifact.forgeTools(ctx)`). Neither calls the other; either works with neither.
+	*
+	* @returns The full content as a single string.
+	*/
+	async asString() {
+		return this.#reader.readAll();
+	}
+	/**
+	* Forges a fresh {@link @nhtio/adk!ToolRegistry} of ephemeral {@link @nhtio/adk!ArtifactTool} instances that let the
+	* LLM query artifacts already present in `ctx.turnToolCalls`.
+	*
+	* @remarks
+	* Standard subclass extension pattern — each class owns only its own `toolMethods` and its
+	* own `forgeTools`. The base `SpooledArtifact.forgeTools(ctx)` narrows the `callId` enum to
+	* any `tc.results instanceof SpooledArtifact` (so subclass instances are included — that's
+	* the whole point of inheritance) and dispatches the seven base methods (`head`, `tail`,
+	* `grep`, `cat`, `byteLength`, `lineCount`, `estimateTokens`) on the resolved artifact.
+	* Subclasses override `forgeTools` to call this static first and then register their own
+	* tools on the returned registry — see {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and
+	* {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for the canonical shape. There is no
+	* `requiresSubclass` field, no helper indirection, and no `this`-based class narrowing —
+	* just plain `instanceof ThisClass` at each subclass's own filter site.
+	*
+	* For each descriptor in this class's `toolMethods`, the factory:
+	*
+	* 1. Walks `ctx.turnToolCalls` to find `ToolCall`s whose `results instanceof SpooledArtifact`.
+	*    `ToolCall`s flagged `fromArtifactTool === true` are excluded — they carry a
+	*    {@link @nhtio/adk!Tokenizable}, not a `SpooledArtifact`, and including them would let the model
+	*    `artifact_grep` on a previous `artifact_grep` result (an infinite-recursion hazard with
+	*    no semantic value).
+	* 2. Returns an empty registry if no compatible callIds are found — no point shipping tools
+	*    whose `callId` enum is empty.
+	* 3. Otherwise mints an {@link @nhtio/adk!ArtifactTool} with `ephemeral: true` and `onCollision: 'replace'`
+	*    so multiple `Subclass.forgeTools(ctx)` outputs merge silently. The tool's `inputSchema`
+	*    includes a required `callId` field with `.valid(...compatibleIds)`, plus the descriptor's
+	*    own `argsSchema` fields.
+	*
+	* The handler resolves the artifact via `[...ctx.turnToolCalls].find(t => t.id === callId)`,
+	* dispatches the descriptor's method, and serialises the return value (string → as-is;
+	* string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`;
+	* `descriptor.serialise` overrides the defaults). `grep` is special-cased: the handler
+	* constructs `new RegExp(pattern, flags ?? '')` before invoking the artifact's `grep` method.
+	*
+	* The returned registry must be merged into the consumer's main registry and the main
+	* registry must be bound to `ctx` via {@link @nhtio/adk!ToolRegistry.bindContext}:
+	*
+	* ```ts
+	* const executor: DispatchExecutorFn = async (ctx) => {
+	*   const forged = SpooledArtifact.forgeTools(ctx)
+	*   const merged = ToolRegistry.merge([main, forged])
+	*   main.bindContext(ctx)
+	*   const result = await llm.invoke({ tools: merged.all(), ... })
+	*   ctx.ack() // ← ephemeral cleanup fires here
+	* }
+	* ```
+	*
+	* @warning You **must** call `registry.bindContext(ctx)` on the registry hosting these tools,
+	* or ephemeral cleanup will not run and the `callId` enum in subsequent executor calls will
+	* be stale (excluding new tool calls produced in the meantime).
+	*
+	* @param ctx - The execution context whose `turnToolCalls` snapshot defines the `callId` enum.
+	* @returns A fresh `ToolRegistry`. Empty when `turnToolCalls` contains no compatible artifacts.
+	*
+	* @see {@link @nhtio/adk!ToolRegistry.bindContext}
+	* @see {@link @nhtio/adk!ToolRegistry.merge}
+	* @see {@link @nhtio/adk!DispatchContext.onAck}
+	*/
+	static forgeTools(ctx) {
+		const requires = SpooledArtifact;
+		const compatibleIds = [...ctx.turnToolCalls].filter((tc) => !tc.fromArtifactTool && require_tool_registry.isInstanceOf(tc.results, requires.name, requires)).map((tc) => tc.id);
+		if (compatibleIds.length === 0) return new require_tool_registry.ToolRegistry([]);
+		const tools = [];
+		for (const descriptor of this.toolMethods) {
+			const callIdSchema = _nhtio_validation.validator.string().valid(...compatibleIds).required().description("ToolCall id of the artifact to query.");
+			const argsSchema = (descriptor.argsSchema ?? noArgsSchema).append({ callId: callIdSchema });
+			const serialise = descriptor.serialise ?? defaultSerialise;
+			const tool = new ArtifactTool({
+				name: descriptor.name,
+				description: descriptor.description,
+				inputSchema: argsSchema,
+				ephemeral: true,
+				onCollision: "replace",
+				handler: async (rawArgs, ctxInner) => {
+					const args = rawArgs;
+					const tc = [...ctxInner.turnToolCalls].find((t) => t.id === args.callId);
+					if (!tc) return `Error: no tool call with id ${args.callId} in this turn`;
+					const artifact = tc.results;
+					if (!require_tool_registry.isInstanceOf(artifact, requires.name, requires)) return `Error: tool call ${args.callId} results are not a ${requires.name} instance`;
+					const methodArgs = [];
+					if (descriptor.method === "grep") {
+						const pattern = args.pattern;
+						const flags = args.flags ?? "";
+						methodArgs.push(new RegExp(pattern, flags));
+					} else if (descriptor.method === "head" || descriptor.method === "tail") methodArgs.push(args.n ?? 10);
+					else if (descriptor.method === "cat") methodArgs.push(args.start, args.end);
+					else if (descriptor.method === "estimateTokens") methodArgs.push(args.encoding);
+					const fn = artifact[descriptor.method];
+					if (typeof fn !== "function") return `Error: artifact has no method ${descriptor.method}`;
+					return serialise(await Promise.resolve(fn.apply(artifact, methodArgs)));
+				}
+			});
+			tools.push(tool);
+		}
+		return new require_tool_registry.ToolRegistry(tools);
+	}
+};
+//#endregion
+Object.defineProperty(exports, "ArtifactTool", {
+	enumerable: true,
+	get: function() {
+		return ArtifactTool;
+	}
+});
+Object.defineProperty(exports, "SpooledArtifact", {
+	enumerable: true,
+	get: function() {
+		return SpooledArtifact;
+	}
+});
+Object.defineProperty(exports, "defaultSerialise", {
+	enumerable: true,
+	get: function() {
+		return defaultSerialise;
+	}
+});
+Object.defineProperty(exports, "implementsSpoolReader", {
+	enumerable: true,
+	get: function() {
+		return implementsSpoolReader;
+	}
+});
+
+//# sourceMappingURL=spooled_artifact-Cm9Te22K.js.map