@arnilo/prism 0.5.6 → 0.6.0

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/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";
@@ -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.6";
+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";
@@ -27,7 +27,7 @@ export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, req
 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.6";
+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;

package/dist/media-types.js

@@ -0,0 +1,158 @@
+/**
+ * SSRF policy, host/address types, `MediaContentError`, and the URL gate shared by the
+ * media content pipeline (`content.ts`) and the DNS-pinned fetch primitive
+ * (`pinned-fetch.ts`).
+ *
+ * Leaf module: it imports nothing from either consumer, which is what keeps the two off
+ * each other's import graph (plan 070 Task 10, shipped in 0.6.0 — the pair previously formed
+ * a deliberate ESM cycle where each module referenced the other's exports only inside
+ * function bodies). Declarations moved here verbatim; `assertSsrfAllowedUrl` is
+ * re-exported from `content.ts` so every import path and the class identity stay put.
+ */
+import { isIP } from "node:net";
+export class MediaContentError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "MediaContentError";
+        this.code = code;
+    }
+}
+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);
+    // Parsed up front so a malformed policy entry always fails closed, even when another
+    // allow-list short-circuits below. Membership only matters after the denied-name list.
+    const cidrAllowed = isAllowedByCidr(hostname, policy.allowedCidrs);
+    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`);
+    }
+    // Validates the CIDR list even for a denied/absent IP: an unparseable entry fails closed.
+    if (cidrAllowed)
+        return;
+    if (isBlockedIp(hostname)) {
+        throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} is not allowed`);
+    }
+}
+export function normalizeHostname(value) {
+    return value
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "");
+}
+export 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;
+}
+/**
+ * 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 function isAllowedByCidr(hostname, allowedCidrs) {
+    if (!allowedCidrs?.length)
+        return false;
+    const ranges = allowedCidrs.map((entry) => {
+        const range = parseCidr(entry);
+        if (!range)
+            throw new MediaContentError("ssrf_denied", `SSRF policy CIDR '${entry}' is not a valid range`);
+        return range;
+    });
+    const address = normalizeHostname(hostname);
+    const family = isIP(address);
+    if (family !== 4 && family !== 6)
+        return false;
+    const bits = family === 4 ? 32 : 128;
+    const target = addressToBigInt(address, family);
+    return ranges.some((range) => range.bits === bits && target >> BigInt(bits - range.prefix) === range.base >> BigInt(bits - range.prefix));
+}
+function parseCidr(value) {
+    const [address, prefixText, ...rest] = value.split("/");
+    if (rest.length > 0 || address === undefined || prefixText === undefined)
+        return undefined;
+    const family = isIP(normalizeHostname(address));
+    if (family !== 4 && family !== 6)
+        return undefined;
+    const prefix = Number(prefixText);
+    const bits = family === 4 ? 32 : 128;
+    if (!Number.isInteger(prefix) || prefix < 0 || prefix > bits)
+        return undefined;
+    return { base: addressToBigInt(normalizeHostname(address), family), bits, prefix };
+}
+function addressToBigInt(address, family) {
+    const words = family === 4 ? address.split(".").map(Number) : (parseIpv6Words(address) ?? []);
+    return words.reduce((accumulator, word) => (accumulator << BigInt(family === 4 ? 8 : 16)) | BigInt(word), 0n);
+}
+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;
+}
+//# sourceMappingURL=media-types.js.map

package/dist/pinned-fetch.d.ts

@@ -1,4 +1,5 @@
-import { type MediaHostAddress, type MediaHostnameResolver, type SsrfPolicy } from "./content.js";
+import { type MediaHostAddress, type MediaHostnameResolver, normalizeHostname, type SsrfPolicy } from "./media-types.js";
+export { normalizeHostname };
 export interface PinnedFetchOptions {
     /** Prefix for request-level error messages ("redirects are not allowed", "response exceeds", ...). Default "Request". */
     readonly errorPrefix?: string;
@@ -20,6 +21,5 @@ export declare function defaultResolver(hostname: string): Promise<readonly Medi
 export declare function requestPinned(url: URL, address: MediaHostAddress, init: RequestInit | undefined, errorPrefix?: string): Promise<Response>;
 export declare function boundResponse(response: Response, maxBytes: number, errorPrefix?: string): Response;
 export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | null | undefined): Promise<T>;
-export declare function normalizeHostname(value: string): string;
 export declare function isLoopbackHostname(value: string): boolean;
 export declare function isLoopbackAddress(value: string): boolean;

package/dist/pinned-fetch.js

@@ -11,15 +11,17 @@
  * for 3xx). Error messages are parameterized by `errorPrefix` so each caller
  * (MCP, OIDC, OPA, content) keeps its own taxonomy and message text.
  *
- * NOTE: imports from ./content.js and is imported by it (content's default
- * media fetch routes through here) — a deliberate ESM cycle; both modules only
- * reference the other's exports inside function bodies, never at module scope.
+ * The SSRF gate, `MediaContentError`, and the host/address types come from the leaf
+ * module `./media-types.js` — shared with `content.ts`, which routes its default media
+ * fetch through here. This module transitively imports nothing from `content.ts` (plan
+ * 070 Task 10 broke the deliberate ESM cycle that used to sit between the two).
  */
 import { lookup as dnsLookup } from "node:dns/promises";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
-import { assertSsrfAllowedUrl, MediaContentError } from "./content.js";
+import { assertSsrfAllowedUrl, MediaContentError, normalizeHostname, } from "./media-types.js";
+export { normalizeHostname };
 /** One DNS-pinned, redirect-free, byte-bounded fetch. See module comment. */
 export async function pinnedFetch(url, init, options) {
     const errorPrefix = options?.errorPrefix ?? "Request";
@@ -72,8 +74,11 @@ export async function resolvePinnedAddress(url, resolver, signal, allowLoopback,
         }
         const literal = candidate.family === 6 ? `[${normalized}]` : normalized;
         // Fail closed on resolved candidates: an explicit hostname allow-list is honored
-        // for the URL itself, but every resolved address is still private-checked.
-        const candidatePolicy = ssrf?.allowedHostnames?.length ? { denyPrivateHosts: ssrf.denyPrivateHosts } : ssrf;
+        // for the URL itself, but every resolved address is still private-checked. An
+        // allowed CIDR is a range rule, so it does apply to resolved addresses.
+        const candidatePolicy = ssrf?.allowedHostnames?.length
+            ? { denyPrivateHosts: ssrf.denyPrivateHosts, ...(ssrf.allowedCidrs ? { allowedCidrs: ssrf.allowedCidrs } : {}) }
+            : ssrf;
         try {
             assertSsrfAllowedUrl(`${url.protocol}//${literal}`, candidatePolicy);
         }
@@ -250,12 +255,6 @@ export async function raceAbort(promise, signal) {
         promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
     });
 }
-export function normalizeHostname(value) {
-    return value
-        .toLowerCase()
-        .replace(/^\[|\]$/g, "")
-        .replace(/\.$/, "");
-}
 export function isLoopbackHostname(value) {
     const hostname = normalizeHostname(value);
     return hostname === "localhost" || hostname.endsWith(".localhost") || isLoopbackAddress(hostname);