@demicodes/provider 0.10.3 → 0.12.0

package/README.md

@@ -11,9 +11,21 @@ writing providers.
   `withProviderId`.
 - **HTTP helpers** — `redactSecretText`, `httpErrorCode`, `normalizeErrorCode`,
   `providerErrorFromUnknown`, `authStatusFromKey`, `httpRequestFailedEvent`.
+- **Quota** — optional `Provider.quota` (`ProviderQuota` / `ProviderQuotaSnapshot`),
+  `createProviderQuota`, `ensureQuota`. See
+  [docs/provider-quota.md](../../docs/provider-quota.md).
+- **Credentials** — optional `Provider.credentials` for multi-account pool + global
+  `setActive` (subscription CLIs). See
+  [docs/provider-global-credentials.md](../../docs/provider-global-credentials.md).
 
 ```ts
-import { defineProvider, zeroUsage } from '@demicodes/provider'
+import {
+  defineProvider,
+  createProviderQuota,
+  ensureQuota,
+  type ProviderCredentials,
+  type ProviderQuota,
+} from '@demicodes/provider'
 ```
 
 See [Add a Provider](../../docs/guides/add-a-provider.md). Part of

package/dist/credentials-pool.d.mts

@@ -0,0 +1,60 @@
+import { d as ProviderCredentialInfo } from "./types-Uczx0xBQ.mjs";
+//#region src/credentials-pool.d.ts
+interface CredentialEntryMeta {
+  id: string;
+  label: string;
+  detail?: string | null;
+  updatedAt: string;
+  source?: string | null;
+  /** Stable account key for upsert on re-import (email, accountId, entryKey, …). */
+  identityKey?: string | null;
+}
+interface FileCredentialPoolOptions {
+  /** Demi state root ($DEMI_HOME / ~/.demi). */
+  stateDir?: string;
+  /** Subdir under credentials/ (e.g. codex, grok-build, claude-code). */
+  providerKey: string;
+  /** Secret filename inside each entry (auth.json, oauth.json). */
+  secretFileName: string;
+}
+/**
+ * Demi local state root (`$DEMI_HOME` / `~/.demi`). Canonical copy — host-local
+ * re-exports this for its bridge layout.
+ */
+declare function resolveDemiHome(explicit?: string): string;
+declare function credentialIdFromIdentity(identityKey: string | null | undefined, fallbackLabel: string): string;
+declare function newCredentialId(): string;
+declare class FileCredentialPool {
+  readonly root: string;
+  readonly secretFileName: string;
+  constructor(options: FileCredentialPoolOptions);
+  entriesDir(): string;
+  entryDir(id: string): string;
+  metaPath(id: string): string;
+  secretPath(id: string): string;
+  activePath(): string;
+  list(): Promise<ProviderCredentialInfo[]>;
+  listMeta(): Promise<CredentialEntryMeta[]>;
+  readMeta(id: string): Promise<CredentialEntryMeta | null>;
+  getActiveId(): Promise<string | null>;
+  setActiveId(id: string): Promise<void>;
+  clearActive(): Promise<void>;
+  writeEntry(meta: CredentialEntryMeta, secretText: string): Promise<CredentialEntryMeta>;
+  readSecretText(id: string): Promise<string>;
+  remove(id: string): Promise<void>;
+  private tmpPath;
+  /**
+   * Serializes pool mutations across processes with a create-exclusive lock
+   * file; stale locks (mtime older than 30s) are removed.
+   */
+  private withWriteLock;
+  findByIdentityKey(identityKey: string): Promise<CredentialEntryMeta | null>;
+  /** If active missing but entries exist, pick first and repair active pointer. */
+  ensureActivePointer(): Promise<string | null>;
+}
+declare class CredentialPoolError extends Error {
+  readonly code: 'credential_not_found' | 'credential_invalid';
+  constructor(code: 'credential_not_found' | 'credential_invalid', message: string);
+}
+//#endregion
+export { CredentialEntryMeta, CredentialPoolError, FileCredentialPool, FileCredentialPoolOptions, credentialIdFromIdentity, newCredentialId, resolveDemiHome };

package/dist/credentials-pool.mjs

@@ -0,0 +1,206 @@
+import { errorCode, isRecord, nonEmptyString } from "@demicodes/utils";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+//#region src/credentials-pool.ts
+/**
+* Demi multi-credential pool on disk:
+*   <stateDir>/credentials/<providerKey>/{active,entries/<id>/{meta.json,secret}}
+*/
+/**
+* Demi local state root (`$DEMI_HOME` / `~/.demi`). Canonical copy — host-local
+* re-exports this for its bridge layout.
+*/
+function resolveDemiHome(explicit) {
+	if (explicit && explicit.trim()) return resolve(explicit.trim());
+	const fromEnv = process.env.DEMI_HOME;
+	if (fromEnv && fromEnv.trim()) return resolve(fromEnv.trim());
+	return join(homedir(), ".demi");
+}
+function credentialIdFromIdentity(identityKey, fallbackLabel) {
+	const basis = nonEmptyString(identityKey) ?? fallbackLabel;
+	return `cred-${createHash("sha256").update(basis).digest("hex").slice(0, 16)}`;
+}
+function newCredentialId() {
+	return `cred-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+var FileCredentialPool = class {
+	root;
+	secretFileName;
+	constructor(options) {
+		const stateDir = resolveDemiHome(options.stateDir);
+		this.root = join(stateDir, "credentials", options.providerKey);
+		this.secretFileName = options.secretFileName;
+	}
+	entriesDir() {
+		return join(this.root, "entries");
+	}
+	entryDir(id) {
+		return join(this.entriesDir(), id);
+	}
+	metaPath(id) {
+		return join(this.entryDir(id), "meta.json");
+	}
+	secretPath(id) {
+		return join(this.entryDir(id), this.secretFileName);
+	}
+	activePath() {
+		return join(this.root, "active");
+	}
+	async list() {
+		return (await this.listMeta()).map((m) => ({
+			id: m.id,
+			label: m.label,
+			detail: m.detail ?? null,
+			updatedAt: m.updatedAt
+		}));
+	}
+	async listMeta() {
+		let names;
+		try {
+			names = await readdir(this.entriesDir());
+		} catch {
+			return [];
+		}
+		const out = [];
+		for (const name of names) {
+			const meta = await this.readMeta(name);
+			if (meta) out.push(meta);
+		}
+		out.sort((a, b) => a.id.localeCompare(b.id));
+		return out;
+	}
+	async readMeta(id) {
+		try {
+			const raw = JSON.parse(await readFile(this.metaPath(id), "utf8"));
+			if (!isRecord(raw)) return null;
+			const entryId = nonEmptyString(raw.id) ?? id;
+			const label = nonEmptyString(raw.label);
+			if (!label) return null;
+			return {
+				id: entryId,
+				label,
+				detail: nonEmptyString(raw.detail) ?? null,
+				updatedAt: nonEmptyString(raw.updatedAt) ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+				source: nonEmptyString(raw.source) ?? null,
+				identityKey: nonEmptyString(raw.identityKey) ?? null
+			};
+		} catch {
+			return null;
+		}
+	}
+	async getActiveId() {
+		try {
+			const id = (await readFile(this.activePath(), "utf8")).trim();
+			if (!id) return null;
+			return await this.readMeta(id) ? id : null;
+		} catch {
+			return null;
+		}
+	}
+	async setActiveId(id) {
+		if (!await this.readMeta(id)) throw new CredentialPoolError("credential_not_found", `Credential "${id}" not found`);
+		try {
+			await readFile(this.secretPath(id), "utf8");
+		} catch {
+			throw new CredentialPoolError("credential_not_found", `Credential "${id}" has no secret material`);
+		}
+		await this.withWriteLock(async () => {
+			const tmp = this.tmpPath(this.activePath());
+			await writeFile(tmp, `${id}\n`, { mode: 384 });
+			await rename(tmp, this.activePath());
+		});
+	}
+	async clearActive() {
+		await rm(this.activePath(), { force: true }).catch(() => void 0);
+	}
+	async writeEntry(meta, secretText) {
+		return this.withWriteLock(async () => {
+			const dir = this.entryDir(meta.id);
+			await mkdir(dir, {
+				recursive: true,
+				mode: 448
+			});
+			const secretTmp = this.tmpPath(this.secretPath(meta.id));
+			const metaTmp = this.tmpPath(this.metaPath(meta.id));
+			await writeFile(secretTmp, secretText, { mode: 384 });
+			await chmod(secretTmp, 384).catch(() => void 0);
+			await rename(secretTmp, this.secretPath(meta.id));
+			await writeFile(metaTmp, `${JSON.stringify(meta, null, 2)}\n`, { mode: 384 });
+			await rename(metaTmp, this.metaPath(meta.id));
+			return meta;
+		});
+	}
+	async readSecretText(id) {
+		return readFile(this.secretPath(id), "utf8");
+	}
+	async remove(id) {
+		await this.withWriteLock(async () => {
+			const active = await this.getActiveId();
+			await rm(this.entryDir(id), {
+				recursive: true,
+				force: true
+			});
+			if (active === id) await this.clearActive();
+		});
+	}
+	tmpPath(target) {
+		return `${target}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+	}
+	/**
+	* Serializes pool mutations across processes with a create-exclusive lock
+	* file; stale locks (mtime older than 30s) are removed.
+	*/
+	async withWriteLock(fn) {
+		await mkdir(this.root, {
+			recursive: true,
+			mode: 448
+		});
+		const lockPath = join(this.root, ".lock");
+		const started = Date.now();
+		while (true) try {
+			await writeFile(lockPath, `${process.pid}\n`, {
+				flag: "wx",
+				mode: 384
+			});
+			break;
+		} catch (error) {
+			if (errorCode(error) !== "EEXIST") throw error;
+			const info = await stat(lockPath).catch(() => null);
+			if (info && Date.now() - info.mtimeMs > 3e4) {
+				await rm(lockPath, { force: true }).catch(() => void 0);
+				continue;
+			}
+			if (Date.now() - started > 5e3) throw new CredentialPoolError("credential_invalid", `Timed out waiting for credential pool lock ${lockPath}`);
+			await new Promise((resolve) => setTimeout(resolve, 25));
+		}
+		try {
+			return await fn();
+		} finally {
+			await rm(lockPath, { force: true }).catch(() => void 0);
+		}
+	}
+	async findByIdentityKey(identityKey) {
+		return (await this.listMeta()).find((m) => m.identityKey === identityKey) ?? null;
+	}
+	/** If active missing but entries exist, pick first and repair active pointer. */
+	async ensureActivePointer() {
+		const active = await this.getActiveId();
+		if (active) return active;
+		const all = await this.listMeta();
+		if (all.length === 0) return null;
+		await this.setActiveId(all[0].id);
+		return all[0].id;
+	}
+};
+var CredentialPoolError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "CredentialPoolError";
+	}
+};
+//#endregion
+export { CredentialPoolError, FileCredentialPool, credentialIdFromIdentity, newCredentialId, resolveDemiHome };

package/dist/index.d.mts

@@ -1,6 +1,12 @@
-import { A as ProviderQuotaSnapshot, B as usedPercentFromRatio, C as ProviderQuotaCapability, D as ProviderQuotaProbeOptions, E as ProviderQuotaProbeCost, F as clampUsedPercent, I as createProviderQuota, L as ensureQuota, M as ProviderQuotaUnsupportedError, N as ProviderQuotaWindow, O as ProviderQuotaProbeResult, P as ProviderQuotaWindowUnit, R as severityFromUsedPercent, S as ProviderQuota, T as ProviderQuotaPlan, _ as ProviderSelection, a as ModelPolicy, b as CreateProviderQuotaOptions, c as ProviderAuthState, d as ProviderModel, f as ProviderModelCost, g as ProviderRuntimeState, h as ProviderRuntimeFactory, i as InferenceSteer, j as ProviderQuotaSource, k as ProviderQuotaSeverity, l as ProviderEvent, m as ProviderRun, n as InferenceItem, o as Provider, p as ProviderModelList, r as InferenceRequest, s as ProviderAuth, t as AgentProvider, u as ProviderFactoryDefinition, v as ProviderServiceTier, w as ProviderQuotaObserveInput, x as EnsureQuotaOptions, y as ToolDefinition, z as unixSecondsToIso } from "./types-jho3Wgsx.mjs";
-import { FileExtension, ModelSelection, ThinkingCapability, ThinkingConfig } from "@demicodes/core";
-
+import { A as ProviderQuota, B as ProviderQuotaUnsupportedError, C as ProviderRuntimeFactory, D as ToolDefinition, E as ProviderServiceTier, F as ProviderQuotaProbeOptions, G as ensureQuota, H as ProviderQuotaWindowUnit, I as ProviderQuotaProbeResult, J as usedPercentFromRatio, K as severityFromUsedPercent, L as ProviderQuotaSeverity, M as ProviderQuotaObserveInput, N as ProviderQuotaPlan, O as CreateProviderQuotaOptions, P as ProviderQuotaProbeCost, R as ProviderQuotaSnapshot, S as ProviderRun, T as ProviderSelection, U as clampUsedPercent, V as ProviderQuotaWindow, W as createProviderQuota, _ as ProviderEvent, a as ModelPolicy, b as ProviderModelCost, c as ProviderAuthState, d as ProviderCredentialInfo, f as ProviderCredentialLoginOptions, g as ProviderCredentialsCapability, h as ProviderCredentials, i as InferenceSteer, j as ProviderQuotaCapability, k as EnsureQuotaOptions, l as ProviderCredentialActive, m as ProviderCredentialLoginResult, n as InferenceItem, o as Provider, p as ProviderCredentialLoginPending, q as unixSecondsToIso, r as InferenceRequest, s as ProviderAuth, t as AgentProvider, u as ProviderCredentialAddInput, v as ProviderFactoryDefinition, w as ProviderRuntimeState, x as ProviderModelList, y as ProviderModel, z as ProviderQuotaSource } from "./types-Uczx0xBQ.mjs";
+import { FileExtension, ModelSelection, ThinkingCapability, ThinkingConfig, ToolResultContentBlock } from "@demicodes/core";
+//#region src/content.d.ts
+/**
+ * Flattens a tool result to plain text for wire formats without native media
+ * blocks; non-text blocks become `[<type>:<mediaType>]` placeholders.
+ */
+declare function toolResultContentToText(output: ToolResultContentBlock[]): string;
+//#endregion
 //#region src/provider.d.ts
 declare function defineProvider(definition: ProviderFactoryDefinition): Provider;
 declare function providerRuntime(provider: Provider, selection: ProviderSelection): Promise<AgentProvider> | AgentProvider;
@@ -41,6 +47,8 @@ type HeadersResolver = () => Record<string, string> | Promise<Record<string, str
 declare function clampPromptCacheKey(value: string): string;
 /** Replaces every occurrence of `secret` in `value` with a redaction marker. */
 declare function redactSecretText(value: string, secret: string | null | undefined): string;
+/** Masks bearer tokens and named credential fields in free-form auth error text. */
+declare function redactCredentialText(text: string, extraFieldPatterns?: readonly string[]): string;
 /** Maps an HTTP status (and response text) to a coarse provider error code. */
 declare function httpErrorCode(status: number, message: string): string | null;
 /** Classifies a provider error code/message into a coarse category, falling back to `code`. */
@@ -51,7 +59,9 @@ declare function providerErrorFromUnknown(error: unknown, secret: string | null
 declare function authStatusFromKey(resolveKey: SecretResolver, resolveHeaders: HeadersResolver | undefined, authHeader: string, providerLabel: string): Promise<ProviderAuthState>;
 /** Parses a Retry-After header (delta-seconds or HTTP-date) into milliseconds. */
 declare function retryAfterMsFromHeader(value: string | null): number | undefined;
+/** Reads a header as a finite number, or null when absent/blank/non-numeric. */
+declare function numberHeader(headers: Headers, name: string): number | null;
 /** Builds a redacted provider `error` event from a failed HTTP response. */
 declare function httpRequestFailedEvent(response: Response, secret: string | null | undefined, providerLabel: string): Promise<ProviderEvent>;
 //#endregion
-export { AgentProvider, type CreateProviderQuotaOptions, DEFAULT_ATTACHMENT_EXTENSIONS, type EnsureQuotaOptions, InferenceItem, InferenceRequest, InferenceSteer, ModelPolicy, type ModelSelectionFromCatalogOptions, Provider, ProviderAuth, ProviderAuthState, ProviderEvent, ProviderFactoryDefinition, ProviderModel, ProviderModelCost, ProviderModelList, type ProviderQuota, type ProviderQuotaCapability, type ProviderQuotaObserveInput, type ProviderQuotaPlan, type ProviderQuotaProbeCost, type ProviderQuotaProbeOptions, type ProviderQuotaProbeResult, type ProviderQuotaSeverity, type ProviderQuotaSnapshot, type ProviderQuotaSource, ProviderQuotaUnsupportedError, type ProviderQuotaWindow, type ProviderQuotaWindowUnit, ProviderRun, ProviderRuntimeFactory, ProviderRuntimeState, ProviderSelection, ProviderServiceTier, ToolDefinition, applyModelPolicy, authStatusFromKey, clampPromptCacheKey, clampUsedPercent, createProviderQuota, defineProvider, ensureQuota, httpErrorCode, httpRequestFailedEvent, modelSelectionFromCatalog, normalizeErrorCode, providerErrorFromUnknown, providerRuntime, redactSecretText, retryAfterMsFromHeader, severityFromUsedPercent, thinkingCapabilitiesFromProviderModel, unixSecondsToIso, usedPercentFromRatio, withProviderId };
+export { AgentProvider, type CreateProviderQuotaOptions, DEFAULT_ATTACHMENT_EXTENSIONS, type EnsureQuotaOptions, InferenceItem, InferenceRequest, InferenceSteer, ModelPolicy, type ModelSelectionFromCatalogOptions, Provider, ProviderAuth, ProviderAuthState, ProviderCredentialActive, ProviderCredentialAddInput, ProviderCredentialInfo, ProviderCredentialLoginOptions, ProviderCredentialLoginPending, ProviderCredentialLoginResult, ProviderCredentials, ProviderCredentialsCapability, ProviderEvent, ProviderFactoryDefinition, ProviderModel, ProviderModelCost, ProviderModelList, type ProviderQuota, type ProviderQuotaCapability, type ProviderQuotaObserveInput, type ProviderQuotaPlan, type ProviderQuotaProbeCost, type ProviderQuotaProbeOptions, type ProviderQuotaProbeResult, type ProviderQuotaSeverity, type ProviderQuotaSnapshot, type ProviderQuotaSource, ProviderQuotaUnsupportedError, type ProviderQuotaWindow, type ProviderQuotaWindowUnit, ProviderRun, ProviderRuntimeFactory, ProviderRuntimeState, ProviderSelection, ProviderServiceTier, ToolDefinition, applyModelPolicy, authStatusFromKey, clampPromptCacheKey, clampUsedPercent, createProviderQuota, defineProvider, ensureQuota, httpErrorCode, httpRequestFailedEvent, modelSelectionFromCatalog, normalizeErrorCode, numberHeader, providerErrorFromUnknown, providerRuntime, redactCredentialText, redactSecretText, retryAfterMsFromHeader, severityFromUsedPercent, thinkingCapabilitiesFromProviderModel, toolResultContentToText, unixSecondsToIso, usedPercentFromRatio, withProviderId };

package/dist/index.mjs

@@ -1,4 +1,14 @@
+import { VIDEO_FILE_EXTENSIONS } from "@demicodes/core";
 import { shortHash } from "@demicodes/utils";
+//#region src/content.ts
+/**
+* Flattens a tool result to plain text for wire formats without native media
+* blocks; non-text blocks become `[<type>:<mediaType>]` placeholders.
+*/
+function toolResultContentToText(output) {
+	return output.map((block) => block.type === "text" ? block.text : `[${block.type}:${block.source.mediaType}]`).join("\n");
+}
+//#endregion
 //#region src/provider.ts
 const runtimeFactorySymbol = Symbol("demi.provider.runtimeFactory");
 function defineProvider(definition) {
@@ -89,7 +99,7 @@ function modelSelectionFromCatalog(providerId, model, options = {}) {
 			contextWindow: model?.contextWindow ?? 0,
 			inputLimit: null,
 			thinking: thinkingCapabilitiesFromProviderModel(model),
-			acceptedExtensions: model?.supportsAttachments ? [...accepted] : []
+			acceptedExtensions: [...model?.supportsAttachments ? accepted : [], ...model?.supportsVideo ? VIDEO_FILE_EXTENSIONS : []]
 		},
 		thinking: options.thinking ?? null,
 		serviceTierId: options.serviceTierId ?? null
@@ -108,10 +118,21 @@ function clampPromptCacheKey(value) {
 function redactSecretText(value, secret) {
 	return secret ? value.split(secret).join("[redacted]") : value;
 }
+/** Masks bearer tokens and named credential fields in free-form auth error text. */
+function redactCredentialText(text, extraFieldPatterns = []) {
+	const fields = [
+		"access_token",
+		"refresh_token",
+		"id_token",
+		...extraFieldPatterns
+	];
+	return text.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/g, "Bearer [REDACTED]").replace(new RegExp(`(${fields.join("|")})["'=:\\s]+[A-Za-z0-9._~+/=-]+`, "gi"), "$1=[REDACTED]");
+}
 /** Maps an HTTP status (and response text) to a coarse provider error code. */
 function httpErrorCode(status, message) {
 	if (status === 401 || status === 403) return "auth_expired";
-	if (status === 408 || status === 409 || status === 425 || status === 429 || status >= 500) return "rate_limit";
+	if (status === 429) return "rate_limit";
+	if (status === 408 || status === 409 || status === 425 || status >= 500) return "overloaded";
 	if (status === 400 && /context|too long|token/i.test(message)) return "context_length_exceeded";
 	return null;
 }
@@ -119,9 +140,9 @@ function httpErrorCode(status, message) {
 function normalizeErrorCode(code, message) {
 	const value = `${code ?? ""} ${message}`.toLowerCase();
 	if (/context|too long|max.*token/.test(value)) return "context_length_exceeded";
-	if (/rate|quota|billing|limit/.test(value)) return "rate_limit";
-	if (/auth|unauth|invalid.*key|expired/.test(value)) return "auth_expired";
-	if (/overload|unavailable|timeout/.test(value)) return "overloaded";
+	if (/rate|quota|usage|billing|balance|limit/.test(value)) return "rate_limit";
+	if (/\bauth(?:entication|orization)?\b/.test(value) || /(?:invalid|expired).*(?:api|access|auth)[_\s-]*(?:key|token)/.test(value) || /(?:api|access|auth)[_\s-]*(?:key|token).*(?:invalid|expired)/.test(value)) return "auth_expired";
+	if (/overload|unavailable|(?:server|internal|api)[_\s-]*error|timed?\s?out|fetch failed|network|socket|econn/.test(value)) return "overloaded";
 	return code;
 }
 /** Builds a provider `error` event from an unknown thrown value, redacting `secret`. */
@@ -150,6 +171,13 @@ function retryAfterMsFromHeader(value) {
 	const dateMs = Date.parse(value);
 	if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
 }
+/** Reads a header as a finite number, or null when absent/blank/non-numeric. */
+function numberHeader(headers, name) {
+	const raw = headers.get(name);
+	if (raw == null || raw === "") return null;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : null;
+}
 /** Builds a redacted provider `error` event from a failed HTTP response. */
 async function httpRequestFailedEvent(response, secret, providerLabel) {
 	const text = await response.text().catch(() => "");
@@ -207,13 +235,14 @@ function createProviderQuota(options) {
 		};
 	};
 	const materialize = (partial, source) => {
+		const previous = source === "observation" ? latest : null;
 		const snapshot = {
 			providerId: options.providerId,
 			observedAt: (/* @__PURE__ */ new Date()).toISOString(),
 			source,
-			plan: partial.plan ?? null,
-			accountLabel: partial.accountLabel ?? null,
-			windows: partial.windows,
+			plan: partial.plan === void 0 ? previous?.plan ?? null : partial.plan,
+			accountLabel: partial.accountLabel === void 0 ? previous?.accountLabel ?? null : partial.accountLabel,
+			windows: previous ? mergeQuotaWindows(previous.windows, partial.windows) : partial.windows,
 			raw: partial.raw
 		};
 		latest = snapshot;
@@ -222,9 +251,13 @@ function createProviderQuota(options) {
 	const quota = {
 		capability,
 		latest: () => latest,
+		clearLatest: () => {
+			latest = null;
+		},
 		async probe(probeOptions = {}) {
 			if (!options.canProbe) throw new ProviderQuotaUnsupportedError(options.providerId);
-			return materialize(await options.probe(probeOptions), "probe");
+			const partial = await options.probe(probeOptions);
+			return materialize(partial, "probe");
 		}
 	};
 	if (options.observe) {
@@ -237,6 +270,13 @@ function createProviderQuota(options) {
 	}
 	return quota;
 }
+function mergeQuotaWindows(previous, observed) {
+	const observedById = new Map(observed.map((window) => [window.id, window]));
+	const merged = previous.map((window) => observedById.get(window.id) ?? window);
+	const previousIds = new Set(previous.map((window) => window.id));
+	for (const window of observed) if (!previousIds.has(window.id)) merged.push(window);
+	return merged;
+}
 /** Clamp percent into 0–100 or null. */
 function clampUsedPercent(value) {
 	if (typeof value !== "number" || !Number.isFinite(value)) return null;
@@ -269,4 +309,4 @@ function severityFromUsedPercent(usedPercent) {
 	return "normal";
 }
 //#endregion
-export { DEFAULT_ATTACHMENT_EXTENSIONS, ProviderQuotaUnsupportedError, applyModelPolicy, authStatusFromKey, clampPromptCacheKey, clampUsedPercent, createProviderQuota, defineProvider, ensureQuota, httpErrorCode, httpRequestFailedEvent, modelSelectionFromCatalog, normalizeErrorCode, providerErrorFromUnknown, providerRuntime, redactSecretText, retryAfterMsFromHeader, severityFromUsedPercent, thinkingCapabilitiesFromProviderModel, unixSecondsToIso, usedPercentFromRatio, withProviderId };
+export { DEFAULT_ATTACHMENT_EXTENSIONS, ProviderQuotaUnsupportedError, applyModelPolicy, authStatusFromKey, clampPromptCacheKey, clampUsedPercent, createProviderQuota, defineProvider, ensureQuota, httpErrorCode, httpRequestFailedEvent, modelSelectionFromCatalog, normalizeErrorCode, numberHeader, providerErrorFromUnknown, providerRuntime, redactCredentialText, redactSecretText, retryAfterMsFromHeader, severityFromUsedPercent, thinkingCapabilitiesFromProviderModel, toolResultContentToText, unixSecondsToIso, usedPercentFromRatio, withProviderId };

package/dist/testing.d.mts

@@ -1,5 +1,4 @@
-import { i as InferenceSteer, l as ProviderEvent, m as ProviderRun, r as InferenceRequest, t as AgentProvider } from "./types-jho3Wgsx.mjs";
-
+import { S as ProviderRun, _ as ProviderEvent, i as InferenceSteer, r as InferenceRequest, t as AgentProvider } from "./types-Uczx0xBQ.mjs";
 //#region src/testing.d.ts
 /**
  * Scripted provider for testing. Each "turn" is a list of events to yield.
@@ -20,6 +19,7 @@ declare class StubProvider implements AgentProvider {
   private turns;
   private cursor;
   constructor(turns: TurnScript[]);
+  clone(): AgentProvider;
   run(request: InferenceRequest): AsyncIterable<ProviderEvent>;
   /** Number of turns consumed so far. Useful for assertions. */
   get consumedTurns(): number;

package/dist/testing.mjs

@@ -20,6 +20,12 @@ var StubProvider = class {
 	constructor(turns) {
 		this.turns = turns;
 	}
+	clone() {
+		return {
+			run: (request) => this.run(request),
+			clone: () => this.clone()
+		};
+	}
 	async *run(request) {
 		const turn = this.turns[this.cursor];
 		this.cursor += 1;

package/dist/{types-jho3Wgsx.d.mts → types-Uczx0xBQ.d.mts}

@@ -1,5 +1,4 @@
-import { ModelSelection, ThinkingConfig, ThinkingEffort, TokenUsage, ToolResultContentBlock, UserContentBlock } from "@demicodes/core";
-
+import { ModelSelection, ProviderErrorDiagnostics, ThinkingConfig, ThinkingEffort, TokenUsage, ToolResultContentBlock, UserContentBlock } from "@demicodes/core";
 //#region src/quota.d.ts
 /**
  * Unified subscription / rate-limit quota surface for concrete providers.
@@ -50,7 +49,8 @@ type ProviderQuotaCapability = {
 } | {
   mode: 'supported';
   canProbe: boolean;
-  canObserve: boolean; /** free = dedicated usage API; minimal_request = burns a tiny inference */
+  canObserve: boolean;
+  /** free = dedicated usage API; minimal_request = burns a tiny inference */
   probeCost?: ProviderQuotaProbeCost;
   staleAfterMs?: number;
 };
@@ -73,6 +73,11 @@ interface ProviderQuota {
   capability(): ProviderQuotaCapability;
   probe(options?: ProviderQuotaProbeOptions): Promise<ProviderQuotaSnapshot>;
   latest(): ProviderQuotaSnapshot | null;
+  /**
+   * Drop the in-memory latest snapshot (e.g. after credentials.setActive so the
+   * next ensureQuota/probe does not show the previous account).
+   */
+  clearLatest?(): void;
   /**
    * Optional passive update from a vendor HTTP response (headers, etc.).
    * Returns the new snapshot when observation succeeded; otherwise null.
@@ -201,13 +206,24 @@ type ProviderEvent = {
   toolUseId: string;
   toolName: string;
   input: unknown;
-} | {
+} |
+/**
+ * End of a model response. `usage` MUST be the usage of a single API request
+ * — the final one when the provider made several internally (e.g. a CLI turn
+ * with tool calls). The agent anchors its context-size estimation on it
+ * (input + output + cache reads/writes ≈ the context the next request will
+ * carry), so a turn-cumulative total here inflates the estimate and triggers
+ * spurious compaction.
+ */
+{
   type: 'response';
   usage: TokenUsage;
 } | {
   type: 'error';
   message: string;
-  code: string | null; /** Server-suggested retry delay (e.g. from a Retry-After header), if any. */
+  code: string | null;
+  diagnostics?: ProviderErrorDiagnostics;
+  /** Server-suggested retry delay (e.g. from a Retry-After header), if any. */
   retryAfterMs?: number;
 } | {
   type: 'abort';
@@ -223,6 +239,14 @@ interface ProviderRun extends AsyncIterable<ProviderEvent> {
 }
 interface AgentProvider {
   run(request: InferenceRequest): ProviderRun;
+  /**
+   * Creates an independent runtime with the same provider configuration.
+   *
+   * Configuration dependencies such as auth stores and quota observers may be
+   * shared, but mutable per-session execution state (subprocesses, sockets,
+   * pending tool calls, and continuation state) must not be shared.
+   */
+  clone(): AgentProvider;
   /**
    * Releases any resources the provider holds open across turns — e.g. a long-lived CLI
    * subprocess kept alive for a whole session. Called once when the owning session closes.
@@ -249,6 +273,113 @@ type ProviderAuthState = {
 interface ProviderAuth {
   status(): Promise<ProviderAuthState> | ProviderAuthState;
 }
+/** Public metadata only — never tokens, cookies, or raw auth files. */
+interface ProviderCredentialInfo {
+  /** Stable id within this provider (not globally unique across providers). */
+  id: string;
+  /** Human label: email, account id, or import tag. */
+  label: string;
+  /** Optional secondary display (plan name, issuer, …). */
+  detail?: string | null;
+  /** ISO-8601 when this entry was last imported or refreshed in the pool. */
+  updatedAt?: string | null;
+}
+interface ProviderCredentialActive {
+  credentialId: string | null;
+  /** Same shape as auth status, for the active credential. */
+  status: ProviderAuthState;
+}
+/**
+ * User-facing material issued mid-flow by a device-code login: the product
+ * relays it to the user, who completes login from any browser on any device.
+ */
+interface ProviderCredentialLoginPending {
+  /** URL the user opens to confirm the login. */
+  verificationUrl: string;
+  /** One-time code the user enters at the verification URL (device-code flows). */
+  userCode?: string | null;
+  /** ISO-8601 expiry of the code, when the vendor exposes one. */
+  expiresAt?: string | null;
+  /**
+   * True when the vendor displays a code AFTER approval that the user must
+   * bring back; the product collects it via `promptForCode`.
+   */
+  requiresCodeInput?: boolean;
+}
+interface ProviderCredentialLoginOptions {
+  /** Abort the login flow. */
+  signal?: AbortSignal;
+  /** Fires once when the flow issues user-facing material (device-code login). */
+  onPending?: (pending: ProviderCredentialLoginPending) => void;
+  /** Collects the code the user copied back from the vendor page (`requiresCodeInput` flows). */
+  promptForCode?: () => Promise<string>;
+}
+/**
+ * Login invoke result. Every login flow runs the vendor's public protocol
+ * natively, imports the resulting material into the pool, and returns the
+ * pool `credentialId`.
+ */
+type ProviderCredentialLoginResult = {
+  status: 'completed';
+  credentialId: string;
+} | {
+  status: 'cancelled';
+} | {
+  status: 'unavailable';
+  message: string;
+} | {
+  status: 'failed';
+  message: string;
+};
+/**
+ * Provider-specific add payloads. Concrete packages document accepted variants.
+ * Do not put secrets on browser-visible control protocols.
+ */
+type ProviderCredentialAddInput = {
+  [key: string]: unknown;
+};
+type ProviderCredentialsCapability = {
+  mode: 'none';
+} | {
+  mode: 'supported';
+  /** Can run the vendor's native login flow (`beginLogin`). */
+  canBeginLogin?: boolean;
+  /** Can import from the vendor default location into the pool. */
+  canImportDefault?: boolean;
+  /** Can register externally supplied material (`add`). */
+  canAdd?: boolean;
+  /** Pool can hold more than one credential. */
+  multi?: boolean;
+};
+/**
+ * Multi-credential pool + process-global active switch.
+ * See `docs/provider-global-credentials.md`.
+ */
+interface ProviderCredentials {
+  capability(): ProviderCredentialsCapability;
+  list(): Promise<ProviderCredentialInfo[]> | ProviderCredentialInfo[];
+  getActive(): Promise<ProviderCredentialActive> | ProviderCredentialActive;
+  /**
+   * Make `credentialId` the process-global active credential for this provider.
+   * Subsequent auth / quota / inference use it.
+   */
+  setActive(credentialId: string): Promise<ProviderCredentialActive> | ProviderCredentialActive;
+  /**
+   * Run the vendor's public login protocol natively (device code or copy-back
+   * OAuth), surfacing user-facing material via `onPending`. On completion the
+   * material is imported into the pool and its `credentialId` is returned.
+   */
+  beginLogin?(options?: ProviderCredentialLoginOptions): Promise<ProviderCredentialLoginResult>;
+  /**
+   * Snapshot current vendor-default material into the demi pool.
+   * Assigns a stable `id` and returns public metadata (no secrets).
+   */
+  importDefault?(): Promise<ProviderCredentialInfo>;
+  /** Register material supplied by the product. */
+  add?(input: ProviderCredentialAddInput): Promise<ProviderCredentialInfo>;
+  /** Remove a pool entry. */
+  remove?(credentialId: string): Promise<void>;
+}
 type ProviderRuntimeState = {
   status: 'unknown';
   message?: string;
@@ -268,6 +399,8 @@ interface Provider {
   auth?: ProviderAuth;
   /** Optional subscription / rate-limit quota surface (`@demicodes/provider` quota helpers). */
   quota?: ProviderQuota;
+  /** Optional multi-credential pool + global active switch. */
+  credentials?: ProviderCredentials;
   state?(): Promise<ProviderRuntimeState> | ProviderRuntimeState;
   listModels?(): Promise<ProviderModelList> | ProviderModelList;
 }
@@ -297,6 +430,10 @@ interface ProviderModel {
   outputLimit: number | null;
   supportsTools: boolean | null;
   supportsAttachments: boolean | null;
+  /** Whether the model accepts native video input (not frame extraction). Most models
+   *  (all current Anthropic/Claude Code models) do not — their API has no video block.
+   *  Optional: unset/undefined means "no video", so existing catalogs need no change. */
+  supportsVideo?: boolean | null;
   supportsReasoning: boolean | null;
   supportedThinkingEfforts: ThinkingEffort[] | null;
   defaultThinkingEffort: ThinkingEffort | null;
@@ -324,4 +461,4 @@ type ModelPolicy = {
   default?: string;
 };
 //#endregion
-export { ProviderQuotaSnapshot as A, usedPercentFromRatio as B, ProviderQuotaCapability as C, ProviderQuotaProbeOptions as D, ProviderQuotaProbeCost as E, clampUsedPercent as F, createProviderQuota as I, ensureQuota as L, ProviderQuotaUnsupportedError as M, ProviderQuotaWindow as N, ProviderQuotaProbeResult as O, ProviderQuotaWindowUnit as P, severityFromUsedPercent as R, ProviderQuota as S, ProviderQuotaPlan as T, ProviderSelection as _, ModelPolicy as a, CreateProviderQuotaOptions as b, ProviderAuthState as c, ProviderModel as d, ProviderModelCost as f, ProviderRuntimeState as g, ProviderRuntimeFactory as h, InferenceSteer as i, ProviderQuotaSource as j, ProviderQuotaSeverity as k, ProviderEvent as l, ProviderRun as m, InferenceItem as n, Provider as o, ProviderModelList as p, InferenceRequest as r, ProviderAuth as s, AgentProvider as t, ProviderFactoryDefinition as u, ProviderServiceTier as v, ProviderQuotaObserveInput as w, EnsureQuotaOptions as x, ToolDefinition as y, unixSecondsToIso as z };
+export { ProviderQuota as A, ProviderQuotaUnsupportedError as B, ProviderRuntimeFactory as C, ToolDefinition as D, ProviderServiceTier as E, ProviderQuotaProbeOptions as F, ensureQuota as G, ProviderQuotaWindowUnit as H, ProviderQuotaProbeResult as I, usedPercentFromRatio as J, severityFromUsedPercent as K, ProviderQuotaSeverity as L, ProviderQuotaObserveInput as M, ProviderQuotaPlan as N, CreateProviderQuotaOptions as O, ProviderQuotaProbeCost as P, ProviderQuotaSnapshot as R, ProviderRun as S, ProviderSelection as T, clampUsedPercent as U, ProviderQuotaWindow as V, createProviderQuota as W, ProviderEvent as _, ModelPolicy as a, ProviderModelCost as b, ProviderAuthState as c, ProviderCredentialInfo as d, ProviderCredentialLoginOptions as f, ProviderCredentialsCapability as g, ProviderCredentials as h, InferenceSteer as i, ProviderQuotaCapability as j, EnsureQuotaOptions as k, ProviderCredentialActive as l, ProviderCredentialLoginResult as m, InferenceItem as n, Provider as o, ProviderCredentialLoginPending as p, unixSecondsToIso as q, InferenceRequest as r, ProviderAuth as s, AgentProvider as t, ProviderCredentialAddInput as u, ProviderFactoryDefinition as v, ProviderRuntimeState as w, ProviderModelList as x, ProviderModel as y, ProviderQuotaSource as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/provider",
   "description": "Provider contract and shared building blocks for Demi inference adapters.",
-  "version": "0.10.3",
+  "version": "0.12.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,11 +12,15 @@
     "./testing": {
       "types": "./dist/testing.d.mts",
       "import": "./dist/testing.mjs"
+    },
+    "./credentials-pool": {
+      "types": "./dist/credentials-pool.d.mts",
+      "import": "./dist/credentials-pool.mjs"
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.10.3",
-    "@demicodes/utils": "^0.10.3"
+    "@demicodes/core": "^0.12.0",
+    "@demicodes/utils": "^0.12.0"
   },
   "license": "Apache-2.0",
   "main": "./dist/index.mjs",