@arnilo/prism 0.4.0 → 0.5.0

package/dist/capture.d.ts

@@ -0,0 +1,63 @@
+/** Provider request/response capture middleware (plan 062, review §7 P1):
+ *  opt-in observation of already-normalized provider shapes — never raw HTTP.
+ *
+ *  Request side rides the existing `provider_request` middleware hook; response
+ *  side rides the existing subscriber-event seam (`provider_turn_finished`,
+ *  which core already redacts). No new seam. Captured entries land in a capped
+ *  FIFO ring buffer (`maxEvents`, default 100).
+ *
+ *  Privacy policy `redact` controls content retention:
+ *  - `"all"`: structure only — model id, counts, tool names, usage, latency.
+ *  - `"secrets"` (default): also drops message content (the privacy default:
+ *    captured buffers carry no conversation text unless the host opts in).
+ *  - `"none"`: retains message content for replay debugging.
+ *  Secret redaction is unconditional in every mode (replay-safe by
+ *  construction): retained material passes through the same `redactSecrets`
+ *  helper the logging seams use, so credentials never survive into a buffer
+ *  that a host might persist or replay. Provider request/response options and
+ *  headers are never captured at all — headers are where credentials ride.
+ */
+import type { AgentEvent, ProviderRequest } from "./contracts.js";
+import type { Middleware } from "./middleware.js";
+import { type SecretRedactor } from "./redaction.js";
+export type CaptureRedaction = "secrets" | "all" | "none";
+export interface ProviderCapturePolicy {
+    /** Content-retention level; `"secrets"` (default) drops message content. */
+    readonly redact?: CaptureRedaction;
+    /** Ring-buffer capacity; oldest entries evict first. Default 100. */
+    readonly maxEvents?: number;
+}
+export interface ProviderCaptureOptions {
+    readonly policy?: ProviderCapturePolicy;
+    /** Secrets redacted from every retained field, matching the logging seams. */
+    readonly secrets?: readonly (string | undefined)[];
+    readonly redactor?: SecretRedactor;
+    readonly now?: () => number;
+}
+export interface ProviderCaptureEntry {
+    readonly kind: "request" | "response";
+    readonly at: string;
+    readonly redaction: CaptureRedaction;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly messageCount?: number;
+    readonly toolNames?: readonly string[];
+    /** Message content — present only when the policy retains it (`"none"`), secrets redacted. */
+    readonly content?: unknown;
+    /** Response entries: normalized usage numbers (never sensitive). */
+    readonly usage?: unknown;
+    readonly latencyMs?: number;
+    readonly error?: unknown;
+}
+export interface ProviderCapture {
+    /** Register on the existing `provider_request` middleware hook. Passes the
+     *  request through untouched and records one entry per round. */
+    middleware(): Middleware<ProviderRequest>;
+    /** Feed `provider_turn_finished` events from the session's existing
+     *  subscriber loop (`session.subscribe()`) to record response entries. */
+    observeEvent(event: AgentEvent): void;
+    /** Ring-buffer snapshot, oldest first. */
+    events(): readonly ProviderCaptureEntry[];
+    clear(): void;
+}
+export declare function createProviderCapture(options?: ProviderCaptureOptions): ProviderCapture;

package/dist/capture.js

@@ -0,0 +1,67 @@
+import { resolveRedactor } from "./redaction.js";
+const DEFAULT_MAX_EVENTS = 100;
+const HARD_MAX_EVENTS_CAP = 10_000;
+function resolveMaxEvents(maxEvents) {
+    const value = maxEvents ?? DEFAULT_MAX_EVENTS;
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error("maxEvents must be a positive integer");
+    return Math.min(value, HARD_MAX_EVENTS_CAP);
+}
+export function createProviderCapture(options = {}) {
+    const redaction = options.policy?.redact ?? "secrets";
+    const maxEvents = resolveMaxEvents(options.policy?.maxEvents);
+    const now = options.now ?? Date.now;
+    const redactor = resolveRedactor(options.redactor, options.secrets);
+    const buffer = [];
+    const record = (entry) => {
+        buffer.push(entry);
+        if (buffer.length > maxEvents)
+            buffer.splice(0, buffer.length - maxEvents);
+    };
+    return {
+        middleware() {
+            return (request, next) => {
+                const entry = {
+                    kind: "request",
+                    at: new Date(now()).toISOString(),
+                    redaction,
+                    provider: request.model.provider,
+                    model: request.model.model,
+                    messageCount: request.messages.length,
+                    toolNames: request.tools?.map((tool) => tool.name),
+                    ...(redaction === "none" && request.messages.length > 0
+                        ? { content: redactor ? redactor.redact(request.messages) : request.messages }
+                        : {}),
+                };
+                record(entry);
+                return next(request);
+            };
+        },
+        observeEvent(event) {
+            if (event.type !== "provider_turn_finished")
+                return;
+            const metadata = (event.metadata ?? {});
+            record({
+                kind: "response",
+                at: new Date(now()).toISOString(),
+                redaction,
+                provider: typeof metadata.providerId === "string" ? metadata.providerId : undefined,
+                model: typeof metadata.model?.model === "string"
+                    ? metadata.model.model
+                    : undefined,
+                usage: event.usage,
+                latencyMs: typeof metadata.latencyMs === "number" ? metadata.latencyMs : undefined,
+                // Core already redacts emitted errors; redact again so replay safety holds even
+                // when a host feeds events captured before redaction.
+                error: event.error && redactor ? redactor.redact(event.error) : event.error,
+            });
+        },
+        events() {
+            return [...buffer];
+        },
+        clear() {
+            buffer.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=capture.js.map

package/dist/cli-init.d.ts

@@ -39,11 +39,27 @@ export interface TemplateInfo {
     readonly version?: string;
     readonly path: string;
 }
+interface ProviderSpec {
+    readonly id: string;
+    readonly packageName?: string;
+    /** Module specifier the CLI's real-provider mode dynamically imports (e.g. `@arnilo/prism-providers/openai`). */
+    readonly factoryModule?: string;
+    /** Named export on `factoryModule` that builds the provider. */
+    readonly factoryExport?: string;
+    readonly envKey?: string;
+    readonly envPlaceholder?: string;
+    readonly modelProvider: string;
+    readonly modelName: string;
+    readonly imports: string;
+    readonly providerExpression: string;
+    readonly modelExpression: string;
+}
+/** Provider catalog shared by `prism init` templates and the CLI's real-provider mode. */
+export declare function loadProvidersCatalog(templatesRoot?: string): ReadonlyMap<string, ProviderSpec>;
 /** Provider ids supported by `prism init --provider`. Loaded from templates data. */
 export declare function listInitProviders(templatesRoot?: string): readonly string[];
 /** Template list discovered from the templates gallery. */
 export declare function listInitTemplates(galleryRoot?: string): readonly TemplateInfo[];
-export declare function isInitTemplate(value: string, galleryRoot?: string): boolean;
 export declare function getInitUsage(templatesRoot?: string, galleryRoot?: string): string;
 export declare const initUsage: string;
 export declare function parseInitArgs(argv: readonly string[], templatesRoot?: string, galleryRoot?: string): InitOptions;
@@ -51,4 +67,4 @@ export declare function runInitCommand(argv: readonly string[], runtime: InitRun
 export declare function createInitProject(options: InitOptions, runtime?: InitRuntime): Promise<InitResult>;
 export declare function defaultTemplatesRoot(): string;
 export declare function defaultGalleryRoot(): string;
-export declare function isInitProvider(value: string, templatesRoot?: string): value is InitProvider;
+export {};

package/dist/cli-init.js

@@ -9,7 +9,8 @@ let cachedProviderIds;
 function providersCatalogPath(templatesRoot) {
     return join(templatesRoot, "providers.json");
 }
-function loadProvidersCatalog(templatesRoot = defaultTemplatesRoot()) {
+/** Provider catalog shared by `prism init` templates and the CLI's real-provider mode. */
+export function loadProvidersCatalog(templatesRoot = defaultTemplatesRoot()) {
     if (cachedCatalog && templatesRoot === defaultTemplatesRoot())
         return cachedCatalog;
     const raw = JSON.parse(readFileSync(providersCatalogPath(templatesRoot), "utf8"));
@@ -85,9 +86,6 @@ export function listInitTemplates(galleryRoot = defaultGalleryRoot()) {
         ]);
     }
 }
-export function isInitTemplate(value, galleryRoot) {
-    return listInitTemplates(galleryRoot).some((t) => t.name === value);
-}
 export function getInitUsage(templatesRoot, galleryRoot) {
     const providers = listInitProviders(templatesRoot).join("|");
     const templates = listInitTemplates(galleryRoot)
@@ -388,9 +386,6 @@ function buildTokensForTemplate(input) {
         __PROVIDER_README_NOTE__: "",
     };
 }
-export function isInitProvider(value, templatesRoot) {
-    return listInitProviders(templatesRoot).includes(value);
-}
 function resolveInitDirectory(input, cwd) {
     const trimmed = input.trim();
     if (!trimmed)

package/dist/cli-runner.d.ts

@@ -49,7 +49,7 @@ export interface CliRuntime {
     readonly stdin: Readable;
     readonly stdout: Writable;
     readonly stderr: Writable;
-    readonly createSession?: (options: CliOptions) => AgentSession;
+    readonly createSession?: (options: CliOptions) => AgentSession | Promise<AgentSession>;
     readonly commands?: RpcSessionFactory["commands"];
     /** Workspace root for `--discover`. Defaults to `process.cwd()`. */
     readonly workspaceRoot?: string;
@@ -71,7 +71,7 @@ export interface CliRuntime {
     /** Test injection for `prism dev`: overrides `@arnilo/prism-dev` resolution. */
     readonly loadDevCli?: () => Promise<unknown>;
 }
-export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]\n       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]\n       prism dev [--port <n>] [--host <addr>]   (loopback inspector; delegates into @arnilo/prism-dev)\n\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  --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> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]\n       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]\n       prism dev [--port <n>] [--host <addr>]   (loopback inspector; delegates into @arnilo/prism-dev)\n\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Provider id from the init provider catalog ('mock' is built in;\n                             real providers need their @arnilo/prism-providers package +\n                             credential env var)\n  --model <name>             Explicit model name\n  --session <id>             Session id\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

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname } from "node:path";
 import process from "node:process";
 import { runPrismDevSubcommand } from "./cli-dev.js";
-import { initUsage, runInitCommand } from "./cli-init.js";
+import { initUsage, loadProvidersCatalog, runInitCommand } from "./cli-init.js";
 import { providerAddUsage, runProviderAddCommand } from "./cli-provider-add.js";
 import { createContributionRegistries, registerDiscoveredContributions } from "./contributions.js";
 import { createAgent, createContributionRegistry, createMockProvider, providerDone, providerTextDelta, resolveInstructionInjectors, } from "./index.js";
@@ -21,7 +21,9 @@ export const usage = `Usage: prism [--mode print|json|rpc] [-p prompt] [options]
 
 Options:
   -p, --prompt <text>        Prompt to run in print/json mode
-  --provider <name>          Explicit provider id (mock is built in for smoke tests)
+  --provider <name>          Provider id from the init provider catalog ('mock' is built in;
+                             real providers need their @arnilo/prism-providers package +
+                             credential env var)
   --model <name>             Explicit model name
   --session <id>             Session id
   --system <text>            System instructions
@@ -315,7 +317,7 @@ export async function runCli(argv, runtime) {
             });
             options = { ...options, systemPromptLayers: layers };
         }
-        const session = (runtime.createSession ?? defaultCreateSession)(options);
+        const session = await (runtime.createSession ?? defaultCreateSession)(options);
         await runPromptMode(session, options, runtime.stdout, mode);
         return 0;
     }
@@ -346,13 +348,47 @@ export async function runPromptMode(session, options, stdout, mode) {
 }
 export class CliUsageError extends Error {
 }
-function defaultCreateSession(options) {
-    if (options.provider !== "mock")
-        throw new CliUsageError("No provider configured. Pass --provider mock for a smoke test or embed Prism with an explicit provider.");
-    const model = { provider: "mock", model: options.model ?? "mock" };
+/** Build the agent session for the CLI. Real providers resolve through the init
+ *  provider catalog (`templates/init/providers.json`): the catalog names the
+ *  factory module/export and credential env var, the CLI imports it from the
+ *  consumer's node_modules — same catalog `prism init` scaffolds from, so the
+ *  CLI and the scaffold never disagree about how a provider is built. */
+async function defaultCreateSession(options) {
+    const providerId = options.provider;
+    if (!providerId) {
+        throw new CliUsageError("No provider configured. Pass --provider <id> (see the init provider catalog, or 'mock') or embed Prism with an explicit provider.");
+    }
+    if (providerId === "mock")
+        return mockSession(options);
+    const spec = loadProvidersCatalog().get(providerId);
+    if (!spec?.factoryModule || !spec.factoryExport) {
+        throw new CliUsageError(`Unknown provider "${providerId}". Supported: ${["mock", ...loadProvidersCatalog().keys()].join(", ")} — or embed Prism with an explicit provider.`);
+    }
+    const envKey = spec.envKey ?? "";
+    if (!process.env[envKey])
+        throw new CliUsageError(`Provider "${providerId}" requires ${envKey} in the environment.`);
+    let factory;
+    try {
+        factory = (await import(spec.factoryModule))[spec.factoryExport];
+    }
+    catch {
+        throw new CliUsageError(`Provider "${providerId}" needs the ${spec.packageName} package installed (import ${spec.factoryModule} failed).`);
+    }
+    if (typeof factory !== "function") {
+        throw new CliUsageError(`Provider "${providerId}": ${spec.factoryModule} does not export ${spec.factoryExport}.`);
+    }
+    const providerInstance = factory({ apiKey: () => process.env[envKey] });
+    const modelConfig = { provider: spec.modelProvider, model: options.model ?? spec.modelName };
+    return agentSession({ ...options, providerInstance, modelConfig });
+}
+function mockSession(options) {
+    const modelConfig = { provider: "mock", model: options.model ?? "mock" };
+    return agentSession({ ...options, providerInstance: createMockProvider([providerTextDelta("Hello"), providerDone()]), modelConfig });
+}
+function agentSession(options) {
     return createAgent({
-        model,
-        provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+        model: options.modelConfig,
+        provider: options.providerInstance,
         instructions: options.system,
         // ponytail: Phase 31 — file layers compose with `instructions` (base) via the existing
         // composeSystemPrompt pipeline; rank order (user<package<app<run) is enforced inside.

package/dist/content.d.ts

@@ -1,6 +1,6 @@
-import type { ContentBlock, ImageContent, Message, ModelConfig, ResourceLoadContext, ResourceLoader } from "./contracts.js";
+import type { ContentBlock, ImageContent, Message, ModelConfig, ResourceLoadContext, ResourceLoader, VideoContent } from "./contracts.js";
 /** Known model input capability tags for `ModelCapabilities.input`. */
-export declare const MODEL_INPUT_CAPABILITIES: readonly ["text", "image", "audio", "file", "document"];
+export declare const MODEL_INPUT_CAPABILITIES: readonly ["text", "image", "audio", "file", "document", "video"];
 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;
@@ -45,7 +45,7 @@ export interface DocumentContent {
     readonly transcript?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-export type MediaContentBlock = AudioContent | FileContent | DocumentContent | ImageContent;
+export type MediaContentBlock = AudioContent | FileContent | DocumentContent | ImageContent | VideoContent;
 export interface MediaContentBounds {
     readonly maxItemBytes?: number;
     readonly maxRequestBytes?: number;

package/dist/content.js

@@ -3,7 +3,7 @@ import { isIP } from "node:net";
 import { pinnedFetch } from "./pinned-fetch.js";
 import { assertPermission } from "./security.js";
 /** Known model input capability tags for `ModelCapabilities.input`. */
-export const MODEL_INPUT_CAPABILITIES = ["text", "image", "audio", "file", "document"];
+export const MODEL_INPUT_CAPABILITIES = ["text", "image", "audio", "file", "document", "video"];
 /** Default per-item media byte ceiling (10 MB; aligns with coding-agent image bounds). */
 export const DEFAULT_MAX_MEDIA_ITEM_BYTES = 10_000_000;
 /** Default total media byte budget per request assembly. */
@@ -44,6 +44,8 @@ export function contentBlockInputModality(block) {
             return "file";
         case "document":
             return "document";
+        case "video":
+            return "video";
         default:
             return undefined;
     }

package/dist/contracts-core/agent.d.ts

@@ -77,6 +77,8 @@ export interface AgentConfig {
     readonly systemPrompt?: SystemPromptConfig;
     readonly redactor?: SecretRedactor;
     readonly runLedger?: RunLedger;
+    /** Optional host-supplied pricing adapter: turn usage without a provider-reported cost is priced through it; absent or stale quotes degrade to usage-only. */
+    readonly costCatalog?: import("./content.js").CostCatalog;
     /** Optional durable recovery store. */
     readonly effectStore?: ToolEffectStore;
     readonly ownership?: OwnershipScope;

package/dist/contracts-core/batch.d.ts

@@ -0,0 +1,97 @@
+/** Provider-neutral async batch-jobs contract (plan 061 Task 7).
+ *
+ * Standalone contract — deliberately not coupled to the orchestration saga seam
+ * in v1 (plan decision). Job ids are opaque strings; request payloads are
+ * provider-native `JsonObject` bodies and inherit the provider's request caps;
+ * polling is a plain exported utility (`pollBatch`), never loop-integrated into
+ * core.
+ */
+import type { JsonObject, ModelCapabilities, ModelConfig } from "./content.js";
+/** Neutral job state union. Adapters map provider states onto these:
+ *  `queued` (submitted, not yet running), `cancelling`, and the three terminal
+ *  states `completed` / `failed` / `cancelled` / `expired`. */
+export type BatchJobState = "queued" | "running" | "cancelling" | "completed" | "failed" | "cancelled" | "expired";
+export declare const BATCH_TERMINAL_STATES: readonly BatchJobState[];
+export declare function isBatchJobTerminal(job: Pick<BatchJob, "state">): boolean;
+export type BatchJobsErrorCode = "empty_requests" | "too_many_requests" | "unsupported_model" | "job_not_found" | "invalid_cursor" | "request_failed" | "response_malformed" | "unsupported_operation" | "job_failed" | "job_cancelled" | "job_expired";
+export declare class BatchJobsError extends Error {
+    readonly code: BatchJobsErrorCode;
+    constructor(code: BatchJobsErrorCode, message: string);
+}
+export declare function modelSupportsBatchJobs(capabilities?: ModelCapabilities): boolean;
+export declare function assertBatchJobsSupported(model: ModelConfig): void;
+/** One batched request: provider-native body plus an optional caller-assigned
+ *  correlation id echoed on results. Bodies are opaque to the contract. */
+export interface BatchRequestItem {
+    readonly customId?: string;
+    readonly body: JsonObject;
+}
+export interface BatchSubmitRequest {
+    readonly model: string;
+    readonly requests: readonly BatchRequestItem[];
+    /** Provider-native routing metadata (weights, priorities) — opaque passthrough. */
+    readonly metadata?: JsonObject;
+    readonly signal?: AbortSignal;
+}
+export interface BatchJob {
+    /** Opaque provider job id — contract never parses or scopes it. */
+    readonly id: string;
+    readonly state: BatchJobState;
+    readonly requestCounts?: {
+        readonly total: number;
+        readonly completed: number;
+        readonly failed: number;
+    };
+    readonly createdAt?: string;
+    readonly completedAt?: string;
+    readonly expiresAt?: string;
+    /** Provider-native job fields, unmodified, for host-side audits. */
+    readonly raw?: JsonObject;
+    /** Terminal failure detail when `state` is `failed`. */
+    readonly error?: {
+        readonly code?: string;
+        readonly message?: string;
+    };
+}
+export interface BatchResultItem {
+    readonly customId: string;
+    /** Provider-native per-request response (status + payload), when it succeeded. */
+    readonly response?: JsonObject;
+    /** Per-request failure detail (the job itself may still be `completed`). */
+    readonly error?: {
+        readonly code?: string;
+        readonly message?: string;
+    };
+    /** Provider-native raw line for audits. */
+    readonly raw?: JsonObject;
+}
+export interface BatchResultsPage {
+    readonly job?: BatchJob;
+    readonly items: readonly BatchResultItem[];
+    /** Opaque continuation token; `null`/`undefined` when the page is last. */
+    readonly nextCursor?: string | null;
+}
+export interface BatchResultsOptions {
+    readonly cursor?: string | null;
+    readonly pageSize?: number;
+    readonly signal?: AbortSignal;
+}
+export interface BatchJobsProvider {
+    readonly id: string;
+    submit(request: BatchSubmitRequest): Promise<BatchJob>;
+    status(jobId: string): Promise<BatchJob>;
+    cancel(jobId: string): Promise<BatchJob>;
+    results(jobId: string, options?: BatchResultsOptions): Promise<BatchResultsPage>;
+}
+export interface PollBatchOptions {
+    readonly intervalMs?: number;
+    /** Backoff multiplier applied per poll; caps at `maxIntervalMs`. */
+    readonly backoffMultiplier?: number;
+    readonly maxIntervalMs?: number;
+    readonly maxAttempts?: number;
+    readonly signal?: AbortSignal;
+}
+/** Poll a job until it reaches a terminal state. Plain utility — core never
+ *  calls it. Terminal failure states surface typed `BatchJobsError`s
+ *  (`job_failed` / `job_cancelled` / `job_expired`); only `completed` resolves. */
+export declare function pollBatch(provider: BatchJobsProvider, jobId: string, options?: PollBatchOptions): Promise<BatchJob>;

package/dist/contracts-core/batch.js

@@ -0,0 +1,65 @@
+export const BATCH_TERMINAL_STATES = ["completed", "failed", "cancelled", "expired"];
+export function isBatchJobTerminal(job) {
+    return BATCH_TERMINAL_STATES.includes(job.state);
+}
+export class BatchJobsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "BatchJobsError";
+        this.code = code;
+    }
+}
+export function modelSupportsBatchJobs(capabilities) {
+    return capabilities?.batchJobs === true;
+}
+export function assertBatchJobsSupported(model) {
+    if (!modelSupportsBatchJobs(model.capabilities)) {
+        throw new BatchJobsError("unsupported_model", `Model ${model.provider}/${model.model} does not declare the batchJobs capability`);
+    }
+}
+/** Poll a job until it reaches a terminal state. Plain utility — core never
+ *  calls it. Terminal failure states surface typed `BatchJobsError`s
+ *  (`job_failed` / `job_cancelled` / `job_expired`); only `completed` resolves. */
+export async function pollBatch(provider, jobId, options = {}) {
+    const intervalMs = options.intervalMs ?? 30_000;
+    const multiplier = options.backoffMultiplier ?? 1;
+    const maxIntervalMs = options.maxIntervalMs ?? intervalMs * 16;
+    const maxAttempts = options.maxAttempts ?? Number.POSITIVE_INFINITY;
+    let delay = intervalMs;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? new Error("pollBatch aborted");
+        let job;
+        try {
+            job = await provider.status(jobId);
+        }
+        catch (error) {
+            if (error instanceof BatchJobsError && error.code === "job_not_found") {
+                throw new BatchJobsError("job_not_found", `pollBatch: job ${jobId} not found`);
+            }
+            throw error;
+        }
+        if (isBatchJobTerminal(job)) {
+            if (job.state === "completed")
+                return job;
+            if (job.state === "cancelled")
+                throw new BatchJobsError("job_cancelled", `Batch job ${jobId} was cancelled`);
+            if (job.state === "expired")
+                throw new BatchJobsError("job_expired", `Batch job ${jobId} expired before completion`);
+            throw new BatchJobsError("job_failed", `Batch job ${jobId} failed: ${job.error?.message ?? "provider reported failure"}`);
+        }
+        if (attempt === maxAttempts)
+            break;
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, delay);
+            options.signal?.addEventListener("abort", () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+        delay = Math.min(delay * multiplier, maxIntervalMs);
+    }
+    throw new BatchJobsError("request_failed", `Batch job ${jobId} did not reach a terminal state within ${maxAttempts} polls`);
+}
+//# sourceMappingURL=batch.js.map

package/dist/contracts-core/content.d.ts

@@ -16,7 +16,7 @@ export interface ErrorInfo {
     readonly retryAfterMs?: number;
     readonly cause?: unknown;
 }
-export type ContentBlock = TextContent | ImageContent | AudioContent | FileContent | DocumentContent | ThinkingContent | ToolCallDeltaContent | ToolCallContent | ToolResultContent;
+export type ContentBlock = TextContent | ImageContent | AudioContent | FileContent | DocumentContent | VideoContent | ThinkingContent | ToolCallDeltaContent | ToolCallContent | ToolResultContent;
 export interface TextContent {
     readonly type: "text";
     readonly text: string;
@@ -30,6 +30,19 @@ export interface ImageContent {
     readonly name?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+export interface VideoContent {
+    readonly type: "video";
+    readonly mediaType?: string;
+    readonly name?: string;
+    /** Base64-encoded video bytes. */
+    readonly data?: string;
+    readonly url?: string;
+    readonly resourceUri?: string;
+    readonly durationMs?: number;
+    /** Frame-sampling hint for providers that downsample (e.g. Qwen-VL defaults to 2.0). */
+    readonly fps?: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
 export interface ThinkingContent {
     readonly type: "thinking";
     readonly text: string;
@@ -92,6 +105,22 @@ export interface ModelCapabilities {
     readonly streaming?: boolean;
     /** Native JSON-schema structured output support for this model. */
     readonly structuredOutput?: boolean | "json_schema";
+    /** Provider-neutral embeddings generation support (plan 061). */
+    readonly embeddings?: boolean;
+    /** Portable thinking/reasoning effort levels this model declares, ascending ladder order (`none` < `minimal` < `low` < `medium` < `high` < `xhigh` < `max`). Advisory legality metadata for hosts; absent means forward-compat passthrough (phase 65). */
+    readonly thinkingLevels?: readonly string[];
+    /** Provider-neutral speech synthesis support (plan 061). */
+    readonly speech?: boolean;
+    /** Provider-neutral speech transcription support (plan 061). */
+    readonly transcription?: boolean;
+    /** Provider-neutral image generation/editing support (plan 061). */
+    readonly imageGeneration?: boolean;
+    /** Provider-neutral video generation support (plan 061). */
+    readonly videoGeneration?: boolean;
+    /** Provider-neutral moderation classification support (plan 061). */
+    readonly moderation?: boolean;
+    /** Provider-neutral async batch-jobs support (plan 061). */
+    readonly batchJobs?: boolean;
 }
 export interface ModelLimits {
     readonly contextWindow?: number;
@@ -105,6 +134,36 @@ export interface ModelCost {
     readonly currency?: string;
     readonly unit?: string;
 }
+/** Normalized model-list/capability discovery provenance (plan 062): where a
+ *  listing came from, when, and how long hosts may cache it. */
+export interface ModelDiscoveryProvenance {
+    readonly provider: string;
+    /** ISO-8601 timestamp of the fetch (or catalog snapshot) moment. */
+    readonly fetchedAt: string;
+    /** `"api"` = live provider listing; `"catalog"` = host/registry snapshot, no network. */
+    readonly source: "api" | "catalog";
+    /** Cache-TTL guidance in milliseconds; hosts may serve the result from cache this long. */
+    readonly ttlMs?: number;
+}
+export interface ModelDiscoveryOptions {
+    /** Cache window in ms; within TTL a cached result is returned without network.
+     *  `0` forces a refresh. Defaults to the adapter's configured TTL. */
+    readonly ttlMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Normalized `listModels()` result: the existing `ModelConfig` contract verbatim
+ *  (id = `model`, context window = `limits`, capabilities = `capabilities`, pricing
+ *  hint = `cost`) plus provenance. No new model shape ships. */
+export interface ModelDiscoveryResult {
+    readonly models: readonly ModelConfig[];
+    readonly provenance: ModelDiscoveryProvenance;
+}
+/** Model-list/capability discovery seam (plan 062). Adapter implementations
+ *  normalize provider listings to `ModelConfig` and cache per provider within
+ *  the configured TTL; hosts merge their own catalog overrides on top. */
+export interface ModelDiscovery {
+    listModels(options?: ModelDiscoveryOptions): Promise<ModelDiscoveryResult>;
+}
 export interface Usage {
     readonly inputTokens?: number;
     readonly outputTokens?: number;
@@ -114,3 +173,15 @@ export interface Usage {
     readonly cost?: number;
     readonly currency?: string;
 }
+/**
+ * Host-supplied pricing adapter (plan 062): quotes cost rates per model id. Core
+ * ships no pricing tables — when no catalog is configured, usage is reported
+ * without cost fields. Quotes follow the repo-wide `per_million_tokens` unit
+ * convention (see {@link ModelCost}); a stale or unknown model must resolve to
+ * `undefined` (degrades to usage-only), never throw.
+ */
+export interface CostCatalog {
+    get(modelId: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ModelCost | undefined>;
+}

package/dist/contracts-core/embeddings.d.ts

@@ -0,0 +1,30 @@
+/** Provider-neutral embeddings contract (plan 061 Task 2).
+ *  One-shot batch shape: the request carries the abort signal, results report the
+ *  shared `Usage`. Adapters enforce provider batch caps with typed errors — they
+ *  never silently auto-chunk; callers chunk (e.g. memory's `embedBatched`).
+ *  ponytail: per-item token caps are server-enforced; the local cap is batch count. */
+import type { ModelCapabilities, ModelConfig, Usage } from "./content.js";
+export interface EmbeddingsRequest {
+    readonly model: string;
+    readonly inputs: readonly string[];
+    /** Output dimensions override; only for models that support reduced dimensions. */
+    readonly dimensions?: number;
+    readonly signal?: AbortSignal;
+}
+export interface EmbeddingsResult {
+    /** Vectors in input order; `vectors[i]` corresponds to `inputs[i]`. */
+    readonly vectors: readonly (readonly number[])[];
+    readonly usage: Usage;
+    readonly dimensions: number;
+}
+export interface EmbeddingsProvider {
+    readonly id: string;
+    embedMany(request: EmbeddingsRequest): Promise<EmbeddingsResult>;
+}
+export type EmbeddingsErrorCode = "empty_input" | "batch_too_large" | "request_failed" | "response_malformed" | "unsupported_model";
+export declare class EmbeddingsError extends Error {
+    readonly code: EmbeddingsErrorCode;
+    constructor(code: EmbeddingsErrorCode, message: string);
+}
+export declare function modelSupportsEmbeddings(capabilities?: ModelCapabilities): boolean;
+export declare function assertEmbeddingsSupported(model: ModelConfig): void;