@arnilo/prism 0.5.5 → 0.6.0

package/dist/content.js

@@ -1,7 +1,13 @@
 import { lookup as dnsLookup } from "node:dns/promises";
 import { isIP } from "node:net";
+import { assertSsrfAllowedUrl, isAllowedByCidr, isBlockedIp, MediaContentError, normalizeHostname, } from "./media-types.js";
 import { pinnedFetch } from "./pinned-fetch.js";
 import { assertPermission } from "./security.js";
+// SSRF policy, host/address types, `MediaContentError`, and the URL gate live in the leaf
+// module shared with `pinned-fetch.ts` (plan 070 Task 10); re-exported here so the
+// `@arnilo/prism` surface and the error-class identity are unchanged. `normalizeHostname`
+// is imported for internal use only — it is public through `pinned-fetch.ts`, not here.
+export { assertSsrfAllowedUrl, MediaContentError } from "./media-types.js";
 /** Known model input capability tags for `ModelCapabilities.input`. */
 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). */
@@ -26,14 +32,6 @@ export class UnsupportedModalityError extends Error {
         this.model = model.model;
     }
 }
-export class MediaContentError extends Error {
-    code;
-    constructor(code, message, options) {
-        super(message, options);
-        this.name = "MediaContentError";
-        this.code = code;
-    }
-}
 export function contentBlockInputModality(block) {
     switch (block.type) {
         case "image":
@@ -90,41 +88,6 @@ export function assertMediaBlocksWithinBounds(blocks, bounds = {}) {
         }
     }
 }
-export function assertSsrfAllowedUrl(url, policy = {}) {
-    let parsed;
-    try {
-        parsed = new URL(url);
-    }
-    catch {
-        throw new MediaContentError("ssrf_denied", "Media URL is not a valid absolute URL");
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new MediaContentError("unsupported_url_scheme", `Media URL scheme ${parsed.protocol} is not allowed`);
-    }
-    if (parsed.username || parsed.password) {
-        throw new MediaContentError("ssrf_denied", "Media URL must not embed credentials");
-    }
-    const hostname = normalizeHostname(parsed.hostname);
-    if (policy.allowedHostnames?.length) {
-        if (!policy.allowedHostnames.some((allowed) => hostname === normalizeHostname(allowed))) {
-            throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} is not allow-listed`);
-        }
-        return;
-    }
-    if (policy.denyPrivateHosts === false)
-        return;
-    if (hostname === "localhost" ||
-        hostname.endsWith(".localhost") ||
-        hostname.endsWith(".local") ||
-        hostname === "metadata" ||
-        hostname === "metadata.google.internal" ||
-        hostname === "instance-data") {
-        throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} is not allowed`);
-    }
-    if (isBlockedIp(hostname)) {
-        throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} is not allowed`);
-    }
-}
 export function sniffMediaMimeType(bytes) {
     if (startsWith(bytes, [0x25, 0x50, 0x44, 0x46, 0x2d]))
         return "application/pdf";
@@ -364,7 +327,9 @@ async function resolvePublicAddress(hostname, resolver, signal, policy) {
     if (addresses.length > 32)
         throw new MediaContentError("fetch_failed", "Media hostname resolved to too many addresses");
     if (policy?.denyPrivateHosts !== false && !policy?.allowedHostnames?.length) {
-        if (addresses.some(({ address }) => isBlockedIp(normalizeHostname(address)))) {
+        // An allow-listed CIDR covers resolved answers too, but only the private-IP block.
+        const blocked = addresses.some(({ address }) => isBlockedIp(normalizeHostname(address)) && !isAllowedByCidr(address, policy?.allowedCidrs));
+        if (blocked) {
             throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} resolved to a private address`);
         }
     }
@@ -450,61 +415,6 @@ function mediaTypesCompatible(declared, sniffed) {
         return true;
     return false;
 }
-function normalizeHostname(hostname) {
-    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-    return normalized.endsWith(".") ? normalized.slice(0, -1) : normalized;
-}
-function isBlockedIp(hostname) {
-    const normalized = normalizeHostname(hostname);
-    const family = isIP(normalized);
-    if (family === 4)
-        return isBlockedIpv4(normalized);
-    if (family === 6)
-        return isBlockedIpv6(normalized);
-    return false;
-}
-function isBlockedIpv4(address) {
-    const [a, b] = address.split(".").map(Number);
-    return (a === 0 ||
-        a === 10 ||
-        a === 127 ||
-        (a === 100 && b >= 64 && b <= 127) ||
-        (a === 169 && b === 254) ||
-        (a === 172 && b >= 16 && b <= 31) ||
-        (a === 192 && (b === 0 || b === 168)) ||
-        (a === 198 && (b === 18 || b === 19 || b === 51)) ||
-        (a === 203 && b === 0) ||
-        a >= 224);
-}
-function isBlockedIpv6(address) {
-    const words = parseIpv6Words(address);
-    if (!words)
-        return true;
-    if (words.every((word) => word === 0) || (words.slice(0, 7).every((word) => word === 0) && words[7] === 1))
-        return true;
-    if ((words[0] & 0xfe00) === 0xfc00)
-        return true;
-    if ((words[0] & 0xffc0) === 0xfe80 || (words[0] & 0xffc0) === 0xfec0)
-        return true;
-    if ((words[0] & 0xff00) === 0xff00)
-        return true;
-    if (words[0] === 0x2001 && words[1] === 0x0db8)
-        return true;
-    const mapped = words.slice(0, 5).every((word) => word === 0) && (words[5] === 0 || words[5] === 0xffff);
-    return mapped && isBlockedIpv4(`${words[6] >> 8}.${words[6] & 0xff}.${words[7] >> 8}.${words[7] & 0xff}`);
-}
-function parseIpv6Words(address) {
-    const parts = address.split("::");
-    if (parts.length > 2)
-        return undefined;
-    const left = parts[0] ? parts[0].split(":") : [];
-    const right = parts[1] ? parts[1].split(":") : [];
-    const missing = 8 - left.length - right.length;
-    if (missing < 0 || (parts.length === 1 && missing !== 0))
-        return undefined;
-    const words = [...left, ...Array.from({ length: missing }, () => "0"), ...right].map((part) => Number.parseInt(part, 16));
-    return words.length === 8 && words.every((word) => Number.isInteger(word) && word >= 0 && word <= 0xffff) ? words : undefined;
-}
 function startsWith(bytes, prefix) {
     if (bytes.length < prefix.length)
         return false;

package/dist/context-budget.d.ts

@@ -1,10 +1,21 @@
 import type { ContextBlock, InputAssemblyLayout, Message, ProviderRequest, Skill, ToolDefinition } from "./contracts.js";
 import { type LoadedSkillSet, type SkillsDisclosure } from "./skill-disclosure.js";
+/**
+ * Host-supplied token estimator. Budget-only: it never reaches billing, provider
+ * usage, or the wire — it decides what the assembler evicts and nothing else.
+ */
+export type TokenEstimator = (text: string) => number;
 /** Assembler-time input budget. At least one max required when present. */
 export interface ContextBudget {
     readonly maxInputTokens?: number;
     readonly maxInputBytes?: number;
     readonly reportOmissions?: boolean;
+    /**
+     * Overrides the built-in UTF-16/4 heuristic for eviction accounting. Must return a
+     * non-negative finite token count (a NaN/negative/absent return fails the assembly
+     * closed with a `TypeError`). Byte caps are estimator-independent and always enforced.
+     */
+    readonly tokenEstimator?: TokenEstimator;
 }
 export type ContextBudgetOmissionKind = "skills" | "skill_body" | "context" | "history" | "tool_results" | "summaries" | "attachments" | "tools";
 export interface ContextBudgetOmission {
@@ -43,7 +54,7 @@ export declare function isContextBudgetError(error: unknown): error is ContextBu
 /** UTF-16 code units / 4. Estimate only — not billing. */
 export declare function estimateTextTokens(text: string): number;
 export declare function estimateTextBytes(text: string): number;
-export declare function estimateMessageTokens(message: Message): number;
+export declare function estimateMessageTokens(message: Message, estimateTokens?: TokenEstimator): number;
 export declare function estimateMessageBytes(message: Message): number;
 export declare function estimateAssemblyTokens(messages: readonly Message[]): number;
 export declare function resolveContextBudget(budget: ContextBudget): Required<Pick<ContextBudget, "reportOmissions">> & ContextBudget;

package/dist/context-budget.js

@@ -22,8 +22,8 @@ export function estimateTextTokens(text) {
 export function estimateTextBytes(text) {
     return Buffer.byteLength(text, "utf8");
 }
-export function estimateMessageTokens(message) {
-    return estimateTextTokens(messageText(message));
+export function estimateMessageTokens(message, estimateTokens = estimateTextTokens) {
+    return estimateTokens(messageText(message));
 }
 export function estimateMessageBytes(message) {
     return estimateTextBytes(messageText(message));
@@ -41,6 +41,9 @@ export function resolveContextBudget(budget) {
         assertPositiveCap(budget.maxInputTokens, "maxInputTokens", HARD_MAX_CONTEXT_BUDGET_TOKENS);
     if (hasBytes)
         assertPositiveCap(budget.maxInputBytes, "maxInputBytes", HARD_MAX_CONTEXT_BUDGET_BYTES);
+    if (budget.tokenEstimator !== undefined && typeof budget.tokenEstimator !== "function") {
+        throw new TypeError("contextBudget.tokenEstimator must be a function");
+    }
     return { ...budget, reportOmissions: budget.reportOmissions === true };
 }
 export function getContextBudgetReport(request) {
@@ -49,6 +52,7 @@ export function getContextBudgetReport(request) {
 }
 export function applyContextBudget(options) {
     const budget = resolveContextBudget(options.budget);
+    const estimateTokens = resolveTokenEstimator(budget);
     const layout = options.layout ?? "cache_aware";
     const groups = {
         instructions: [...options.groups.instructions],
@@ -67,9 +71,9 @@ export function applyContextBudget(options) {
     const historyCursor = { index: 0 };
     // Measure once, then subtract each dropped item's own estimate (dropNext computes it
     // with the same estimators) — avoids an O(n²) re-scan of the full keep-set per drop.
-    const kept = measureAll(groups, context, skills, tools, skillContext, demotedBodies);
+    const kept = measureAll(groups, context, skills, tools, skillContext, demotedBodies, estimateTokens);
     while (overBudget(kept, budget)) {
-        const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor);
+        const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor, estimateTokens);
         if (!drop) {
             throw new ContextBudgetError();
         }
@@ -97,7 +101,7 @@ export function applyContextBudget(options) {
         },
     };
 }
-function dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor) {
+function dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor, estimateTokens) {
     // ponytail: drop droppable groups in layout order; within history, advance a cursor and slice once.
     // cache_aware keeps attachments longer so stable prefix stays intact while budget still allows it.
     const order = layout === "cache_aware"
@@ -106,19 +110,19 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
     for (const kind of order) {
         if (kind === "tool_results" && groups.toolResults.length > 0) {
             const message = groups.toolResults.pop();
-            return omission("tool_results", message.id ?? toolResultId(message), message);
+            return omission("tool_results", message.id ?? toolResultId(message), message, estimateTokens);
         }
         if (kind === "history" && historyCursor.index < groups.history.length) {
             const message = groups.history[historyCursor.index++];
-            return omission("history", message.id, message);
+            return omission("history", message.id, message, estimateTokens);
         }
         if (kind === "summaries" && groups.summaries.length > 0) {
             const message = groups.summaries.pop();
-            return omission("summaries", message.id, message);
+            return omission("summaries", message.id, message, estimateTokens);
         }
         if (kind === "attachments" && groups.attachments.length > 0) {
             const message = groups.attachments.pop();
-            return omission("attachments", message.id, message);
+            return omission("attachments", message.id, message, estimateTokens);
         }
         if (kind === "context" && context.length > 0) {
             const index = pickVictimIndex(context, (block) => block.priority ?? 0);
@@ -127,7 +131,7 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
             return {
                 kind: "context",
                 id: block.id ?? block.title,
-                tokenEstimate: estimateTextTokens(text),
+                tokenEstimate: estimateTokens(text),
                 byteLength: estimateTextBytes(text),
             };
         }
@@ -142,7 +146,7 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
                 return {
                     kind: "skill_body",
                     id: skill.name,
-                    tokenEstimate: estimateTextTokens(beforeText) - estimateTextTokens(afterText),
+                    tokenEstimate: estimateTokens(beforeText) - estimateTokens(afterText),
                     byteLength: estimateTextBytes(beforeText) - estimateTextBytes(afterText),
                 };
             }
@@ -152,31 +156,50 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
             return {
                 kind: "skills",
                 id: skill.name,
-                tokenEstimate: estimateTextTokens(text),
+                tokenEstimate: estimateTokens(text),
                 byteLength: estimateTextBytes(text),
             };
         }
     }
     return undefined;
 }
-function omission(kind, id, message) {
+function omission(kind, id, message, estimateTokens) {
     return {
         kind,
         id,
-        tokenEstimate: estimateMessageTokens(message),
+        tokenEstimate: estimateMessageTokens(message, estimateTokens),
         byteLength: estimateMessageBytes(message),
     };
 }
+/**
+ * Resolves the budget's estimator, validating each return value: a host estimator that
+ * yields NaN/negative/non-finite tokens would make every eviction decision unsound, so it
+ * fails the assembly closed instead of silently keeping or dropping the wrong content.
+ */
+function resolveTokenEstimator(budget) {
+    const estimator = budget.tokenEstimator;
+    if (estimator === undefined)
+        return estimateTextTokens;
+    if (typeof estimator !== "function")
+        throw new TypeError("contextBudget.tokenEstimator must be a function");
+    return (text) => {
+        const tokens = estimator(text);
+        if (typeof tokens !== "number" || !Number.isFinite(tokens) || tokens < 0) {
+            throw new TypeError("contextBudget.tokenEstimator must return a non-negative finite number of tokens");
+        }
+        return tokens;
+    };
+}
 function toolResultId(message) {
     const block = message.content.find((part) => part.type === "tool_result");
     return block && block.type === "tool_result" ? block.toolCallId : undefined;
 }
-function measureAll(groups, context, skills, tools, skillContext, demotedBodies) {
+function measureAll(groups, context, skills, tools, skillContext, demotedBodies, estimateTokens) {
     const renderContext = withDemoted(skillContext, demotedBodies);
     let tokens = 0;
     let bytes = 0;
     const addMessage = (message) => {
-        tokens += estimateMessageTokens(message);
+        tokens += estimateMessageTokens(message, estimateTokens);
         bytes += estimateMessageBytes(message);
     };
     for (const message of groups.instructions)
@@ -193,17 +216,17 @@ function measureAll(groups, context, skills, tools, skillContext, demotedBodies)
         addMessage(message);
     for (const block of context) {
         const text = `${block.title ? `${block.title}:\n` : "Context:\n"}${contextBlockText(block)}`;
-        tokens += estimateTextTokens(text);
+        tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     for (const skill of skills) {
         const text = skillPromptText(skill, renderContext) ?? "";
-        tokens += estimateTextTokens(text);
+        tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     if (tools?.length) {
         const text = `Available tools:\n${tools.map((tool) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ""}`).join("\n")}`;
-        tokens += estimateTextTokens(text);
+        tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     return { tokens, bytes };

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

@@ -127,7 +127,18 @@ export interface AgentSessionConfig {
     readonly store?: SessionStore;
     readonly leafId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * TTL of the in-memory `session.snapshot()` branch cache in milliseconds.
+     * Default `DEFAULT_SNAPSHOT_CACHE_TTL_MS`; `0` disables the cache (every snapshot read
+     * rebuilds from the store); at most `HARD_MAX_SNAPSHOT_CACHE_TTL_MS`. The cache is always
+     * invalidated by a new leaf or a mutation, so the TTL only bounds staleness-free reuse.
+     */
+    readonly snapshotCacheTtlMs?: number;
 }
+/** Default `session.snapshot()` branch-cache TTL (milliseconds). */
+export declare const DEFAULT_SNAPSHOT_CACHE_TTL_MS = 1000;
+/** Upper bound for `AgentSessionConfig.snapshotCacheTtlMs` (milliseconds). */
+export declare const HARD_MAX_SNAPSHOT_CACHE_TTL_MS = 30000;
 export interface AgentSessionForkOptions {
     readonly leafId?: string;
 }

package/dist/contracts-core/agent.js

@@ -1,6 +1,9 @@
 /** Contracts-core agent family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
-export {};
+/** Default `session.snapshot()` branch-cache TTL (milliseconds). */
+export const DEFAULT_SNAPSHOT_CACHE_TTL_MS = 1_000;
+/** Upper bound for `AgentSessionConfig.snapshotCacheTtlMs` (milliseconds). */
+export const HARD_MAX_SNAPSHOT_CACHE_TTL_MS = 30_000;
 /** Directory-name spelling for discovered contribution kinds. Maps to a
  *  {@link ManifestContributionDeclaration} kind for non-skill kinds:
  *  `context` → `contextProvider`, `instructions` → `systemPromptContribution`. */

package/dist/extensions.d.ts

@@ -1,4 +1,4 @@
-import type { Extension, ExtensionEvent, ExtensionLifecycleEventName } from "./contracts.js";
+import type { CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, ToolDefinition } from "./contracts.js";
 import { type ContributionRegistries } from "./contributions.js";
 import { type MiddlewareRegistry } from "./middleware.js";
 import { type PermissionPolicy } from "./security.js";
@@ -40,3 +40,20 @@ export interface ExtensionKernel {
 }
 export declare function createExtensionEventBus(options?: Pick<ExtensionKernelOptions, "errorPolicy" | "secrets">): ExtensionEventBus;
 export declare function createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel;
+/** Host-owned activation: copy contributed entries into the `createAgent()`
+ *  fields that accept plain arrays. Contributions stay inert until the host
+ *  passes the returned fields into runtime config. Array slots only —
+ *  single-slot builders (`inputBuilder`/`promptBuilder`), `compaction`,
+ *  `retry`, provider/model selection, and skill activation remain host-owned
+ *  decisions; `commands` are for host RPC surfaces, not an `AgentConfig` field. */
+export interface ActivatedKernelConfig {
+    readonly tools: readonly ToolDefinition[];
+    readonly skills: readonly Skill[];
+    readonly instructionInjectors: readonly InstructionInjector[];
+    readonly context: readonly ContextProvider[];
+    /** For host command surfaces (CLI/RPC/UI); not part of `AgentConfig`. */
+    readonly commands: readonly CommandDefinition[];
+    /** The kernel middleware registry itself; runs only when passed to runtime config. */
+    readonly middleware: MiddlewareRegistry;
+}
+export declare function activateKernel(kernel: ExtensionKernel): ActivatedKernelConfig;

package/dist/extensions.js

@@ -190,6 +190,16 @@ export function createExtensionKernel(options = {}) {
         },
     };
 }
+export function activateKernel(kernel) {
+    return {
+        tools: kernel.registries.tools.list(),
+        skills: kernel.registries.skills.list(),
+        instructionInjectors: kernel.registries.instructionInjectors.list(),
+        context: kernel.registries.contextProviders.list(),
+        commands: kernel.registries.commands.list(),
+        middleware: kernel.middleware,
+    };
+}
 async function assertExtensionLoadPolicy(policy, extension) {
     if (!policy)
         return;

package/dist/index.d.ts

@@ -23,11 +23,11 @@ export type { ConfigLayer, ConfigLoadContext, ConfigProvider } from "./config.js
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export type { AudioContent, DocumentContent, FileContent, MediaContentBlock, MediaContentBounds, MediaHostAddress, MediaHostnameResolver, MediaMimePolicy, MediaUrlRequest, MediaUrlRequester, ModelInputCapability, ResolvedMediaContent, ResolveMediaContentOptions, SsrfPolicy, } from "./content.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
-export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission, ContextBudgetOmissionKind, ContextBudgetReport, } from "./context-budget.js";
+export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission, ContextBudgetOmissionKind, ContextBudgetReport, TokenEstimator, } from "./context-budget.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
 export type * from "./contracts.js";
 export type { ApprovalOutcome, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, ResumeNestedRun, RunDecision, RunLimitCounters, RunLimitName, SecureAgentOptions, StickyDecision, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
-export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, DEFAULT_SNAPSHOT_CACHE_TTL_MS, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions, } from "./contributions.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
@@ -43,8 +43,8 @@ export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, Even
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
-export type { ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
-export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
+export type { ActivatedKernelConfig, ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
+export { activateKernel, createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export type { MemoryRunFeedbackStoreOptions, PrepareRunFeedbackOptions, RunFeedbackLimits, RunFeedbackRun, RunFeedbackRunResolver, } from "./feedback.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
 export type { ApplyFieldPolicyOptions, AuditFieldRedaction, AuditFieldRedactorLike, AuditFieldRedactorOptions, FieldPolicy, FieldPolicyAction, FieldPolicyDecision, FieldPolicyInput, ProtectedFieldPolicyOptions, } from "./field-policy.js";
@@ -54,7 +54,7 @@ export { assertGuardrailsAllowed, GuardrailError, MAX_GUARDRAIL_CONCURRENCY, run
 export type { AgentIdentity, AssertIdentityActiveOptions, IdentityLimits, IdentityVerifier, NarrowIdentityOptions, Principal, ResolvedIdentityLimits, } from "./identity.js";
 export { assertIdentityActive, assertIdentityMatchesOwnership, assertIdentityPropagation, DEFAULT_IDENTITY_LIMITS, HARD_IDENTITY_LIMITS, IdentityError, identityTelemetryAttributes, narrowIdentity, ownershipFromIdentity, resolveIdentityLimits, resolveRunIdentity, } from "./identity.js";
 export type { AgentInput, AssembleProviderInputOptions, DefaultInputBuildContext, DefaultInputBuilder, DefaultPromptBuilder, InputAttachment, PromptInstruction, PromptTemplateOptions, ResolveContextOptions, } from "./input.js";
-export { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBuilder, renderPromptTemplate, resolveContextProviders, } from "./input.js";
+export { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBuilder, EMPTY_TOOL_RESULT_TEXT, renderPromptTemplate, resolveContextProviders, } from "./input.js";
 export type { ResolveInstructionInjectorsOptions } from "./instruction-injection.js";
 export { resolveInstructionInjectors, runInstructionInjectors } from "./instruction-injection.js";
 export { createMemoryLeaseStore, LEASE_CONFLICT_CODE, LeaseConflictError } from "./leases.js";
@@ -119,5 +119,5 @@ export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.5.5";
+export declare const version = "0.6.0";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -13,7 +13,7 @@ export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compac
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
-export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, DEFAULT_SNAPSHOT_CACHE_TTL_MS, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
@@ -22,12 +22,12 @@ export { createDelegatedAgentStep, DelegatedAgentStepError, MAX_DELEGATED_AGENT_
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
-export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
+export { activateKernel, createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
 export { ALLOW_FIELD_POLICY, applyFieldPolicy, createAuditFieldRedactor, createProtectedFieldPolicy, FIELD_POLICY_LIMITS, FieldPolicyError, } from "./field-policy.js";
 export { assertGuardrailsAllowed, GuardrailError, MAX_GUARDRAIL_CONCURRENCY, runGuardrails } from "./guardrails.js";
 export { assertIdentityActive, assertIdentityMatchesOwnership, assertIdentityPropagation, DEFAULT_IDENTITY_LIMITS, HARD_IDENTITY_LIMITS, IdentityError, identityTelemetryAttributes, narrowIdentity, ownershipFromIdentity, resolveIdentityLimits, resolveRunIdentity, } from "./identity.js";
-export { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBuilder, renderPromptTemplate, resolveContextProviders, } from "./input.js";
+export { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBuilder, EMPTY_TOOL_RESULT_TEXT, renderPromptTemplate, resolveContextProviders, } from "./input.js";
 export { resolveInstructionInjectors, runInstructionInjectors } from "./instruction-injection.js";
 export { createMemoryLeaseStore, LEASE_CONFLICT_CODE, LeaseConflictError } from "./leases.js";
 export { definePrismManifest, parsePrismManifest } from "./manifests.js";
@@ -66,6 +66,6 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.5.5";
+export const version = "0.6.0";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/input.d.ts

@@ -6,6 +6,12 @@ import { type LoadedSkillSet, type SkillsDisclosure } from "./skill-disclosure.j
 import { type ResolvedToolResultFoldOptions } from "./tool-result-fold.js";
 import { type ToolsDisclosure, type ToolsSearchOptions } from "./tool-search.js";
 export type AgentInput = string | Message | readonly Message[];
+/**
+ * Wire payload for a tool result that carries no `value`, no `type:text` content, and no error.
+ * Every provider route serializes a tool result from this block, so the empty case must be a
+ * constant non-empty string instead of an absent payload (strict providers reject empty results).
+ */
+export declare const EMPTY_TOOL_RESULT_TEXT = "(tool completed with no output)";
 export interface PromptInstruction {
     readonly text: string;
     readonly label?: string;

package/dist/input.js

@@ -8,6 +8,12 @@ import { skillMessages as buildSkillMessages } from "./skill-disclosure.js";
 import { composeSystemPrompt } from "./system-prompts.js";
 import { foldToolResultHistory, foldToolResults } from "./tool-result-fold.js";
 import { selectDisclosedTools } from "./tool-search.js";
+/**
+ * Wire payload for a tool result that carries no `value`, no `type:text` content, and no error.
+ * Every provider route serializes a tool result from this block, so the empty case must be a
+ * constant non-empty string instead of an absent payload (strict providers reject empty results).
+ */
+export const EMPTY_TOOL_RESULT_TEXT = "(tool completed with no output)";
 export function createDefaultInputBuilder() {
     return {
         name: "default-input",
@@ -328,7 +334,12 @@ function toolResultPayload(result) {
         .map((block) => block.text)
         .filter(Boolean)
         .join("\n");
-    return text.length > 0 ? text : undefined;
+    if (text.length > 0)
+        return text;
+    // An error already carries the outcome; without one, send the constant sentinel so no route
+    // (JSON string content, a content string, a function response, or a typed output part) emits
+    // an empty or absent payload.
+    return result.error === undefined || result.error === null ? EMPTY_TOOL_RESULT_TEXT : undefined;
 }
 function toolResultMessages(results) {
     return (results ?? []).map(toToolResultMessage);

package/dist/media-types.d.ts

@@ -0,0 +1,34 @@
+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[];
+    /**
+     * Optional IP-literal CIDR allow-list (IPv4 + IPv6, e.g. `"10.0.0.0/8"`). Checked
+     * after the hostname allow-list and the denied-name list, and applied to both URL
+     * literals and resolved DNS candidates. Membership bypasses **only** the private-IP
+     * block: metadata-style hostnames (`metadata.google.internal`), loopback names, and
+     * embedded credentials stay denied, and a hostname in the list can never match.
+     * An unparseable entry fails the check closed. Explicit host trust override — see
+     * `docs/multimodal-content.md` / `docs/host-security.md`.
+     */
+    readonly allowedCidrs?: readonly string[];
+}
+export interface MediaHostAddress {
+    readonly address: string;
+    readonly family: 4 | 6;
+}
+export type MediaHostnameResolver = (hostname: string, signal: AbortSignal) => Promise<readonly MediaHostAddress[]>;
+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" | "redirect" | "fetch_failed" | "fetch_timeout" | "resource_required" | "mime_mismatch" | "unsupported_url_scheme";
+    constructor(code: MediaContentError["code"], message: string, options?: ErrorOptions);
+}
+export declare function assertSsrfAllowedUrl(url: string, policy?: SsrfPolicy): void;
+export declare function normalizeHostname(value: string): string;
+export declare function isBlockedIp(hostname: string): boolean;
+/**
+ * Membership test for `SsrfPolicy.allowedCidrs`. Non-IP hostnames can never match; an
+ * entry that does not parse as `address/prefix` throws `ssrf_denied` (fail closed,
+ * including entries of the other address family than the one being tested).
+ */
+export declare function isAllowedByCidr(hostname: string, allowedCidrs: readonly string[] | undefined): boolean;