@arnilo/prism 0.5.6 → 0.6.0

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## [0.6.0] - 2026-09-12 (plans 070, 071)
+
+> **0.5.7 was never published.** This release folds that cut's content (durable concurrent tool rounds, strict-provider tool results, host-tunable knobs, peer/options truth, the dependency refresh, and the module splits) together with the 0.6.0 changes below, so a host on 0.5.6 upgrades once. See [docs/migrate-to-0.6.md](docs/migrate-to-0.6.md).
+
+### Fixed
+- **Concurrent tool dispatch dropped sibling results.** With `toolConcurrency > 1` a failed or aborted call threw before the round's results were appended, so every successful sibling result was lost and the next provider request carried unanswered `tool_use` blocks. Results are now persisted before the round fails: successes as-is, the failing call as a real redacted `tool_execution_failed` error, and calls that never started as `tool_call_not_dispatched`. Run-level control errors (`ERR_PRISM_AGENT_RUN_SUSPENDED`, `ERR_PRISM_DELEGATION_SUSPENDED`, `ERR_PRISM_LOOP_*`) still skip synthetic results so durable recovery re-dispatches instead of double-appending.
+- **Content-less tool results serialized as an empty payload.** A `ToolResult` with no `content`/`result` now folds to `EMPTY_TOOL_RESULT_TEXT` (`(tool completed with no output)`) through the shared `serializeToolResultJson` seam (OpenAI-compatible, Alibaba, DeepSeek, Kimi/Moonshot, NeuralWatt, OpenCode-Go), so strict providers stop rejecting zero-length tool payloads.
+- **A failing coverage child hid its own error.** `npm run test:coverage` reported a crashed or failed workspace suite as a bare `no coverage data (suite failed)`, with the child's output discarded (the diagnostic gap that made a one-off `@arnilo/prism-memory` flake unreadable). The summary now prints the child's output tail under the failing row and records `status`/`exitCode`/`tail` on its artifact row — redacted through the public `createSecretRedactor` (repo root and home become placeholders, credential-shaped env values become `[REDACTED]`) and char-bounded (last 40 lines, 8 KiB) so one pathological line cannot bloat the artifact. Passing rows are byte-identical to before.
+- **Memory patch merge aliased caller objects.** `packages/memory`'s `mergeJsonObjects` deep-merged in place; it now delegates to core `mergeConfigLayers` (deep copy, strict JSON validation — `undefined`/`Date`/function values fail closed — with the `MemoryValidationError` taxonomy preserved).
+- **`redactSecrets` was O(n·m) in needles.** A guarded single-pass alternation fast path handles large inputs (≥16 KiB, 2–32 non-overlapping needles) with byte-identical output (~13× faster on 1 MiB transcripts); the ordered loop remains the fallback for overlapping needle sets and small inputs.
+- **Peer manifest resolution broke for packages that do not export `./package.json`** (e.g. `@dietrichgebert/ponytail`): upstream resolvers now resolve the package entry point and walk up to the manifest.
+
+### Added
+- **Host-tunable context assembly:** `AssembleProviderInputOptions.tokenEstimator?: (text: string) => number` replaces the built-in UTF-16/4 heuristic for eviction accounting (byte caps stay estimator-independent).
+- **Host-tunable session snapshot cache:** `AgentSessionConfig.snapshotCacheTtlMs` — `DEFAULT_SNAPSHOT_CACHE_TTL_MS` (1000), `HARD_MAX_SNAPSHOT_CACHE_TTL_MS` (30000), `0` disables the branch-rebuild cache.
+- **Host-tunable memory-session search caps:** `createMemorySessionStore(entries, { search: { maxLinearSessions, maxLinearEntries, maxLinearBytes } })`, validated against the same hard bounds as the defaults.
+- **SSRF allow-list:** `SsrfPolicy.allowedCidrs` accepts IPv4 and IPv6 CIDR entries so a host can explicitly reach a private range; hostname denials (metadata endpoints), credential checks, and the fail-closed unparseable-CIDR behavior are unchanged.
+- **Browser run lifetime:** `BrowserLimitOptions.idleRunTtlMs` (default `0`, `HARD_IDLE_RUN_TTL_MS` 30 min) reaps runs with nothing queued; any interaction resets the idle clock.
+- **Host onboarding docs:** [`docs/peer-dependencies.md`](docs/peer-dependencies.md) (every third-party peer declaration with range, optionality, subpath, install line, and network footprint) and [`docs/options-index.md`](docs/options-index.md) (123 public option/limits/config surfaces routed to the page that documents them), both gated by `live-doc-check` against the manifests and the source.
+- **Real-peer and ACP round-trip coverage:** contract smoke tests for the `@dietrichgebert/ponytail` and `@nanonets/graft` layouts, and stdio round-trip tests driving a spawned ACP agent with the real `@agentclientprotocol/sdk` client (spawn→close, mode negotiation, config options, refused/cancelled permissions).
+- **Release-truth gates:** `scripts/version-literal-gate.test.mjs` asserts every release-claim surface (manifests, internal ranges, `package-lock.json`, the `src/index.ts` version constant, the `docs/index.md` current line, `release.yml` tag lists, `scripts/package-truth.json`) equals the root manifest, so a half-finished cut fails the suite instead of shipping; `scripts/workflow-liveness.test.mjs` resolves every workflow script/workspace/`uses:` reference and requires 40-hex SHA pins for actions; `scripts/wiki-scratch-isolation.test.mjs` proves the memory wiki suites leave tracked fixtures and the repository root untouched; `scripts/run-all-tests.mjs` runs every test stage without short-circuiting, and the startup import budget now asserts a machine-relative ratio (absolute 250 ms ceiling only off-load) so a busy machine no longer reports a false regression.
+
+### Changed
+- **Node floor raised to `>=22`** in all ten publishable packages (`@types/node` `^20.19.0` → `^22.20.0`; the `node20-compat` release leg becomes `node22-compat` on Node 22). Node 20 is upstream EOL since 2026-04-30; Node 24 stays the CI default. This is the host-breaking support-matrix change that the unreleased 0.5.7 deliberately deferred to a minor.
+- **Dependency refresh:** `pg` 8.23, `playwright-core` 1.63.0, `zod` ^4.6.2, `@ai-sdk/provider` 4.0.13 (`@ai-sdk/openai` 4.0.65 with a new supported-version matrix entry), `@office-open/*` 0.14.5 (adapters use the `*Sync` parse variants), `@biomejs/biome` 2.5.13, `@agentclientprotocol/sdk` exact-pinned 1.4.0, and the `@arnilo/prism-memory` `@nanonets/graft` peer range widened to `^0.16.0 || ^0.18.0`.
+- **Examples are Node-20-floor safe:** four runnable examples used `import.meta.main` (Node ≥22.18/≥24.2) on a Node-20 floor; they now use the house `import.meta.url` + `process.argv[1]` guard.
+- **Release gate:** lockstep cuts now require every internal `@arnilo/*` range to be the cut version exactly (`0.6.0` or `^0.6.0`) instead of merely satisfying it, so one release line cannot resolve two first-party minors.
+- **Test/coverage tooling:** the npm test chain runs every stage through `scripts/run-all-tests.mjs` (no short-circuit, one summary), coverage discovery finds nested `dist/**/__tests__` in all 9 workspace packages, `coverage-thresholds.json` may no longer name retired packages, and protected legs use one blocked-gate shape (`scripts/blocked-gate.mjs`) with env **names** only in the release evidence.
+- **Internal structure, additive-only surface:** `runtime/server/artifacts.ts` split into four modules, `enterprise/postgres/model-router.ts` split into a directory (`util`/`circuit`/`capacity`/`reservations`/`expiry`/`state-store`), MCP OAuth discovery extracted to `oauth-metadata.ts`, one abort-aware `Semaphore` shared across `@arnilo/prism-coding-tools` (sandbox error types preserved), shared upstream persona primitives in `@arnilo/prism-coding-tools/src/upstream/`, shared provider HTTP retry primitives (`@arnilo/prism-providers/src/shared/retry-http.ts`), and the `content.ts` ↔ `pinned-fetch.ts` ESM cycle broken via the leaf module `src/media-types.ts`. Compat baselines were regenerated (`--update-baseline`): **69 added declarations, zero removals** — the five new host-tunable surfaces plus the helpers the moved modules now export from their new files.
+
+### Removed
+- **`@arnilo/prism-office` optional `playwright-core` peer** (test-only: `/diagrams` drives a host-supplied iframe). Hosts no longer install a browser for office; see [`docs/peer-dependencies.md`](docs/peer-dependencies.md).
+
+### Notes
+- **Lockstep `0.5.6` → `0.6.0` bump:** all 10 publishable manifests move to `0.6.0` with internal ranges `^0.6.0`; the predecessor published release is **0.5.6** (0.5.7 was never published and is superseded by this cut).
+- **Retired-gate and test-truth fixes** landed in the same window (plans 070/071): frozen-era version markers derive from the root manifest, retired doc paths resolve through the frozen lineage, the packed-consumer enterprise journey no longer inherits a Postgres env var (the `pg` peer is not installed in a packed consumer), the `sandbox-browser` workflow references live packages again, the secret scan is operator-independent (tracked files only), the LSP restart-budget test awaits the exhaustion transition instead of racing a write, and the release workflow tag lists carry every published tag.
+
 ## [0.5.6] - 2026-09-09 (plan 069)
 
 ### Added

package/README.md

@@ -162,16 +162,16 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.5.6 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-coding-tools` | 0.5.6 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.5.6 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
-| `@arnilo/prism-providers` | 0.5.6 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.5.6 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.5.6 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.5.6 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.5.6 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
-| `@arnilo/prism-office` | 0.5.6 | capability — /documents, /sheets, /diagrams subpaths |
-| `@arnilo/prism-web-tools` | 0.5.6 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism` | 0.6.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-coding-tools` | 0.6.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.6.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
+| `@arnilo/prism-providers` | 0.6.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.6.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.6.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-mcp` | 0.6.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.6.0 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
+| `@arnilo/prism-office` | 0.6.0 | capability — /documents, /sheets, /diagrams subpaths |
+| `@arnilo/prism-web-tools` | 0.6.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
 <!-- generated:package-truth:inventory end -->
 
 ## Scripts

package/dist/agent-approval.js

@@ -37,8 +37,9 @@ export function assertValidAgentRunResume(resume) {
     if (!Number.isSafeInteger(resume.expectedVersion) || resume.expectedVersion <= 0) {
         throw invalid("Resume expectedVersion must be a positive safe integer");
     }
+    const decisions = resume.decisions;
     const hasDecision = resume.decision !== undefined;
-    const hasDecisions = resume.decisions !== undefined;
+    const hasDecisions = decisions !== undefined;
     if (hasDecision && hasDecisions)
         throw invalid("Resume accepts exactly one of decision or decisions");
     if (!hasDecision && !hasDecisions)
@@ -49,7 +50,6 @@ export function assertValidAgentRunResume(resume) {
         }
         return;
     }
-    const decisions = resume.decisions;
     if (!Array.isArray(decisions))
         throw invalid("Decision batch must be an array");
     if (decisions.length === 0)
@@ -242,10 +242,11 @@ export function decisionScopesEqual(a, b) {
         return false;
     if (a.actionConstraints === undefined || b.actionConstraints === undefined)
         return a.actionConstraints === b.actionConstraints;
-    const keys = Object.keys(a.actionConstraints);
-    return (keys.length === Object.keys(b.actionConstraints).length &&
-        keys.every((key) => key in b.actionConstraints &&
-            canonicalToolEffectJson(a.actionConstraints[key]) === canonicalToolEffectJson(b.actionConstraints[key])));
+    const aConstraints = a.actionConstraints;
+    const bConstraints = b.actionConstraints;
+    const keys = Object.keys(aConstraints);
+    return (keys.length === Object.keys(bConstraints).length &&
+        keys.every((key) => key in bConstraints && canonicalToolEffectJson(aConstraints[key]) === canonicalToolEffectJson(bConstraints[key])));
 }
 export function nestedOutcomeToolResult(outcome, toolCallId, name) {
     return outcome.status === "completed"

package/dist/agent-loops.js

@@ -1,6 +1,7 @@
 import { AgentLoopStateError } from "./contracts.js";
 import { createId } from "./ids.js";
 import { inputMessages, toToolResultMessage } from "./input.js";
+import { errorToErrorInfo } from "./redaction.js";
 import { artifactStructuredOutputRequest, withoutStructuredOutput } from "./structured-output.js";
 function throwIfAborted(signal) {
     if (signal.aborted)
@@ -207,12 +208,13 @@ export function generateValidateReviseLoop(opts) {
                         : { ok: true, value: text };
                 // Parse failure consumes revision budget like a validation failure; the
                 // repairer receives `undefined` value plus a synthetic parse issue.
-                const parseFailure = !parsed.ok || parsed.value === undefined
-                    ? { ok: false, errors: [{ path: "$", message: parsed.error ?? "artifact parse failed" }], metadata: { reason: "parse_error" } }
-                    : undefined;
+                const candidate = parsed.ok && parsed.value !== undefined ? { ok: true, value: parsed.value } : undefined;
                 const attempt = ++attempts;
                 ctx.emit({ type: "artifact_validation_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt });
-                const result = parseFailure ?? (await opts.validator(parsed.value, artifactCtx));
+                const result = candidate
+                    ? await opts.validator(candidate.value, artifactCtx)
+                    : { ok: false, errors: [{ path: "$", message: parsed.error ?? "artifact parse failed" }], metadata: { reason: "parse_error" } };
+                const parseFailure = candidate ? undefined : result;
                 ctx.emit({ type: "artifact_validation_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                 if (result.ok) {
                     ctx.emit({ type: "artifact_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
@@ -271,39 +273,76 @@ export async function dispatchToolCallsInOrder(calls, ctx) {
     let nextIndex = 0;
     let stopped = false;
     let firstFailure;
-    const recordFailure = (error) => {
+    let failureIndex = -1;
+    const recordFailure = (error, index) => {
         if (stopped)
             return;
         stopped = true;
         firstFailure = error;
+        failureIndex = index;
     };
     const workers = Array.from({ length: concurrency }, async () => {
         for (;;) {
             if (stopped)
                 return;
+            let index = -1;
             try {
                 throwIfAborted(ctx.signal);
-                const index = nextIndex;
+                index = nextIndex;
                 nextIndex += 1;
                 if (index >= calls.length)
                     return;
                 results[index] = await ctx.dispatchToolCall(calls[index]);
             }
             catch (error) {
-                recordFailure(error);
+                recordFailure(error, index >= 0 && index < calls.length ? index : -1);
                 return;
             }
         }
     });
     await Promise.allSettled(workers);
+    // Persist before rethrowing: a stopped batch must not leave the branch with `tool_call`
+    // ids that never got a `tool_result` (providers reject that history on the next turn).
+    // ponytail: synthetic rows carry `errorToErrorInfo` output only — no cause chain; the
+    // store redacts entries again at `appendEntry`, and `ctx.history` mirrors the run error.
+    const claimed = Math.min(nextIndex, calls.length);
+    for (let index = 0; index < calls.length; index += 1) {
+        const result = results[index];
+        if (result) {
+            await appendToolResultMessage(result, ctx);
+            continue;
+        }
+        // Suspension/loop-state errors are not tool outcomes: their machinery appends the real
+        // result on resume, so a synthetic row here would duplicate it.
+        if (index === failureIndex && isRunControlError(firstFailure))
+            continue;
+        const call = calls[index];
+        if (call === undefined)
+            continue;
+        await appendToolResultMessage(syntheticFailureResult(call, index < claimed ? firstFailure : undefined), ctx);
+    }
     if (stopped)
         throw firstFailure;
-    for (const result of results) {
-        throwIfAborted(ctx.signal);
-        if (!result)
-            continue;
-        await appendToolResultMessage(result, ctx);
+}
+/** Run-level control errors rethrown by `dispatchToolCall` (mirrors `src/tools.ts`). */
+function isRunControlError(error) {
+    const code = error?.code;
+    return (typeof code === "string" &&
+        (code === "ERR_PRISM_AGENT_RUN_SUSPENDED" || code === "ERR_PRISM_DELEGATION_SUSPENDED" || code.startsWith("ERR_PRISM_LOOP_")));
+}
+function syntheticFailureResult(call, failure) {
+    if (failure === undefined) {
+        return {
+            toolCallId: call.id,
+            name: call.name,
+            error: {
+                code: "tool_call_not_dispatched",
+                message: "Tool call was not dispatched: the batch stopped after an earlier call failed or the run was aborted.",
+            },
+        };
     }
+    const info = errorToErrorInfo(failure);
+    return { toolCallId: call.id, name: call.name, error: { name: info.name, message: info.message, code: info.code } };
 }
 async function appendToolResultMessage(result, ctx) {
     // Approval-gated calls return a marker instead of a real result; the transcript must not

package/dist/agent-session/session.d.ts

@@ -60,6 +60,7 @@ export declare class RuntimeAgentSession implements AgentSession {
     private ledgerFailure;
     private snapshotGeneration;
     private snapshotCache?;
+    private readonly snapshotCacheTtlMs;
     constructor(config: AgentSessionConfig & {
         readonly agent: Agent;
     });

package/dist/agent-session/session.js

@@ -1,7 +1,7 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { policyList } from "../agent-tool-dispatch.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.js";
-import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS } from "../contracts.js";
+import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, } from "../contracts.js";
 import { GuardrailError, runGuardrails } from "../guardrails.js";
 import { applyDefaultProviderRequestOptions, createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult, } from "../provider-request-policy.js";
 import { redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "../redaction.js";
@@ -78,12 +78,14 @@ export class RuntimeAgentSession {
     ledgerFailure;
     snapshotGeneration = 0;
     snapshotCache;
+    snapshotCacheTtlMs;
     constructor(config) {
         this.id = config.id ?? randomId("session");
         this.agent = config.agent;
         this.metadata = config.metadata;
         this.store = config.store ?? config.agent.config.store ?? createMemorySessionStore();
         this.currentLeafId = config.leafId;
+        this.snapshotCacheTtlMs = resolveSnapshotCacheTtlMs(config.snapshotCacheTtlMs);
     }
     get leafId() {
         return this.currentLeafId;
@@ -470,8 +472,24 @@ export class RuntimeAgentSession {
         const value = reader
             ? await rebuildSessionContext(reader, { sessionId: this.id, leafId: this.currentLeafId })
             : rebuildSessionContext(await this.store.list(this.id), { leafId: this.currentLeafId });
-        this.snapshotCache = { leafId: this.currentLeafId, generation: this.snapshotGeneration, expiresAt: now + 1_000, value };
+        this.snapshotCache = {
+            leafId: this.currentLeafId,
+            generation: this.snapshotGeneration,
+            expiresAt: now + this.snapshotCacheTtlMs,
+            value,
+        };
         return value;
     }
 }
+/**
+ * `snapshotCacheTtlMs` resolution: `0` disables the branch cache (a host that needs a
+ * fresh store read per snapshot), otherwise a safe integer up to the hard cap.
+ */
+function resolveSnapshotCacheTtlMs(value) {
+    const ttl = value ?? DEFAULT_SNAPSHOT_CACHE_TTL_MS;
+    if (!Number.isSafeInteger(ttl) || ttl < 0 || ttl > HARD_MAX_SNAPSHOT_CACHE_TTL_MS) {
+        throw new TypeError(`AgentSessionConfig.snapshotCacheTtlMs must be a safe integer from 0 to ${HARD_MAX_SNAPSHOT_CACHE_TTL_MS}`);
+    }
+    return ttl;
+}
 //# sourceMappingURL=session.js.map

package/dist/agent-tool-dispatch.js

@@ -51,8 +51,9 @@ export async function validateElicitationPayload(agent, state, target, payload,
     // Tool-declared answer-shape validation, re-derived from the current registry (never persisted).
     const call = state.pendingCalls?.find((entry) => entry.call.id === target.toolCallId)?.call;
     const tool = call ? activeTools(agent.config.tools).registry.get(call.name) : undefined;
-    const validate = tool?.elicitation && call
-        ? safeToolElicitationValidate(tool, call.arguments, {
+    const elicitation = tool?.elicitation;
+    const validate = elicitation && call
+        ? safeToolElicitationValidate(elicitation, call.arguments, {
             sessionId: state.sessionId,
             runId: state.runId,
             toolCallId: target.toolCallId ?? "elicitation",
@@ -68,9 +69,9 @@ export async function validateElicitationPayload(agent, state, target, payload,
         }
     }
 }
-function safeToolElicitationValidate(tool, args, context) {
+function safeToolElicitationValidate(elicitation, args, context) {
     try {
-        return tool.elicitation(args, context)?.validate;
+        return elicitation(args, context)?.validate;
     }
     catch {
         return undefined;

package/dist/content.d.ts

@@ -1,4 +1,7 @@
 import type { ContentBlock, ImageContent, Message, ModelConfig, ResourceLoadContext, ResourceLoader, VideoContent } from "./contracts.js";
+import { type MediaHostAddress, type MediaHostnameResolver, type SsrfPolicy } from "./media-types.js";
+export type { MediaHostAddress, MediaHostnameResolver, SsrfPolicy } from "./media-types.js";
+export { assertSsrfAllowedUrl, MediaContentError } from "./media-types.js";
 /** Known model input capability tags for `ModelCapabilities.input`. */
 export declare const MODEL_INPUT_CAPABILITIES: readonly ["text", "image", "audio", "file", "document", "video"];
 export type ModelInputCapability = (typeof MODEL_INPUT_CAPABILITIES)[number];
@@ -53,21 +56,10 @@ export interface MediaContentBounds {
     readonly maxAudioDurationMs?: number;
     readonly fetchTimeoutMs?: number;
 }
-export interface SsrfPolicy {
-    /** When true (default), deny private/link-local/metadata hostnames and IPs. */
-    readonly denyPrivateHosts?: boolean;
-    /** Optional hostname allow-list. When set, only listed hosts are permitted. */
-    readonly allowedHostnames?: readonly string[];
-}
 export interface MediaMimePolicy {
     /** Reject when magic bytes disagree with declared media type. Default `true`. */
     readonly strictMagicValidation?: boolean;
 }
-export interface MediaHostAddress {
-    readonly address: string;
-    readonly family: 4 | 6;
-}
-export type MediaHostnameResolver = (hostname: string, signal: AbortSignal) => Promise<readonly MediaHostAddress[]>;
 export interface MediaUrlRequest {
     readonly url: URL;
     readonly address: MediaHostAddress;
@@ -103,16 +95,11 @@ export declare class UnsupportedModalityError extends Error {
     readonly model: string;
     constructor(modality: ModelInputCapability, model: ModelConfig);
 }
-export declare class MediaContentError extends Error {
-    readonly code: "ambiguous_source" | "missing_source" | "item_too_large" | "request_too_large" | "too_many_items" | "audio_too_long" | "invalid_base64" | "ssrf_denied" | "redirect" | "fetch_failed" | "fetch_timeout" | "resource_required" | "mime_mismatch" | "unsupported_url_scheme";
-    constructor(code: MediaContentError["code"], message: string, options?: ErrorOptions);
-}
 export declare function contentBlockInputModality(block: ContentBlock): ModelInputCapability | undefined;
 export declare function collectMessageContentBlocks(messages: readonly Message[]): ContentBlock[];
 export declare function assertModelSupportsContentBlocks(model: ModelConfig, blocks: readonly ContentBlock[]): void;
 export declare function assertMessagesSupportModelCapabilities(model: ModelConfig, messages: readonly Message[]): void;
 export declare function assertMediaBlocksWithinBounds(blocks: readonly MediaContentBlock[], bounds?: MediaContentBounds): void;
-export declare function assertSsrfAllowedUrl(url: string, policy?: SsrfPolicy): void;
 export declare function sniffMediaMimeType(bytes: Uint8Array): string | undefined;
 export declare function assertDeclaredMediaTypeMatches(declaredMediaType: string, bytes: Uint8Array, policy?: MediaMimePolicy): void;
 export declare function resolveMediaContentBlock(block: MediaContentBlock, options?: ResolveMediaContentOptions): Promise<ResolvedMediaContent>;

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;