@arnilo/prism 0.5.5 → 0.6.0

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);

package/dist/redaction.js

@@ -3,6 +3,18 @@ const REDACTED = "[REDACTED]";
 // Depth bound matching agent-run-state.ts; hostile deep structures yield a placeholder
 // instead of a stack overflow.
 const MAX_REDACT_DEPTH = 32;
+// Plan 070 Task 9: single-pass fast path. One left-to-right alternation replaces every
+// occurrence of every needle in a single scan, instead of one split/join pass per needle.
+// It is only equivalent to the ordered reduce below when no needle occurrence can overlap
+// another needle's occurrence or a produced placeholder, so `singlePassMatcher` returns
+// null for such sets and the loop stays authoritative. Below this length the set check
+// costs more than the passes it saves (measured crossover ~4 KB, so the fast path only
+// engages with a wide margin).
+const SINGLE_PASS_MIN_CHARS = 16 * 1024;
+// ponytail: bound the fast path to this needle count. The set check is O(k²) and the
+// alternation compile grows with k, so the loop is no slower beyond it. Raise if a host
+// redacts with much larger secret sets.
+const SINGLE_PASS_MAX_NEEDLES = 32;
 export function createSecretRedactor(secrets) {
     return { redact: (value) => redactSecrets(value, secrets) };
 }
@@ -35,7 +47,18 @@ export function redactSecrets(value, secrets) {
     const needles = secrets.filter((secret) => Boolean(secret));
     if (needles.length === 0)
         return value;
-    const redactString = (text) => needles.reduce((current, secret) => current.split(secret).join(REDACTED), text);
+    // Decided lazily on the first large string, and only once per call: a redaction of many
+    // small strings never pays the set check and never regresses against the loop.
+    let singlePass;
+    const redactString = (text) => {
+        if (text.length >= SINGLE_PASS_MIN_CHARS) {
+            if (singlePass === undefined)
+                singlePass = singlePassMatcher(needles);
+            if (singlePass)
+                return text.replace(singlePass, REDACTED);
+        }
+        return needles.reduce((current, secret) => current.split(secret).join(REDACTED), text);
+    };
     const redactKey = (key) => {
         if (typeof key === "string")
             return redactString(key);
@@ -90,6 +113,56 @@ export function redactSecrets(value, secrets) {
     };
     return redact(value);
 }
+function escapeRegExpLiteral(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Compiled single-pass matcher for `needles`, or null when the set is not provably
+ * equivalent to the ordered reduce/split/join in `redactSecrets`. Equivalence holds when
+ * no needle occurrence can overlap another needle's occurrence (overlap would make the
+ * result depend on which needle is mentioned first rather than on position) and no needle
+ * can occur inside or across the edges of a produced "[REDACTED]" placeholder (a later
+ * pass would then redact text the single scan never sees). Both checks are conservative:
+ * a false negative only costs the fast path.
+ */
+function singlePassMatcher(needles) {
+    if (needles.length < 2 || needles.length > SINGLE_PASS_MAX_NEEDLES)
+        return null;
+    for (const needle of needles) {
+        if (needleTouchesPlaceholder(needle))
+            return null;
+    }
+    for (const left of needles) {
+        for (const right of needles) {
+            if (left !== right && needlesOverlap(left, right))
+                return null;
+        }
+    }
+    return new RegExp(needles.map(escapeRegExpLiteral).join("|"), "g");
+}
+/** A placeholder-relative occurrence: needle inside "[REDACTED]", or a needle prefix equal
+ * to a placeholder suffix / needle suffix equal to a placeholder prefix (a match spanning
+ * the placeholder's edge that the ordered passes would create). */
+function needleTouchesPlaceholder(needle) {
+    if (REDACTED.includes(needle))
+        return true;
+    for (let n = 1; n < needle.length; n += 1) {
+        if (REDACTED.endsWith(needle.slice(0, n)) || REDACTED.startsWith(needle.slice(n)))
+            return true;
+    }
+    return false;
+}
+/** One occurrence of `left` overlapping one of `right`: containment either way, or a proper
+ * suffix of `left` equal to a proper prefix of `right` (callers check both directions). */
+function needlesOverlap(left, right) {
+    if (right.includes(left))
+        return true;
+    for (let n = 1; n < left.length && n < right.length; n += 1) {
+        if (right.startsWith(left.slice(left.length - n)))
+            return true;
+    }
+    return false;
+}
 export function errorToErrorInfo(error, secrets = []) {
     const code = readErrorCode(error);
     const retry = readRetryAfterMs(error);

package/dist/session-stores.d.ts

@@ -28,5 +28,16 @@ export type MemorySessionSearchMode = "linear" | "unsupported";
 export interface CreateMemorySessionStoreOptions {
     /** Default `"linear"`: capped in-process scan. `"unsupported"`: typed throw. */
     readonly sessionSearchMode?: MemorySessionSearchMode;
+    /**
+     * Optional overrides for the capped in-process scan. Hosts with a small session set can
+     * raise the caps (bounded by the contract `HARD_MAX_SESSION_SEARCH_LINEAR_*` values);
+     * defaults are the contract `DEFAULT_MAX_SESSION_SEARCH_LINEAR_*` caps. Values below 1
+     * or above the hard cap fail store construction closed with a `TypeError`.
+     */
+    readonly search?: {
+        readonly maxLinearSessions?: number;
+        readonly maxLinearEntries?: number;
+        readonly maxLinearBytes?: number;
+    };
 }
 export declare function createMemorySessionStore(initialEntries?: readonly SessionEntry[], options?: CreateMemorySessionStoreOptions): SessionStore;

package/dist/session-stores.js

@@ -1,4 +1,4 @@
-import { DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+import { DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 import { createId } from "./ids.js";
 export function createSessionEntry(options) {
     const { createId, now, ...entry } = options;
@@ -96,12 +96,27 @@ function rebuildSessionContextCore(entries, options = {}) {
     }
     return { leafId: branch.at(-1)?.id, entries: branch, messages, summaries };
 }
+function resolveLinearSearchCaps(search) {
+    return {
+        sessions: assertLinearCap(search?.maxLinearSessions, "maxLinearSessions", DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS),
+        entries: assertLinearCap(search?.maxLinearEntries, "maxLinearEntries", DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES),
+        bytes: assertLinearCap(search?.maxLinearBytes, "maxLinearBytes", DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES),
+    };
+}
+function assertLinearCap(value, name, fallback, hardMax) {
+    const cap = value ?? fallback;
+    if (!Number.isSafeInteger(cap) || cap < 1 || cap > hardMax) {
+        throw new TypeError(`CreateMemorySessionStoreOptions.search.${name} must be a safe integer from 1 to ${hardMax}`);
+    }
+    return cap;
+}
 export function createMemorySessionStore(initialEntries = [], options = {}) {
     const byId = new Map();
     const bySession = new Map();
     const leafBySession = new Map();
     const idempotencySeen = new Set();
     const mode = options.sessionSearchMode ?? "linear";
+    const searchCaps = resolveLinearSearchCaps(options.search);
     for (const entry of initialEntries)
         add(entry);
     return {
@@ -118,7 +133,7 @@ export function createMemorySessionStore(initialEntries = [], options = {}) {
         async searchSessions(query) {
             if (mode === "unsupported")
                 throw new SessionSearchUnsupportedError();
-            return searchMemorySessionsLinear(bySession, leafBySession, query);
+            return searchMemorySessionsLinear(bySession, leafBySession, query, searchCaps);
         },
     };
     function add(entry, options) {
@@ -160,7 +175,7 @@ export function createMemorySessionStore(initialEntries = [], options = {}) {
         leafBySession.set(entry.sessionId, entry.id);
     }
 }
-function searchMemorySessionsLinear(bySession, leafBySession, query) {
+function searchMemorySessionsLinear(bySession, leafBySession, query, caps) {
     const q = resolveSessionSearchQuery(query);
     q.signal?.throwIfAborted();
     let sessionsScanned = 0;
@@ -168,11 +183,11 @@ function searchMemorySessionsLinear(bySession, leafBySession, query) {
     let bytesScanned = 0;
     const matches = [];
     for (const [sessionId, entries] of bySession) {
-        if (sessionsScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS)
+        if (sessionsScanned >= caps.sessions)
             break;
-        if (entriesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES)
+        if (entriesScanned >= caps.entries)
             break;
-        if (bytesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES)
+        if (bytesScanned >= caps.bytes)
             break;
         q.signal?.throwIfAborted();
         sessionsScanned += 1;
@@ -190,9 +205,9 @@ function searchMemorySessionsLinear(bySession, leafBySession, query) {
         let matchedModel = false;
         let snippetSource;
         for (const entry of entries) {
-            if (entriesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES)
+            if (entriesScanned >= caps.entries)
                 break;
-            if (bytesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES)
+            if (bytesScanned >= caps.bytes)
                 break;
             entriesScanned += 1;
             const text = entrySearchText(entry);

package/docs/acp.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-ag-ui/acp` (stable ACP **v1**, `@agentclientprotocol/sdk@1.3.0` root exports only) exposes two adapters:
+`@arnilo/prism-ag-ui/acp` (stable ACP **v1**, `@agentclientprotocol/sdk@1.4.0` root exports only) exposes two adapters:
 
 - `createPrismAcpAgent(options)` — serves ACP as an **agent**: an editor/AI client connects through the SDK transport and drives host-owned Prism sessions with `session/new`, `session/load`, `session/resume`, `session/prompt`, `session/set_mode`, `session/set_config_option`, `session/list`, `session/delete`, `session/close`, and `session/cancel`. The agent is a thin protocol adapter: every capability, decision, and byte cap is wired from host seams, and there is **no second policy engine** on the agent side.
 - `createAcpEventMapper(options)` — maps a Prism `AgentEvent` stream (or `CoWorkEvent`) to ACP `SessionUpdate`s for hosts that stream through their own transport.

package/docs/ag-ui.md

@@ -1,11 +1,13 @@
 # Frontend interoperability (AG-UI and ACP)
 
+> **Required peer install:** `zod` (the pinned ACP SDK peers it) — see [Optional peer dependencies](peer-dependencies.md).
+
 ## What it does
 
 `@arnilo/prism-ag-ui` is an optional, framework-free protocol adapter over Prism's existing redacted `AgentEvent`, session, durable-run, and persistence seams.
 
 - Root export maps Prism events to AG-UI `@ag-ui/core` **0.0.59** events and offers `createAgUiHandler()` (`Request` → SSE `Response`), compatible `createPersistenceAgUiReplay()` pages, distributed `createAgentEventSourceAgUiReplay()` follow, and explicit `createAgUiMcpAdapter()` / `createAgUiMcpAppHandler()` / `createAgUiA2AAdapter()` protocol handshakes.
-- `@arnilo/prism-ag-ui/acp` is the stable ACP **v1** sibling: `createAcpEventMapper()` and `createPrismAcpAgent()` over `@agentclientprotocol/sdk` **1.3.0** root exports. ACP is a protocol adapter — sessions, modes, MCP, fs/terminal, lifecycle mapping, and caps live on the host seams. See [ACP coding-host interop](acp.md) for the full reference; this page covers AG-UI only.
+- `@arnilo/prism-ag-ui/acp` is the stable ACP **v1** sibling: `createAcpEventMapper()` and `createPrismAcpAgent()` over `@agentclientprotocol/sdk` **1.4.0** root exports. ACP is a protocol adapter — sessions, modes, MCP, fs/terminal, lifecycle mapping, and caps live on the host seams. See [ACP coding-host interop](acp.md) for the full reference; this page covers AG-UI only.
 - Core remains protocol-free. `resumeAgentRunStream()` / `AgentRunLifecycle.resumeStream()` are generic durable-resume streams shared by adapters.
 
 ## When to use it
@@ -38,7 +40,7 @@ npm install @arnilo/prism @arnilo/prism-ag-ui
 | `projection` | Explicit safe tool/state/messages/activity/reasoning/raw/custom/interrupt projection. Omit each callback for default deny. Prefer `composeAgUiProjections(createMessagesFromSessionProjection(...), createStateFromStoreProjection(...), createActivityFromToolProgressProjection(), host)` for standard families. |
 | `a2ui` | Opt-in A2UI painting middleware (`{ catalogId, mode, renderToolName?, allowedCatalogIds?, limits? }`). Detects `a2ui_operations` tool results and/or streams from `render_a2ui` args; paints `a2ui-surface` activity events. Absent = inert. |
 | `capabilities` | Optional host declaration narrowed to implemented SSE/projector/lifecycle features; read `handler.capabilities`. |
-| `redactor`, `limits` | Host redaction and narrowing-only finite caps. |
+| `redactor`, `limits` | Host redaction and narrowing-only finite caps (`AgUiLimitOptions`, with its A2UI variant). |
 
 The handler accepts only `POST` JSON validated with official AG-UI `RunAgentInputSchema`. Every aggregate is bounded before a callback runs. With no `input.project`, it preserves compatibility: final text user message only; non-empty state or frontend tools fail before authorization/session lookup. With a projector, all current roles/history, context, state, forwarded props, multimodal parts, parent lineage, and tool-result continuations are available as untrusted input. The projector must apply Prism media URL/SSRF/MIME policy before forwarding media. Start a run with no `resume` and no `?cursor=`; replay supplies `?cursor=`.
 

package/docs/agent-events.md

@@ -1,5 +1,7 @@
 # Agent events
 
+> **Optional peer install:** `@nats-io/jetstream` + `@nats-io/transport-node` for the JetStream event source — see [Optional peer dependencies](peer-dependencies.md).
+
 ## What it does
 
 `AgentEvent` is the single observable stream every `AgentSession` run emits. Subscribers receive normalized, redacted, in-order events covering agent lifecycle, assistant message streaming, delegated-agent activity, tool execution, queue updates, subscriber overflow, compaction, retry, artifact validation/refinement, and terminal errors. The stream is in-memory, live-only, and bounded per subscriber by `SubscribeOptions`; there is no durable queue, no background work, and no extra dependency.

package/docs/agent-loops.md

@@ -233,7 +233,7 @@ await session.run(input, { loop: twoShotLoop });
 - `ArtifactValidation.errors[].message` may echo model text — `artifact_*` event payloads flow through the same `redactAgentEvent` path as other `AgentEvent`s (see [Agent events](agent-events.md)).
 - `generateValidateReviseLoop` makes at most `1 + maxRevisions + maxToolRounds` provider turns when bounded tools are enabled (otherwise `maxRevisions + 1`); it cannot loop forever. Each revision costs one provider turn plus one store append.
 - Bounded artifact tool calls run sequentially through `dispatchToolCall` (permission + validation + execute); their assistant call and result are persisted before the next provider request. `singleShotLoop` retains its bounded parallel worker pool and original call-order transcript behavior.
-- In a parallel single-shot batch, the worker pool stops claiming calls after the first dispatch error or abort, waits for every already-claimed worker with `Promise.allSettled`, appends no buffered tool-result rows for a failed batch, then rethrows the first failure. Already-claimed side effects may finish and are not rolled back; successful batches still append results in original call order. The round-level `chargeToolRound` approval gate runs before workers, so approval suspension starts no worker.
+- In a parallel single-shot batch, the worker pool stops claiming calls after the first dispatch error or abort, waits for every already-claimed worker with `Promise.allSettled`, then persists rows in call order before rethrowing the first failure: real results for calls that finished, an error row carrying the failure for the call that threw, and a `tool_call_not_dispatched` row for calls the batch never started. A stopped batch therefore never ends the run with `tool_call` ids that have no `tool_result` (providers reject such a history on the next turn); run-level suspension errors (`AgentRunSuspended`, `ERR_PRISM_DELEGATION_SUSPENDED`, `ERR_PRISM_LOOP_*`) are the exception — their resume machinery appends the real result, so the failed call gets no synthetic row. Already-claimed side effects may finish and are not rolled back; successful batches still append results in original call order. The round-level `chargeToolRound` approval gate runs before workers, so approval suspension starts no worker.
 - The loop is a plain object/factory; no class hierarchy, no background work, no extra dependencies. `LoopContext` is a single object literal of bound arrows built once per run.
 - The host-domain-free boundary is guarded by tests: `src/` imports no host-domain package, and the `Artifact*`/`AgentLoop*`/`LoopContext` contracts contain no `workflow`/`node`/`step` field names. Hosts supply their own schema; no host domain type is imported by `src/`.
 

package/docs/agent-session-runtime.md

@@ -45,7 +45,7 @@ createAgentSession(config: AgentSessionConfig & { agent: Agent }): AgentSession
 string | Message | readonly Message[]
 ```
 
-`AgentSessionConfig.store` overrides `AgentConfig.store`; otherwise the session gets a private memory store. `AgentSessionConfig.leafId` selects the branch leaf to resume from.
+`AgentSessionConfig.store` overrides `AgentConfig.store`; otherwise the session gets a private memory store. `AgentSessionConfig.leafId` selects the branch leaf to resume from. `AgentSessionConfig.snapshotCacheTtlMs` tunes the in-memory branch cache behind `session.snapshot()`: default `DEFAULT_SNAPSHOT_CACHE_TTL_MS` (1000 ms), `0` disables caching so every read rebuilds from the store, maximum `HARD_MAX_SNAPSHOT_CACHE_TTL_MS` (30 s); values outside `0..hard` fail session construction with `TypeError`. The cache is invalidated by any new leaf or mutation, so the TTL only bounds reuse of an unchanged branch.
 
 `AgentConfig.limits` sets run ceilings; `RunOptions.limits` may only narrow configured agent values (`null` counts as no cap, so a configured finite ceiling still wins). Limits cover turns, provider attempts, tool rounds/calls, wall time, request/response bytes, tokens, and optional single-currency cost. Policy axes accept `null` (0.5.4) to disable the axis; request/response bytes reject `null` and stay process-hard at 64 MiB. A breach emits one `run_limit_exceeded` event and throws `AgentRunError` with `result.limit`; see [Runs and usage ledger](runs-and-usage.md#run-limits).
 
@@ -55,6 +55,8 @@ string | Message | readonly Message[]
 
 ## Outputs / response / events
 
+`session.fork(options?)` / `session.clone(options?)` take `AgentSessionForkOptions` / `AgentSessionCloneOptions` (leaf id, new session id, metadata, and store overrides), and `session.steer(input, options?)` takes `SteerOptions`. See [Public contracts](public-contracts.md) for the field tables, and the [options index](options-index.md) for every session option surface.
+
 `session.run()` / `session.prompt()` resolve to an `AgentRunResult` with `sessionId`, `runId`, `status`, `text`, `content`, optional `message`/`usage`/`leafId`, and terminal `error`/`abortReason` when applicable. Callers may ignore the return value. Failed and aborted runs still emit their terminal events, then reject with `AgentRunError` whose `.result` carries the same shape.
 
 `session.stream(input, options?)` subscribes first, starts exactly one run, yields only that run's events, and terminates when the run succeeds, fails, or aborts. Early consumer return aborts the owned run and releases the session. `SubscribeOptions.maxQueuedEvents` / `overflow` may be passed alongside `RunOptions`.

package/docs/browser-automation.md

@@ -1,5 +1,7 @@
 # Browser automation
 
+> **Optional peer install:** `playwright-core@1.63.0` (exact pin) — see [Optional peer dependencies](peer-dependencies.md).
+
 ## What it does
 
 The `@arnilo/prism-web-tools/browser` subpath exposes six exclusive model-facing tools—`browser_open`, `browser_snapshot`, `browser_act`, `browser_close`, `browser_evaluate`, and `browser_observe`—over a host-supplied Playwright `Browser`. Prism creates one non-persistent `BrowserContext` per run, serializes actions, returns bounded AI-mode accessibility snapshots with snapshot-scoped refs, enforces egress/side-effect/upload/download/screenshot policy, and closes context/pages/listeners/quarantined downloads on close, abort, or manager disposal. Since 0.1.4 the package also rides playwright-core's existing CDP transport for bounded page evaluation, console/network observation, and network/emulation control on Chromium hosts — zero new dependencies, Prism still never launches or downloads browsers.
@@ -100,8 +102,9 @@ await browser.close();
 
 ## Extension and configuration notes
 
-- Compatibility line: `playwright-core@1.61.0` optional peer. Hosts pin browser binaries/images; Prism package install downloads nothing.
-- Default/hard caps: pages 4/16; actions 100/256; queued actions 16/64; snapshot refs 2k/10k; depth 30/100; snapshot bytes 256 KiB/2 MiB; navigation 30s/120s; action 10s/60s; wait 30s/120s; run wall 20min/30min; popups 4/16; dialogs 16/64; close grace 5s/30s; network requests 1k/10k; redirects/request 10/32; WebSockets 8/32; screenshots 16/64 with 16/64 megapixels and 10 MiB/32 MiB encoded; uploads 8/32 files, 16 MiB/64 MiB each, 64 MiB/256 MiB aggregate; downloads 8/32 files, 32 MiB/256 MiB each, 64 MiB/512 MiB aggregate.
+- Compatibility line: `playwright-core@1.63.0` optional peer. Hosts pin browser binaries/images; Prism package install downloads nothing.
+- Default/hard caps: pages 4/16; actions 100/256; queued actions 16/64; snapshot refs 2k/10k; depth 30/100; snapshot bytes 256 KiB/2 MiB; navigation 30s/120s; action 10s/60s; wait 30s/120s; run wall 20min/30min; idle run TTL 0 (off)/30min; popups 4/16; dialogs 16/64; close grace 5s/30s; network requests 1k/10k; redirects/request 10/32; WebSockets 8/32; screenshots 16/64 with 16/64 megapixels and 10 MiB/32 MiB encoded; uploads 8/32 files, 16 MiB/64 MiB each, 64 MiB/256 MiB aggregate; downloads 8/32 files, 32 MiB/256 MiB each, 64 MiB/512 MiB aggregate.
+- Optional `idleRunTtlMs` (default `0` = off, hard-capped at the run wall-time cap) arms one unref'd manager-scoped sweep interval. A run with no queued action and no activity for the TTL is disposed exactly like `manager.closeRun(runId)` — context and pages closed — so later calls fail with `ERR_PRISM_BROWSER_STATE` and the host can `open()` it again. Any operation (open/snapshot/act/evaluate/observe) resets the clock, in-flight work is never reaped mid-action, and the reaper is cleared by `manager.close()`. Hosts that already close runs explicitly can leave it off; enabling it bounds contexts leaked by abandoned runs.
 - Contexts use `serviceWorkers: "block"` and install `BrowserContext.route()` for every visible HTTP(S)/WebSocket request. `acceptDownloads` is enabled only when `downloads` is configured.
 - `networkPolicy` defaults to `requireContainedProxy: true` (fail closed). Hosts must supply `containedProxyAttestation: { proxyEndpoint, denyDirectEgress: true }`. Private/loopback/link-local, `file`/`data`/`blob`/`javascript`/`devtools` schemes are denied by default. Playwright routing is defense in depth — production DNS/private egress is a host firewall/proxy.
 - Uploads require absolute paths under `uploads.roots` (realpath-contained; symlink escapes rejected). Downloads stream into `downloads.quarantine` with SHA-256/MIME/name metadata; `download_release` requires host `approveRelease`. Screenshots return bounded `ImageContent`.

package/docs/cli-rpc.md

@@ -10,7 +10,7 @@ The `prism` bin is a thin adapter over `AgentSession` plus a tiny project scaffo
 - `prism init <dir>`: create a minimal TypeScript project with one selected provider, `.env.example`, and one offline mock test.
 - `prism dev`: boot the loopback dev inspector over the scaffolded agent (delegates into `@arnilo/prism-coding-tools/dev` when resolvable; plan 040 Task 4).
 
-It does not add a TUI, app tools, provider globals, extension discovery, resource discovery, or credential storage. `init` uses Node standard-library filesystem APIs and checked-in templates only — no interactive prompts or template-engine dependency.
+It does not add a TUI, app tools, provider globals, resource discovery, or credential storage, and it never auto-discovers extension packages — `--extension` loads only explicitly named modules (relative paths inside the working directory, or allow-listed package/absolute specifiers). `init` uses Node standard-library filesystem APIs and checked-in templates only — no interactive prompts or template-engine dependency.
 
 ## Live CLI journey (plans/064 Task 5)
 
@@ -115,6 +115,7 @@ Manifests of the negotiation are simple: the agent is loaded from the scaffold c
 | `--discover` | Opt-in workspace contribution discovery (`SKILL.md`/`manifest.json`). Never auto-activates or imports. |
 | `--discover-kinds <csv>` | Kinds to scan; defaults to `skill`. Accepts `skill,tool,context,instructions`. |
 | `--no-discovery` | Hard-disable discovery even if `--discover` is set. |
+| `--extension <specifier>` | Load a trusted extension module (repeatable). Relative `./`/`../` paths must realpath-contain inside the working directory; package names and absolute paths must exactly match an entry in `PRISM_EXTENSION_ALLOWLIST` (comma-separated), checked before `import()`. See the extension loading section below. |
 | `--agents-config <path>` | App config root holding `agents/<name>/AGENT.md` bundles (opt-in). Envelopes only; the host resolves them via `resolveAgentBundle`. The CLI never defaults to the user's home directory. |
 | `--instruction <name>` | Select a registered/discovered instruction injector (repeatable). `--instruction false` disables injectors for the run. Names resolve fail-closed. |
 | `--injector-file <path>` | Load a markdown file as a static `every_turn` injector (repeatable). |
@@ -124,6 +125,19 @@ Manifests of the negotiation are simple: the agent is loaded from the scaffold c
 | `--system-md-file <path>` | Read SYSTEM.md from `<path>` instead — user-owned, `source: "user"` (Phase 31). |
 | `--help` | Print usage. |
 
+### Extension loading (`--extension`)
+
+```bash
+# cwd-relative trusted module (no allow-list needed)
+prism --provider mock --extension ./my-ext.js -p "hello"
+
+# package name or absolute path requires an exact allow-list entry
+PRISM_EXTENSION_ALLOWLIST=@acme/prism-foo \
+  prism --provider mock --extension @acme/prism-foo -p "hello"
+```
+
+Each module must export `createExtension()`, a default function, or a default `{ name, setup }` extension. Loaded modules are trusted host code (same trust level as the provider factory import) — the gates decide which code may load, not what loaded code may do: relative paths fail closed on realpath escape (symlinks cannot leave the working directory), package/absolute specifiers fail closed without an allow-list entry, and a broken or wrong-shaped module is a usage error, not a silent skip. Registered contributions activate through `activateKernel` into the run's agent (tools, skills, injectors, context, middleware); extension skills follow the normal fail-closed skill activation (`RunOptions.activeSkills`). There is no npm marketplace, no `plugin.json`, and no MCP auto-start.
+
 RPC request envelope:
 
 ```ts

package/docs/contributing.md

@@ -0,0 +1,37 @@
+# Contribution quality budgets
+
+## What it does
+
+Records the code-quality ceilings a change must not raise, and the procedure for lowering them. Three budgets exist today: the non-null assertion allowance per directory, the public export surface per package, and the benchmark/timing envelopes. All live in `scripts/budgets.json` and are enforced by in-chain gates that run as part of `npm test`.
+
+## When to use it
+
+Before a change that adds a `!` non-null assertion, adds a public export, or moves code between directories; and after any sweep that removes them — the recorded numbers are lowered in the same change, never later.
+
+## Non-null assertions
+
+`style/noNonNullAssertion` is an **error** repo-wide in `biome.json`. Directories that still carry legacy sites are switched back to `off` per directory through `overrides`, and `scripts/budgets.json` → `nonNullAssertions` records how many sites remain in each of them.
+
+Rules:
+
+- New code does not add `!`. Narrow the value once — a local `const` behind an explicit guard — or capture the seam in a helper (the durable-session and elicitation seams are the models). Do not trade the assertion for an `as` cast or a `??` placeholder.
+- Keep the allowlist and the budget rows identical: the gate asserts that the `biome.json` allowlist directories and the `nonNullAssertions.byPath` keys describe the same set, so there is no ambiguity about which row an override corresponds to.
+- A sweep lowers the directory's `byPath` number and the `ceiling` in the same change. Raising a number needs a reason in the `$comment`.
+- When a directory reaches zero sites, delete its `overrides` entry and its `byPath` row: the gate fails on a stale zero row rather than letting the allowance rot.
+- The clusters swept in that pass — `src/agent-approval.ts`, `src/agent-loops.ts`, `src/agent-tool-dispatch.ts`, `packages/prism-coding-tools/src/agent/{glob-match,delete,git*}.ts`, `packages/prism-coding-tools/src/agent/language/framing.ts`, and `packages/prism-coding-tools/src/security/{sandbox-tar,sandbox-fs-operations}.ts` — are re-enabled as errors by the last override in `biome.json` (the last matching override wins), so they cannot regress. The gate rejects a rename that would silently drop that enforcement.
+- Measure locally with one pass: `node_modules/.bin/biome lint --only=style/noNonNullAssertion --reporter=json .`. `--only` reports the rule inside allowlisted directories too, which is what makes the counting gate possible; the gate also fails when a site appears outside the allowlist.
+
+## Public export surface
+
+`scripts/budgets.json` → `exportCounts` records a ceiling per package. Growth fails the gate and names the package and the exact delta. Prefer re-exporting an existing symbol (or documenting the host-side composition) over widening a package's surface; moving an existing internal helper between modules does not change the count, because the counter dedupes by name.
+
+## Timing envelopes
+
+Benchmark medians and p95 ceilings in `scripts/budgets.json` are non-flaky sanity bounds, not portable SLOs; the startup gate additionally compares a machine-relative ratio so external CPU load cannot fail the suite. `scripts/benchmark.mjs` produces the evidence-of-record numbers.
+
+## Related APIs
+
+- `scripts/budget-gates.mjs`: `measureNonNullAssertions()`, `evaluateNonNullBudget()`, `measureExportCounts()`, `checkExportBudget()`, and the startup helpers.
+- `scripts/budget-gate.test.mjs`: the in-chain gate, including the negative fixtures that prove each failure mode.
+- `scripts/run-all-tests.mjs`: the stages `npm test` runs (`gate suites` includes the budget gate).
+- [Release and install](release-and-install.md): the release gates that re-assert these budgets before publication.

package/docs/core.md

@@ -21,6 +21,8 @@ npm install pg
 npm install @nats-io/jetstream @nats-io/transport-node
 ```
 
+Every peer below is optional and fails closed at first use; the [optional peer dependencies](peer-dependencies.md) matrix lists the exact ranges, pins, and which of them reach the network.
+
 ## Subpaths Map
 
 | Subpath | Description | Optional Peers |

package/docs/document-reader.md

@@ -1,5 +1,7 @@
 # Document reader (`@arnilo/prism-coding-tools/document-reader`)
 
+> **Optional peer install:** `pdf-parse` and/or `mammoth` — see [Optional peer dependencies](peer-dependencies.md).
+
 ## What it does
 
 Optional bounded literal-text extraction for PDF and DOCX files, consumed by the coding `read` tool (plan 018 closeout `doc-reader`, 0.1.6). `createDocumentReader()` returns a `DocumentReader` that the host wires into `createReadTool(cwd, { documentReader })`; the read tool then extracts text from supported documents instead of falling back to the raw text page.

package/docs/documents.md

@@ -35,7 +35,7 @@ Do **not** use this package for collaborative real-time editing (OT/CRDT), macro
 | `createPatchHistory` | `(initialModel: DocumentModel) => PatchHistory` | Creates an interactive undo/redo history manager for host editing workflows. |
 | `renderPreviewBlocks` | `(model: DocumentModel, options?: PreviewBlocksOptions) => PreviewBlock[]` | Emits framework-neutral structured blocks (document outlines, bounded sheet grid chunks, slide summaries). |
 | `renderPreviewHtml` | `(model: DocumentModel, options?: PreviewHtmlOptions) => string` | Emits safe, bounded HTML fragments with all entities escaped and external URLs neutralized. |
-| `getDocumentModelSchema`| `(options: GetDocumentModelSchemaOptions) => Record<string, unknown>` | Retrieves full Draft-07 JSON Schema or a self-contained sliced sub-schema with resolved `$defs`. |
+| `documentModelSchema` | `(kind: DocumentKind, slice?: string \| readonly string[]) => JsonSchema` | Retrieves the Draft-07 JSON Schema for a document kind, or a self-contained sliced sub-schema with resolved `$defs` (`docModelSchema` / `sheetModelSchema` / `deckModelSchema` expose the unsliced schemas). |
 | `validateDocumentModel`| `(model: unknown) => asserts model is DocumentModel` | Validates arbitrary JSON objects against Draft-07 document schemas and structural invariants. |
 
 ### Capacity Limits and Defaults