toolnexus 0.23.0 → 0.24.0

package/dist/media.js

@@ -0,0 +1,540 @@
+/**
+ * Media generation (SPEC §7G, ADR 0036) — one engine, two faces: typed verbs a host calls and
+ * tools (source "media") an LLM calls. Providers are styles: JSON data, never code.
+ */
+import { readFileSync } from "node:fs";
+/** Canonical verbs — `conformance/media/verbs.json`, embedded verbatim (byte contract). */
+export const MEDIA_VERBS = [
+    {
+        "verb": "image",
+        "tool": "generate_image",
+        "description": "Generate an image from a text prompt.",
+        "args": [
+            {
+                "name": "prompt",
+                "type": "string",
+                "description": "What to draw.",
+                "required": true
+            },
+            {
+                "name": "width",
+                "type": "integer",
+                "description": "Width in pixels."
+            },
+            {
+                "name": "height",
+                "type": "integer",
+                "description": "Height in pixels."
+            },
+            {
+                "name": "aspectRatio",
+                "type": "string",
+                "description": "Aspect ratio, e.g. 16:9."
+            },
+            {
+                "name": "seed",
+                "type": "integer",
+                "description": "Seed for reproducible output."
+            }
+        ]
+    },
+    {
+        "verb": "video",
+        "tool": "generate_video",
+        "description": "Generate a short video from a prompt, optionally starting from an image URL. Can take minutes.",
+        "args": [
+            {
+                "name": "prompt",
+                "type": "string",
+                "description": "What should happen in the video.",
+                "required": true
+            },
+            {
+                "name": "image",
+                "type": "string",
+                "description": "URL of the starting image."
+            },
+            {
+                "name": "seconds",
+                "type": "integer",
+                "description": "Video length in seconds."
+            },
+            {
+                "name": "aspectRatio",
+                "type": "string",
+                "description": "Aspect ratio, e.g. 9:16."
+            }
+        ]
+    },
+    {
+        "verb": "speech",
+        "tool": "generate_speech",
+        "description": "Speak text aloud and return the audio.",
+        "args": [
+            {
+                "name": "text",
+                "type": "string",
+                "description": "The text to speak.",
+                "required": true
+            },
+            {
+                "name": "voice",
+                "type": "string",
+                "description": "Voice or speaker id."
+            }
+        ]
+    },
+    {
+        "verb": "transcribe",
+        "tool": "transcribe_audio",
+        "description": "Transcribe speech in an audio URL to text.",
+        "args": [
+            {
+                "name": "audio",
+                "type": "string",
+                "description": "URL of the audio.",
+                "required": true
+            }
+        ]
+    },
+    {
+        "verb": "cloneVoice",
+        "tool": "clone_voice",
+        "description": "Create a cloned voice from audio sample URLs and return its voice id.",
+        "args": [
+            {
+                "name": "name",
+                "type": "string",
+                "description": "Name for the new voice.",
+                "required": true
+            },
+            {
+                "name": "samples",
+                "type": "array",
+                "items": "string",
+                "description": "URLs of audio samples of the voice.",
+                "required": true
+            }
+        ]
+    },
+    {
+        "verb": "talking",
+        "tool": "talking_video",
+        "description": "Make the person in an image speak the given audio (lip-synced video).",
+        "args": [
+            {
+                "name": "image",
+                "type": "string",
+                "description": "URL of the face image.",
+                "required": true
+            },
+            {
+                "name": "audio",
+                "type": "string",
+                "description": "URL of the speech audio.",
+                "required": true
+            }
+        ]
+    }
+];
+/** Read one style file (JSON). */
+export function loadMediaStyle(path) {
+    const style = JSON.parse(readFileSync(path, "utf8"));
+    validateStyle(style);
+    return style;
+}
+/** §7G Empty dotPath: an args entry mapped to "" is a style error (sorted, so deterministic). */
+function validateStyle(style) {
+    for (const verb of Object.keys(style.verbs ?? {}).sort()) {
+        const args = style.verbs[verb]?.args ?? {};
+        for (const key of Object.keys(args).sort()) {
+            if (args[key] === "")
+                throw new Error(`style: empty path for argument "${key}"`);
+        }
+    }
+}
+// ---- dotPath ---------------------------------------------------------------------------------
+const isIndex = (seg) => /^[0-9]+$/.test(seg);
+function readPath(obj, path) {
+    if (path === "")
+        return obj; // §7G: empty dotPath is the whole value
+    let cur = obj;
+    for (const seg of path.split(".")) {
+        if (cur === null || cur === undefined || typeof cur !== "object")
+            return undefined;
+        if (Array.isArray(cur)) {
+            if (!isIndex(seg))
+                return undefined;
+            cur = cur[Number(seg)];
+        }
+        else {
+            if (!Object.prototype.hasOwnProperty.call(cur, seg))
+                return undefined;
+            cur = cur[seg];
+        }
+    }
+    return cur;
+}
+function writePath(obj, path, value) {
+    const segs = path.split(".");
+    let cur = obj;
+    for (let i = 0; i < segs.length; i++) {
+        const seg = segs[i];
+        const key = Array.isArray(cur) && isIndex(seg) ? Number(seg) : seg;
+        if (Array.isArray(cur) && typeof key === "number")
+            while (cur.length < key)
+                cur.push(null);
+        if (i === segs.length - 1) {
+            cur[key] = value;
+            return;
+        }
+        let next = cur[key];
+        // A scalar — or an array followed by a non-numeric segment — is replaced (§7G).
+        if (next === null || next === undefined || typeof next !== "object" || (Array.isArray(next) && !isIndex(segs[i + 1]))) {
+            next = isIndex(segs[i + 1]) ? [] : {};
+            cur[key] = next;
+        }
+        cur = next;
+    }
+}
+// ---- helpers ---------------------------------------------------------------------------------
+function expandEnv(v) {
+    return v.replace(/\$\{([A-Za-z0-9_]+)\}/g, (_, name) => process.env[name] ?? "");
+}
+const MIME = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif",
+    mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime",
+    mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", m4a: "audio/mp4", flac: "audio/flac",
+};
+const KIND_DEFAULT_MIME = { image: "image/png", video: "video/mp4", audio: "audio/mpeg" };
+const KIND_FILE_TYPE = { image: "image", audio: "audio", video: "file" };
+function mimeFor(url, kind) {
+    let path = url.split("#")[0].split("?")[0];
+    const scheme = path.indexOf("://");
+    if (scheme >= 0) {
+        const slash = path.indexOf("/", scheme + 3);
+        path = slash >= 0 ? path.slice(slash) : "";
+    }
+    const last = path.slice(path.lastIndexOf("/") + 1);
+    const dot = last.lastIndexOf(".");
+    const ext = dot >= 0 ? last.slice(dot + 1).toLowerCase() : "";
+    return MIME[ext] ?? KIND_DEFAULT_MIME[kind];
+}
+function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        const bb = b;
+        return a.length === bb.length && a.every((x, i) => jsonEqual(x, bb[i]));
+    }
+    const ka = Object.keys(a), kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => jsonEqual(a[k], b[k]));
+}
+function renderScalar(v) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" && Number.isInteger(v))
+        return String(v);
+    return JSON.stringify(v);
+}
+/** Poll status text (§7G): string as-is, numbers like the envelope code, anything else "". */
+function statusText(v) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    return "";
+}
+/** RFC 3986: keep unreserved A-Z a-z 0-9 - . _ ~, %XX (uppercase) every other UTF-8 byte. */
+function percentEncode(s) {
+    return encodeURIComponent(s).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+}
+/** §7G Redirects: the followed statuses; anything else (or no Location) is an HTTP error. */
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+class TooManyRedirects extends Error {
+}
+/** Echoed error bodies keep their first 1000 code points, then "…" (§7G). */
+function capBody(text) {
+    const cps = Array.from(text);
+    return cps.length <= 1000 ? text : cps.slice(0, 1000).join("") + "\u2026";
+}
+/** §7G: an interval/timeout that is absent, not a number or <= 0 takes the default. */
+const positive = (v, dflt) => (typeof v === "number" && v > 0 ? v : dflt);
+const originOf = (u) => new URL(u).origin;
+function abortError(signal) {
+    return signal.reason ?? Object.assign(new Error("The operation was aborted"), { name: "AbortError" });
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(abortError(signal));
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(abortError(signal));
+        };
+        const t = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function flattenStrings(v, out) {
+    if (typeof v === "string") {
+        if (v !== "")
+            out.push(v);
+    }
+    else if (Array.isArray(v)) {
+        for (const x of v)
+            flattenStrings(x, out);
+    }
+}
+// ---- engine ----------------------------------------------------------------------------------
+export class Media {
+    opts;
+    styles;
+    constructor(styles, opts = {}) {
+        this.opts = opts;
+        this.styles = Array.isArray(styles) ? styles : [styles];
+        for (const s of this.styles)
+            validateStyle(s);
+    }
+    resolve(verb) {
+        for (const style of this.styles) {
+            const spec = style.verbs[verb];
+            if (spec)
+                return { style, spec };
+        }
+        return undefined;
+    }
+    /** Generic entry point: run `verb` with normalised `args` (§7G engine). */
+    async generate(verb, args, callOpts = {}) {
+        const resolved = this.resolve(verb);
+        if (!resolved)
+            throw new Error(`media: no style supports "${verb}"`);
+        const { style, spec } = resolved;
+        const present = Object.entries(args ?? {}).filter(([, v]) => v !== undefined && v !== null);
+        for (const key of present.map(([k]) => k).sort()) {
+            if (!Object.prototype.hasOwnProperty.call(spec.args, key)) {
+                throw new Error(`${verb}: argument "${key}" not supported by this style`);
+            }
+        }
+        const body = spec.defaults ? structuredClone(spec.defaults) : {};
+        for (const [key, value] of present)
+            writePath(body, spec.args[key], value);
+        for (const [k, v] of Object.entries(callOpts.providerOptions ?? {}))
+            body[k] = v;
+        const base = style.baseUrl.replace(/\/+$/, "");
+        const signal = callOpts.signal;
+        const styleHeaders = () => {
+            const h = {};
+            for (const [k, v] of Object.entries(style.headers ?? {}))
+                h[k] = expandEnv(v);
+            return h;
+        };
+        const doFetch = this.opts.fetch ?? fetch;
+        // Every request is bounded by the time left until the job deadline (§7G Per-request timeout).
+        const timeout = positive(spec.poll?.timeoutMs, 600000);
+        const deadline = Date.now() + timeout;
+        let jobId;
+        const timedOut = () => new Error(jobId !== undefined ? `job ${jobId} timed out after ${timeout}ms` : `${verb}: timed out after ${timeout}ms`);
+        // Redirects are followed by hand so style headers never reach another origin (§7G Redirects).
+        const send = async (url, method, json, reqSignal) => {
+            const origin = originOf(url);
+            let body = json !== undefined ? JSON.stringify(json) : undefined;
+            for (let hops = 0;; hops++) {
+                const sameOrigin = originOf(url) === origin;
+                const headers = { ...(body !== undefined ? { "Content-Type": "application/json" } : {}), ...(sameOrigin ? styleHeaders() : {}) };
+                const res = await doFetch(url, { method, headers, body, signal: reqSignal, redirect: "manual" });
+                const loc = res.headers?.get?.("location");
+                if (!REDIRECTS.has(res.status) || !loc)
+                    return res;
+                await res.body?.cancel().catch(() => { });
+                if (hops >= 10)
+                    throw new TooManyRedirects();
+                url = new URL(loc, url).toString();
+                if (res.status <= 303 && method !== "GET" && method !== "HEAD") {
+                    method = "GET";
+                    body = undefined;
+                }
+            }
+        };
+        const call = async (method, path, json) => {
+            if (signal?.aborted)
+                throw abortError(signal);
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw timedOut();
+            const ctl = new AbortController();
+            const timer = setTimeout(() => ctl.abort(), remaining);
+            const forward = () => ctl.abort();
+            signal?.addEventListener("abort", forward, { once: true });
+            let res, text;
+            try {
+                res = await send(base + path, method, json, ctl.signal);
+                text = await res.text();
+            }
+            catch (e) {
+                if (signal?.aborted)
+                    throw abortError(signal);
+                if (ctl.signal.aborted)
+                    throw timedOut();
+                if (e instanceof TooManyRedirects)
+                    throw new Error(`${verb}: too many redirects`);
+                throw new Error(`${verb}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            finally {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", forward);
+            }
+            if (res.status < 200 || res.status > 299)
+                throw new Error(`HTTP ${res.status}: ${capBody(text)}`);
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`${verb}: response is not JSON`);
+            }
+            const env = style.errorEnvelope;
+            if (env) {
+                const code = readPath(data, env.codePath);
+                if (code !== undefined && !env.okValues.some((ok) => jsonEqual(ok, code))) {
+                    const msg = env.messagePath ? readPath(data, env.messagePath) : undefined;
+                    throw new Error(`API error ${renderScalar(code)}: ${typeof msg === "string" ? msg : ""}`);
+                }
+            }
+            return data;
+        };
+        let final;
+        let status = "completed";
+        const startResp = await call((spec.start.method ?? "POST").toUpperCase(), spec.start.path, body);
+        if (spec.mode === "async") {
+            const poll = spec.poll;
+            const idPath = spec.idPath ?? "";
+            const rawId = readPath(startResp, idPath);
+            if (typeof rawId === "string" && rawId !== "")
+                jobId = rawId;
+            else if (typeof rawId === "number" && Number.isInteger(rawId))
+                jobId = String(rawId);
+            else
+                throw new Error(`${verb}: no job id at ${idPath}`);
+            const interval = positive(poll.intervalMs, 5000);
+            const pollPath = poll.path.split("{id}").join(percentEncode(jobId));
+            for (;;) {
+                await sleep(interval, signal);
+                const resp = await call((poll.method ?? "GET").toUpperCase(), pollPath);
+                const s = statusText(readPath(resp, poll.statusPath));
+                this.opts.onProgress?.({ verb: verb, jobId, status: s });
+                if ((poll.done ?? []).includes(s)) {
+                    final = resp;
+                    status = s;
+                    break;
+                }
+                if ((poll.failed ?? []).includes(s)) {
+                    const m = poll.errorPath ? readPath(resp, poll.errorPath) : undefined;
+                    throw new Error(typeof m === "string" && m !== "" ? `job ${jobId} ${s}: ${m}` : `job ${jobId} ${s}`);
+                }
+                if (Date.now() >= deadline)
+                    throw timedOut();
+            }
+        }
+        else {
+            final = startResp;
+        }
+        const value = readPath(final, spec.resultPath);
+        const result = { files: [], status };
+        if (spec.kind === "text") {
+            if (typeof value === "string")
+                result.text = value;
+            else if (typeof value === "number")
+                result.text = renderScalar(value);
+            else
+                throw new Error(`${verb}: no result at ${spec.resultPath}`);
+        }
+        else {
+            const urls = [];
+            flattenStrings(value, urls);
+            if (urls.length === 0)
+                throw new Error(`${verb}: no result at ${spec.resultPath}`);
+            result.files = urls.map((url) => ({ type: KIND_FILE_TYPE[spec.kind], mimeType: mimeFor(url, spec.kind), url }));
+        }
+        if (jobId !== undefined)
+            result.jobId = jobId;
+        return result;
+    }
+    typed(verb, input) {
+        const { providerOptions, signal, ...args } = input;
+        return this.generate(verb, args, { providerOptions, signal });
+    }
+    image(input) {
+        return this.typed("image", input);
+    }
+    video(input) {
+        return this.typed("video", input);
+    }
+    speech(input) {
+        return this.typed("speech", input);
+    }
+    transcribe(input) {
+        return this.typed("transcribe", input);
+    }
+    cloneVoice(input) {
+        return this.typed("cloneVoice", input);
+    }
+    talking(input) {
+        return this.typed("talking", input);
+    }
+    /** One Tool (source "media") per supported verb, in canonical order (§7G tool face). */
+    tools() {
+        const out = [];
+        for (const v of MEDIA_VERBS) {
+            const resolved = this.resolve(v.verb);
+            if (!resolved)
+                continue;
+            const mapped = v.args.filter((a) => Object.prototype.hasOwnProperty.call(resolved.spec.args, a.name));
+            const properties = {};
+            for (const a of mapped) {
+                properties[a.name] = a.type === "array"
+                    ? { type: "array", items: { type: a.items }, description: a.description }
+                    : { type: a.type, description: a.description };
+            }
+            const inputSchema = { type: "object", properties, required: mapped.filter((a) => a.required).map((a) => a.name) };
+            const kind = resolved.spec.kind;
+            const mode = resolved.spec.mode;
+            out.push({
+                name: v.tool,
+                description: v.description,
+                inputSchema,
+                source: "media",
+                // Each call is an independent remote job: always concurrency-safe (§7G, §8 Tool scheduling).
+                concurrencySafe: () => true,
+                execute: async (args, ctx) => {
+                    try {
+                        const r = await this.generate(v.verb, args ?? {}, { signal: ctx?.signal });
+                        const metadata = { source: "media", verb: v.verb };
+                        if (mode === "async" && r.jobId !== undefined)
+                            metadata.jobId = r.jobId;
+                        metadata.status = r.status;
+                        if (kind === "text")
+                            return { isError: false, output: r.text ?? "", metadata };
+                        const parts = r.files.map((f) => ({ type: f.type, mimeType: f.mimeType, url: f.url }));
+                        return { isError: false, output: `${kind} ready: ` + r.files.map((f) => f.url).join("\n"), parts, metadata };
+                    }
+                    catch (e) {
+                        return { isError: true, output: e instanceof Error ? e.message : String(e) };
+                    }
+                },
+            });
+        }
+        return out;
+    }
+}
+/** Build a media engine over one style or a list (first style declaring a verb wins). */
+export function createMedia(styles, opts = {}) {
+    return new Media(styles, opts);
+}

package/dist/toolconcurrency.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool scheduling (SPEC §8 "Tool scheduling"): the calls of one model response run in emitted
+ * order as consecutive runs — safe calls overlap under a cap, each unsafe call runs alone.
+ */
+import type { Tool } from "./types.js";
+/** The cap when neither the option nor TOOLNEXUS_MAX_TOOL_CONCURRENCY sets one. */
+export declare const DEFAULT_MAX_TOOL_CONCURRENCY = 10;
+/** option > env TOOLNEXUS_MAX_TOOL_CONCURRENCY > 10. Non-positive or non-numeric values fall back. */
+export declare function resolveMaxToolConcurrency(option?: number): number;
+/** Whether a call to `tool` with `args` may run alongside other safe calls. The tool's own
+ * predicate wins; otherwise only a tool whose hints say readOnly is safe. */
+export declare function isConcurrencySafe(tool: Tool, args: Record<string, unknown>): boolean;
+/** Runs `fn` over `items` in emitted order: safe items overlap (at most `cap`), an unsafe item
+ * waits for everything before it and runs alone. Results keep item order. The first failure
+ * stops new items from starting and is rethrown once the running ones settle. */
+export declare function scheduleCalls<T, R>(items: T[], safe: (item: T) => boolean, cap: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/dist/toolconcurrency.js

@@ -0,0 +1,59 @@
+/** The cap when neither the option nor TOOLNEXUS_MAX_TOOL_CONCURRENCY sets one. */
+export const DEFAULT_MAX_TOOL_CONCURRENCY = 10;
+/** option > env TOOLNEXUS_MAX_TOOL_CONCURRENCY > 10. Non-positive or non-numeric values fall back. */
+export function resolveMaxToolConcurrency(option) {
+    if (typeof option === "number" && Number.isInteger(option) && option > 0)
+        return option;
+    const raw = typeof process !== "undefined" ? process.env.TOOLNEXUS_MAX_TOOL_CONCURRENCY : undefined;
+    if (raw !== undefined && /^\s*[+]?\d+\s*$/.test(raw)) {
+        const n = Number.parseInt(raw, 10);
+        if (n > 0)
+            return n;
+    }
+    return DEFAULT_MAX_TOOL_CONCURRENCY;
+}
+/** Whether a call to `tool` with `args` may run alongside other safe calls. The tool's own
+ * predicate wins; otherwise only a tool whose hints say readOnly is safe. */
+export function isConcurrencySafe(tool, args) {
+    if (tool.concurrencySafe)
+        return tool.concurrencySafe(args);
+    return tool.hints?.readOnly === true;
+}
+/** Runs `fn` over `items` in emitted order: safe items overlap (at most `cap`), an unsafe item
+ * waits for everything before it and runs alone. Results keep item order. The first failure
+ * stops new items from starting and is rethrown once the running ones settle. */
+export async function scheduleCalls(items, safe, cap, fn) {
+    const out = new Array(items.length);
+    const running = new Set();
+    let failed;
+    for (let i = 0; i < items.length && !failed; i++) {
+        const item = items[i];
+        if (!safe(item)) {
+            await Promise.all(running);
+            if (failed)
+                break;
+            try {
+                out[i] = await fn(item);
+            }
+            catch (e) {
+                failed = { e };
+            }
+            continue;
+        }
+        while (running.size >= cap)
+            await Promise.race(running);
+        if (failed)
+            break;
+        const p = fn(item).then((r) => {
+            out[i] = r;
+        }, (e) => {
+            if (!failed)
+                failed = { e };
+        }).finally(() => running.delete(p));
+        running.add(p);
+    }
+    await Promise.all(running);
+    if (failed)
+        throw failed.e;
+    return out;
+}

package/dist/toolkit.d.ts

@@ -9,6 +9,7 @@ import { type Agent } from "./a2a.js";
 import { type A2AConfig, type OnTask, type ServeHandle } from "./serve.js";
 import { type MCPServeConfig, type OnCall } from "./mcpserve.js";
 import type { Client } from "./client.js";
+import type { Media } from "./media.js";
 export interface ToolkitOptions {
     mcpConfig?: string | object;
     skillsDir?: string | string[];
@@ -28,6 +29,8 @@ export interface ToolkitOptions {
     /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
     skillSampleLimit?: number;
     extraTools?: Tool[];
+    /** Media generation (§7G): registers `media.tools()` (source "media"). */
+    media?: Media;
     /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
     builtins?: BuiltinsConfig;
     /** Remote A2A agents — each advertised skill becomes a tool (source:"a2a"). */

package/dist/toolkit.js

@@ -89,7 +89,7 @@ export class Toolkit {
             console.warn(`[toolnexus] A2A agent "${a.card}" failed: ${e instanceof Error ? e.message : String(e)}`);
             return [];
         })));
-        const agentToolsFlat = agentToolLists.flat();
+        const agentToolsFlat = [...agentToolLists.flat(), ...(opts.media ? opts.media.tools() : [])];
         // A2A inbound profile: a top-level `a2a` block on a parsed config object
         // (mirrors builtins/agents). serve() prefers its inline `a2a` over this.
         let a2aConfig;

package/dist/types.d.ts

@@ -9,7 +9,7 @@ export type JSONSchema = {
     [k: string]: unknown;
 };
 import type { ContentPart } from "./content.js";
-export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "custom";
+export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "media" | "custom";
 export interface ToolResult {
     output: string;
     isError: boolean;
@@ -96,6 +96,9 @@ export interface Tool {
     /** What the tool may do (§4C). Builtins always carry hints; MCP tools carry them when the
      * server sends annotations. Advisory: a server can mislabel its tools. */
     hints?: ToolHints;
+    /** Decides per call whether this tool may run alongside other safe calls of the same model
+     * response (SPEC §8 "Tool scheduling"). Absent ⇒ safe only when `hints.readOnly`. */
+    concurrencySafe?: (args: Record<string, unknown>) => boolean;
 }
 export type McpStatus = "connected" | "disabled" | "failed";
 /** Replace anything outside [a-zA-Z0-9_-] with "_" (same as opencode). */