@arnilo/prism 0.0.3 → 0.0.5

package/dist/cli-init.js

@@ -0,0 +1,390 @@
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { constants as fsConstants, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+export class InitUsageError extends Error {
+}
+let cachedCatalog;
+let cachedProviderIds;
+function providersCatalogPath(templatesRoot) {
+    return join(templatesRoot, "providers.json");
+}
+function loadProvidersCatalog(templatesRoot = defaultTemplatesRoot()) {
+    if (cachedCatalog && templatesRoot === defaultTemplatesRoot())
+        return cachedCatalog;
+    const raw = JSON.parse(readFileSync(providersCatalogPath(templatesRoot), "utf8"));
+    const map = new Map();
+    for (const [id, spec] of Object.entries(raw)) {
+        if (!id || typeof spec !== "object" || spec === null) {
+            throw new Error(`Invalid init provider catalog entry: ${id}`);
+        }
+        map.set(id, { ...spec, id });
+    }
+    if (map.size === 0)
+        throw new Error("Init provider catalog is empty");
+    if (templatesRoot === defaultTemplatesRoot()) {
+        cachedCatalog = map;
+        cachedProviderIds = Object.freeze([...map.keys()]);
+    }
+    return map;
+}
+/** Provider ids supported by `prism init --provider`. Loaded from templates data. */
+export function listInitProviders(templatesRoot) {
+    if (!templatesRoot && cachedProviderIds)
+        return cachedProviderIds;
+    return Object.freeze([...loadProvidersCatalog(templatesRoot).keys()]);
+}
+/** @deprecated Prefer listInitProviders(); retained for tests that import the name. */
+export const INIT_PROVIDERS = listInitProviders();
+export function getInitUsage(templatesRoot) {
+    const providers = listInitProviders(templatesRoot).join("|");
+    return `Usage: prism init <dir> [options]
+
+Create a minimal TypeScript Prism project with one explicit provider and an offline mock test.
+
+Arguments:
+  <dir>                      Destination directory (created if missing)
+
+Options:
+  --provider <name>          Provider id (${providers}). Default: mock
+  --with-workflows           Add optional workflows dependency and example
+  --with-evals               Add optional evals dependency and example
+  --force                    Overwrite existing generated files
+  -h, --help                 Show this help
+
+Examples:
+  prism init my-agent
+  prism init my-agent --provider openai
+  prism init my-agent --provider openai --with-workflows
+`;
+}
+export const initUsage = getInitUsage();
+export function parseInitArgs(argv, templatesRoot) {
+    let directory;
+    let provider = "mock";
+    let withWorkflows = false;
+    let withEvals = false;
+    let force = false;
+    let help = false;
+    const providers = listInitProviders(templatesRoot);
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            help = true;
+            continue;
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--with-workflows") {
+            withWorkflows = true;
+            continue;
+        }
+        if (arg === "--with-evals") {
+            withEvals = true;
+            continue;
+        }
+        if (arg === "--provider") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                throw new InitUsageError("Missing value for --provider");
+            }
+            i += 1;
+            if (!providers.includes(value)) {
+                throw new InitUsageError(`Unknown provider: ${value}. Expected one of ${providers.join(", ")}`);
+            }
+            provider = value;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new InitUsageError(`Unknown flag: ${arg}`);
+        }
+        if (directory !== undefined) {
+            throw new InitUsageError(`Unexpected argument: ${arg}`);
+        }
+        directory = arg;
+    }
+    if (!help && directory === undefined) {
+        throw new InitUsageError("Missing destination directory");
+    }
+    return {
+        directory: directory ?? ".",
+        provider,
+        withWorkflows,
+        withEvals,
+        force,
+        help,
+    };
+}
+export async function runInitCommand(argv, runtime) {
+    let options;
+    try {
+        options = parseInitArgs(argv, runtime.templatesRoot);
+    }
+    catch (error) {
+        write(runtime.stderr, `${error instanceof Error ? error.message : String(error)}\n${getInitUsage(runtime.templatesRoot)}`);
+        return 2;
+    }
+    if (options.help) {
+        write(runtime.stdout, getInitUsage(runtime.templatesRoot));
+        return 0;
+    }
+    try {
+        const result = await createInitProject(options, runtime);
+        write(runtime.stdout, [
+            `Created Prism project in ${result.targetDir}`,
+            `  provider: ${result.provider}`,
+            `  files: ${result.writtenFiles.length}`,
+            `  bytes: ${result.totalBytes}`,
+            ...(result.withWorkflows ? ["  optional: workflows"] : []),
+            ...(result.withEvals ? ["  optional: evals"] : []),
+            "",
+            "Next:",
+            `  cd ${shellQuote(displayPath(result.targetDir, runtime.cwd ?? process.cwd()))}`,
+            "  npm install",
+            "  npm test",
+            "",
+        ].join("\n"));
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof InitUsageError) {
+            write(runtime.stderr, `${message}\n${getInitUsage(runtime.templatesRoot)}`);
+            return 2;
+        }
+        write(runtime.stderr, `${message}\n`);
+        return 1;
+    }
+}
+export async function createInitProject(options, runtime = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    const cwd = runtime.cwd ?? process.cwd();
+    const targetDir = resolveInitDirectory(options.directory, cwd);
+    const templatesRoot = runtime.templatesRoot ?? defaultTemplatesRoot();
+    const version = runtime.packageVersion ?? (await readPackageVersion());
+    const catalog = loadProvidersCatalog(templatesRoot);
+    const provider = catalog.get(options.provider);
+    if (!provider) {
+        throw new InitUsageError(`Unknown provider: ${options.provider}. Expected one of ${[...catalog.keys()].join(", ")}`);
+    }
+    const projectName = sanitizePackageName(basenameSafe(targetDir));
+    await assertDestinationWritable(targetDir, options.force);
+    const tokens = buildTokens({
+        projectName,
+        version,
+        provider,
+        withWorkflows: options.withWorkflows,
+        withEvals: options.withEvals,
+    });
+    const planned = await planFiles({
+        templatesRoot,
+        withWorkflows: options.withWorkflows,
+        withEvals: options.withEvals,
+    });
+    if (!options.force) {
+        for (const file of planned) {
+            const dest = join(targetDir, file.relativePath);
+            if (await exists(dest)) {
+                throw new InitUsageError(`Refusing to overwrite existing file: ${file.relativePath} (pass --force to overwrite)`);
+            }
+        }
+    }
+    const writtenFiles = [];
+    let totalBytes = 0;
+    for (const file of planned) {
+        const dest = join(targetDir, file.relativePath);
+        assertPathInside(targetDir, dest);
+        const raw = await readFile(file.sourcePath, "utf8");
+        const content = applyTokens(raw, tokens);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, content, "utf8");
+        writtenFiles.push(file.relativePath);
+        totalBytes += Buffer.byteLength(content, "utf8");
+    }
+    return {
+        targetDir,
+        writtenFiles,
+        provider: options.provider,
+        withWorkflows: options.withWorkflows,
+        withEvals: options.withEvals,
+        totalBytes,
+    };
+}
+export function defaultTemplatesRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "init");
+}
+export function isInitProvider(value, templatesRoot) {
+    return listInitProviders(templatesRoot).includes(value);
+}
+function resolveInitDirectory(input, cwd) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        throw new InitUsageError("Missing destination directory");
+    if (trimmed.includes("\0"))
+        throw new InitUsageError("Invalid destination directory");
+    // Reject Windows drive-relative oddities and keep the path normal.
+    const normalizedInput = normalize(trimmed);
+    if (normalizedInput.split(sep).includes("..") && !isAbsolute(normalizedInput)) {
+        // Allow intentional relative parents, but still resolve and validate after join.
+    }
+    const resolved = resolve(cwd, normalizedInput);
+    if (resolved === sep || /^[A-Za-z]:[\\/]?$/.test(resolved)) {
+        throw new InitUsageError(`Refusing to scaffold into filesystem root: ${resolved}`);
+    }
+    return resolved;
+}
+async function assertDestinationWritable(targetDir, force) {
+    if (!(await exists(targetDir))) {
+        await mkdir(targetDir, { recursive: true });
+        return;
+    }
+    const entries = await readdir(targetDir);
+    if (entries.length > 0 && !force) {
+        throw new InitUsageError(`Destination is not empty: ${targetDir} (pass --force to overwrite generated files)`);
+    }
+}
+async function planFiles(options) {
+    const root = options.templatesRoot;
+    const files = [
+        { relativePath: "package.json", sourcePath: join(root, "package.json.tmpl") },
+        { relativePath: "tsconfig.json", sourcePath: join(root, "tsconfig.json.tmpl") },
+        { relativePath: ".gitignore", sourcePath: join(root, "gitignore.tmpl") },
+        { relativePath: ".env.example", sourcePath: join(root, "env.example.tmpl") },
+        { relativePath: "README.md", sourcePath: join(root, "README.md.tmpl") },
+        { relativePath: "src/agent.ts", sourcePath: join(root, "src/agent.ts.tmpl") },
+        { relativePath: "src/index.ts", sourcePath: join(root, "src/index.ts.tmpl") },
+        { relativePath: "src/__tests__/agent.test.ts", sourcePath: join(root, "src/tests/agent.test.ts.tmpl") },
+    ];
+    if (options.withWorkflows) {
+        files.push({
+            relativePath: "src/workflows-example.ts",
+            sourcePath: join(root, "optional/workflows-example.ts.tmpl"),
+        });
+    }
+    if (options.withEvals) {
+        files.push({
+            relativePath: "src/evals-example.ts",
+            sourcePath: join(root, "optional/evals-example.ts.tmpl"),
+        });
+    }
+    for (const file of files) {
+        try {
+            await access(file.sourcePath, fsConstants.R_OK);
+        }
+        catch {
+            throw new Error(`Missing init template: ${file.sourcePath}`);
+        }
+    }
+    return files;
+}
+function buildTokens(input) {
+    const dependencies = {
+        "@arnilo/prism": input.version,
+    };
+    if (input.provider.packageName) {
+        dependencies[input.provider.packageName] = input.version;
+    }
+    if (input.withWorkflows) {
+        dependencies["@arnilo/prism-workflows"] = input.version;
+    }
+    if (input.withEvals) {
+        dependencies["@arnilo/prism-evals"] = input.version;
+    }
+    const dependencyLines = Object.entries(dependencies)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, ver]) => `    ${JSON.stringify(name)}: ${JSON.stringify(ver)}`)
+        .join(",\n");
+    const envBlock = input.provider.envKey
+        ? `# Placeholder only — never commit real secrets.\n${input.provider.envKey}=${input.provider.envPlaceholder ?? ""}\n`
+        : `# No API key required for the mock provider.\n# Switch providers with: prism init <dir> --provider openai --force\n`;
+    const nextStepsLive = input.provider.envKey
+        ? `2. Copy \`.env.example\` to \`.env\` and set \`${input.provider.envKey}\`.\n3. Run \`npm start\` for a live provider call.`
+        : `2. Run \`npm start\` (mock provider; no network or credentials).`;
+    const optionalDocs = [
+        ...(input.withWorkflows
+            ? ["- `src/workflows-example.ts` — tiny DAG example using `@arnilo/prism-workflows`."]
+            : []),
+        ...(input.withEvals
+            ? ["- `src/evals-example.ts` — deterministic scorer example using `@arnilo/prism-evals`."]
+            : []),
+    ].join("\n");
+    return {
+        __PROJECT_NAME__: input.projectName,
+        __PRISM_VERSION__: input.version,
+        __PROVIDER_ID__: input.provider.id,
+        __PROVIDER_PACKAGE__: input.provider.packageName ?? "",
+        __DEPENDENCIES__: dependencyLines,
+        __PROVIDER_IMPORTS__: input.provider.imports,
+        __PROVIDER_EXPRESSION__: input.provider.providerExpression,
+        __MODEL_EXPRESSION__: input.provider.modelExpression,
+        __ENV_EXAMPLE__: envBlock,
+        __NEXT_STEPS_LIVE__: nextStepsLive,
+        __OPTIONAL_DOCS__: optionalDocs.length > 0 ? `${optionalDocs}\n` : "",
+        __PROVIDER_README_NOTE__: input.provider.packageName
+            ? `Selected provider package: \`${input.provider.packageName}\` (model \`${input.provider.modelName}\`).`
+            : "Selected provider: built-in `mock` (offline demos and tests).",
+    };
+}
+function applyTokens(template, tokens) {
+    let out = template;
+    for (const [token, value] of Object.entries(tokens)) {
+        out = out.split(token).join(value);
+    }
+    if (/__[A-Z0-9_]+__/.test(out)) {
+        const leftover = out.match(/__[A-Z0-9_]+__/g) ?? [];
+        throw new Error(`Unresolved init template tokens: ${Array.from(new Set(leftover)).join(", ")}`);
+    }
+    return out;
+}
+async function readPackageVersion() {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    if (!pkg.version)
+        throw new Error(`Missing version in ${pkgPath}`);
+    return pkg.version;
+}
+function assertPathInside(root, candidate) {
+    const rel = relative(root, candidate);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return;
+    throw new InitUsageError(`Refusing to write outside destination: ${candidate}`);
+}
+async function exists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sanitizePackageName(name) {
+    const cleaned = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned.length > 0 ? cleaned : "prism-agent";
+}
+function basenameSafe(path) {
+    const parts = path.split(/[\\/]/).filter(Boolean);
+    return parts[parts.length - 1] ?? "prism-agent";
+}
+function displayPath(targetDir, cwd) {
+    const rel = relative(cwd, targetDir);
+    if (rel && !rel.startsWith("..") && !isAbsolute(rel))
+        return rel || ".";
+    return targetDir;
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:@-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function write(stream, text) {
+    stream.write(text);
+}
+//# sourceMappingURL=cli-init.js.map

package/dist/cli-runner.d.ts

@@ -60,8 +60,14 @@ export interface CliRuntime {
     /** Optional global root for SYSTEM.md auto-load (host-controlled). No default;
      *  the CLI does not auto-touch the user's home directory. */
     readonly globalRoot?: string;
+    /** Override init template root (tests). */
+    readonly initTemplatesRoot?: string;
+    /** Override version stamped by `prism init` (tests). */
+    readonly initPackageVersion?: string;
+    /** Working directory for relative `prism init` destinations (tests). */
+    readonly cwd?: string;
 }
-export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --config <path>            Explicit config path (recorded, not auto-loaded)\n  --resource <uri>           Explicit resource URI (recorded, not auto-loaded)\n  --extension <name>         Explicit extension name (recorded, not auto-loaded)\n  --tool <name>              Explicit tool name (recorded, not auto-enabled)\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
+export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --config <path>            Explicit config path (recorded, not auto-loaded)\n  --resource <uri>           Explicit resource URI (recorded, not auto-loaded)\n  --extension <name>         Explicit extension name (recorded, not auto-loaded)\n  --tool <name>              Explicit tool name (recorded, not auto-enabled)\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
 export declare function parseCliArgs(argv: readonly string[]): CliOptions;
 export declare function runCli(argv: readonly string[], runtime: CliRuntime): Promise<number>;
 export declare function runPromptMode(session: AgentSession, options: CliOptions, stdout: Writable, mode: "print" | "json"): Promise<void>;

package/dist/cli-runner.js

@@ -10,7 +10,9 @@ import { registerDiscoveredInstructionInjectors } from "./node/instruction-injec
 import { loadSystemPromptFiles } from "./node/system-project-prompts.js";
 import { createPathTrustPolicy } from "./node/trust.js";
 import { runRpcServer } from "./rpc.js";
+import { initUsage, runInitCommand } from "./cli-init.js";
 export const usage = `Usage: prism [--mode print|json|rpc] [-p prompt] [options]
+       prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]
 
 Options:
   -p, --prompt <text>        Prompt to run in print/json mode
@@ -167,6 +169,16 @@ function parseKinds(csv, flag) {
     return kinds;
 }
 export async function runCli(argv, runtime) {
+    if (argv[0] === "init") {
+        const initRuntime = {
+            stdout: runtime.stdout,
+            stderr: runtime.stderr,
+            ...(runtime.initTemplatesRoot !== undefined ? { templatesRoot: runtime.initTemplatesRoot } : {}),
+            ...(runtime.initPackageVersion !== undefined ? { packageVersion: runtime.initPackageVersion } : {}),
+            ...(runtime.cwd !== undefined ? { cwd: runtime.cwd } : {}),
+        };
+        return runInitCommand(argv.slice(1), initRuntime);
+    }
     let options;
     try {
         options = parseCliArgs(argv);
@@ -176,7 +188,7 @@ export async function runCli(argv, runtime) {
         return 2;
     }
     if (options.help) {
-        write(runtime.stdout, usage);
+        write(runtime.stdout, `${usage}\n${initUsage}`);
         return 0;
     }
     try {

package/dist/compaction.js

@@ -59,7 +59,15 @@ function blockText(block) {
         return `[tool_call_delta ${block.name ?? block.index}]`;
     if (block.type === "tool_result")
         return `[tool_result ${block.name}]`;
-    return "[image]";
+    if (block.type === "image")
+        return "[image]";
+    if (block.type === "audio")
+        return "[audio]";
+    if (block.type === "file")
+        return "[file]";
+    if (block.type === "document")
+        return "[document]";
+    return "[content]";
 }
 function truncate(text, max) {
     if (max === 0 || text.length <= max)

package/dist/content.d.ts

@@ -0,0 +1,121 @@
+import type { ContentBlock, ImageContent, Message, ModelConfig, ResourceLoadContext, ResourceLoader } from "./contracts.js";
+/** Known model input capability tags for `ModelCapabilities.input`. */
+export declare const MODEL_INPUT_CAPABILITIES: readonly ["text", "image", "audio", "file", "document"];
+export type ModelInputCapability = (typeof MODEL_INPUT_CAPABILITIES)[number];
+/** Default per-item media byte ceiling (10 MB; aligns with coding-agent image bounds). */
+export declare const DEFAULT_MAX_MEDIA_ITEM_BYTES = 10000000;
+/** Default total media byte budget per request assembly. */
+export declare const DEFAULT_MAX_MEDIA_REQUEST_BYTES: number;
+/** Default decoded audio duration ceiling. */
+export declare const DEFAULT_MAX_AUDIO_DURATION_MS: number;
+/** Default URL fetch timeout for media resolution. */
+export declare const DEFAULT_MEDIA_FETCH_TIMEOUT_MS = 30000;
+/** Default maximum media-bearing blocks per request assembly. */
+export declare const DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST = 32;
+export interface AudioContent {
+    readonly type: "audio";
+    readonly mediaType: string;
+    readonly name?: string;
+    /** Base64-encoded audio bytes. */
+    readonly data?: string;
+    readonly url?: string;
+    readonly resourceUri?: string;
+    readonly durationMs?: number;
+    readonly transcript?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface FileContent {
+    readonly type: "file";
+    readonly mediaType: string;
+    readonly name?: string;
+    /** Base64-encoded file bytes. */
+    readonly data?: string;
+    readonly url?: string;
+    readonly resourceUri?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface DocumentContent {
+    readonly type: "document";
+    readonly mediaType: string;
+    readonly name?: string;
+    /** Base64-encoded document bytes. */
+    readonly data?: string;
+    readonly url?: string;
+    readonly resourceUri?: string;
+    readonly transcript?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export type MediaContentBlock = AudioContent | FileContent | DocumentContent | ImageContent;
+export interface MediaContentBounds {
+    readonly maxItemBytes?: number;
+    readonly maxRequestBytes?: number;
+    readonly maxItems?: number;
+    readonly maxAudioDurationMs?: number;
+    readonly fetchTimeoutMs?: number;
+}
+export interface SsrfPolicy {
+    /** When true (default), deny private/link-local/metadata hostnames and IPs. */
+    readonly denyPrivateHosts?: boolean;
+    /** Optional hostname allow-list. When set, only listed hosts are permitted. */
+    readonly allowedHostnames?: readonly string[];
+}
+export interface MediaMimePolicy {
+    /** Reject when magic bytes disagree with declared media type. Default `true`. */
+    readonly strictMagicValidation?: boolean;
+}
+export interface MediaHostAddress {
+    readonly address: string;
+    readonly family: 4 | 6;
+}
+export type MediaHostnameResolver = (hostname: string, signal: AbortSignal) => Promise<readonly MediaHostAddress[]>;
+export interface MediaUrlRequest {
+    readonly url: URL;
+    readonly address: MediaHostAddress;
+    readonly maxBytes: number;
+    readonly signal: AbortSignal;
+}
+export type MediaUrlRequester = (request: MediaUrlRequest) => Promise<Uint8Array>;
+export interface ResolveMediaContentOptions {
+    readonly bounds?: MediaContentBounds;
+    readonly ssrf?: SsrfPolicy;
+    readonly mime?: MediaMimePolicy;
+    readonly loader?: ResourceLoader;
+    readonly loadContext?: ResourceLoadContext;
+    /** Trusted custom transport; the host owns DNS resolution and rebinding protection. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Test/custom resolver used only with the default or `requestUrl` pinned transport. */
+    readonly resolveHostname?: MediaHostnameResolver;
+    /** Trusted custom transport that must connect to `request.address`, not resolve `request.url` again. */
+    readonly requestUrl?: MediaUrlRequester;
+    readonly signal?: AbortSignal;
+}
+export interface ResolvedMediaContent {
+    readonly mediaType: string;
+    readonly bytes: Uint8Array;
+    readonly name?: string;
+    readonly durationMs?: number;
+    readonly transcript?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export declare class UnsupportedModalityError extends Error {
+    readonly modality: ModelInputCapability;
+    readonly provider: string;
+    readonly model: string;
+    constructor(modality: ModelInputCapability, model: ModelConfig);
+}
+export declare class MediaContentError extends Error {
+    readonly code: "ambiguous_source" | "missing_source" | "item_too_large" | "request_too_large" | "too_many_items" | "audio_too_long" | "invalid_base64" | "ssrf_denied" | "fetch_failed" | "fetch_timeout" | "resource_required" | "mime_mismatch" | "unsupported_url_scheme";
+    constructor(code: MediaContentError["code"], message: string);
+}
+export declare function contentBlockInputModality(block: ContentBlock): ModelInputCapability | undefined;
+export declare function collectMessageContentBlocks(messages: readonly Message[]): ContentBlock[];
+export declare function assertModelSupportsContentBlocks(model: ModelConfig, blocks: readonly ContentBlock[]): void;
+export declare function assertMessagesSupportModelCapabilities(model: ModelConfig, messages: readonly Message[]): void;
+export declare function assertMediaBlocksWithinBounds(blocks: readonly MediaContentBlock[], bounds?: MediaContentBounds): void;
+export declare function assertSsrfAllowedUrl(url: string, policy?: SsrfPolicy): void;
+export declare function sniffMediaMimeType(bytes: Uint8Array): string | undefined;
+export declare function assertDeclaredMediaTypeMatches(declaredMediaType: string, bytes: Uint8Array, policy?: MediaMimePolicy): void;
+export declare function resolveMediaContentBlock(block: MediaContentBlock, options?: ResolveMediaContentOptions): Promise<ResolvedMediaContent>;
+/** Resolve and validate one complete media request before provider serialization/upload. */
+export declare function resolveMediaContentBlocks(blocks: readonly MediaContentBlock[], options?: ResolveMediaContentOptions): Promise<readonly ResolvedMediaContent[]>;
+export declare function loadBoundedBinaryResource(loader: ResourceLoader, uri: string, context: ResourceLoadContext | undefined, maxBytes: number, signal?: AbortSignal): Promise<Uint8Array>;