@nhtio/adk 1.20260609.0 → 1.20260610.0

package/batteries/media/forge.cjs

@@ -0,0 +1,403 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+require("../../common-DZl3ADJs.js");
+const require_tool_call = require("../../tool_call-DixVlW40.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-ClX72lek.js");
+require("../../guards.cjs");
+const require_exceptions = require("../../exceptions-CQi_lNs1.js");
+const require_validate = require("../../validate-BFaUYHDN.js");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/batteries/media/forge.ts
+/**
+* Agent glue: forge ADK tools from a media pipeline, so a model can drive local media work.
+*
+* @module @nhtio/adk/batteries/media/forge
+*
+* @remarks
+* The pipeline core (`@nhtio/adk/batteries/media`) is agent-agnostic; this module is the layer
+* that knows the ADK loop. {@link forgeMediaTools} mints `Tool` instances over a configured
+* {@link @nhtio/adk/batteries/media!MediaPipeline} in one of two surfaces (the consumer picks
+* per deployment):
+*
+* - `'composite'` — one `media_query` tool taking `{ media_id, q }` (a pipe expression — the
+*   headline LLM DSL) or `{ media_id, ops }` (structured form), plus `list_media`. The tool
+*   description embeds the engine-narrowed verb grammar so the model never sees a verb the
+*   deployment can't run. One round-trip for multi-step work.
+* - `'granular'` — one narrow tool per available verb (`doc_select`, `sheet_update_cells`, …),
+*   each internally a one-verb plan. Friendlier to small models; bigger tool list.
+*
+* Media flows in by reference: the model passes `media_id` values it discovered via the
+* `list_media` tool (or inline id markers, where the LLM battery renders them); the resolver
+* scans `ctx.turnMessages[].attachments` and `ctx.turnToolCalls[].results` by default. Outputs
+* are persisted through `ctx.storeMediaBytes` and returned as `Media.toolGenerated(...)`, so
+* file results land on `ToolCall.results` as first-class media.
+*
+* Processing failures return readable strings (`Error (CODE): …`) the model can act on; the
+* pipe DSL's own syntax/semantic errors render the same way, so a model can repair its
+* statement and retry. An optional {@link ToolGateFn} runs before every execution — the seam
+* for human-approval/RBAC flows built on `ctx.waitFor` (the ADK gates primitive).
+*/
+/**
+* The default media resolver: scan `ctx.turnMessages[].attachments`, then
+* `ctx.turnToolCalls[].results`, for a Media with the given id.
+*
+* @param ctx - The dispatch context.
+* @param mediaId - The id to find.
+* @returns The Media, or `undefined` when nothing in the turn carries that id.
+*/
+var defaultResolveMedia = (ctx, mediaId) => {
+	for (const message of ctx.turnMessages) for (const attachment of message.attachments ?? []) if (attachment.id === mediaId) return attachment;
+	for (const toolCall of ctx.turnToolCalls) {
+		const results = toolCall.results;
+		if (require_tool_call.Media.isMedia(results) && results.id === mediaId) return results;
+		if (Array.isArray(results)) {
+			const hit = results.find((r) => require_tool_call.Media.isMedia(r) && r.id === mediaId);
+			if (hit) return hit;
+		}
+	}
+};
+/** Enumerate every Media visible in the turn (for `list_media` and MEDIA_NOT_FOUND hints). */
+var enumerateMedia = (ctx) => {
+	const out = [];
+	for (const message of ctx.turnMessages) for (const attachment of message.attachments ?? []) out.push({
+		id: attachment.id,
+		filename: attachment.filename,
+		kind: attachment.kind,
+		mimeType: attachment.mimeType,
+		source: attachment.source,
+		origin: "attachment"
+	});
+	for (const toolCall of ctx.turnToolCalls) {
+		const results = toolCall.results;
+		const mediaList = require_tool_call.Media.isMedia(results) ? [results] : Array.isArray(results) ? results.filter((r) => require_tool_call.Media.isMedia(r)) : [];
+		for (const media of mediaList) out.push({
+			id: media.id,
+			filename: media.filename,
+			kind: media.kind,
+			mimeType: media.mimeType,
+			source: media.source,
+			origin: "tool-result"
+		});
+	}
+	return out;
+};
+var failure = (code, message) => `Error (${code}): ${message}`;
+var mediaKindOf = (mimeType) => {
+	const mime = mimeType.toLowerCase();
+	if (mime.startsWith("image/")) return "image";
+	if (mime.startsWith("audio/")) return "audio";
+	if (mime.startsWith("video/")) return "video";
+	return "document";
+};
+/** Load a resolved Media's bytes into a pipeline payload. */
+var toPayload = async (media) => ({
+	bytes: await media.asBytes(),
+	mimeType: media.mimeType,
+	filename: media.filename
+});
+/** Persist a payload through the dispatch byte conduit and mint a first-party Media. */
+var toMedia = async (ctx, payload, toolName) => {
+	const id = crypto.randomUUID();
+	const reader = await ctx.storeMediaBytes(id, payload.bytes);
+	return require_tool_call.Media.toolGenerated({
+		id,
+		kind: mediaKindOf(payload.mimeType),
+		mimeType: payload.mimeType,
+		filename: payload.filename,
+		reader,
+		source: `tool:${toolName}`
+	});
+};
+/** Render a plan result as a tool handler return value. */
+var renderResult = async (ctx, result, toolName) => {
+	if (result.kind === "media") return toMedia(ctx, result.payload, toolName);
+	if (result.kind === "media-list") return Promise.all(result.payloads.map((p) => toMedia(ctx, p, toolName)));
+	return typeof result.data === "string" ? result.data : JSON.stringify(result.data, null, 2);
+};
+/** Resolve + acquire the input media or produce a model-actionable failure string. */
+var acquire = async (ctx, resolveMedia, mediaId) => {
+	const media = await resolveMedia(ctx, mediaId);
+	if (!media) {
+		const visible = enumerateMedia(ctx);
+		return {
+			ok: false,
+			failure: failure("MEDIA_NOT_FOUND", `no media with id "${mediaId}". ${visible.length > 0 ? `Visible media ids: ${visible.map((m) => `${m.id} (${m.filename})`).join(", ")}` : "No media is visible in this turn — ask the user to attach a file, or call list_media to check."}`)
+		};
+	}
+	return {
+		ok: true,
+		payload: await toPayload(media)
+	};
+};
+/** Build a per-run @id ref resolver bound to this dispatch's visible media. */
+var refResolverFor = (ctx, resolveMedia) => async (id) => {
+	const media = await resolveMedia(ctx, id);
+	if (!media) {
+		const visible = enumerateMedia(ctx).map((m) => m.id).join(", ");
+		throw new Error(`referenced media @${id} was not found in this turn. Visible ids: ${visible || "(none)"}`);
+	}
+	return toPayload(media);
+};
+/** Run the optional gate; a throw becomes the tool's error (standard downstream wrapping). */
+var runGate = async (gate, ctx, tool, args) => {
+	if (gate) await gate(ctx, {
+		tool,
+		args
+	});
+};
+/** Map a thrown pipeline error to a readable failure string the model can act on. */
+var renderError = (err) => {
+	if (require_tool_registry.isError(err) && err.name.startsWith("E_MEDIA_")) return failure(err.name.replace(/^E_MEDIA_/, ""), err.message);
+	throw err;
+};
+var argHelp = (name, arg) => {
+	return `${name}${arg.required ? "" : "?"}=${arg.type === "enum" ? (arg.values ?? []).join("|") : arg.type === "json" ? "'<JSON>'" : arg.type}`;
+};
+var verbHelp = (spec) => {
+	const verb = spec.id.replace(/\./g, " ");
+	const args = Object.entries(spec.args).map(([n, a]) => argHelp(n, a)).join(" ");
+	return args.length > 0 ? `${verb} ${args}` : verb;
+};
+/**
+* Generate the model-facing grammar text for the configured deployment: only available verbs,
+* with arg signatures, plus few-shot examples rendered from real plans via `toPipe` so they
+* can never drift from the parser.
+*/
+var grammarText = (pipeline) => {
+	const available = new Set(require_validate.availableVerbs(pipeline.capabilities));
+	const lines = [];
+	for (const spec of require_validate.VERB_INDEX.values()) {
+		if (!available.has(spec.id.replace(/[._]+/g, " "))) continue;
+		lines.push(`- ${verbHelp(spec)} — ${spec.description}`);
+	}
+	const examples = [require_validate.toPipe({ steps: [{
+		verb: "select",
+		args: { pages: [
+			2,
+			3,
+			4,
+			5
+		] }
+	}, {
+		verb: "extract.text",
+		args: {}
+	}] }), require_validate.toPipe({ steps: [{
+		verb: "extract.text",
+		args: {}
+	}, {
+		verb: "chunk",
+		args: {
+			by: "sentence",
+			size: 512
+		}
+	}] })];
+	if (available.has("redact")) examples.push(require_validate.toPipe({ steps: [{
+		verb: "redact",
+		args: {
+			match: [{
+				source: "\\d{3}-\\d{2}-\\d{4}",
+				flags: ""
+			}],
+			replace: "[SSN]"
+		}
+	}] }));
+	return [
+		"Statements are pipe expressions: verb name=value ... | verb name=value ...",
+		"Named args only. Indices are 1-based. Quote values containing spaces or dashes.",
+		"Structured payloads are quoted JSON: updates='[{\"address\":\"B2\",\"value\":3}]'.",
+		"Reference other media inline by id: merge with=@<media id> (ids come from list_media).",
+		"",
+		"Available verbs:",
+		...lines,
+		"",
+		"Examples (remember: inside JSON tool args, backslashes must be doubled — \\\\d):",
+		...examples.map((e) => `  ${e}`)
+	].join("\n");
+};
+var buildListMediaTool = (overrides) => {
+	return new require_tool.Tool({
+		name: overrides?.list_media?.name ?? "list_media",
+		description: overrides?.list_media?.description ?? "Lists every media file visible in this conversation turn (user attachments and files produced by prior tool calls), with the media ids other media tools require.",
+		inputSchema: _nhtio_validation.validator.object({}),
+		artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+		handler: async (_args, ctx) => {
+			const media = enumerateMedia(ctx);
+			return JSON.stringify(media, null, 2);
+		}
+	});
+};
+var buildCompositeTool = (pipeline, resolveMedia, gate, overrides) => {
+	const name = overrides?.media_query?.name ?? "media_query";
+	return new require_tool.Tool({
+		name,
+		description: overrides?.media_query?.description ?? `Runs a media-processing statement against a file from this conversation, locally (no external services). Provide media_id (from list_media) and either q (a pipe statement) or ops (structured steps).
+
+${grammarText(pipeline)}`,
+		inputSchema: _nhtio_validation.validator.object({
+			media_id: _nhtio_validation.validator.string().required().description("The id of the media to process (call list_media to discover ids)."),
+			q: _nhtio_validation.validator.string().description("A pipe statement, e.g. \"select pages=2-5 | extract text\"."),
+			ops: _nhtio_validation.validator.array().items(_nhtio_validation.validator.object({
+				verb: _nhtio_validation.validator.string().required(),
+				args: _nhtio_validation.validator.object().unknown(true).required()
+			})).description("Structured alternative to q: [{ verb, args }] steps.")
+		}),
+		handler: async (args, ctx) => {
+			const { media_id: mediaId, q, ops } = args;
+			if (q === void 0 === (ops === void 0)) return failure("BAD_REQUEST", "provide exactly one of q (pipe statement) or ops (structured steps)");
+			const dispatch = ctx;
+			await runGate(gate, dispatch, name, args);
+			const acquired = await acquire(dispatch, resolveMedia, mediaId);
+			if (!acquired.ok) return acquired.failure;
+			try {
+				const runOptions = {
+					signal: dispatch.abortSignal,
+					resolveRef: refResolverFor(dispatch, resolveMedia)
+				};
+				return await renderResult(dispatch, q !== void 0 ? await pipeline.query(acquired.payload, q, runOptions) : await pipeline.ops(acquired.payload, ops, runOptions), name);
+			} catch (err) {
+				return renderError(err);
+			}
+		}
+	});
+};
+/** Convert a granular tool's flat args into the verb's op args (drops media_id). */
+var opArgsFrom = (args) => {
+	const out = {};
+	for (const [k, v] of Object.entries(args)) {
+		if (k === "media_id" || v === void 0) continue;
+		out[k] = v;
+	}
+	return out;
+};
+var granularSchemaFor = (spec) => {
+	const shape = { media_id: _nhtio_validation.validator.string().required().description("The id of the media to process (call list_media to discover ids).") };
+	for (const [argName, arg] of Object.entries(spec.args)) {
+		let schema;
+		switch (arg.type) {
+			case "number":
+				schema = _nhtio_validation.validator.number();
+				if (arg.min !== void 0) schema = schema.min(arg.min);
+				if (arg.max !== void 0) schema = schema.max(arg.max);
+				break;
+			case "boolean":
+				schema = _nhtio_validation.validator.boolean();
+				break;
+			case "enum":
+				schema = _nhtio_validation.validator.string().valid(...arg.values ?? []);
+				break;
+			case "number-list":
+				schema = _nhtio_validation.validator.array().items(_nhtio_validation.validator.number().min(arg.min ?? 1));
+				break;
+			case "string-list":
+				schema = arg.values ? _nhtio_validation.validator.array().items(_nhtio_validation.validator.string().valid(...arg.values)) : _nhtio_validation.validator.array().items(_nhtio_validation.validator.string());
+				break;
+			case "media-ref":
+				schema = _nhtio_validation.validator.string().description("A media id (from list_media) for the other media in this operation.");
+				break;
+			case "media-ref-list":
+				schema = _nhtio_validation.validator.array().items(_nhtio_validation.validator.string());
+				break;
+			case "name-or-index":
+				schema = _nhtio_validation.validator.alternatives().try(_nhtio_validation.validator.number().integer().min(1), _nhtio_validation.validator.string());
+				break;
+			case "regex-or-string-list":
+				schema = _nhtio_validation.validator.alternatives().try(_nhtio_validation.validator.string(), _nhtio_validation.validator.array().items(_nhtio_validation.validator.string()));
+				break;
+			case "json":
+				schema = _nhtio_validation.validator.any().optional();
+				break;
+			default: schema = _nhtio_validation.validator.string();
+		}
+		schema = schema.description(arg.description);
+		if (arg.required) schema = schema.required();
+		shape[argName] = schema;
+	}
+	return _nhtio_validation.validator.object(shape);
+};
+/** Normalize a granular tool's media-ref string args to MediaRef IR values. */
+var normalizeRefArgs = (spec, args) => {
+	for (const [argName, arg] of Object.entries(spec.args)) {
+		const value = args[argName];
+		if (value === void 0) continue;
+		if (arg.type === "media-ref" && typeof value === "string") args[argName] = {
+			kind: "id",
+			id: value
+		};
+		if (arg.type === "media-ref-list" && Array.isArray(value)) args[argName] = value.map((v) => typeof v === "string" ? {
+			kind: "id",
+			id: v
+		} : v);
+	}
+};
+var buildGranularTool = (pipeline, spec, resolveMedia, gate, overrides) => {
+	const defaultName = spec.id.replace(/\./g, "_");
+	const name = overrides?.[defaultName]?.name ?? defaultName;
+	return new require_tool.Tool({
+		name,
+		description: overrides?.[defaultName]?.description ?? `${spec.description} Processes a media file from this conversation locally. Indices are 1-based.`,
+		inputSchema: granularSchemaFor(spec),
+		handler: async (args, ctx) => {
+			const dispatch = ctx;
+			const { media_id: mediaId } = args;
+			await runGate(gate, dispatch, name, args);
+			const acquired = await acquire(dispatch, resolveMedia, mediaId);
+			if (!acquired.ok) return acquired.failure;
+			const opArgs = opArgsFrom(args);
+			normalizeRefArgs(spec, opArgs);
+			try {
+				return await renderResult(dispatch, await pipeline.ops(acquired.payload, [{
+					verb: spec.id,
+					args: opArgs
+				}], {
+					signal: dispatch.abortSignal,
+					resolveRef: refResolverFor(dispatch, resolveMedia)
+				}), name);
+			} catch (err) {
+				return renderError(err);
+			}
+		}
+	});
+};
+/**
+* Forge agent tools over a configured media pipeline.
+*
+* @remarks
+* The minted set follows the pipeline's configured engines: in the composite surface the
+* `media_query` grammar text only advertises available verbs; in the granular surface a tool
+* is minted only for verbs whose engine (if any) is configured. Either way `list_media` is
+* included — it is the model's entry point for discovering `media_id` values.
+*
+* The returned record is keyed by tool name so consumers can register selectively or pass
+* `Object.values(tools)` to `TurnRunnerConfig.tools`.
+*
+* @param pipeline - A pipeline from `createMediaPipeline`.
+* @param options - Surface, resolver, gate, and overrides.
+* @returns The minted tools, keyed by name.
+*/
+var forgeMediaTools = (pipeline, options) => {
+	if (options?.surface !== "composite" && options?.surface !== "granular") throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`forgeMediaTools requires surface: 'composite' | 'granular'`]);
+	const resolveMedia = options.resolveMedia ?? defaultResolveMedia;
+	const tools = {};
+	const listTool = buildListMediaTool(options.overrides);
+	tools[listTool.name] = listTool;
+	if (options.surface === "composite") {
+		const composite = buildCompositeTool(pipeline, resolveMedia, options.gate, options.overrides);
+		tools[composite.name] = composite;
+		return tools;
+	}
+	const available = new Set(require_validate.availableVerbs(pipeline.capabilities));
+	for (const spec of require_validate.VERB_INDEX.values()) {
+		if (!available.has(spec.id.replace(/[._]+/g, " "))) continue;
+		const tool = buildGranularTool(pipeline, spec, resolveMedia, options.gate, options.overrides);
+		tools[tool.name] = tool;
+	}
+	return tools;
+};
+//#endregion
+exports.defaultResolveMedia = defaultResolveMedia;
+exports.foldVerb = require_validate.foldVerb;
+exports.forgeMediaTools = forgeMediaTools;
+
+//# sourceMappingURL=forge.cjs.map

package/batteries/media/forge.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge.cjs","names":[],"sources":["../../../src/batteries/media/forge.ts"],"sourcesContent":["/**\n * Agent glue: forge ADK tools from a media pipeline, so a model can drive local media work.\n *\n * @module @nhtio/adk/batteries/media/forge\n *\n * @remarks\n * The pipeline core (`@nhtio/adk/batteries/media`) is agent-agnostic; this module is the layer\n * that knows the ADK loop. {@link forgeMediaTools} mints `Tool` instances over a configured\n * {@link @nhtio/adk/batteries/media!MediaPipeline} in one of two surfaces (the consumer picks\n * per deployment):\n *\n * - `'composite'` — one `media_query` tool taking `{ media_id, q }` (a pipe expression — the\n *   headline LLM DSL) or `{ media_id, ops }` (structured form), plus `list_media`. The tool\n *   description embeds the engine-narrowed verb grammar so the model never sees a verb the\n *   deployment can't run. One round-trip for multi-step work.\n * - `'granular'` — one narrow tool per available verb (`doc_select`, `sheet_update_cells`, …),\n *   each internally a one-verb plan. Friendlier to small models; bigger tool list.\n *\n * Media flows in by reference: the model passes `media_id` values it discovered via the\n * `list_media` tool (or inline id markers, where the LLM battery renders them); the resolver\n * scans `ctx.turnMessages[].attachments` and `ctx.turnToolCalls[].results` by default. Outputs\n * are persisted through `ctx.storeMediaBytes` and returned as `Media.toolGenerated(...)`, so\n * file results land on `ToolCall.results` as first-class media.\n *\n * Processing failures return readable strings (`Error (CODE): …`) the model can act on; the\n * pipe DSL's own syntax/semantic errors render the same way, so a model can repair its\n * statement and retry. An optional {@link ToolGateFn} runs before every execution — the seam\n * for human-approval/RBAC flows built on `ctx.waitFor` (the ADK gates primitive).\n */\n\nimport { toPipe } from './plan'\nimport { isError } from '@nhtio/adk/guards'\nimport { availableVerbs } from './validate'\nimport { validator } from '@nhtio/validation'\nimport { VERB_INDEX, foldVerb } from './verbs'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from './exceptions'\nimport { Tool, Media, SpooledJsonArtifact } from '@nhtio/adk/common'\nimport type { MediaPipeline } from './index'\nimport type { MediaOp, MediaArgValue } from './plan'\nimport type { VerbSpec, VerbArgSpec } from './verbs'\nimport type { DispatchContext } from '@nhtio/adk/types'\nimport type { StepPayload, PlanResult } from './runtime'\n\n/**\n * Resolves a `media_id` to a {@link @nhtio/adk!Media} visible in the current dispatch.\n * The default implementation scans turn messages' attachments and prior tool-call results.\n */\nexport type MediaResolverFn = (\n  ctx: DispatchContext,\n  mediaId: string\n) => Media | undefined | Promise<Media | undefined>\n\n/**\n * Optional per-call gate run before any pipeline execution. Throwing aborts the call and\n * surfaces through the standard tool-error path. The canonical implementation awaits\n * `ctx.waitFor({ reason: 'tool_approval', payload: call })` and throws on denial — WHO\n * approves and HOW is the consumer's contract; this is the seam.\n */\nexport type ToolGateFn = (\n  ctx: DispatchContext,\n  call: { tool: string; args: unknown }\n) => void | Promise<void>\n\n/** Options for {@link forgeMediaTools}. */\nexport interface ForgeMediaToolsOptions {\n  /** Which tool surface to mint. */\n  surface: 'composite' | 'granular'\n  /** Media-id resolution. Default: scan turn attachments + tool-call Media results. */\n  resolveMedia?: MediaResolverFn\n  /** Optional pre-execution gate (see {@link ToolGateFn}). */\n  gate?: ToolGateFn\n  /** Per-tool name/description overrides, keyed by the minted tool's default name. */\n  overrides?: Record<string, { name?: string; description?: string }>\n}\n\n/**\n * The default media resolver: scan `ctx.turnMessages[].attachments`, then\n * `ctx.turnToolCalls[].results`, for a Media with the given id.\n *\n * @param ctx - The dispatch context.\n * @param mediaId - The id to find.\n * @returns The Media, or `undefined` when nothing in the turn carries that id.\n */\nexport const defaultResolveMedia: MediaResolverFn = (ctx, mediaId) => {\n  for (const message of ctx.turnMessages) {\n    for (const attachment of message.attachments ?? []) {\n      if (attachment.id === mediaId) return attachment\n    }\n  }\n  for (const toolCall of ctx.turnToolCalls) {\n    const results = toolCall.results\n    if (Media.isMedia(results) && results.id === mediaId) return results\n    if (Array.isArray(results)) {\n      const hit = results.find((r) => Media.isMedia(r) && r.id === mediaId)\n      if (hit) return hit as Media\n    }\n  }\n  return undefined\n}\n\n/** Enumerate every Media visible in the turn (for `list_media` and MEDIA_NOT_FOUND hints). */\nconst enumerateMedia = (\n  ctx: DispatchContext\n): Array<{\n  id: string\n  filename: string\n  kind: string\n  mimeType: string\n  source?: string\n  origin: string\n}> => {\n  const out: Array<{\n    id: string\n    filename: string\n    kind: string\n    mimeType: string\n    source?: string\n    origin: string\n  }> = []\n  for (const message of ctx.turnMessages) {\n    for (const attachment of message.attachments ?? []) {\n      out.push({\n        id: attachment.id,\n        filename: attachment.filename,\n        kind: attachment.kind,\n        mimeType: attachment.mimeType,\n        source: attachment.source,\n        origin: 'attachment',\n      })\n    }\n  }\n  for (const toolCall of ctx.turnToolCalls) {\n    const results = toolCall.results\n    const mediaList = Media.isMedia(results)\n      ? [results]\n      : Array.isArray(results)\n        ? results.filter((r): r is Media => Media.isMedia(r))\n        : []\n    for (const media of mediaList) {\n      out.push({\n        id: media.id,\n        filename: media.filename,\n        kind: media.kind,\n        mimeType: media.mimeType,\n        source: media.source,\n        origin: 'tool-result',\n      })\n    }\n  }\n  return out\n}\n\nconst failure = (code: string, message: string): string => `Error (${code}): ${message}`\n\nconst mediaKindOf = (mimeType: string): 'image' | 'audio' | 'video' | 'document' => {\n  const mime = mimeType.toLowerCase()\n  if (mime.startsWith('image/')) return 'image'\n  if (mime.startsWith('audio/')) return 'audio'\n  if (mime.startsWith('video/')) return 'video'\n  return 'document'\n}\n\n/** Load a resolved Media's bytes into a pipeline payload. */\nconst toPayload = async (media: Media): Promise<StepPayload> => ({\n  bytes: await media.asBytes(),\n  mimeType: media.mimeType,\n  filename: media.filename,\n})\n\n/** Persist a payload through the dispatch byte conduit and mint a first-party Media. */\nconst toMedia = async (\n  ctx: DispatchContext,\n  payload: StepPayload,\n  toolName: string\n): Promise<Media> => {\n  const id = crypto.randomUUID()\n  const reader = await ctx.storeMediaBytes(id, payload.bytes)\n  return Media.toolGenerated({\n    id,\n    kind: mediaKindOf(payload.mimeType),\n    mimeType: payload.mimeType,\n    filename: payload.filename,\n    reader,\n    source: `tool:${toolName}`,\n  })\n}\n\n/** Render a plan result as a tool handler return value. */\nconst renderResult = async (\n  ctx: DispatchContext,\n  result: PlanResult,\n  toolName: string\n): Promise<string | Media | Media[]> => {\n  if (result.kind === 'media') return toMedia(ctx, result.payload, toolName)\n  if (result.kind === 'media-list') {\n    return Promise.all(result.payloads.map((p) => toMedia(ctx, p, toolName)))\n  }\n  return typeof result.data === 'string' ? result.data : JSON.stringify(result.data, null, 2)\n}\n\n/** Resolve + acquire the input media or produce a model-actionable failure string. */\nconst acquire = async (\n  ctx: DispatchContext,\n  resolveMedia: MediaResolverFn,\n  mediaId: string\n): Promise<{ ok: true; payload: StepPayload } | { ok: false; failure: string }> => {\n  const media = await resolveMedia(ctx, mediaId)\n  if (!media) {\n    const visible = enumerateMedia(ctx)\n    const hint =\n      visible.length > 0\n        ? `Visible media ids: ${visible.map((m) => `${m.id} (${m.filename})`).join(', ')}`\n        : 'No media is visible in this turn — ask the user to attach a file, or call list_media to check.'\n    return {\n      ok: false,\n      failure: failure('MEDIA_NOT_FOUND', `no media with id \"${mediaId}\". ${hint}`),\n    }\n  }\n  return { ok: true, payload: await toPayload(media) }\n}\n\n/** Build a per-run @id ref resolver bound to this dispatch's visible media. */\nconst refResolverFor =\n  (ctx: DispatchContext, resolveMedia: MediaResolverFn) =>\n  async (id: string): Promise<StepPayload> => {\n    const media = await resolveMedia(ctx, id)\n    if (!media) {\n      const visible = enumerateMedia(ctx)\n        .map((m) => m.id)\n        .join(', ')\n      throw new Error(\n        `referenced media @${id} was not found in this turn. Visible ids: ${visible || '(none)'}`\n      )\n    }\n    return toPayload(media)\n  }\n\n/** Run the optional gate; a throw becomes the tool's error (standard downstream wrapping). */\nconst runGate = async (\n  gate: ToolGateFn | undefined,\n  ctx: DispatchContext,\n  tool: string,\n  args: unknown\n): Promise<void> => {\n  if (gate) await gate(ctx, { tool, args })\n}\n\n/** Map a thrown pipeline error to a readable failure string the model can act on. */\nconst renderError = (err: unknown): string => {\n  if (isError(err) && err.name.startsWith('E_MEDIA_')) {\n    return failure(err.name.replace(/^E_MEDIA_/, ''), err.message)\n  }\n  throw err\n}\n\n// ── grammar text generation (composite surface) ──────────────────────────────\n\nconst argHelp = (name: string, arg: VerbArgSpec): string => {\n  const req = arg.required ? '' : '?'\n  const type =\n    arg.type === 'enum' ? (arg.values ?? []).join('|') : arg.type === 'json' ? \"'<JSON>'\" : arg.type\n  return `${name}${req}=${type}`\n}\n\nconst verbHelp = (spec: VerbSpec): string => {\n  const verb = spec.id.replace(/\\./g, ' ')\n  const args = Object.entries(spec.args)\n    .map(([n, a]) => argHelp(n, a))\n    .join(' ')\n  return args.length > 0 ? `${verb} ${args}` : verb\n}\n\n/**\n * Generate the model-facing grammar text for the configured deployment: only available verbs,\n * with arg signatures, plus few-shot examples rendered from real plans via `toPipe` so they\n * can never drift from the parser.\n */\nconst grammarText = (pipeline: MediaPipeline): string => {\n  const available = new Set(availableVerbs(pipeline.capabilities))\n  const lines: string[] = []\n  for (const spec of VERB_INDEX.values()) {\n    if (!available.has(spec.id.replace(/[._]+/g, ' '))) continue\n    lines.push(`- ${verbHelp(spec)} — ${spec.description}`)\n  }\n  const examples: string[] = [\n    toPipe({\n      steps: [\n        { verb: 'select', args: { pages: [2, 3, 4, 5] } },\n        { verb: 'extract.text', args: {} },\n      ],\n    }),\n    toPipe({\n      steps: [\n        { verb: 'extract.text', args: {} },\n        { verb: 'chunk', args: { by: 'sentence', size: 512 } },\n      ],\n    }),\n  ]\n  if (available.has('redact')) {\n    examples.push(\n      toPipe({\n        steps: [\n          {\n            verb: 'redact',\n            args: { match: [{ source: '\\\\d{3}-\\\\d{2}-\\\\d{4}', flags: '' }], replace: '[SSN]' },\n          },\n        ],\n      })\n    )\n  }\n  return [\n    'Statements are pipe expressions: verb name=value ... | verb name=value ...',\n    'Named args only. Indices are 1-based. Quote values containing spaces or dashes.',\n    'Structured payloads are quoted JSON: updates=\\'[{\"address\":\"B2\",\"value\":3}]\\'.',\n    'Reference other media inline by id: merge with=@<media id> (ids come from list_media).',\n    '',\n    'Available verbs:',\n    ...lines,\n    '',\n    'Examples (remember: inside JSON tool args, backslashes must be doubled — \\\\\\\\d):',\n    ...examples.map((e) => `  ${e}`),\n  ].join('\\n')\n}\n\n// ── the tools ────────────────────────────────────────────────────────────────\n\nconst buildListMediaTool = (overrides: ForgeMediaToolsOptions['overrides']): Tool => {\n  const name = overrides?.list_media?.name ?? 'list_media'\n  return new Tool({\n    name,\n    description:\n      overrides?.list_media?.description ??\n      'Lists every media file visible in this conversation turn (user attachments and files produced by prior tool calls), with the media ids other media tools require.',\n    inputSchema: validator.object({}),\n    artifactConstructor: () => SpooledJsonArtifact,\n    handler: async (_args, ctx) => {\n      const media = enumerateMedia(ctx as DispatchContext)\n      return JSON.stringify(media, null, 2)\n    },\n  })\n}\n\nconst buildCompositeTool = (\n  pipeline: MediaPipeline,\n  resolveMedia: MediaResolverFn,\n  gate: ToolGateFn | undefined,\n  overrides: ForgeMediaToolsOptions['overrides']\n): Tool => {\n  const name = overrides?.media_query?.name ?? 'media_query'\n  const description =\n    overrides?.media_query?.description ??\n    `Runs a media-processing statement against a file from this conversation, locally (no external services). Provide media_id (from list_media) and either q (a pipe statement) or ops (structured steps).\n\n${grammarText(pipeline)}`\n  return new Tool({\n    name,\n    description,\n    inputSchema: validator.object({\n      media_id: validator\n        .string()\n        .required()\n        .description('The id of the media to process (call list_media to discover ids).'),\n      q: validator\n        .string()\n        .description('A pipe statement, e.g. \"select pages=2-5 | extract text\".'),\n      ops: validator\n        .array()\n        .items(\n          validator.object({\n            verb: validator.string().required(),\n            args: validator.object().unknown(true).required(),\n          })\n        )\n        .description('Structured alternative to q: [{ verb, args }] steps.'),\n    }),\n    handler: async (args, ctx) => {\n      const {\n        media_id: mediaId,\n        q,\n        ops,\n      } = args as { media_id: string; q?: string; ops?: MediaOp[] }\n      if ((q === undefined) === (ops === undefined)) {\n        return failure(\n          'BAD_REQUEST',\n          'provide exactly one of q (pipe statement) or ops (structured steps)'\n        )\n      }\n      const dispatch = ctx as DispatchContext\n      await runGate(gate, dispatch, name, args)\n      const acquired = await acquire(dispatch, resolveMedia, mediaId)\n      if (!acquired.ok) return acquired.failure\n      try {\n        const runOptions = {\n          signal: dispatch.abortSignal,\n          resolveRef: refResolverFor(dispatch, resolveMedia),\n        }\n        const result =\n          q !== undefined\n            ? await pipeline.query(acquired.payload, q, runOptions)\n            : await pipeline.ops(acquired.payload, ops as MediaOp[], runOptions)\n        return await renderResult(dispatch, result, name)\n      } catch (err) {\n        return renderError(err)\n      }\n    },\n  })\n}\n\n/** Convert a granular tool's flat args into the verb's op args (drops media_id). */\nconst opArgsFrom = (args: Record<string, unknown>): Record<string, MediaArgValue> => {\n  const out: Record<string, MediaArgValue> = {}\n  for (const [k, v] of Object.entries(args)) {\n    if (k === 'media_id' || v === undefined) continue\n    out[k] = v as MediaArgValue\n  }\n  return out\n}\n\nconst granularSchemaFor = (spec: VerbSpec): ReturnType<typeof validator.object> => {\n  const shape: Record<string, ReturnType<typeof validator.any>> = {\n    media_id: validator\n      .string()\n      .required()\n      .description('The id of the media to process (call list_media to discover ids).'),\n  }\n  for (const [argName, arg] of Object.entries(spec.args)) {\n    let schema\n    switch (arg.type) {\n      case 'number':\n        schema = validator.number()\n        if (arg.min !== undefined) schema = schema.min(arg.min)\n        if (arg.max !== undefined) schema = schema.max(arg.max)\n        break\n      case 'boolean':\n        schema = validator.boolean()\n        break\n      case 'enum':\n        schema = validator.string().valid(...(arg.values ?? []))\n        break\n      case 'number-list':\n        schema = validator.array().items(validator.number().min(arg.min ?? 1))\n        break\n      case 'string-list':\n        schema = arg.values\n          ? validator.array().items(validator.string().valid(...arg.values))\n          : validator.array().items(validator.string())\n        break\n      case 'media-ref':\n        schema = validator\n          .string()\n          .description('A media id (from list_media) for the other media in this operation.')\n        break\n      case 'media-ref-list':\n        schema = validator.array().items(validator.string())\n        break\n      case 'name-or-index':\n        schema = validator\n          .alternatives()\n          .try(validator.number().integer().min(1), validator.string())\n        break\n      case 'regex-or-string-list':\n        schema = validator\n          .alternatives()\n          .try(validator.string(), validator.array().items(validator.string()))\n        break\n      case 'json':\n        schema = validator.any().optional()\n        break\n      default:\n        schema = validator.string()\n    }\n    schema = schema.description(arg.description)\n    if (arg.required) schema = schema.required()\n    shape[argName] = schema\n  }\n  return validator.object(shape)\n}\n\n/** Normalize a granular tool's media-ref string args to MediaRef IR values. */\nconst normalizeRefArgs = (spec: VerbSpec, args: Record<string, MediaArgValue>): void => {\n  for (const [argName, arg] of Object.entries(spec.args)) {\n    const value = args[argName]\n    if (value === undefined) continue\n    if (arg.type === 'media-ref' && typeof value === 'string') {\n      args[argName] = { kind: 'id', id: value }\n    }\n    if (arg.type === 'media-ref-list' && Array.isArray(value)) {\n      args[argName] = (value as unknown[]).map((v) =>\n        typeof v === 'string' ? { kind: 'id', id: v } : (v as MediaArgValue)\n      ) as MediaArgValue\n    }\n  }\n}\n\nconst buildGranularTool = (\n  pipeline: MediaPipeline,\n  spec: VerbSpec,\n  resolveMedia: MediaResolverFn,\n  gate: ToolGateFn | undefined,\n  overrides: ForgeMediaToolsOptions['overrides']\n): Tool => {\n  const defaultName = spec.id.replace(/\\./g, '_')\n  const name = overrides?.[defaultName]?.name ?? defaultName\n  return new Tool({\n    name,\n    description:\n      overrides?.[defaultName]?.description ??\n      `${spec.description} Processes a media file from this conversation locally. Indices are 1-based.`,\n    inputSchema: granularSchemaFor(spec),\n    handler: async (args, ctx) => {\n      const dispatch = ctx as DispatchContext\n      const { media_id: mediaId } = args as { media_id: string }\n      await runGate(gate, dispatch, name, args)\n      const acquired = await acquire(dispatch, resolveMedia, mediaId)\n      if (!acquired.ok) return acquired.failure\n      const opArgs = opArgsFrom(args as Record<string, unknown>)\n      normalizeRefArgs(spec, opArgs)\n      try {\n        const result = await pipeline.ops(acquired.payload, [{ verb: spec.id, args: opArgs }], {\n          signal: dispatch.abortSignal,\n          resolveRef: refResolverFor(dispatch, resolveMedia),\n        })\n        return await renderResult(dispatch, result, name)\n      } catch (err) {\n        return renderError(err)\n      }\n    },\n  })\n}\n\n/**\n * Forge agent tools over a configured media pipeline.\n *\n * @remarks\n * The minted set follows the pipeline's configured engines: in the composite surface the\n * `media_query` grammar text only advertises available verbs; in the granular surface a tool\n * is minted only for verbs whose engine (if any) is configured. Either way `list_media` is\n * included — it is the model's entry point for discovering `media_id` values.\n *\n * The returned record is keyed by tool name so consumers can register selectively or pass\n * `Object.values(tools)` to `TurnRunnerConfig.tools`.\n *\n * @param pipeline - A pipeline from `createMediaPipeline`.\n * @param options - Surface, resolver, gate, and overrides.\n * @returns The minted tools, keyed by name.\n */\nexport const forgeMediaTools = (\n  pipeline: MediaPipeline,\n  options: ForgeMediaToolsOptions\n): Record<string, Tool> => {\n  if (options?.surface !== 'composite' && options?.surface !== 'granular') {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      `forgeMediaTools requires surface: 'composite' | 'granular'`,\n    ])\n  }\n  const resolveMedia = options.resolveMedia ?? defaultResolveMedia\n  const tools: Record<string, Tool> = {}\n  const listTool = buildListMediaTool(options.overrides)\n  tools[listTool.name] = listTool\n\n  if (options.surface === 'composite') {\n    const composite = buildCompositeTool(pipeline, resolveMedia, options.gate, options.overrides)\n    tools[composite.name] = composite\n    return tools\n  }\n\n  const available = new Set(availableVerbs(pipeline.capabilities))\n  for (const spec of VERB_INDEX.values()) {\n    if (!available.has(spec.id.replace(/[._]+/g, ' '))) continue\n    const tool = buildGranularTool(pipeline, spec, resolveMedia, options.gate, options.overrides)\n    tools[tool.name] = tool\n  }\n  return tools\n}\n\n/** Re-exported so consumers can fold verbs the same way the forge does. */\nexport { foldVerb }\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,IAAa,uBAAwC,KAAK,YAAY;CACpE,KAAK,MAAM,WAAW,IAAI,cACxB,KAAK,MAAM,cAAc,QAAQ,eAAe,CAAC,GAC/C,IAAI,WAAW,OAAO,SAAS,OAAO;CAG1C,KAAK,MAAM,YAAY,IAAI,eAAe;EACxC,MAAM,UAAU,SAAS;EACzB,IAAI,kBAAA,MAAM,QAAQ,OAAO,KAAK,QAAQ,OAAO,SAAS,OAAO;EAC7D,IAAI,MAAM,QAAQ,OAAO,GAAG;GAC1B,MAAM,MAAM,QAAQ,MAAM,MAAM,kBAAA,MAAM,QAAQ,CAAC,KAAK,EAAE,OAAO,OAAO;GACpE,IAAI,KAAK,OAAO;EAClB;CACF;AAEF;;AAGA,IAAM,kBACJ,QAQI;CACJ,MAAM,MAOD,CAAC;CACN,KAAK,MAAM,WAAW,IAAI,cACxB,KAAK,MAAM,cAAc,QAAQ,eAAe,CAAC,GAC/C,IAAI,KAAK;EACP,IAAI,WAAW;EACf,UAAU,WAAW;EACrB,MAAM,WAAW;EACjB,UAAU,WAAW;EACrB,QAAQ,WAAW;EACnB,QAAQ;CACV,CAAC;CAGL,KAAK,MAAM,YAAY,IAAI,eAAe;EACxC,MAAM,UAAU,SAAS;EACzB,MAAM,YAAY,kBAAA,MAAM,QAAQ,OAAO,IACnC,CAAC,OAAO,IACR,MAAM,QAAQ,OAAO,IACnB,QAAQ,QAAQ,MAAkB,kBAAA,MAAM,QAAQ,CAAC,CAAC,IAClD,CAAC;EACP,KAAK,MAAM,SAAS,WAClB,IAAI,KAAK;GACP,IAAI,MAAM;GACV,UAAU,MAAM;GAChB,MAAM,MAAM;GACZ,UAAU,MAAM;GAChB,QAAQ,MAAM;GACd,QAAQ;EACV,CAAC;CAEL;CACA,OAAO;AACT;AAEA,IAAM,WAAW,MAAc,YAA4B,UAAU,KAAK,KAAK;AAE/E,IAAM,eAAe,aAA+D;CAClF,MAAM,OAAO,SAAS,YAAY;CAClC,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO;CACtC,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO;CACtC,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO;CACtC,OAAO;AACT;;AAGA,IAAM,YAAY,OAAO,WAAwC;CAC/D,OAAO,MAAM,MAAM,QAAQ;CAC3B,UAAU,MAAM;CAChB,UAAU,MAAM;AAClB;;AAGA,IAAM,UAAU,OACd,KACA,SACA,aACmB;CACnB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,SAAS,MAAM,IAAI,gBAAgB,IAAI,QAAQ,KAAK;CAC1D,OAAO,kBAAA,MAAM,cAAc;EACzB;EACA,MAAM,YAAY,QAAQ,QAAQ;EAClC,UAAU,QAAQ;EAClB,UAAU,QAAQ;EAClB;EACA,QAAQ,QAAQ;CAClB,CAAC;AACH;;AAGA,IAAM,eAAe,OACnB,KACA,QACA,aACsC;CACtC,IAAI,OAAO,SAAS,SAAS,OAAO,QAAQ,KAAK,OAAO,SAAS,QAAQ;CACzE,IAAI,OAAO,SAAS,cAClB,OAAO,QAAQ,IAAI,OAAO,SAAS,KAAK,MAAM,QAAQ,KAAK,GAAG,QAAQ,CAAC,CAAC;CAE1E,OAAO,OAAO,OAAO,SAAS,WAAW,OAAO,OAAO,KAAK,UAAU,OAAO,MAAM,MAAM,CAAC;AAC5F;;AAGA,IAAM,UAAU,OACd,KACA,cACA,YACiF;CACjF,MAAM,QAAQ,MAAM,aAAa,KAAK,OAAO;CAC7C,IAAI,CAAC,OAAO;EACV,MAAM,UAAU,eAAe,GAAG;EAKlC,OAAO;GACL,IAAI;GACJ,SAAS,QAAQ,mBAAmB,qBAAqB,QAAQ,KALjE,QAAQ,SAAS,IACb,sBAAsB,QAAQ,KAAK,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,IAAI,MAC7E,kGAGwE;EAC9E;CACF;CACA,OAAO;EAAE,IAAI;EAAM,SAAS,MAAM,UAAU,KAAK;CAAE;AACrD;;AAGA,IAAM,kBACH,KAAsB,iBACvB,OAAO,OAAqC;CAC1C,MAAM,QAAQ,MAAM,aAAa,KAAK,EAAE;CACxC,IAAI,CAAC,OAAO;EACV,MAAM,UAAU,eAAe,GAAG,EAC/B,KAAK,MAAM,EAAE,EAAE,EACf,KAAK,IAAI;EACZ,MAAM,IAAI,MACR,qBAAqB,GAAG,4CAA4C,WAAW,UACjF;CACF;CACA,OAAO,UAAU,KAAK;AACxB;;AAGF,IAAM,UAAU,OACd,MACA,KACA,MACA,SACkB;CAClB,IAAI,MAAM,MAAM,KAAK,KAAK;EAAE;EAAM;CAAK,CAAC;AAC1C;;AAGA,IAAM,eAAe,QAAyB;CAC5C,IAAI,sBAAA,QAAQ,GAAG,KAAK,IAAI,KAAK,WAAW,UAAU,GAChD,OAAO,QAAQ,IAAI,KAAK,QAAQ,aAAa,EAAE,GAAG,IAAI,OAAO;CAE/D,MAAM;AACR;AAIA,IAAM,WAAW,MAAc,QAA6B;CAI1D,OAAO,GAAG,OAHE,IAAI,WAAW,KAAK,IAGX,GADnB,IAAI,SAAS,UAAU,IAAI,UAAU,CAAC,GAAG,KAAK,GAAG,IAAI,IAAI,SAAS,SAAS,aAAa,IAAI;AAEhG;AAEA,IAAM,YAAY,SAA2B;CAC3C,MAAM,OAAO,KAAK,GAAG,QAAQ,OAAO,GAAG;CACvC,MAAM,OAAO,OAAO,QAAQ,KAAK,IAAI,EAClC,KAAK,CAAC,GAAG,OAAO,QAAQ,GAAG,CAAC,CAAC,EAC7B,KAAK,GAAG;CACX,OAAO,KAAK,SAAS,IAAI,GAAG,KAAK,GAAG,SAAS;AAC/C;;;;;;AAOA,IAAM,eAAe,aAAoC;CACvD,MAAM,YAAY,IAAI,IAAI,iBAAA,eAAe,SAAS,YAAY,CAAC;CAC/D,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,QAAQ,iBAAA,WAAW,OAAO,GAAG;EACtC,IAAI,CAAC,UAAU,IAAI,KAAK,GAAG,QAAQ,UAAU,GAAG,CAAC,GAAG;EACpD,MAAM,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,KAAK,aAAa;CACxD;CACA,MAAM,WAAqB,CACzB,iBAAA,OAAO,EACL,OAAO,CACL;EAAE,MAAM;EAAU,MAAM,EAAE,OAAO;GAAC;GAAG;GAAG;GAAG;EAAC,EAAE;CAAE,GAChD;EAAE,MAAM;EAAgB,MAAM,CAAC;CAAE,CACnC,EACF,CAAC,GACD,iBAAA,OAAO,EACL,OAAO,CACL;EAAE,MAAM;EAAgB,MAAM,CAAC;CAAE,GACjC;EAAE,MAAM;EAAS,MAAM;GAAE,IAAI;GAAY,MAAM;EAAI;CAAE,CACvD,EACF,CAAC,CACH;CACA,IAAI,UAAU,IAAI,QAAQ,GACxB,SAAS,KACP,iBAAA,OAAO,EACL,OAAO,CACL;EACE,MAAM;EACN,MAAM;GAAE,OAAO,CAAC;IAAE,QAAQ;IAAwB,OAAO;GAAG,CAAC;GAAG,SAAS;EAAQ;CACnF,CACF,EACF,CAAC,CACH;CAEF,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA,GAAG;EACH;EACA;EACA,GAAG,SAAS,KAAK,MAAM,KAAK,GAAG;CACjC,EAAE,KAAK,IAAI;AACb;AAIA,IAAM,sBAAsB,cAAyD;CAEnF,OAAO,IAAI,aAAA,KAAK;EACd,MAFW,WAAW,YAAY,QAAQ;EAG1C,aACE,WAAW,YAAY,eACvB;EACF,aAAa,kBAAA,UAAU,OAAO,CAAC,CAAC;EAChC,2BAA2B,kCAAA;EAC3B,SAAS,OAAO,OAAO,QAAQ;GAC7B,MAAM,QAAQ,eAAe,GAAsB;GACnD,OAAO,KAAK,UAAU,OAAO,MAAM,CAAC;EACtC;CACF,CAAC;AACH;AAEA,IAAM,sBACJ,UACA,cACA,MACA,cACS;CACT,MAAM,OAAO,WAAW,aAAa,QAAQ;CAM7C,OAAO,IAAI,aAAA,KAAK;EACd;EACA,aANA,WAAW,aAAa,eACxB;;EAEF,YAAY,QAAQ;EAIlB,aAAa,kBAAA,UAAU,OAAO;GAC5B,UAAU,kBAAA,UACP,OAAO,EACP,SAAS,EACT,YAAY,mEAAmE;GAClF,GAAG,kBAAA,UACA,OAAO,EACP,YAAY,6DAA2D;GAC1E,KAAK,kBAAA,UACF,MAAM,EACN,MACC,kBAAA,UAAU,OAAO;IACf,MAAM,kBAAA,UAAU,OAAO,EAAE,SAAS;IAClC,MAAM,kBAAA,UAAU,OAAO,EAAE,QAAQ,IAAI,EAAE,SAAS;GAClD,CAAC,CACH,EACC,YAAY,sDAAsD;EACvE,CAAC;EACD,SAAS,OAAO,MAAM,QAAQ;GAC5B,MAAM,EACJ,UAAU,SACV,GACA,QACE;GACJ,IAAK,MAAM,KAAA,OAAgB,QAAQ,KAAA,IACjC,OAAO,QACL,eACA,qEACF;GAEF,MAAM,WAAW;GACjB,MAAM,QAAQ,MAAM,UAAU,MAAM,IAAI;GACxC,MAAM,WAAW,MAAM,QAAQ,UAAU,cAAc,OAAO;GAC9D,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS;GAClC,IAAI;IACF,MAAM,aAAa;KACjB,QAAQ,SAAS;KACjB,YAAY,eAAe,UAAU,YAAY;IACnD;IAKA,OAAO,MAAM,aAAa,UAHxB,MAAM,KAAA,IACF,MAAM,SAAS,MAAM,SAAS,SAAS,GAAG,UAAU,IACpD,MAAM,SAAS,IAAI,SAAS,SAAS,KAAkB,UAAU,GAC3B,IAAI;GAClD,SAAS,KAAK;IACZ,OAAO,YAAY,GAAG;GACxB;EACF;CACF,CAAC;AACH;;AAGA,IAAM,cAAc,SAAiE;CACnF,MAAM,MAAqC,CAAC;CAC5C,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,IAAI,GAAG;EACzC,IAAI,MAAM,cAAc,MAAM,KAAA,GAAW;EACzC,IAAI,KAAK;CACX;CACA,OAAO;AACT;AAEA,IAAM,qBAAqB,SAAwD;CACjF,MAAM,QAA0D,EAC9D,UAAU,kBAAA,UACP,OAAO,EACP,SAAS,EACT,YAAY,mEAAmE,EACpF;CACA,KAAK,MAAM,CAAC,SAAS,QAAQ,OAAO,QAAQ,KAAK,IAAI,GAAG;EACtD,IAAI;EACJ,QAAQ,IAAI,MAAZ;GACE,KAAK;IACH,SAAS,kBAAA,UAAU,OAAO;IAC1B,IAAI,IAAI,QAAQ,KAAA,GAAW,SAAS,OAAO,IAAI,IAAI,GAAG;IACtD,IAAI,IAAI,QAAQ,KAAA,GAAW,SAAS,OAAO,IAAI,IAAI,GAAG;IACtD;GACF,KAAK;IACH,SAAS,kBAAA,UAAU,QAAQ;IAC3B;GACF,KAAK;IACH,SAAS,kBAAA,UAAU,OAAO,EAAE,MAAM,GAAI,IAAI,UAAU,CAAC,CAAE;IACvD;GACF,KAAK;IACH,SAAS,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,OAAO,EAAE,IAAI,IAAI,OAAO,CAAC,CAAC;IACrE;GACF,KAAK;IACH,SAAS,IAAI,SACT,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,OAAO,EAAE,MAAM,GAAG,IAAI,MAAM,CAAC,IAC/D,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,OAAO,CAAC;IAC9C;GACF,KAAK;IACH,SAAS,kBAAA,UACN,OAAO,EACP,YAAY,qEAAqE;IACpF;GACF,KAAK;IACH,SAAS,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,OAAO,CAAC;IACnD;GACF,KAAK;IACH,SAAS,kBAAA,UACN,aAAa,EACb,IAAI,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,kBAAA,UAAU,OAAO,CAAC;IAC9D;GACF,KAAK;IACH,SAAS,kBAAA,UACN,aAAa,EACb,IAAI,kBAAA,UAAU,OAAO,GAAG,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,OAAO,CAAC,CAAC;IACtE;GACF,KAAK;IACH,SAAS,kBAAA,UAAU,IAAI,EAAE,SAAS;IAClC;GACF,SACE,SAAS,kBAAA,UAAU,OAAO;EAC9B;EACA,SAAS,OAAO,YAAY,IAAI,WAAW;EAC3C,IAAI,IAAI,UAAU,SAAS,OAAO,SAAS;EAC3C,MAAM,WAAW;CACnB;CACA,OAAO,kBAAA,UAAU,OAAO,KAAK;AAC/B;;AAGA,IAAM,oBAAoB,MAAgB,SAA8C;CACtF,KAAK,MAAM,CAAC,SAAS,QAAQ,OAAO,QAAQ,KAAK,IAAI,GAAG;EACtD,MAAM,QAAQ,KAAK;EACnB,IAAI,UAAU,KAAA,GAAW;EACzB,IAAI,IAAI,SAAS,eAAe,OAAO,UAAU,UAC/C,KAAK,WAAW;GAAE,MAAM;GAAM,IAAI;EAAM;EAE1C,IAAI,IAAI,SAAS,oBAAoB,MAAM,QAAQ,KAAK,GACtD,KAAK,WAAY,MAAoB,KAAK,MACxC,OAAO,MAAM,WAAW;GAAE,MAAM;GAAM,IAAI;EAAE,IAAK,CACnD;CAEJ;AACF;AAEA,IAAM,qBACJ,UACA,MACA,cACA,MACA,cACS;CACT,MAAM,cAAc,KAAK,GAAG,QAAQ,OAAO,GAAG;CAC9C,MAAM,OAAO,YAAY,cAAc,QAAQ;CAC/C,OAAO,IAAI,aAAA,KAAK;EACd;EACA,aACE,YAAY,cAAc,eAC1B,GAAG,KAAK,YAAY;EACtB,aAAa,kBAAkB,IAAI;EACnC,SAAS,OAAO,MAAM,QAAQ;GAC5B,MAAM,WAAW;GACjB,MAAM,EAAE,UAAU,YAAY;GAC9B,MAAM,QAAQ,MAAM,UAAU,MAAM,IAAI;GACxC,MAAM,WAAW,MAAM,QAAQ,UAAU,cAAc,OAAO;GAC9D,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS;GAClC,MAAM,SAAS,WAAW,IAA+B;GACzD,iBAAiB,MAAM,MAAM;GAC7B,IAAI;IAKF,OAAO,MAAM,aAAa,UAAU,MAJf,SAAS,IAAI,SAAS,SAAS,CAAC;KAAE,MAAM,KAAK;KAAI,MAAM;IAAO,CAAC,GAAG;KACrF,QAAQ,SAAS;KACjB,YAAY,eAAe,UAAU,YAAY;IACnD,CAAC,GAC2C,IAAI;GAClD,SAAS,KAAK;IACZ,OAAO,YAAY,GAAG;GACxB;EACF;CACF,CAAC;AACH;;;;;;;;;;;;;;;;;AAkBA,IAAa,mBACX,UACA,YACyB;CACzB,IAAI,SAAS,YAAY,eAAe,SAAS,YAAY,YAC3D,MAAM,IAAI,mBAAA,gCAAgC,CACxC,4DACF,CAAC;CAEH,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,MAAM,QAA8B,CAAC;CACrC,MAAM,WAAW,mBAAmB,QAAQ,SAAS;CACrD,MAAM,SAAS,QAAQ;CAEvB,IAAI,QAAQ,YAAY,aAAa;EACnC,MAAM,YAAY,mBAAmB,UAAU,cAAc,QAAQ,MAAM,QAAQ,SAAS;EAC5F,MAAM,UAAU,QAAQ;EACxB,OAAO;CACT;CAEA,MAAM,YAAY,IAAI,IAAI,iBAAA,eAAe,SAAS,YAAY,CAAC;CAC/D,KAAK,MAAM,QAAQ,iBAAA,WAAW,OAAO,GAAG;EACtC,IAAI,CAAC,UAAU,IAAI,KAAK,GAAG,QAAQ,UAAU,GAAG,CAAC,GAAG;EACpD,MAAM,OAAO,kBAAkB,UAAU,MAAM,cAAc,QAAQ,MAAM,QAAQ,SAAS;EAC5F,MAAM,KAAK,QAAQ;CACrB;CACA,OAAO;AACT"}

package/batteries/media/forge.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Agent glue: forge ADK tools from a media pipeline, so a model can drive local media work.
+ *
+ * @module @nhtio/adk/batteries/media/forge
+ *
+ * @remarks
+ * The pipeline core (`@nhtio/adk/batteries/media`) is agent-agnostic; this module is the layer
+ * that knows the ADK loop. {@link forgeMediaTools} mints `Tool` instances over a configured
+ * {@link @nhtio/adk/batteries/media!MediaPipeline} in one of two surfaces (the consumer picks
+ * per deployment):
+ *
+ * - `'composite'` — one `media_query` tool taking `{ media_id, q }` (a pipe expression — the
+ *   headline LLM DSL) or `{ media_id, ops }` (structured form), plus `list_media`. The tool
+ *   description embeds the engine-narrowed verb grammar so the model never sees a verb the
+ *   deployment can't run. One round-trip for multi-step work.
+ * - `'granular'` — one narrow tool per available verb (`doc_select`, `sheet_update_cells`, …),
+ *   each internally a one-verb plan. Friendlier to small models; bigger tool list.
+ *
+ * Media flows in by reference: the model passes `media_id` values it discovered via the
+ * `list_media` tool (or inline id markers, where the LLM battery renders them); the resolver
+ * scans `ctx.turnMessages[].attachments` and `ctx.turnToolCalls[].results` by default. Outputs
+ * are persisted through `ctx.storeMediaBytes` and returned as `Media.toolGenerated(...)`, so
+ * file results land on `ToolCall.results` as first-class media.
+ *
+ * Processing failures return readable strings (`Error (CODE): …`) the model can act on; the
+ * pipe DSL's own syntax/semantic errors render the same way, so a model can repair its
+ * statement and retry. An optional {@link ToolGateFn} runs before every execution — the seam
+ * for human-approval/RBAC flows built on `ctx.waitFor` (the ADK gates primitive).
+ */
+import { foldVerb } from "./verbs";
+import { Tool, Media } from "../../common";
+import type { MediaPipeline } from "./index";
+import type { DispatchContext } from "../../types";
+/**
+ * Resolves a `media_id` to a {@link @nhtio/adk!Media} visible in the current dispatch.
+ * The default implementation scans turn messages' attachments and prior tool-call results.
+ */
+export type MediaResolverFn = (ctx: DispatchContext, mediaId: string) => Media | undefined | Promise<Media | undefined>;
+/**
+ * Optional per-call gate run before any pipeline execution. Throwing aborts the call and
+ * surfaces through the standard tool-error path. The canonical implementation awaits
+ * `ctx.waitFor({ reason: 'tool_approval', payload: call })` and throws on denial — WHO
+ * approves and HOW is the consumer's contract; this is the seam.
+ */
+export type ToolGateFn = (ctx: DispatchContext, call: {
+    tool: string;
+    args: unknown;
+}) => void | Promise<void>;
+/** Options for {@link forgeMediaTools}. */
+export interface ForgeMediaToolsOptions {
+    /** Which tool surface to mint. */
+    surface: 'composite' | 'granular';
+    /** Media-id resolution. Default: scan turn attachments + tool-call Media results. */
+    resolveMedia?: MediaResolverFn;
+    /** Optional pre-execution gate (see {@link ToolGateFn}). */
+    gate?: ToolGateFn;
+    /** Per-tool name/description overrides, keyed by the minted tool's default name. */
+    overrides?: Record<string, {
+        name?: string;
+        description?: string;
+    }>;
+}
+/**
+ * The default media resolver: scan `ctx.turnMessages[].attachments`, then
+ * `ctx.turnToolCalls[].results`, for a Media with the given id.
+ *
+ * @param ctx - The dispatch context.
+ * @param mediaId - The id to find.
+ * @returns The Media, or `undefined` when nothing in the turn carries that id.
+ */
+export declare const defaultResolveMedia: MediaResolverFn;
+/**
+ * Forge agent tools over a configured media pipeline.
+ *
+ * @remarks
+ * The minted set follows the pipeline's configured engines: in the composite surface the
+ * `media_query` grammar text only advertises available verbs; in the granular surface a tool
+ * is minted only for verbs whose engine (if any) is configured. Either way `list_media` is
+ * included — it is the model's entry point for discovering `media_id` values.
+ *
+ * The returned record is keyed by tool name so consumers can register selectively or pass
+ * `Object.values(tools)` to `TurnRunnerConfig.tools`.
+ *
+ * @param pipeline - A pipeline from `createMediaPipeline`.
+ * @param options - Surface, resolver, gate, and overrides.
+ * @returns The minted tools, keyed by name.
+ */
+export declare const forgeMediaTools: (pipeline: MediaPipeline, options: ForgeMediaToolsOptions) => Record<string, Tool>;
+/** Re-exported so consumers can fold verbs the same way the forge does. */
+export { foldVerb };