@nhtio/adk/batteries/media/forge

Agent glue: forge ADK tools from a media pipeline, so a model can drive local media work.

Remarks

The pipeline core (@nhtio/adk/batteries/media) is agent-agnostic; this module is the layer that knows the ADK loop. forgeMediaTools mints Tool instances over a configured @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 ToolGateFn runs before every execution — the seam for human-approval/RBAC flows built on ctx.waitFor (the ADK gates primitive).

Interfaces

Interface	Description
ForgeMediaToolsOptions	Options for forgeMediaTools.

Type Aliases

Type Alias	Description
MediaResolverFn	Resolves a media_id to a @nhtio/adk!Media visible in the current dispatch. The default implementation scans turn messages' attachments and prior tool-call results.
ToolGateFn	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.

Variables

Variable	Description
defaultResolveMedia	The default media resolver: scan ctx.turnMessages[].attachments, then ctx.turnToolCalls[].results, for a Media with the given id.

Functions

Function	Description
foldVerb	Fold a verb token sequence to canonical form: lowercase, separators (space/_/.) normalized so extract_text ≡ extract text ≡ extract.text all match extract.text.
forgeMediaTools	Forge agent tools over a configured media pipeline.