@nhtio/adk 0.1.0-master-f0aa531d

package/spooled_artifact-C5ZtGxuJ.mjs

@@ -0,0 +1,544 @@
+import { a as validateOrThrow, i as passesSchema, n as ValidationException } from "./exceptions-NrzIHw_R.mjs";
+import { a as Tokenizable, i as TokenEncoding, s as isInstanceOf, t as ToolRegistry } from "./tool_registry-DqLOyGyG.mjs";
+import { C as E_NOT_A_SPOOL_READER, d as E_INVALID_INITIAL_TOOL_VALUE } from "./runtime-CrEPIFgr.mjs";
+import { t as Tool } from "./tool-D2WB1EA1.mjs";
+import { validator } from "@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 = validator.object({
+	name: validator.string().required(),
+	description: validator.string().required(),
+	inputSchema: validator.any().custom((value, helpers) => {
+		if (validator.isSchema(value) && value.type === "object") return value;
+		return helpers.error("any.invalid");
+	}).required(),
+	handler: validator.function().required(),
+	meta: validator.object().pattern(validator.string(), validator.any()).default({}),
+	ephemeral: validator.boolean().default(false),
+	trusted: validator.boolean().default(false),
+	onCollision: validator.string().valid("throw", "replace", "keep").default("throw"),
+	artifactConstructor: 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 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 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 {
+			validateOrThrow(rawArtifactToolSchema, raw, true);
+		} catch (err) {
+			if (isInstanceOf(err, "ValidationException", ValidationException)) throw new 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 = 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 passesSchema(spoolReaderSchema, value);
+};
+//#endregion
+//#region src/lib/classes/spooled_artifact.ts
+var noArgsSchema = 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: validator.object({ n: 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: validator.object({ n: 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: validator.object({
+			pattern: validator.string().required().description("Regular expression pattern, applied via JavaScript RegExp."),
+			flags: 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: validator.object({
+			start: validator.number().integer().min(0).optional().description("Start line (inclusive)."),
+			end: 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: validator.object({ encoding: validator.string().valid(...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 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 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 (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 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 && isInstanceOf(tc.results, requires.name, requires)).map((tc) => tc.id);
+		if (compatibleIds.length === 0) return new ToolRegistry([]);
+		const tools = [];
+		for (const descriptor of this.toolMethods) {
+			const callIdSchema = 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 (!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 ToolRegistry(tools);
+	}
+};
+//#endregion
+export { ArtifactTool as i, defaultSerialise as n, implementsSpoolReader as r, SpooledArtifact as t };
+
+//# sourceMappingURL=spooled_artifact-C5ZtGxuJ.mjs.map

package/spooled_artifact-C5ZtGxuJ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"spooled_artifact-C5ZtGxuJ.mjs","names":["#reader"],"sources":["../src/lib/classes/artifact_tool.ts","../src/lib/contracts/spool_reader.ts","../src/lib/classes/spooled_artifact.ts"],"sourcesContent":["import { Tool } from './tool'\nimport { validator } from '@nhtio/validation'\nimport { isInstanceOf } from '../utils/guards'\nimport { E_INVALID_INITIAL_TOOL_VALUE } from '../exceptions/runtime'\nimport { validateOrThrow, ValidationException } from '../utils/validation'\nimport type { Registry } from './registry'\nimport type { Schema } from '@nhtio/validation'\nimport type { Tokenizable } from './tokenizable'\nimport type { DispatchContext } from '../contracts/dispatch_context'\n\n/**\n * The execution function for an {@link ArtifactTool}.\n *\n * @remarks\n * Identical to the base tool handler except the return type is narrowed to\n * `string | Tokenizable | Promise<string | Tokenizable>`. Forged artifact-query tools emit\n * model-visible strings — the ADK wraps a bare-string return into a {@link @nhtio/adk!Tokenizable}\n * at the result-wrapping site so downstream code can rely on\n * `ToolCall.results instanceof Tokenizable` for every `ArtifactTool` invocation.\n */\nexport type ArtifactToolHandler = (\n  args: unknown,\n  ctx: DispatchContext,\n  meta: Registry\n) => string | Tokenizable | Promise<string | Tokenizable>\n\n/**\n * Plain input object supplied to {@link ArtifactTool} at construction time.\n *\n * @remarks\n * Mirrors the base `RawTool` except `artifactConstructor` is forbidden — an `ArtifactTool`\n * emits a {@link @nhtio/adk!Tokenizable} directly into `ToolCall.results` and explicitly opts out of\n * `SpooledArtifact` wrapping. The forbidden field is enforced by {@link ArtifactTool.schema}\n * at construction time.\n */\nexport interface RawArtifactTool {\n  /** Unique identifier used in LLM tool definitions. Recommend lowercase snake_case. */\n  name: string\n  /** Human-readable description passed to the model to explain what the tool does. */\n  description: string\n  /** @nhtio/validation schema for the tool's input arguments. */\n  inputSchema: Schema\n  /** Execution function. Returns a string or {@link @nhtio/adk!Tokenizable}; the ADK wraps a bare string into a `Tokenizable` at the result-wrapping site. */\n  handler: ArtifactToolHandler\n  /** Optional arbitrary metadata for this tool. Defaults to `{}`. */\n  meta?: Record<string, unknown>\n  /**\n   * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext}.\n   *\n   * @remarks\n   * `ArtifactTool` instances produced by `SpooledArtifact.forgeTools(ctx)` set this to `true`\n   * so that `ToolRegistry.pruneEphemeral()` drops them at ctx-completion.\n   *\n   * @defaultValue `false`\n   */\n  ephemeral?: boolean\n  /**\n   * When `true`, declares that this tool's output should be treated as **trusted developer/user\n   * intent** rather than as untrusted third-party text when surfaced to the model.\n   *\n   * @remarks\n   * Forged artifact-query tools default to `false` because their results are derived from\n   * spooled artifact bodies — which may themselves be untrusted upstream tool output. The\n   * trust signal does not promote handle-query results above the trust tier of the underlying\n   * artifact.\n   *\n   * @defaultValue `false`\n   */\n  trusted?: boolean\n  /**\n   * Self-declared merge collision policy honoured by `ToolRegistry.merge`.\n   *\n   * @remarks\n   * Forged artifact-query tools set this to `'replace'` so that merging multiple\n   * `Subclass.forgeTools(ctx)` outputs (whose base-method tools overlap by name) resolves\n   * silently — the descriptors, snapshot, and handler behaviour are interchangeable across\n   * subclasses, so replacement is a behavioural no-op.\n   *\n   * @defaultValue `'throw'`\n   */\n  onCollision?: 'throw' | 'replace' | 'keep'\n}\n\n/**\n * Validator schema for a {@link RawArtifactTool}.\n *\n * @remarks\n * Mirrors the base tool schema but explicitly forbids `artifactConstructor` — the entire\n * point of `ArtifactTool` is to opt out of `SpooledArtifact` wrapping.\n */\nconst rawArtifactToolSchema = validator.object<RawArtifactTool & { artifactConstructor?: never }>({\n  name: validator.string().required(),\n  description: validator.string().required(),\n  inputSchema: validator\n    .any()\n    .custom((value, helpers) => {\n      if (validator.isSchema(value) && (value as any).type === 'object') return value\n      return helpers.error('any.invalid')\n    })\n    .required(),\n  handler: validator.function().required(),\n  meta: validator.object().pattern(validator.string(), validator.any()).default({}),\n  ephemeral: validator.boolean().default(false),\n  trusted: validator.boolean().default(false),\n  onCollision: validator.string().valid('throw', 'replace', 'keep').default('throw'),\n  artifactConstructor: validator.any().forbidden(),\n})\n\n/**\n * A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a\n * {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it\n * lands on `ToolCall.results`.\n *\n * @remarks\n * `ArtifactTool` is the canonical producer for **forged artifact-query tools** — the tools\n * `SpooledArtifact.forgeTools(ctx)` emits so the model can `head`, `tail`, `grep`, `json_get`,\n * `md_headings` (etc.) an artifact that is already in `ctx.turnToolCalls`.\n *\n * The difference from {@link @nhtio/adk!Tool} is structural, not stylistic:\n *\n * - A normal `Tool`'s handler returns bytes the ADK wraps in a fresh `SpooledArtifact`.\n *   The artifact lands in `ToolCall.results`, joins `ctx.turnToolCalls`, and is itself a\n *   first-class queryable artifact in the turn.\n * - An `ArtifactTool`'s handler returns a string that is **already the model-visible answer**\n *   to a query against an existing artifact. The ADK wraps it in a `Tokenizable` rather\n *   than a `SpooledArtifact`; nothing new is queryable on its own. Subsequent\n *   `forgeTools(ctx)` calls exclude `ToolCall`s produced by an `ArtifactTool` from the\n *   `callId` enum (via the `ToolCall.fromArtifactTool` marker) — this is the structural fix\n *   that breaks the otherwise-recursive grep-on-the-grep-result loop.\n *\n * Consumers who want to build their own artifact-query tools (e.g. for a domain-specific\n * spooled subclass not shipped by the ADK) should extend or instantiate this class.\n */\nexport class ArtifactTool extends Tool {\n  /**\n   * Validator schema that accepts a {@link RawArtifactTool} object.\n   *\n   * @remarks\n   * Differs from {@link @nhtio/adk!Tool.schema} by forbidding `artifactConstructor` — wrapping is\n   * exactly the thing this class opts out of. Typed identically to {@link @nhtio/adk!Tool.schema} so the\n   * subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the\n   * runtime validation rules still differ as declared by `rawArtifactToolSchema`.\n   */\n  public static schema = rawArtifactToolSchema as unknown as typeof Tool.schema\n\n  /**\n   * Returns `true` if `value` is an {@link ArtifactTool} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link ArtifactTool} instance.\n   */\n  public static isArtifactTool(value: unknown): value is ArtifactTool {\n    return isInstanceOf(value, 'ArtifactTool', ArtifactTool)\n  }\n\n  /**\n   * @param raw - Raw tool input validated against {@link ArtifactTool.schema}.\n   *\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy\n   *   {@link ArtifactTool.schema} (most commonly, when `artifactConstructor` is supplied — it is\n   *   explicitly forbidden on this class) or when the base {@link @nhtio/adk!Tool} constructor rejects the\n   *   input for any reason.\n   */\n  constructor(raw: RawArtifactTool) {\n    // Enforce the forbidden `artifactConstructor` field up-front so the error reports against\n    // ArtifactTool's contract, not the base Tool's. The base Tool constructor re-validates\n    // against its own schema and stores the resolved fields.\n    try {\n      validateOrThrow(rawArtifactToolSchema, raw, true)\n    } catch (err) {\n      if (isInstanceOf(err, 'ValidationException', ValidationException)) {\n        throw new E_INVALID_INITIAL_TOOL_VALUE({ cause: err })\n      }\n      throw err\n    }\n    super(raw as never)\n  }\n}\n","import { validator } from '@nhtio/validation'\nimport { passesSchema } from '../utils/validation'\n\n/**\n * Backing store contract for a {@link @nhtio/adk!SpooledArtifact}.\n *\n * @remarks\n * Implementations may read from memory, a file handle, a network stream, or any other byte\n * source. The interface is intentionally minimal — the artifact layer handles all higher-level\n * operations (`head`, `tail`, `grep`, etc.) by composing calls to these three primitives.\n *\n * Line indexing is 0-based. Implementations must return `undefined` from {@link SpoolReader.line}\n * when the index is out of range rather than throwing.\n *\n * All three methods may be synchronous or asynchronous to accommodate both in-memory and I/O-\n * backed implementations without forcing unnecessary promise overhead on simple cases.\n */\nexport interface SpoolReader {\n  /**\n   * Returns the line at the given 0-based index, or `undefined` when out of range.\n   *\n   * @param index - 0-based line index.\n   * @returns The raw line string (without trailing newline), or `undefined`.\n   */\n  line(index: number): string | undefined | Promise<string | undefined>\n\n  /**\n   * Returns the total number of bytes in the underlying data.\n   *\n   * @remarks\n   * Used for reporting and token-estimation purposes. Byte length is distinct from character\n   * length for multi-byte encodings.\n   *\n   * @returns The byte length of the underlying data.\n   */\n  byteLength(): number | Promise<number>\n\n  /**\n   * Returns the total number of lines in the underlying data.\n   *\n   * @remarks\n   * Required so consumers know when to stop iterating; the line count must remain stable for the\n   * lifetime of the reader.\n   *\n   * @returns The total line count.\n   */\n  lineCount(): number | Promise<number>\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * Unlike {@link SpoolReader.line}, this method preserves trailing newlines and any non-`\\n`\n   * line terminators (e.g. `\\r\\n`) present in the original bytes. It is the primitive that\n   * powers `SpooledArtifact.asString()` — the round-trip-faithful alternative to assembling\n   * the artifact body from per-line reads.\n   *\n   * Implementations should make this O(n) in the size of the underlying data and may cache the\n   * result if the read source is durable. Streaming implementations may choose not to cache.\n   *\n   * @returns The full underlying content as a single string.\n   */\n  readAll(): string | Promise<string>\n}\n\n/**\n * Validator schema used to validate a {@link SpoolReader} value.\n *\n * @remarks\n * Because `SpoolReader` is a structural interface with no associated constructor, validation is\n * duck-typed: the value must be an object, class instance, or function with `line`, `byteLength`,\n * and `lineCount` present as callable properties. Arity is not enforced — implementations may add\n * optional parameters beyond the contract.\n */\nexport const spoolReaderSchema = validator.any().custom((value, helpers) => {\n  if (\n    value !== null &&\n    value !== undefined &&\n    typeof (value as any).line === 'function' &&\n    typeof (value as any).byteLength === 'function' &&\n    typeof (value as any).lineCount === 'function' &&\n    typeof (value as any).readAll === 'function'\n  ) {\n    return value as SpoolReader\n  }\n  return helpers.error('any.invalid')\n})\n\n/**\n * Returns `true` if `value` implements the {@link SpoolReader} interface.\n *\n * @remarks\n * Duck-typed: checks that `value` is non-null with `line`, `byteLength`, `lineCount`, and\n * `readAll` as callable functions. Does not use `instanceof` — there is no `SpoolReader`\n * constructor.\n *\n * @param value - The value to test.\n * @returns `true` when `value` conforms to the {@link SpoolReader} interface.\n */\nexport const implementsSpoolReader = (value: unknown): value is SpoolReader => {\n  return passesSchema(spoolReaderSchema, value)\n}\n","import { validator } from '@nhtio/validation'\nimport { isInstanceOf } from '../utils/guards'\nimport { ArtifactTool } from './artifact_tool'\nimport { ToolRegistry } from './tool_registry'\nimport { Tokenizable, TokenEncoding } from './tokenizable'\nimport { E_NOT_A_SPOOL_READER } from '../exceptions/runtime'\nimport { implementsSpoolReader } from '../contracts/spool_reader'\nimport type { ObjectSchema } from '@nhtio/validation'\nimport type { SpoolReader } from '../contracts/spool_reader'\nimport type { DispatchContext } from '../contracts/dispatch_context'\n\n/**\n * Constructor signature for {@link SpooledArtifact} and any subclass.\n *\n * @remarks\n * Used by {@link @nhtio/adk!Tool} to declare the artifact subclass the consumer should use when wrapping\n * the handler's serialised output. The variadic rest parameter accommodates subclass-specific\n * constructor arguments (e.g. `SpooledJsonArtifact(reader, format?)`).\n *\n * @typeParam A - The {@link SpooledArtifact} subtype the constructor produces.\n */\nexport type SpooledArtifactConstructor<A extends SpooledArtifact = SpooledArtifact> = new (\n  reader: SpoolReader,\n  ...rest: any[]\n) => A\n\n/**\n * Metadata table entry for one of the artifact's existing query methods, used by\n * {@link SpooledArtifact.forgeTools} to surface that method as an {@link @nhtio/adk!ArtifactTool}.\n *\n * @remarks\n * This is a metadata shape, not a general method → tool pipeline. `forgeTools` knows how to\n * marshal arguments for a fixed, closed set of method names (the base seven on\n * {@link SpooledArtifact} and the JSON/Markdown methods on the bundled subclasses); a\n * descriptor is the place to attach a tool name, description, args schema, and optional\n * serializer to one of those methods. Adding a descriptor for a method whose name is not\n * in that closed set will produce a tool whose handler invokes the method with no arguments.\n *\n * For new methods that require custom argument marshalling, branching, multi-step logic,\n * cross-artifact joins, or any other behaviour beyond \"call this existing method,\" override\n * {@link SpooledArtifact.forgeTools} and mint the {@link @nhtio/adk!ArtifactTool} directly — do not try\n * to express it through a descriptor.\n *\n * Zero-arg methods are the exception: a descriptor with no `argsSchema` (or one that adds\n * only `callId`-adjacent fields you don't consume) works for any method that takes no\n * arguments, regardless of name.\n */\nexport interface ToolMethodDescriptor {\n  /** Absolute tool name as exposed to the LLM (e.g. `'artifact_head'`). */\n  name: string\n  /** Method to invoke on the resolved artifact instance (e.g. `'head'`, `'json_get'`). */\n  method: string\n  /** Human-readable description passed to the model. Should mention \"in this turn\" so the model understands the artifact's lifecycle scope. */\n  description: string\n  /** Schema for the method's own args, NOT including `callId`. `forgeTools()` injects `callId`. */\n  argsSchema?: ObjectSchema\n  /** Optional formatter for non-string return values. Defaults: string → as-is; string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`. */\n  serialise?: (result: unknown) => string\n}\n\nconst noArgsSchema = validator.object<Record<string, never>>({})\n\n/**\n * Default serialiser for {@link @nhtio/adk!ArtifactTool} handler return values when a descriptor does not\n * provide its own. Exported for reuse by subclass `forgeTools` overrides.\n *\n * @param result - The artifact-method return value.\n * @returns A string suitable for inclusion in an LLM tool-call response.\n */\nexport const defaultSerialise = (result: unknown): string => {\n  if (result === undefined) return '(undefined)'\n  if (result === null) return 'null'\n  if (typeof result === 'string') return result\n  if (Array.isArray(result) && result.every((r) => typeof r === 'string')) {\n    if (result.length === 0) return '(empty list)'\n    return (result as string[]).join('\\n')\n  }\n  if (typeof result === 'number') return String(result)\n  return JSON.stringify(result, null, 2)\n}\n\nconst baseToolMethods: ReadonlyArray<ToolMethodDescriptor> = Object.freeze([\n  {\n    name: 'artifact_head',\n    method: 'head',\n    description:\n      'Return the first n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.',\n    argsSchema: validator.object({\n      n: validator.number().integer().min(1).default(10).description('Number of lines to return.'),\n    }),\n  },\n  {\n    name: 'artifact_tail',\n    method: 'tail',\n    description:\n      'Return the last n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.',\n    argsSchema: validator.object({\n      n: validator.number().integer().min(1).default(10).description('Number of lines to return.'),\n    }),\n  },\n  {\n    name: 'artifact_grep',\n    method: 'grep',\n    description:\n      'Return all lines matching a regular expression pattern from a spooled artifact produced earlier in this turn.',\n    argsSchema: validator.object({\n      pattern: validator\n        .string()\n        .required()\n        .description('Regular expression pattern, applied via JavaScript RegExp.'),\n      flags: validator\n        .string()\n        .pattern(/^[imsu]*$/)\n        .optional()\n        .description(\n          \"Optional RegExp flags. Allowed: 'i' (case-insensitive), 'm' (multiline), 's' (dotAll), 'u' (unicode). 'g' and 'y' are disallowed because per-line matching is stateless.\"\n        ),\n    }),\n  },\n  {\n    name: 'artifact_cat',\n    method: 'cat',\n    description:\n      'Return lines from a spooled artifact produced earlier in this turn, optionally bounded to a range.',\n    argsSchema: validator.object({\n      start: validator.number().integer().min(0).optional().description('Start line (inclusive).'),\n      end: validator.number().integer().min(0).optional().description('End line (exclusive).'),\n    }),\n  },\n  {\n    name: 'artifact_byte_length',\n    method: 'byteLength',\n    description:\n      'Return the total byte length of a spooled artifact produced earlier in this turn.',\n    argsSchema: noArgsSchema,\n  },\n  {\n    name: 'artifact_line_count',\n    method: 'lineCount',\n    description: 'Return the total line count of a spooled artifact produced earlier in this turn.',\n    argsSchema: noArgsSchema,\n  },\n  {\n    name: 'artifact_estimate_tokens',\n    method: 'estimateTokens',\n    description:\n      'Estimate the total token count of a spooled artifact produced earlier in this turn under a named encoding.',\n    argsSchema: validator.object({\n      encoding: validator\n        .string()\n        .valid(...TokenEncoding)\n        .required()\n        .description('Token encoding identifier.'),\n    }),\n  },\n])\n\n/**\n * A lazy, line-oriented view over an arbitrary backing store.\n *\n * @remarks\n * All I/O methods are async to remain compatible with both in-memory and streaming\n * {@link @nhtio/adk!SpoolReader} implementations. Token estimation delegates to\n * {@link @nhtio/adk!Tokenizable.estimateTokens} — the same backends used elsewhere in the ADK.\n *\n * The class is read-only by design: mutation of the underlying data is the responsibility of the\n * producer that created the {@link @nhtio/adk!SpoolReader}, not the consumer reading from this artifact.\n */\nexport class SpooledArtifact {\n  /**\n   * The set of artifact-query methods this class surfaces via {@link SpooledArtifact.forgeTools}.\n   *\n   * @remarks\n   * The base set covers the generic line-oriented operations every artifact supports:\n   * `artifact_head`, `artifact_tail`, `artifact_grep`, `artifact_cat`, `artifact_byte_length`,\n   * `artifact_line_count`, `artifact_estimate_tokens`. Each `toolMethods` array lists **only**\n   * its own class's descriptors — subclasses do not concatenate inherited descriptors. The\n   * subclass instead overrides {@link SpooledArtifact.forgeTools} to merge the base registry\n   * (produced by `SpooledArtifact.forgeTools(ctx)`) with its own — see\n   * {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for\n   * the canonical shape and the pattern downstream consumers should follow when building\n   * their own `SpooledArtifact` subclasses.\n   *\n   * Tool names are absolute (not subclass-prefixed). Forged tools carry\n   * `Tool.onCollision = 'replace'` so merging multiple subclasses' `forgeTools()` outputs is\n   * silent — every same-named tool dispatches the same method on whatever artifact the\n   * `callId` resolves to, so the overlap is behaviourally interchangeable.\n   *\n   * Frozen at module load.\n   */\n  public static toolMethods: ReadonlyArray<ToolMethodDescriptor> = baseToolMethods\n\n  #reader: SpoolReader\n\n  /**\n   * @param reader - The backing store to read from.\n   * @throws {@link @nhtio/adk!E_NOT_A_SPOOL_READER} when `reader` does not implement {@link @nhtio/adk!SpoolReader}.\n   */\n  constructor(reader: SpoolReader) {\n    if (!implementsSpoolReader(reader)) {\n      throw new E_NOT_A_SPOOL_READER()\n    }\n    this.#reader = reader\n  }\n\n  /**\n   * Returns the line at the given 0-based index, or `undefined` when out of range.\n   *\n   * @remarks\n   * Protected so subclasses can scan the backing store line-by-line without allocating\n   * intermediate arrays. Delegates directly to the {@link @nhtio/adk!SpoolReader}.\n   *\n   * @param index - 0-based line index.\n   * @returns The raw line string, or `undefined` when out of range.\n   */\n  protected async line(index: number): Promise<string | undefined> {\n    return this.#reader.line(index)\n  }\n\n  /**\n   * Returns `true` if `value` is a {@link SpooledArtifact} instance (including any subclass).\n   *\n   * @remarks\n   * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then\n   * `Symbol.hasInstance`, then a `constructor.name` fallback. Subclass instances (e.g.\n   * {@link @nhtio/adk!SpooledJsonArtifact}) satisfy this guard because `instanceof` walks the prototype\n   * chain. The fallbacks handle the dual-module-copy case where two distinct `SpooledArtifact`\n   * classes coexist in the same realm (e.g. one bundled into a downstream library, one in the\n   * consumer's `node_modules`).\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link SpooledArtifact} instance.\n   */\n  public static isSpooledArtifact(value: unknown): value is SpooledArtifact {\n    return isInstanceOf(value, 'SpooledArtifact', SpooledArtifact)\n  }\n\n  /**\n   * Returns `true` if `value` is a constructor function whose prototype chain includes\n   * {@link SpooledArtifact} (including `SpooledArtifact` itself).\n   *\n   * @remarks\n   * Used by {@link @nhtio/adk!Tool} to validate the optional `artifactConstructor` field. Performs an\n   * `instanceof`-based check on the prototype chain; falls back to a duck-type test that looks\n   * for the canonical SpooledArtifact instance methods on `value.prototype` for cross-realm\n   * safety (constructors passed from a different module copy or VM context).\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a constructor for `SpooledArtifact` or a subclass.\n   */\n  public static isSpooledArtifactConstructor(\n    value: unknown\n  ): value is SpooledArtifactConstructor<SpooledArtifact> {\n    if (typeof value !== 'function') return false\n    if (value === SpooledArtifact) return true\n    const proto = (value as { prototype?: unknown }).prototype\n    if (proto === undefined || proto === null) return false\n    if (isInstanceOf(proto, 'SpooledArtifact', SpooledArtifact)) return true\n    // Cross-realm duck-type fallback: prototype carries the canonical SpooledArtifact methods\n    const methods = ['head', 'tail', 'grep', 'cat', 'byteLength', 'lineCount', 'estimateTokens']\n    return methods.every((m) => typeof (proto as Record<string, unknown>)[m] === 'function')\n  }\n\n  /**\n   * Returns the first `n` lines of the artifact.\n   *\n   * @remarks\n   * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the\n   * behaviour of POSIX `head -n`.\n   *\n   * @param n - Number of lines to return. Defaults to 10.\n   * @returns Array of line strings, without trailing newlines.\n   */\n  async head(n: number = 10): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const limit = Math.min(n, count)\n    const lines: string[] = []\n    for (let i = 0; i < limit; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns the last `n` lines of the artifact.\n   *\n   * @remarks\n   * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the\n   * behaviour of POSIX `tail -n`.\n   *\n   * @param n - Number of lines to return. Defaults to 10.\n   * @returns Array of line strings, without trailing newlines.\n   */\n  async tail(n: number = 10): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const start = Math.max(0, count - n)\n    const lines: string[] = []\n    for (let i = start; i < count; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns all lines that match `pattern`.\n   *\n   * @remarks\n   * Behaves like POSIX `grep`: each line is tested against the pattern and included in the result\n   * when it matches. The pattern is applied as a JavaScript `RegExp`; flags (e.g. case-\n   * insensitivity) should be encoded in the expression itself.\n   *\n   * Stateful flags (`g`, `y`) on the supplied `RegExp` would normally cause `pattern.test()` to\n   * advance `lastIndex` across calls, producing skipped matches and order-dependent results. To\n   * keep the per-line semantics stateless, `grep` resets `pattern.lastIndex` to `0` before each\n   * line test. The forged `artifact_grep` tool also rejects `g` and `y` flags up-front at schema\n   * validation time.\n   *\n   * @param pattern - The regular expression to test each line against.\n   * @returns Array of matching line strings, in order.\n   */\n  async grep(pattern: RegExp): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const matches: string[] = []\n    for (let i = 0; i < count; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        pattern.lastIndex = 0\n        if (pattern.test(line)) {\n          matches.push(line)\n        }\n      }\n    }\n    return matches\n  }\n\n  /**\n   * Returns lines from the artifact, optionally bounded to a range.\n   *\n   * @remarks\n   * Without arguments, returns all lines — equivalent to POSIX `cat`. With `start` and/or `end`,\n   * behaves like `Array.prototype.slice`: `start` defaults to `0`, `end` defaults to the total\n   * line count, and only lines in `[start, end)` are fetched from the backing store. For large\n   * artifacts, prefer a bounded range or {@link SpooledArtifact.head} / {@link SpooledArtifact.tail}.\n   *\n   * @param start - 0-based start line index (inclusive). Defaults to `0`.\n   * @param end - 0-based end line index (exclusive). Defaults to `lineCount()`.\n   * @returns Array of line strings in the requested range.\n   */\n  async cat(start?: number, end?: number): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const from = Math.max(0, start ?? 0)\n    const to = Math.min(count, end ?? count)\n    const lines: string[] = []\n    for (let i = from; i < to; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns the total byte length of the underlying data.\n   *\n   * @returns The byte length as reported by the {@link @nhtio/adk!SpoolReader}.\n   */\n  async byteLength(): Promise<number> {\n    return this.#reader.byteLength()\n  }\n\n  /**\n   * Returns the total number of lines in the artifact.\n   *\n   * @returns The line count as reported by the {@link @nhtio/adk!SpoolReader}.\n   */\n  async lineCount(): Promise<number> {\n    return this.#reader.lineCount()\n  }\n\n  /**\n   * Estimates the total token count of the artifact under `encoding`.\n   *\n   * @remarks\n   * Reads the full byte-faithful content via {@link SpooledArtifact.asString} (which delegates to\n   * {@link @nhtio/adk!SpoolReader.readAll}) and delegates to {@link @nhtio/adk!Tokenizable.estimateTokens}. The estimate\n   * therefore reflects the actual source bytes — including trailing newlines and non-`\\n` line\n   * terminators that the line-based {@link SpooledArtifact.cat} view would otherwise discard or\n   * misrepresent.\n   *\n   * @param encoding - The encoding identifier to use for counting.\n   * @returns The estimated number of tokens.\n   */\n  async estimateTokens(encoding: TokenEncoding): Promise<number> {\n    const content = await this.#reader.readAll()\n    return Tokenizable.estimateTokens(content, encoding)\n  }\n\n  /**\n   * Returns the full artifact body as a single byte-faithful string.\n   *\n   * @remarks\n   * Round-trip faithful to whatever bytes the {@link @nhtio/adk!SpoolReader} was constructed over —\n   * preserves trailing newlines and non-`\\n` line terminators that {@link SpooledArtifact.cat}\n   * discards via its line-based view. This is the canonical primitive for \"inline the artifact\n   * content directly into a message\" use cases.\n   *\n   * `asString()` and the static `forgeTools(ctx)` factory on each subclass are independent\n   * alternatives — a consumer chooses per turn whether to inline the body in a message\n   * (`await tc.results.asString()`) or hand the model query tools\n   * (`SpooledArtifact.forgeTools(ctx)`). Neither calls the other; either works with neither.\n   *\n   * @returns The full content as a single string.\n   */\n  async asString(): Promise<string> {\n    return this.#reader.readAll()\n  }\n\n  /**\n   * Forges a fresh {@link @nhtio/adk!ToolRegistry} of ephemeral {@link @nhtio/adk!ArtifactTool} instances that let the\n   * LLM query artifacts already present in `ctx.turnToolCalls`.\n   *\n   * @remarks\n   * Standard subclass extension pattern — each class owns only its own `toolMethods` and its\n   * own `forgeTools`. The base `SpooledArtifact.forgeTools(ctx)` narrows the `callId` enum to\n   * any `tc.results instanceof SpooledArtifact` (so subclass instances are included — that's\n   * the whole point of inheritance) and dispatches the seven base methods (`head`, `tail`,\n   * `grep`, `cat`, `byteLength`, `lineCount`, `estimateTokens`) on the resolved artifact.\n   * Subclasses override `forgeTools` to call this static first and then register their own\n   * tools on the returned registry — see {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and\n   * {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for the canonical shape. There is no\n   * `requiresSubclass` field, no helper indirection, and no `this`-based class narrowing —\n   * just plain `instanceof ThisClass` at each subclass's own filter site.\n   *\n   * For each descriptor in this class's `toolMethods`, the factory:\n   *\n   * 1. Walks `ctx.turnToolCalls` to find `ToolCall`s whose `results instanceof SpooledArtifact`.\n   *    `ToolCall`s flagged `fromArtifactTool === true` are excluded — they carry a\n   *    {@link @nhtio/adk!Tokenizable}, not a `SpooledArtifact`, and including them would let the model\n   *    `artifact_grep` on a previous `artifact_grep` result (an infinite-recursion hazard with\n   *    no semantic value).\n   * 2. Returns an empty registry if no compatible callIds are found — no point shipping tools\n   *    whose `callId` enum is empty.\n   * 3. Otherwise mints an {@link @nhtio/adk!ArtifactTool} with `ephemeral: true` and `onCollision: 'replace'`\n   *    so multiple `Subclass.forgeTools(ctx)` outputs merge silently. The tool's `inputSchema`\n   *    includes a required `callId` field with `.valid(...compatibleIds)`, plus the descriptor's\n   *    own `argsSchema` fields.\n   *\n   * The handler resolves the artifact via `[...ctx.turnToolCalls].find(t => t.id === callId)`,\n   * dispatches the descriptor's method, and serialises the return value (string → as-is;\n   * string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`;\n   * `descriptor.serialise` overrides the defaults). `grep` is special-cased: the handler\n   * constructs `new RegExp(pattern, flags ?? '')` before invoking the artifact's `grep` method.\n   *\n   * The returned registry must be merged into the consumer's main registry and the main\n   * registry must be bound to `ctx` via {@link @nhtio/adk!ToolRegistry.bindContext}:\n   *\n   * ```ts\n   * const executor: DispatchExecutorFn = async (ctx) => {\n   *   const forged = SpooledArtifact.forgeTools(ctx)\n   *   const merged = ToolRegistry.merge([main, forged])\n   *   main.bindContext(ctx)\n   *   const result = await llm.invoke({ tools: merged.all(), ... })\n   *   ctx.ack() // ← ephemeral cleanup fires here\n   * }\n   * ```\n   *\n   * @warning You **must** call `registry.bindContext(ctx)` on the registry hosting these tools,\n   * or ephemeral cleanup will not run and the `callId` enum in subsequent executor calls will\n   * be stale (excluding new tool calls produced in the meantime).\n   *\n   * @param ctx - The execution context whose `turnToolCalls` snapshot defines the `callId` enum.\n   * @returns A fresh `ToolRegistry`. Empty when `turnToolCalls` contains no compatible artifacts.\n   *\n   * @see {@link @nhtio/adk!ToolRegistry.bindContext}\n   * @see {@link @nhtio/adk!ToolRegistry.merge}\n   * @see {@link @nhtio/adk!DispatchContext.onAck}\n   */\n  public static forgeTools(ctx: DispatchContext): ToolRegistry {\n    const requires: SpooledArtifactConstructor = SpooledArtifact\n    const calls = [...ctx.turnToolCalls]\n    const compatibleIds = calls\n      .filter((tc) => !tc.fromArtifactTool && isInstanceOf(tc.results, requires.name, requires))\n      .map((tc) => tc.id)\n    if (compatibleIds.length === 0) return new ToolRegistry([])\n\n    const tools: ArtifactTool[] = []\n    for (const descriptor of this.toolMethods) {\n      const callIdSchema = validator\n        .string()\n        .valid(...compatibleIds)\n        .required()\n        .description('ToolCall id of the artifact to query.')\n\n      const argsSchema = (descriptor.argsSchema ?? noArgsSchema).append({\n        callId: callIdSchema,\n      })\n\n      const serialise = descriptor.serialise ?? defaultSerialise\n\n      const tool = new ArtifactTool({\n        name: descriptor.name,\n        description: descriptor.description,\n        inputSchema: argsSchema,\n        ephemeral: true,\n        onCollision: 'replace',\n        handler: async (rawArgs, ctxInner) => {\n          const args = rawArgs as Record<string, unknown> & { callId: string }\n          const tc = [...ctxInner.turnToolCalls].find((t) => t.id === args.callId)\n          if (!tc) {\n            return `Error: no tool call with id ${args.callId} in this turn`\n          }\n          const artifact = tc.results\n          if (!isInstanceOf(artifact, requires.name, requires)) {\n            return `Error: tool call ${args.callId} results are not a ${requires.name} instance`\n          }\n          const methodArgs: unknown[] = []\n          if (descriptor.method === 'grep') {\n            const pattern = args.pattern as string\n            const flags = (args.flags as string | undefined) ?? ''\n            methodArgs.push(new RegExp(pattern, flags))\n          } else if (descriptor.method === 'head' || descriptor.method === 'tail') {\n            methodArgs.push((args.n as number | undefined) ?? 10)\n          } else if (descriptor.method === 'cat') {\n            methodArgs.push(args.start as number | undefined, args.end as number | undefined)\n          } else if (descriptor.method === 'estimateTokens') {\n            methodArgs.push(args.encoding as TokenEncoding)\n          }\n          const fn = (artifact as unknown as Record<string, (...a: unknown[]) => unknown>)[\n            descriptor.method\n          ]\n          if (typeof fn !== 'function') {\n            return `Error: artifact has no method ${descriptor.method}`\n          }\n          const result = await Promise.resolve(fn.apply(artifact, methodArgs))\n          return serialise(result)\n        },\n      })\n      tools.push(tool)\n    }\n    return new ToolRegistry(tools)\n  }\n}\n"],"mappings":"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"}