toolnexus 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./acp.js";
+export * from "./transcript_search.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./mcphandler.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./acp.js";
+export * from "./transcript_search.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./mcphandler.js";

package/dist/mcp.js

@@ -6,6 +6,7 @@
 import { readFileSync } from "node:fs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
 import { AdoptedStdioTransport } from "./mcp2026/stdio.js";
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { sanitize } from "./types.js";
@@ -398,8 +399,19 @@ function resourceTools(servers) {
  *  exists. Separated from connect so the caller ALWAYS holds a closeable reference — even if the
  *  connect is later abandoned by a timeout/abort, `client.close()` still terminates any spawned
  *  stdio child (no orphaned processes on cancellation). */
+/**
+ * The SDK's default validator, built on first use instead of per Client. Building an Ajv instance
+ * (meta-schemas + formats) costs ~2-3 ms on every connect, yet it is only consulted when a tool
+ * declares an `outputSchema`. Same validator, same results — just not paid for up front.
+ */
+class LazyAjvValidator {
+    inner;
+    getValidator(schema) {
+        return (this.inner ??= new AjvJsonSchemaValidator()).getValidator(schema);
+    }
+}
 function newMcpClient(waitFor) {
-    const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} });
+    const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {}, jsonSchemaValidator: new LazyAjvValidator() });
     if (waitFor) {
         client.setRequestHandler(ElicitRequestSchema, async (request) => answerToElicitResult(await waitFor(elicitationToRequest(request.params))));
     }

package/dist/media.d.ts

@@ -1,6 +1,132 @@
+import type { ContentPart } from "./content.js";
 import type { Tool } from "./types.js";
-export type MediaVerb = "image" | "video" | "speech" | "transcribe" | "cloneVoice" | "talking";
+export type MediaVerb = "image" | "video" | "speech" | "music" | "transcribe" | "cloneVoice" | "talk";
 export type MediaKind = "image" | "video" | "audio" | "text";
+export interface MediaVerbArg {
+    name: string;
+    type: string;
+    items?: string;
+    description: string;
+    required?: boolean;
+}
+export interface MediaVerbSpec {
+    verb: MediaVerb;
+    tool: string;
+    description: string;
+    args: MediaVerbArg[];
+}
+/** Canonical verbs — `conformance/media/verbs.json`, embedded verbatim (byte contract). */
+export declare const MEDIA_VERBS: MediaVerbSpec[];
+export interface MediaFile {
+    type: "image" | "audio" | "file";
+    mimeType: string;
+    /** `http(s)` URL, or `file://` + `path` for a local file. */
+    url?: string;
+    /** Absolute local path (download mode, or a CLI's own file in url mode). */
+    path?: string;
+    /** Standard padded base64 (inline mode). */
+    data?: string;
+}
+export type MediaResultStatus = "completed" | "failed" | "timeout" | "cancelled" | "unavailable" | (string & {});
+export interface MediaResult {
+    files: MediaFile[];
+    text?: string;
+    jobId?: string;
+    status: MediaResultStatus;
+    /** Provider-reported usage only, never estimated (§7G.12 D21). */
+    usage?: MediaUsage;
+    /** Who served the call: the preset id, the HTTP style's name (else "style"), or the client's name (§7G.10b). */
+    style?: string;
+    /** The configured model for the verb of a loaded style, when one was set; never guessed. */
+    model?: string;
+}
+/** §7G.12 D21: what the provider reported; absent fields are absent. */
+export interface MediaUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    raw?: Record<string, unknown>;
+}
+export interface MediaProgress {
+    verb: MediaVerb;
+    client: string;
+    jobId?: string;
+    status: string;
+    elapsedMs: number;
+}
+/** Per-call context (§7G.2). */
+export interface MediaContext {
+    signal?: AbortSignal;
+    /** Absolute deadline (epoch ms or Date); the job ends at the earlier of it and `loop.timeoutMs`. */
+    deadline?: number | Date;
+    /** Called for every progress status; when absent the client's `loop.onProgress` is used. */
+    progress?: (p: MediaProgress) => void;
+    /** Function face only: top-level keys overwrite the request body last. */
+    providerOptions?: Record<string, unknown>;
+}
+/** Per-call options of the typed verbs (`media.image({ prompt, signal })`). */
+export type MediaCallOptions = MediaContext;
+export interface MediaArgSpec {
+    name: string;
+    required: boolean;
+}
+/** Any media provider (§7G.2). Every verb is optional; `supports(verb)` is the truth. */
+export interface MediaClient {
+    readonly name: string;
+    supports(verb: MediaVerb | string): boolean;
+    /** Accepted canonical args; absent ⇒ every canonical arg of the verb, canonical required. */
+    args?(verb: MediaVerb | string): MediaArgSpec[];
+    image?(args: Record<string, unknown>, ctx: MediaContext): Promise<MediaResult>;
+    video?(args: Record<string, unknown>, ctx: MediaContext): Promise<MediaResult>;
+    speech?(args: Record<string, unknown>, ctx: MediaContext): Promise<MediaResult>;
+    music?(args: Record<string, unknown>, ctx: MediaContext): Promise<MediaResult>;
+    transcribe?(args: Record<string, unknown>, ctx: MediaContext): Promise<MediaResult>;
+    cloneVoice?(args: Record<string, unknown>, ctx: MediaContext): Promise<MediaResult>;
+    talk?(args: Record<string, unknown>, ctx: MediaContext): Promise<MediaResult>;
+}
+export type MediaErrorStatus = "failed" | "timeout" | "cancelled" | "unavailable";
+/** A failed media verb (§7G.2): message, status and the job id when known. */
+export declare class MediaError extends Error {
+    readonly status: MediaErrorStatus;
+    jobId?: string;
+    constructor(message: string, status?: MediaErrorStatus, jobId?: string);
+}
+/** The client cannot serve the call now (no credits, quota, no key, CLI missing, ZDR …). */
+export declare class MediaUnavailableError extends MediaError {
+    constructor(message: string, jobId?: string);
+}
+export type GatherMode = "url" | "download" | "inline";
+/** One config shape for every built-in client (§7G.4). */
+export interface MediaClientConfig {
+    /** Model of the client's primary verb (CLI clients: `-m <model>`). */
+    model?: string;
+    /** Per-verb model override; wins over `model` and the default. */
+    models?: Partial<Record<MediaVerb, string>>;
+    /** API key; default the client's env var, read at call time. Never logged. */
+    key?: string;
+    /** Base URL override (any compatible server). */
+    url?: string;
+    /** CLI argv prefix (a string is one executable, never shell-split). */
+    command?: string | string[];
+    loop?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        onProgress?: (p: MediaProgress) => void;
+    };
+    /**
+     * `name`, when set, names saved files `<name><ext>`, then `<name>-2<ext>`, … (first free name);
+     * sanitised to `[A-Za-z0-9._-]`, leading `.`/`-` dropped; empty ⇒ the default naming (§7G.10b).
+     */
+    gather?: {
+        mode?: GatherMode;
+        dir?: string;
+        maxBytes?: number;
+        keep?: boolean;
+        name?: string;
+    };
+    /** HTTP transport (the same seam as the LLM client's `fetch`). Omit ⇒ global fetch. */
+    fetch?: typeof fetch;
+}
 export interface MediaVerbStyle {
     mode: "sync" | "async";
     kind: MediaKind;
@@ -10,6 +136,7 @@ export interface MediaVerbStyle {
     };
     defaults?: Record<string, unknown>;
     args: Record<string, string>;
+    required?: string[];
     idPath?: string;
     poll?: {
         method?: string;
@@ -24,6 +151,7 @@ export interface MediaVerbStyle {
     resultPath: string;
 }
 export interface MediaStyle {
+    name?: string;
     baseUrl: string;
     headers?: Record<string, string>;
     errorEnvelope?: {
@@ -33,33 +161,313 @@ export interface MediaStyle {
     };
     verbs: Partial<Record<MediaVerb, MediaVerbStyle>>;
 }
-export interface MediaFile {
-    type: "image" | "audio" | "file";
+/** The a2e.ai preset — `examples/media-styles/a2e.json`, embedded verbatim. */
+export declare const A2E_STYLE: MediaStyle & {
+    _doc?: string;
+};
+/**
+ * Built-in CLI presets for {@link loadMediaStyle} (ADR 0042): media through a locally installed,
+ * logged-in CLI on the user's own subscription, no API key. The `*Mock` twins behave the same
+ * (name, verbs, args, prompt folding, errors) but never start a process and return a fixed file.
+ */
+export declare const MediaStyle: {
+    /** The `grok` CLI: image and video. */
+    readonly XaiGrokCli: "xai-grok-cli";
+    /** The `codex` CLI: image only. */
+    readonly OpenAICodexCli: "openai-codex-cli";
+    /** Google's Antigravity CLI `agy`: image only. */
+    readonly GoogleAgyCli: "google-agy-cli";
+    readonly XaiGrokCliMock: "xai-grok-cli-mock";
+    readonly OpenAICodexCliMock: "openai-codex-cli-mock";
+    readonly GoogleAgyCliMock: "google-agy-cli-mock";
+};
+/** A built-in CLI preset name. */
+export type MediaStylePreset = (typeof MediaStyle)[keyof typeof MediaStyle];
+/**
+ * A loaded style (§7G.7): an HTTP style file or a built-in CLI preset, configured and usable as a
+ * {@link MediaClient} anywhere one is accepted — `createMedia(loadMediaStyle("xai-grok-cli"))`.
+ */
+export declare class LoadedMediaStyle implements MediaClient {
+    readonly name: string;
+    /** The preset name, when this is a built-in CLI preset. */
+    readonly preset?: MediaStylePreset;
+    /** The parsed style, when this is an HTTP style. */
+    readonly style?: MediaStyle;
+    /** The config the style was loaded with. */
+    readonly config: MediaClientConfig;
+    private readonly client;
+    constructor(source: MediaStyle | MediaStylePreset, config?: MediaClientConfig);
+    supports(verb: MediaVerb | string): boolean;
+    /** Who serves calls: the preset id, else the HTTP style's name, else "style" (§7G.10b). */
+    get id(): string;
+    /**
+     * Can this style run? Cheap and side-effect free (§7G.10b): a CLI preset's command is found and
+     * its own login file exists (never read); an HTTP style's config key or header `${VAR}`s are set.
+     */
+    available(): MediaAvailability;
+    args(verb: MediaVerb | string): MediaArgSpec[];
+    private call;
+    image(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    video(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    speech(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    music(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    transcribe(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    cloneVoice(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    talk(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+}
+/** The cheap pre-flight answer of {@link LoadedMediaStyle.available} (§7G.10b). */
+export interface MediaAvailability {
+    installed: boolean;
+    loggedIn: boolean;
+    reason: string;
+}
+/** Set to "0", every mock preset reports unavailable. */
+export declare const MEDIA_MOCK_AVAILABLE_ENV = "TOOLNEXUS_MEDIA_MOCK_AVAILABLE";
+/**
+ * Load a style: a built-in CLI preset ({@link MediaStyle}`.XaiGrokCli`, …) or a style JSON file
+ * (throws the §7G.7 style errors). `config` configures the client behind it (model, command, loop, gather).
+ */
+export declare function loadMediaStyle(pathOrPreset: MediaStylePreset | string, config?: MediaClientConfig): LoadedMediaStyle;
+interface HttpRes {
+    status: number;
+    headers: Headers;
+    bytes: Uint8Array;
+    over: boolean;
+}
+interface SendOpts {
+    json?: unknown;
+    body?: Uint8Array;
+    contentType?: string;
+    /** false ⇒ never send client headers (downloads, input fetches). */
+    auth?: boolean;
+    /** Stop reading the body at limit + 1 bytes. */
+    limit?: number;
+}
+/** One job's HTTP: redirects by hand, the origin header rule, the per-request deadline. */
+declare class HttpJob {
+    readonly client: string;
+    readonly verb: string;
+    private readonly headers;
+    private readonly doFetch;
+    readonly timeoutMs: number;
+    readonly deadline: number;
+    readonly signal?: AbortSignal | undefined;
+    jobId?: string;
+    private readonly origin;
+    constructor(client: string, verb: string, baseUrl: string, headers: () => Record<string, string>, doFetch: typeof fetch, timeoutMs: number, deadline: number, signal?: AbortSignal | undefined);
+    timedOut(): MediaError;
+    send(url: string, method: string, opts?: SendOpts): Promise<HttpRes>;
+    /** A provider API call: unavailable mapping, then any other non-2xx is `HTTP <s>: <body>`. */
+    api(method: string, url: string, opts?: SendOpts): Promise<HttpRes>;
+    json(method: string, url: string, opts?: SendOpts): Promise<{
+        data: any;
+        res: HttpRes;
+    }>;
+    /** §7G.5 download: GET, no client headers, capped at maxBytes. */
+    download(url: string, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        contentType?: string;
+    }>;
+}
+type RawResult = {
+    bytes: Uint8Array;
+    mimeType: string;
+} | {
+    base64: string;
     mimeType: string;
+} | {
+    dataUrl: string;
+} | {
     url: string;
+} | {
+    path: string;
+};
+interface GatherCfg {
+    mode: GatherMode;
+    dir: string;
+    maxBytes: number;
+    keep: boolean;
+    slug: string;
 }
-export interface MediaResult {
-    files: MediaFile[];
-    text?: string;
-    jobId?: string;
-    status: string;
+declare class Gatherer {
+    readonly cfg: GatherCfg;
+    readonly client: string;
+    readonly verb: string;
+    readonly kind: MediaKind;
+    readonly job?: HttpJob | undefined;
+    constructor(cfg: GatherCfg, client: string, verb: string, kind: MediaKind, job?: HttpJob | undefined);
+    private tooBig;
+    private keepBytes;
+    private target;
+    one(raw: RawResult): Promise<MediaFile>;
+    all(raws: RawResult[]): Promise<MediaFile[]>;
 }
-export interface MediaProgress {
+interface CallEnv {
+    started: number;
+    deadline: number;
+    timeoutMs: number;
+    report: (status: string, jobId?: string) => void;
+}
+interface StyleInternals {
+    keyEnv?: string;
+    gatherMode?: GatherMode;
+}
+/** A media client over one JSON style (the ADR 0036 engine). Named `style.name ?? "style"`. */
+export declare class StyleMediaClient implements MediaClient {
+    readonly name: string;
+    protected readonly style: MediaStyle;
+    protected readonly config: MediaClientConfig;
+    private readonly internals;
+    constructor(style: MediaStyle, config?: MediaClientConfig, internals?: StyleInternals);
+    supports(verb: string): boolean;
+    args(verb: string): MediaArgSpec[];
+    image(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    video(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    speech(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    music(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    transcribe(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    cloneVoice(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    talk(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    /** Hook for subclasses: the request body's defaults for a verb. */
+    protected defaults(_verb: MediaVerb, spec: MediaVerbStyle): Record<string, unknown>;
+    protected baseUrl(): string;
+    private run;
+}
+/** Make a media client from a parsed style (§7G.7). */
+export declare function styleMediaClient(style: MediaStyle | LoadedMediaStyle, config?: MediaClientConfig): StyleMediaClient;
+/** a2e.ai (§7G.9): a style client over the embedded preset, `A2E_API_KEY`, gather `download`. */
+export declare class A2EMediaClient extends StyleMediaClient {
+    constructor(config?: MediaClientConfig);
+    protected defaults(verb: MediaVerb, spec: MediaVerbStyle): Record<string, unknown>;
+}
+interface ApiDef {
+    name: string;
+    keyEnv: string;
+    defaultUrl: string;
+    auth: (key: string) => Record<string, string>;
+    primary: MediaVerb;
+    interval: number;
+    verbs: Partial<Record<MediaVerb, MediaArgSpec[]>>;
+}
+interface ApiCall {
     verb: MediaVerb;
-    jobId: string;
-    status: string;
+    base: string;
+    job: HttpJob;
+    env: CallEnv;
+    gather: Gatherer;
+    interval: number;
+    maxBytes: number;
 }
-export interface MediaOptions {
-    onProgress?: (p: MediaProgress) => void;
-    /** HTTP transport (same seam as the LLM client's `fetch`). Omit ⇒ global fetch. */
-    fetch?: typeof fetch;
+/** The shared HTTP base for code-defined API clients (§7G.8 rules, gather, unavailable). */
+export declare abstract class ApiMediaClient implements MediaClient {
+    readonly name: string;
+    protected readonly config: MediaClientConfig;
+    private readonly def;
+    protected constructor(def: ApiDef, config?: MediaClientConfig);
+    supports(verb: string): boolean;
+    args(verb: string): MediaArgSpec[];
+    /** The model for a verb: `models[verb]`, else `model` for the primary verb, else the default. */
+    protected model(verb: MediaVerb, dflt: string): string;
+    protected begin(verb: MediaVerb, ctx: MediaContext): ApiCall;
+    /** Poll until `check` says done; `check` returns the status text and an optional failure. */
+    protected pollUntil(c: ApiCall, ctx: MediaContext, check: () => Promise<{
+        status: string;
+        done: boolean;
+        error?: string;
+    }>): Promise<void>;
+    protected run(c: ApiCall, fn: () => Promise<MediaResult>): Promise<MediaResult>;
 }
-/** Per-call options of the function face. */
-export interface MediaCallOptions {
-    /** Top-level keys overwrite the request body last. Never exposed on the tool face. */
-    providerOptions?: Record<string, unknown>;
-    signal?: AbortSignal;
+/** ElevenLabs (§7G.9): speech (live-verified), music, transcribe, cloneVoice. */
+export declare class ElevenLabsMediaClient extends ApiMediaClient {
+    constructor(config?: MediaClientConfig);
+    speech(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    music(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    transcribe(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    cloneVoice(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+}
+/** OpenAI (§7G.9): image (live-verified), video, speech, transcribe; `url` ⇒ any compatible server. */
+export declare class OpenAIMediaClient extends ApiMediaClient {
+    constructor(config?: MediaClientConfig);
+    image(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    speech(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    transcribe(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    video(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+}
+/** OpenRouter (§7G.9): image through chat completions (live-verified). */
+export declare class OpenRouterMediaClient extends ApiMediaClient {
+    constructor(config?: MediaClientConfig);
+    image(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+}
+/** fal (§7G.9): the queue API for any hosted model id — image (live-verified), video. */
+export declare class FalMediaClient extends ApiMediaClient {
+    constructor(config?: MediaClientConfig);
+    image(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    video(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    private queue;
+}
+/** What one JSON line of a CLI's stdout means. */
+export interface CliEvent {
+    session?: string;
+    text?: string;
+    paths?: string[];
+    error?: string;
+    status?: string;
+    /** Provider-reported usage (§7G.12 D21). */
+    usage?: MediaUsage;
 }
+/** How a {@link CliMediaClient} drives one CLI. */
+export interface CliSpec {
+    name: string;
+    /** Default argv prefix when `config.command` is absent. */
+    command: string;
+    /** Prompt template per supported verb; `{prompt}` is replaced. */
+    templates: Partial<Record<MediaVerb, string>>;
+    /** Client argv after the command, for one run. */
+    argv(prompt: string, cwd: string, model?: string): string[];
+    /** Fixed env added to the process env. */
+    env?: Record<string, string>;
+    parse(obj: Record<string, unknown>, line: string): CliEvent;
+    /** A folder whose entries are candidate files once the session is known. */
+    folder?(session: string): string | undefined;
+    /** An unavailable message for the last error, or undefined (⇒ failed). */
+    unavailable?(error: string, verb: MediaVerb): string | undefined;
+}
+/** Runs a local subscription CLI once, headless, and collects the files it made (§7G.10). */
+export declare class CliMediaClient implements MediaClient {
+    readonly name: string;
+    protected readonly config: MediaClientConfig;
+    private readonly spec;
+    /** Never start the CLI; write a fixed file instead (§7G CLI mock presets). */
+    private readonly mock;
+    constructor(spec: CliSpec, config?: MediaClientConfig, opts?: {
+        mock?: boolean;
+    });
+    supports(verb: string): boolean;
+    args(verb: string): MediaArgSpec[];
+    image(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    video(args: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    private run;
+    /**
+     * The CLI mock (§7G CLI mock presets): no process. Writes `<gather.dir>/<client>-mock-<verb>.<png|mp4>`
+     * (gather.dir default `<tmp>/toolnexus-media`) holding `toolnexus mock <verb>` and gathers it like a
+     * real CLI file; text = the exact prompt the CLI would have received; jobId "mock".
+     */
+    private mockRun;
+}
+/**
+ * The prompt a CLI style receives (§7G CLI hint folding): `prompt`, then the present size hints in
+ * canonical verb order as ` (h1, h2)`; nothing appended when none is present.
+ */
+export declare function foldMediaPrompt(verb: MediaVerb | string, args: Record<string, unknown>): string;
+/** Grok CLI (§7G.10): image, video via `grok -p … --output-format streaming-json`. */
+export declare class GrokMediaClient extends CliMediaClient {
+    constructor(config?: MediaClientConfig);
+}
+/** Codex CLI (§7G.10): image via `codex exec --json` (ChatGPT plan). */
+export declare class CodexMediaClient extends CliMediaClient {
+    constructor(config?: MediaClientConfig);
+}
+type VerbInput<T> = T & MediaCallOptions;
 export type ImageArgs = {
     prompt: string;
     width?: number;
@@ -77,50 +485,53 @@ export type SpeechArgs = {
     text: string;
     voice?: string;
 };
+export type MusicArgs = {
+    prompt: string;
+    seconds?: number;
+    instrumental?: boolean;
+    lyrics?: string;
+};
 export type TranscribeArgs = {
     audio: string;
+    language?: string;
 };
 export type CloneVoiceArgs = {
     name: string;
     samples: string[];
 };
-export type TalkingArgs = {
+export type TalkArgs = {
     image: string;
-    audio: string;
+    audio?: string;
+    text?: string;
+    voice?: string;
 };
-export interface MediaVerbArg {
-    name: string;
-    type: string;
-    items?: string;
-    description: string;
-    required?: boolean;
-}
-export interface MediaVerbSpec {
-    verb: MediaVerb;
-    tool: string;
-    description: string;
-    args: MediaVerbArg[];
-}
-/** Canonical verbs — `conformance/media/verbs.json`, embedded verbatim (byte contract). */
-export declare const MEDIA_VERBS: MediaVerbSpec[];
-/** Read one style file (JSON). */
-export declare function loadMediaStyle(path: string): MediaStyle;
+/** The seven verbs over an ordered list of clients; falls through only on `unavailable`. */
 export declare class Media {
-    private readonly opts;
-    private readonly styles;
-    constructor(styles: MediaStyle | MediaStyle[], opts?: MediaOptions);
-    private resolve;
-    /** Generic entry point: run `verb` with normalised `args` (§7G engine). */
-    generate(verb: MediaVerb | string, args: Record<string, unknown>, callOpts?: MediaCallOptions): Promise<MediaResult>;
+    readonly clients: MediaClient[];
+    constructor(clients: MediaClient | MediaClient[]);
+    supports(verb: MediaVerb | string): boolean;
+    /** Every verb some source supports, in canonical verb order. */
+    verbs(): MediaVerb[];
+    /** "style" when every source is a loaded style, else "client". */
+    private noun;
+    /** Generic entry point: route `verb` with canonical `args`. */
+    generate(verb: MediaVerb | string, args?: Record<string, unknown>, ctx?: MediaContext): Promise<MediaResult>;
+    private route;
     private typed;
-    image(input: ImageArgs & MediaCallOptions): Promise<MediaResult>;
-    video(input: VideoArgs & MediaCallOptions): Promise<MediaResult>;
-    speech(input: SpeechArgs & MediaCallOptions): Promise<MediaResult>;
-    transcribe(input: TranscribeArgs & MediaCallOptions): Promise<MediaResult>;
-    cloneVoice(input: CloneVoiceArgs & MediaCallOptions): Promise<MediaResult>;
-    talking(input: TalkingArgs & MediaCallOptions): Promise<MediaResult>;
-    /** One Tool (source "media") per supported verb, in canonical order (§7G tool face). */
+    image(input: VerbInput<ImageArgs>): Promise<MediaResult>;
+    video(input: VerbInput<VideoArgs>): Promise<MediaResult>;
+    speech(input: VerbInput<SpeechArgs>): Promise<MediaResult>;
+    music(input: VerbInput<MusicArgs>): Promise<MediaResult>;
+    transcribe(input: VerbInput<TranscribeArgs>): Promise<MediaResult>;
+    cloneVoice(input: VerbInput<CloneVoiceArgs>): Promise<MediaResult>;
+    talk(input: VerbInput<TalkArgs>): Promise<MediaResult>;
+    /** One Tool (source "media") per verb any client supports, in `verbs.json` order (§7G.6). */
     tools(): Tool[];
 }
-/** Build a media engine over one style or a list (first style declaring a verb wins). */
-export declare function createMedia(styles: MediaStyle | MediaStyle[], opts?: MediaOptions): Media;
+/** The saved file's absolute path for a part a media tool produced, if it has one (D20). */
+export declare function mediaPartPath(part: ContentPart): string | undefined;
+/** Route the seven verbs over one client or an ordered list (§7G.3). */
+export declare function createMedia(clients: MediaClient | MediaClient[]): Media;
+/** One-shot sugar: `createMedia(loadMediaStyle(style, config)).generate(verb, args)`. */
+export declare function generateMedia(style: MediaStylePreset | string, verb: MediaVerb | string, args?: Record<string, unknown>, config?: MediaClientConfig): Promise<MediaResult>;
+export {};