@nhtio/adk 0.1.0-master-f0aa531d

package/tool_call-DFgzcVcU.js

@@ -0,0 +1,608 @@
+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_spooled_artifact = require("./spooled_artifact-Cm9Te22K.js");
+let _nhtio_validation = require("@nhtio/validation");
+let uuid = require("uuid");
+//#region src/lib/contracts/media_reader.ts
+/**
+* Validator schema used to validate a MediaReader value.
+*
+* @remarks
+* Because MediaReader is a structural interface with no associated constructor, validation is
+* duck-typed: the value must be an object, class instance, or function with `stream` and
+* `byteLength` present as callable properties. Arity is not enforced.
+*/
+var mediaReaderSchema = _nhtio_validation.validator.any().required().custom((value, helpers) => {
+	if (value !== null && value !== void 0 && typeof value.stream === "function" && typeof value.byteLength === "function") return value;
+	return helpers.error("any.invalid");
+});
+/**
+* Returns `true` if `value` implements the MediaReader interface.
+*
+* @remarks
+* Duck-typed: checks that `value` is non-null with `stream` and `byteLength` as callable
+* functions. Does not use `instanceof` — there is no MediaReader constructor.
+*
+* @param value - The value to test.
+* @returns `true` when `value` conforms to the MediaReader interface.
+*/
+var implementsMediaReader = (value) => {
+	return require_exceptions.passesSchema(mediaReaderSchema, value);
+};
+//#endregion
+//#region src/lib/classes/media.ts
+/**
+* The set of supported media kinds.
+*
+* @remarks
+* Modality coverage is asymmetric across providers. The framework defines no
+* `supportedModalities` field — how a battery handles a modality it cannot natively render is
+* the battery author's call (see `unsupportedMediaPolicy` on the OpenAI Chat Completions
+* battery).
+*/
+var MediaKind = [
+	"image",
+	"audio",
+	"video",
+	"document"
+];
+/**
+* Provenance axis. *Who is the framework willing to vouch for as the source of these bytes?*
+*
+* @remarks
+* Mirrors `RetrievableTrustTier` deliberately — same vocabulary, same question:
+* *did this content come from a place the agent should treat as authoritative?*
+*
+* - `'first-party'` — deployer-vetted bytes (tool output the operator authored, signed
+*   internal assets).
+* - `'third-party-public'` — open-web fetches, public APIs, public corpora.
+* - `'third-party-private'` — user uploads, partner APIs, private corpora.
+*/
+var MediaTrustTier = [
+	"first-party",
+	"third-party-public",
+	"third-party-private"
+];
+/**
+* Modality-hazard axis. *How dangerous is it to let the model decode these bytes?*
+*
+* @remarks
+* Orthogonal to provenance — a first-party trusted PDF can still carry hidden text layers; a
+* third-party-public raw image can still be encoded as opaque pixels with adversarial
+* perturbations.
+*
+* - `'inert'` — bytes the model never decodes as instructions (e.g. a handle that is never
+*   inlined into the prompt).
+* - `'extractable-instructions'` — text-bearing media: PDFs, screenshots with UI text, documents.
+*   Hazard is OCR / embedded-text-layer reads.
+* - `'opaque-perceptual'` — raw vision/audio/video the model encodes directly. Hazard is
+*   steganographic LSB prompts, adversarial perturbations, ultrasonic audio — invisible to any
+*   pre-screen.
+*
+* See `/the-loop/trust-tiers/media` and its research sub-page `/the-loop/trust-tiers/media/research`.
+*/
+var MediaModalityHazard = [
+	"inert",
+	"extractable-instructions",
+	"opaque-perceptual"
+];
+var stashEntrySchema = _nhtio_validation.validator.object({
+	value: _nhtio_validation.validator.any().required(),
+	trustTier: _nhtio_validation.validator.string().valid(...MediaTrustTier).required(),
+	derivedFromMedia: _nhtio_validation.validator.string().optional()
+}).unknown(false);
+/**
+* Validator schema used to validate a {@link RawMedia} before constructing a {@link Media}.
+*/
+var rawMediaSchema = _nhtio_validation.validator.object({
+	id: _nhtio_validation.validator.string().optional(),
+	kind: _nhtio_validation.validator.string().valid(...MediaKind).required(),
+	mimeType: _nhtio_validation.validator.string().required(),
+	filename: _nhtio_validation.validator.string().required(),
+	reader: mediaReaderSchema.required(),
+	trustTier: _nhtio_validation.validator.string().valid(...MediaTrustTier).required(),
+	modalityHazard: _nhtio_validation.validator.string().valid(...MediaModalityHazard).required(),
+	source: _nhtio_validation.validator.string().optional(),
+	stash: _nhtio_validation.validator.object().pattern(_nhtio_validation.validator.string(), stashEntrySchema).optional()
+});
+var conservativeHazardForKind = (kind) => {
+	return kind === "document" ? "extractable-instructions" : "opaque-perceptual";
+};
+/**
+* Cross-environment base64 encoder for a `Uint8Array`.
+*
+* @remarks
+* Prefers Node's `Buffer.from(buf).toString('base64')` when `globalThis.Buffer` exists; otherwise
+* chunk-encodes through `btoa` with a 0x8000-byte window to avoid `Maximum call stack size
+* exceeded` on large buffers.
+*/
+var encodeBase64 = (bytes) => {
+	const maybeBuffer = globalThis.Buffer;
+	if (maybeBuffer && typeof maybeBuffer.from === "function") return maybeBuffer.from(bytes).toString("base64");
+	const chunkSize = 32768;
+	let binary = "";
+	for (let i = 0; i < bytes.length; i += chunkSize) {
+		const chunk = bytes.subarray(i, i + chunkSize);
+		binary += String.fromCharCode.apply(null, Array.from(chunk));
+	}
+	return btoa(binary);
+};
+/**
+* Lazy, re-openable view over a binary asset (image, audio, video, document).
+*
+* @remarks
+* Dual-peer to {@link @nhtio/adk!Tokenizable} (silo) and {@link @nhtio/adk!SpooledArtifact}
+* (handle). Wraps a {@link @nhtio/adk!MediaReader} contract — the framework owns the contract, the
+* implementor owns the storage backend. Bytes are reached only through the reader; the primitive
+* itself never inlines bytes.
+*
+* Construction requires `trustTier` and `modalityHazard` — the framework refuses to guess
+* provenance or decoding hazard. Ergonomic factories ({@link Media.userAttachment},
+* {@link Media.toolGenerated}, {@link Media.retrievedPublic}, {@link Media.retrievedPrivate})
+* force the labelling decision at the call site without becoming defaults on the bare
+* constructor.
+*/
+var Media = class Media {
+	/**
+	* Validator schema that accepts a {@link RawMedia} object.
+	*/
+	static schema = rawMediaSchema;
+	/**
+	* The set of recognised media kinds. Exposed for downstream schemas that need to discriminate
+	* on `kind`.
+	*/
+	static MediaKind = MediaKind;
+	/**
+	* The set of recognised trust tiers.
+	*/
+	static MediaTrustTier = MediaTrustTier;
+	/**
+	* The set of recognised modality hazards.
+	*/
+	static MediaModalityHazard = MediaModalityHazard;
+	/**
+	* Returns `true` if `value` is a {@link Media} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link Media} instance.
+	*/
+	static isMedia(value) {
+		return require_tool_registry.isInstanceOf(value, "Media", Media);
+	}
+	#id;
+	#kind;
+	#mimeType;
+	#filename;
+	#source;
+	#trustTier;
+	#modalityHazard;
+	#reader;
+	#stash;
+	/**
+	* @param raw - The raw media input validated against `rawMediaSchema`.
+	* @throws {@link @nhtio/adk/exceptions!E_INVALID_INITIAL_MEDIA_VALUE} when `raw` does not satisfy the schema.
+	* @throws {@link @nhtio/adk/exceptions!E_NOT_A_MEDIA_READER} when `raw.reader` does not implement {@link @nhtio/adk!MediaReader}.
+	*/
+	constructor(raw) {
+		let resolved;
+		try {
+			resolved = require_exceptions.validateOrThrow(rawMediaSchema, raw, true);
+		} catch (err) {
+			throw new require_runtime.E_INVALID_INITIAL_MEDIA_VALUE({ cause: require_tool_registry.isError(err) ? err : void 0 });
+		}
+		if (!implementsMediaReader(resolved.reader)) throw new require_runtime.E_NOT_A_MEDIA_READER();
+		this.#id = resolved.id ?? (0, uuid.v6)();
+		this.#kind = resolved.kind;
+		this.#mimeType = resolved.mimeType;
+		this.#filename = resolved.filename;
+		this.#source = resolved.source;
+		this.#trustTier = resolved.trustTier;
+		this.#modalityHazard = resolved.modalityHazard;
+		this.#reader = resolved.reader;
+		this.#stash = new require_tool_registry.Registry(resolved.stash);
+		Object.defineProperties(this, {
+			id: {
+				get: () => this.#id,
+				enumerable: true,
+				configurable: false
+			},
+			kind: {
+				get: () => this.#kind,
+				enumerable: true,
+				configurable: false
+			},
+			mimeType: {
+				get: () => this.#mimeType,
+				enumerable: true,
+				configurable: false
+			},
+			filename: {
+				get: () => this.#filename,
+				enumerable: true,
+				configurable: false
+			},
+			source: {
+				get: () => this.#source,
+				enumerable: true,
+				configurable: false
+			},
+			trustTier: {
+				get: () => this.#trustTier,
+				enumerable: true,
+				configurable: false
+			},
+			modalityHazard: {
+				get: () => this.#modalityHazard,
+				enumerable: true,
+				configurable: false
+			},
+			stash: {
+				get: () => this.#stash,
+				enumerable: true,
+				configurable: false
+			}
+		});
+	}
+	/**
+	* Re-opens the underlying byte source and returns a fresh ReadableStream.
+	*
+	* @returns A drainable `ReadableStream` over the underlying bytes.
+	*/
+	async stream() {
+		return this.#reader.stream();
+	}
+	/**
+	* Returns the total number of bytes in the underlying data, or `undefined` if unknown.
+	*
+	* @returns The byte length, or `undefined` when the underlying source cannot report it.
+	*/
+	async byteLength() {
+		return this.#reader.byteLength();
+	}
+	/**
+	* Drains the reader's stream and returns the underlying bytes as a single `Uint8Array`.
+	*
+	* @remarks
+	* Convenience for callers that need the full buffer (e.g. inline base64 encoding). Forces
+	* full materialisation — large assets should be piped through {@link Media.stream} instead.
+	*/
+	async asBytes() {
+		const reader = (await this.stream()).getReader();
+		const chunks = [];
+		let total = 0;
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			if (value) {
+				chunks.push(value);
+				total += value.byteLength;
+			}
+		}
+		const out = new Uint8Array(total);
+		let offset = 0;
+		for (const chunk of chunks) {
+			out.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return out;
+	}
+	/**
+	* Drains the reader's stream and returns the underlying bytes as a base64 string.
+	*
+	* @remarks
+	* Cross-environment: prefers Node's `Buffer.from(buf).toString('base64')` when available;
+	* otherwise chunk-encodes through `btoa` with a 0x8000-byte window to avoid stack overflow
+	* on large buffers.
+	*/
+	async asBase64() {
+		return encodeBase64(await this.asBytes());
+	}
+	/**
+	* Returns the metadata-only serialisation of this Media. Bytes and the reader are stripped
+	* so naive event/log serialisation never materialises bytes.
+	*
+	* @remarks
+	* Implementations that have cheap, already-cached `byteLength` may opt to include it; this
+	* default implementation omits it to preserve the "lazy by default" invariant. Consumers that
+	* need byteLength on the serialised payload should call `await media.byteLength()` and merge
+	* the result.
+	*/
+	toJSON() {
+		return {
+			id: this.#id,
+			kind: this.#kind,
+			mimeType: this.#mimeType,
+			filename: this.#filename,
+			source: this.#source,
+			trustTier: this.#trustTier,
+			modalityHazard: this.#modalityHazard,
+			stash: this.#stash.all()
+		};
+	}
+	/**
+	* Factory: constructs a {@link Media} representing a user-supplied attachment.
+	*
+	* @remarks
+	* Pre-fills `trustTier: 'third-party-private'` and derives `modalityHazard` from `kind`
+	* (`document` → `'extractable-instructions'`; everything else → `'opaque-perceptual'`).
+	* Use the bare constructor when the conservative kind→hazard mapping is wrong for your case.
+	*/
+	static userAttachment(args) {
+		return new Media({
+			...args,
+			trustTier: "third-party-private",
+			modalityHazard: conservativeHazardForKind(args.kind)
+		});
+	}
+	/**
+	* Factory: constructs a {@link Media} produced by a first-party tool.
+	*
+	* @remarks
+	* Pre-fills `trustTier: 'first-party'` and derives `modalityHazard` from `kind`.
+	*/
+	static toolGenerated(args) {
+		return new Media({
+			...args,
+			trustTier: "first-party",
+			modalityHazard: conservativeHazardForKind(args.kind)
+		});
+	}
+	/**
+	* Factory: constructs a {@link Media} retrieved from a public third-party source.
+	*
+	* @remarks
+	* Pre-fills `trustTier: 'third-party-public'` and derives `modalityHazard` from `kind`.
+	*/
+	static retrievedPublic(args) {
+		return new Media({
+			...args,
+			trustTier: "third-party-public",
+			modalityHazard: conservativeHazardForKind(args.kind)
+		});
+	}
+	/**
+	* Factory: constructs a {@link Media} retrieved from a private third-party source.
+	*
+	* @remarks
+	* Pre-fills `trustTier: 'third-party-private'` and derives `modalityHazard` from `kind`.
+	*/
+	static retrievedPrivate(args) {
+		return new Media({
+			...args,
+			trustTier: "third-party-private",
+			modalityHazard: conservativeHazardForKind(args.kind)
+		});
+	}
+};
+/**
+* Returns `true` if `value` is a {@link Media} instance.
+*
+* @remarks
+* Module-level convenience alias for {@link Media.isMedia}. Uses {@link @nhtio/adk!isInstanceOf} for
+* cross-realm safety.
+*/
+var isMedia = (value) => {
+	return require_tool_registry.isInstanceOf(value, "Media", Media);
+};
+//#endregion
+//#region src/lib/classes/tool_call.ts
+var isToolCallResults = (value) => {
+	if (require_tool_registry.Tokenizable.isTokenizable(value)) return true;
+	if (require_spooled_artifact.SpooledArtifact.isSpooledArtifact(value)) return true;
+	if (Media.isMedia(value)) return true;
+	if (Array.isArray(value) && value.length > 0) {
+		if (value.every((entry) => Media.isMedia(entry))) return true;
+		if (value.every((entry) => require_spooled_artifact.SpooledArtifact.isSpooledArtifact(entry))) return true;
+	}
+	return false;
+};
+/**
+* Validator schema used to validate a {@link RawToolCall} before constructing a {@link ToolCall}.
+*
+* @remarks
+* Validates all fields of {@link RawToolCall}:
+* - `id` — required non-empty string.
+* - `tool` — required non-empty string.
+* - `args` — required; either a plain object or a JSON string that deserialises to an object.
+*   Strings are parsed and the resulting object is stored.
+* - `checksum` — required string.
+* - `isComplete` — required boolean.
+* - `isError` — required boolean.
+* - `results` — required; one of {@link @nhtio/adk!Tokenizable}, {@link @nhtio/adk!SpooledArtifact}, a non-empty
+*   `SpooledArtifact[]`, {@link @nhtio/adk!Media}, or a non-empty `Media[]`. Arrays must be homogeneous.
+* - `createdAt` / `updatedAt` / `completedAt` — required datetime-parseable values, normalised to `DateTime`.
+*
+* Throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_CALL_VALUE} (via the {@link ToolCall} constructor) when
+* validation fails.
+*/
+var rawToolCallSchema = _nhtio_validation.validator.object({
+	id: _nhtio_validation.validator.string().required(),
+	tool: _nhtio_validation.validator.string().required(),
+	args: _nhtio_validation.validator.alternatives(_nhtio_validation.validator.object().unknown(true), _nhtio_validation.validator.string().custom((value, helpers) => {
+		try {
+			const parsed = JSON.parse(value);
+			if (!require_tool_registry.isObject(parsed)) return helpers.error("any.invalid");
+			return parsed;
+		} catch {
+			return helpers.error("any.invalid");
+		}
+	})).required(),
+	checksum: _nhtio_validation.validator.string().required(),
+	isComplete: _nhtio_validation.validator.boolean().required(),
+	isError: _nhtio_validation.validator.boolean().required(),
+	results: _nhtio_validation.validator.any().custom((value, helpers) => {
+		if (isToolCallResults(value)) return value;
+		return helpers.error("any.invalid");
+	}).required(),
+	fromArtifactTool: _nhtio_validation.validator.boolean().default(false),
+	inline: _nhtio_validation.validator.boolean().default(true),
+	createdAt: _nhtio_validation.validator.datetime().required(),
+	updatedAt: _nhtio_validation.validator.datetime().required(),
+	completedAt: _nhtio_validation.validator.datetime().required()
+});
+/**
+* An immutable, validated tool call record associated with a turn.
+*
+* @remarks
+* Represents a completed tool invocation from the conversation history — `results`,
+* `completedAt`, `isComplete`, and `isError` are all present and required.
+* Temporal fields are normalised to Luxon `DateTime` instances at construction time.
+*/
+var ToolCall = class ToolCall {
+	/**
+	* Validator schema that accepts a {@link RawToolCall} object.
+	*
+	* @remarks
+	* Reusable fragment for any schema that needs to validate or nest a tool call entry.
+	*/
+	static schema = rawToolCallSchema;
+	/**
+	* Returns `true` if `value` is a {@link ToolCall} 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 a {@link ToolCall} instance.
+	*/
+	static isToolCall(value) {
+		return require_tool_registry.isInstanceOf(value, "ToolCall", ToolCall);
+	}
+	#id;
+	#tool;
+	#args;
+	#checksum;
+	#isComplete;
+	#isError;
+	#results;
+	#fromArtifactTool;
+	#inline;
+	#createdAt;
+	#updatedAt;
+	#completedAt;
+	/**
+	* @param raw - The raw tool call input validated against `rawToolCallSchema`.
+	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_CALL_VALUE} when `raw` does not satisfy the schema.
+	*/
+	constructor(raw) {
+		let resolved;
+		try {
+			resolved = require_exceptions.validateOrThrow(rawToolCallSchema, raw, true);
+		} catch (err) {
+			throw new require_runtime.E_INVALID_INITIAL_TOOL_CALL_VALUE({ cause: require_tool_registry.isError(err) ? err : void 0 });
+		}
+		this.#id = resolved.id;
+		this.#tool = resolved.tool;
+		this.#args = resolved.args;
+		this.#checksum = resolved.checksum;
+		this.#isComplete = resolved.isComplete;
+		this.#isError = resolved.isError;
+		this.#results = resolved.results;
+		this.#fromArtifactTool = resolved.fromArtifactTool;
+		this.#inline = resolved.inline;
+		this.#createdAt = resolved.createdAt;
+		this.#updatedAt = resolved.updatedAt;
+		this.#completedAt = resolved.completedAt;
+		Object.defineProperties(this, {
+			id: {
+				get: () => this.#id,
+				enumerable: true,
+				configurable: false
+			},
+			tool: {
+				get: () => this.#tool,
+				enumerable: true,
+				configurable: false
+			},
+			args: {
+				get: () => this.#args,
+				enumerable: true,
+				configurable: false
+			},
+			checksum: {
+				get: () => this.#checksum,
+				enumerable: true,
+				configurable: false
+			},
+			isComplete: {
+				get: () => this.#isComplete,
+				enumerable: true,
+				configurable: false
+			},
+			isError: {
+				get: () => this.#isError,
+				enumerable: true,
+				configurable: false
+			},
+			results: {
+				get: () => this.#results,
+				enumerable: true,
+				configurable: false
+			},
+			fromArtifactTool: {
+				get: () => this.#fromArtifactTool,
+				enumerable: true,
+				configurable: false
+			},
+			inline: {
+				get: () => this.#inline,
+				enumerable: true,
+				configurable: false
+			},
+			createdAt: {
+				get: () => this.#createdAt,
+				enumerable: true,
+				configurable: false
+			},
+			updatedAt: {
+				get: () => this.#updatedAt,
+				enumerable: true,
+				configurable: false
+			},
+			completedAt: {
+				get: () => this.#completedAt,
+				enumerable: true,
+				configurable: false
+			}
+		});
+	}
+};
+//#endregion
+Object.defineProperty(exports, "Media", {
+	enumerable: true,
+	get: function() {
+		return Media;
+	}
+});
+Object.defineProperty(exports, "ToolCall", {
+	enumerable: true,
+	get: function() {
+		return ToolCall;
+	}
+});
+Object.defineProperty(exports, "implementsMediaReader", {
+	enumerable: true,
+	get: function() {
+		return implementsMediaReader;
+	}
+});
+Object.defineProperty(exports, "isMedia", {
+	enumerable: true,
+	get: function() {
+		return isMedia;
+	}
+});
+Object.defineProperty(exports, "mediaReaderSchema", {
+	enumerable: true,
+	get: function() {
+		return mediaReaderSchema;
+	}
+});
+
+//# sourceMappingURL=tool_call-DFgzcVcU.js.map