@arnilo/prism 0.0.7 → 0.0.8

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+## [0.0.8] - 2026-07-20
+
+### Added
+
+- Added OpenTelemetry GenAI agent/provider/tool hierarchy, context propagation, delegation/guardrail spans, bounded trace references, and evaluation linkage.
+- Added bounded evaluation trace resolution, host model judges, deterministic pairwise reports, serialized artifacts, and CI threshold assertions.
+- Added MCP resources/prompts/roots/sampling/elicitation plus principal-bound Streamable HTTP sessions on pinned SDK 1.29.0, and full A2A 1.0 durable task/rich-part/reconnect/push interoperability.
+- Added immutable-revision CodeQL/dependency/SBOM/license/secret/attestation release gates, weekly dependency updates, and protected bounded provider/MCP/A2A/web live canaries.
+- Added optional `@arnilo/prism-web-tools` with bounded host-selected Brave/Exa search, Firecrawl Markdown/schema extraction, stable citations, late credentials, and explicit untrusted-content results.
+- Added optional `createBatchedRunLedger()` with bounded FIFO/backpressure, explicit durability/flush status, terminal acknowledgement, and documented buffered crash-loss semantics.
+- Added one-leaf, one-second runtime session snapshot caching with mutation/checkout/resume invalidation and reproducible network-free 0.0.8 performance evidence.
+- Versioned all 31 first-party manifests and exact internal ranges to 0.0.8; no tag or publication was created.
+
+### Fixed
+
+- `generateValidateReviseLoop` routes artifact parse failures through the revision budget (`metadata.reason: "parse_error"`, repairer receives `value: undefined`) instead of returning silently after one provider turn.
+- `@arnilo/prism-provider-opencode-go` Anthropic route sends provider-owned `x-api-key` and `anthropic-version: 2023-06-01` headers alongside Bearer, fixing HTTP 401 on MiniMax/Qwen models; `structuredOutput: "json_schema"` is no longer inferred from OpenAI routing alone (verified models only), fixing HTTP 400 on `deepseek-v4-pro`; both stream parsers require protocol completion evidence and fail truncated streams with a terminal `error` instead of a false `done`.
+- `@arnilo/prism-provider-kimi` aligns with official contracts: featured Coding `k3` defaults `reasoning_effort: "high"`, 256K-class context windows use the exact `262_144`, the featured Moonshot catalog adds `kimi-k2.7-code-highspeed`/`kimi-k2.6`/`kimi-k2.5`, routing keys (`route`, `preserve_thinking`) no longer leak into wire bodies, the Coding route sends provider-owned `x-api-key`/`anthropic-version` headers, and both stream parsers fail truncated streams instead of emitting `done`.
+
 ## [0.0.7] - 2026-07-19
 
 ### Added

package/README.md

@@ -53,6 +53,7 @@ npm install @arnilo/prism-sdk @arnilo/prism-provider-openai  # application profi
 npm install @arnilo/prism-all                               # every first-party package
 npm install @arnilo/prism-server @arnilo/prism-workflows    # optional Web API boundary
 npm install @arnilo/prism-supervisor                         # optional local delegation + A2A 1.0
+npm install @arnilo/prism-web-tools                          # optional bounded Brave/Exa/Firecrawl research
 ```
 
 See [docs/release-and-install.md](docs/release-and-install.md) for install
@@ -157,6 +158,7 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-mcp` | MCP client/tool bridge |
 | `@arnilo/prism-workflows` | bounded DAG workflows, durable suspend/resume, schedules/background runs, composition/state/replay, and multi-process coordination |
 | `@arnilo/prism-supervisor` | bounded local child delegation and A2A 1.0 interoperability |
+| `@arnilo/prism-web-tools` | host-selected bounded Brave/Exa search and Firecrawl Markdown/schema extraction |
 | `@arnilo/prism-observability-opentelemetry` | optional OpenTelemetry adapter |
 | `@arnilo/prism-credentials-node` | encrypted-file and keychain credentials |
 | `@arnilo/prism-session-store-sqlite` | SQLite persistence/checkpoints/leases/owned run feedback |
@@ -166,7 +168,7 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-base` | profile: core + compaction + JSON Schema validation |
 | `@arnilo/prism-code` | profile: base + coding tools/security + MCP |
 | `@arnilo/prism-sdk` | profile: base + workflows + MCP + credentials + OpenTelemetry |
-| `@arnilo/prism-all` | every first-party package, including both persistence adapters |
+| `@arnilo/prism-all` | every first-party package, including both persistence adapters and web tools |
 
 ## Scripts
 

package/dist/agent-loops.js

@@ -114,12 +114,14 @@ export function generateValidateReviseLoop(opts) {
                 const parsed = opts.parser
                     ? await opts.parser(text, artifactCtx)
                     : { ok: true, value: text };
-                // Parse failure ends the loop silently (terminal parse errors stay on `error`).
-                if (!parsed.ok || parsed.value === undefined)
-                    return usage;
+                // 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 attempt = ++attempts;
                 ctx.emit({ type: "artifact_validation_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt });
-                const result = await opts.validator(parsed.value, artifactCtx);
+                const result = parseFailure ?? await opts.validator(parsed.value, artifactCtx);
                 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 });
@@ -130,7 +132,7 @@ export function generateValidateReviseLoop(opts) {
                     return usage;
                 }
                 ctx.emit({ type: "artifact_revision_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, failure: result });
-                const repair = await repairer(parsed.value, result, artifactCtx);
+                const repair = await repairer(parseFailure ? undefined : parsed.value, result, artifactCtx);
                 const repairMessages = inputMessages(repair).map((m) => ({ ...m, id: randomId("msg") }));
                 for (const message of repairMessages)
                     await ctx.appendMessage(message);

package/dist/agents.js

@@ -12,6 +12,7 @@ import { errorToErrorInfo, redactAgentEvent, redactProviderRequest, redactRunLed
 import { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 import { createDefaultRetryPolicy, waitForRetry } from "./retry.js";
 import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext } from "./session-stores.js";
+import { isFlushableRunLedger } from "./run-ledger.js";
 import { createToolRegistry, dispatchToolCall } from "./tools.js";
 import { RunLimitError, RunLimitTracker, resolveRunLimits } from "./run-limits.js";
 import { agentFingerprint, initialAgentRunState, loadAgentRunState, publicState, saveAgentRunState, validateRunStateOptions } from "./agent-run-state.js";
@@ -103,6 +104,8 @@ class RuntimeAgentSession {
     activeLoopTurn = 1;
     ledgerChain = Promise.resolve();
     ledgerFailure;
+    snapshotGeneration = 0;
+    snapshotCache;
     constructor(config) {
         this.id = config.id ?? randomId("session");
         this.agent = config.agent;
@@ -168,6 +171,8 @@ class RuntimeAgentSession {
         this.activeIdempotencyKey = options.idempotencyKey ?? this.agent.config.idempotencyKey;
         this.activeGuardrails = mergeGuardrails(this.agent.config.guardrails, options.guardrails);
         this.activeDurable = resumed ?? (durableOptions ? { options: durableOptions, version: 0 } : undefined);
+        if (resumed)
+            this.invalidateSnapshot();
         const model = options.model ?? this.agent.config.model;
         const startedAt = new Date().toISOString();
         let runError;
@@ -442,6 +447,8 @@ class RuntimeAgentSession {
                         ...this.activeOwnership,
                     };
                     await this.activeLedger.appendRun(redactRunLedgerRecord(finishRecord, this.activeRedactor));
+                    if (isFlushableRunLedger(this.activeLedger) && this.activeLedger.durability === "flush_on_terminal")
+                        await this.activeLedger.flush();
                 }
             }
             finally {
@@ -570,6 +577,7 @@ class RuntimeAgentSession {
     }
     async checkout(leafId) {
         this.currentLeafId = leafId;
+        this.invalidateSnapshot();
         await this.rebuildHistory();
     }
     fork(options = {}) {
@@ -853,6 +861,11 @@ class RuntimeAgentSession {
             idempotencyKey: this.activeIdempotencyKey,
         });
         this.currentLeafId = redacted.id;
+        this.invalidateSnapshot();
+    }
+    invalidateSnapshot() {
+        this.snapshotGeneration += 1;
+        this.snapshotCache = undefined;
     }
     redact(value) {
         return this.activeRedactor?.redact(value) ?? value;
@@ -864,10 +877,16 @@ class RuntimeAgentSession {
         this.history = (await this.snapshot()).messages.slice();
     }
     async snapshot() {
+        const now = performance.now();
+        const cached = this.snapshotCache;
+        if (cached && cached.leafId === this.currentLeafId && cached.generation === this.snapshotGeneration && cached.expiresAt > now)
+            return cached.value;
         const reader = this.branchReader();
-        return reader
-            ? rebuildSessionContext(reader, { sessionId: this.id, leafId: this.currentLeafId })
+        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 };
+        return value;
     }
 }
 class EventSubscriber {

package/dist/contracts.d.ts

@@ -1278,6 +1278,21 @@ export interface RunLedger {
 }
 /** Union of records that may be handed to a {@link RunLedger}. */
 export type RunLedgerRecord = RunRecord | AgentEventRecord | ToolCallRecord | UsageRecord;
+export type RunLedgerDurability = "write_through" | "flush_on_terminal" | "buffered";
+export interface RunLedgerFlushResult {
+    readonly accepted: number;
+    readonly flushed: number;
+    readonly buffered: number;
+}
+/** Optional durability seam implemented by bounded ledger adapters. */
+export interface FlushableRunLedger extends RunLedger {
+    readonly durability: RunLedgerDurability;
+    flush(): Promise<RunLedgerFlushResult>;
+    status(): RunLedgerFlushResult;
+    dispose(options?: {
+        readonly flush?: boolean;
+    }): Promise<void>;
+}
 /** Immutable human feedback linked to an existing owned run/trace and optional evaluations. */
 export interface RunFeedbackRecord extends OwnershipScope {
     readonly id: string;

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export type * from "./contracts.js";
 export type { RunLimitCounters, RunLimitName, SecureAgentOptions } from "./contracts.js";
 export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError, AgentRunStateError } from "./contracts.js";
 export { createAgent, createAgentSession, resumeAgentRun } from "./agents.js";
+export { createBatchedRunLedger, isFlushableRunLedger, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_ENTRIES, DEFAULT_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_DELAY_MS, } from "./run-ledger.js";
+export type { BatchedRunLedgerOptions } from "./run-ledger.js";
 export { createSecureAgent } from "./secure-agent.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, requireRunFeedbackOwnership, runFeedbackPageLimit, RunFeedbackError, } from "./feedback.js";
 export type { MemoryRunFeedbackStoreOptions, PrepareRunFeedbackOptions, RunFeedbackLimits, RunFeedbackRun, RunFeedbackRunResolver, } from "./feedback.js";
@@ -81,5 +83,5 @@ export type { DispatchToolCallOptions, ToolArgumentValidationError, ToolArgument
 export type { DuplicateRegistrationOptions, DuplicateRegistrationPolicy } from "./registry-options.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export declare const name = "prism";
-export declare const version = "0.0.7";
+export declare const version = "0.0.8";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError, AgentRunStateError } from "./contracts.js";
 export { createAgent, createAgentSession, resumeAgentRun } from "./agents.js";
+export { createBatchedRunLedger, isFlushableRunLedger, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_ENTRIES, DEFAULT_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_DELAY_MS, } from "./run-ledger.js";
 export { createSecureAgent } from "./secure-agent.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, requireRunFeedbackOwnership, runFeedbackPageLimit, RunFeedbackError, } from "./feedback.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
@@ -44,6 +45,6 @@ export { assertGuardrailsAllowed, GuardrailError, MAX_GUARDRAIL_CONCURRENCY, run
 export { createRunLimitTracker, DEFAULT_RUN_LIMITS, HARD_MAX_RUN_COST, HARD_RUN_LIMITS, RunLimitError, RunLimitTracker, resolveRunLimits } from "./run-limits.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export const name = "prism";
-export const version = "0.0.7";
+export const version = "0.0.8";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/run-ledger.d.ts

@@ -0,0 +1,21 @@
+import type { FlushableRunLedger, RunLedger, RunLedgerDurability } from "./contracts.js";
+export declare const DEFAULT_LEDGER_BATCH_ENTRIES = 128;
+export declare const HARD_LEDGER_BATCH_ENTRIES = 4096;
+export declare const DEFAULT_LEDGER_BATCH_BYTES: number;
+export declare const HARD_LEDGER_BATCH_BYTES: number;
+export declare const DEFAULT_LEDGER_BATCH_DELAY_MS = 25;
+export declare const HARD_LEDGER_BATCH_DELAY_MS = 60000;
+export interface BatchedRunLedgerOptions {
+    readonly maxBatchEntries?: number;
+    readonly maxBatchBytes?: number;
+    readonly maxBufferedEntries?: number;
+    readonly maxBufferedBytes?: number;
+    readonly maxDelayMs?: number;
+    readonly durability?: RunLedgerDurability;
+}
+/**
+ * Wrap any RunLedger with one bounded FIFO. Inputs must already be redacted, as required by RunLedger.
+ * `buffered` may lose accepted records on process crash; call `flush()` for acknowledgement.
+ */
+export declare function createBatchedRunLedger(target: RunLedger, options?: BatchedRunLedgerOptions): FlushableRunLedger;
+export declare function isFlushableRunLedger(ledger: RunLedger): ledger is FlushableRunLedger;

package/dist/run-ledger.js

@@ -0,0 +1,115 @@
+export const DEFAULT_LEDGER_BATCH_ENTRIES = 128;
+export const HARD_LEDGER_BATCH_ENTRIES = 4096;
+export const DEFAULT_LEDGER_BATCH_BYTES = 512 * 1024;
+export const HARD_LEDGER_BATCH_BYTES = 8 * 1024 * 1024;
+export const DEFAULT_LEDGER_BATCH_DELAY_MS = 25;
+export const HARD_LEDGER_BATCH_DELAY_MS = 60_000;
+function integer(value, fallback, hard, name) {
+    const selected = value ?? fallback;
+    if (!Number.isInteger(selected) || selected < 1 || selected > hard)
+        throw new RangeError(`${name} must be an integer in [1, ${hard}]`);
+    return selected;
+}
+function terminal(record) {
+    return record.status !== undefined && record.status !== "queued" && record.status !== "running";
+}
+/**
+ * Wrap any RunLedger with one bounded FIFO. Inputs must already be redacted, as required by RunLedger.
+ * `buffered` may lose accepted records on process crash; call `flush()` for acknowledgement.
+ */
+export function createBatchedRunLedger(target, options = {}) {
+    const maxBatchEntries = integer(options.maxBatchEntries, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_ENTRIES, "maxBatchEntries");
+    const maxBatchBytes = integer(options.maxBatchBytes, DEFAULT_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_BYTES, "maxBatchBytes");
+    const maxBufferedEntries = integer(options.maxBufferedEntries, Math.min(HARD_LEDGER_BATCH_ENTRIES, maxBatchEntries * 2), HARD_LEDGER_BATCH_ENTRIES, "maxBufferedEntries");
+    const maxBufferedBytes = integer(options.maxBufferedBytes, Math.min(HARD_LEDGER_BATCH_BYTES, maxBatchBytes * 2), HARD_LEDGER_BATCH_BYTES, "maxBufferedBytes");
+    const maxDelayMs = integer(options.maxDelayMs, DEFAULT_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_DELAY_MS, "maxDelayMs");
+    const durability = options.durability ?? "flush_on_terminal";
+    const queue = [];
+    let bufferedBytes = 0;
+    let accepted = 0;
+    let flushed = 0;
+    let timer;
+    let flushChain = Promise.resolve();
+    let disposed = false;
+    const status = () => ({ accepted, flushed, buffered: queue.length });
+    const cancelTimer = () => { if (timer)
+        clearTimeout(timer); timer = undefined; };
+    const schedule = () => {
+        if (timer || disposed || queue.length === 0)
+            return;
+        timer = setTimeout(() => { timer = undefined; void flush().catch(() => undefined); }, maxDelayMs);
+        timer.unref?.();
+    };
+    const write = (item) => {
+        if (item.kind === "run")
+            return target.appendRun(item.record);
+        if (item.kind === "event")
+            return target.appendEvent(item.record);
+        if (item.kind === "tool")
+            return target.appendToolCall(item.record);
+        return target.appendUsage(item.record);
+    };
+    const flush = () => {
+        cancelTimer();
+        const operation = flushChain.then(async () => {
+            let entries = 0;
+            let bytes = 0;
+            while (queue.length) {
+                const item = queue[0];
+                if (entries && (entries >= maxBatchEntries || bytes + item.bytes > maxBatchBytes)) {
+                    entries = 0;
+                    bytes = 0;
+                }
+                await write(item);
+                queue.shift();
+                bufferedBytes -= item.bytes;
+                flushed += 1;
+                entries += 1;
+                bytes += item.bytes;
+            }
+            return status();
+        });
+        flushChain = operation.then(() => undefined, () => undefined);
+        return operation;
+    };
+    const enqueue = async (item) => {
+        if (disposed)
+            throw new Error("batched run ledger is disposed");
+        const bytes = Buffer.byteLength(JSON.stringify(item.record));
+        if (bytes > maxBatchBytes || bytes > maxBufferedBytes)
+            throw new RangeError("run ledger record exceeds byte limit");
+        if (queue.length >= maxBufferedEntries || bufferedBytes + bytes > maxBufferedBytes)
+            await flush();
+        queue.push({ ...item, bytes });
+        bufferedBytes += bytes;
+        accepted += 1;
+        if (durability === "write_through" || queue.length >= maxBatchEntries || bufferedBytes >= maxBatchBytes || (item.kind === "run" && terminal(item.record) && durability === "flush_on_terminal"))
+            await flush();
+        else
+            schedule();
+    };
+    return {
+        durability,
+        appendRun: (record) => enqueue({ kind: "run", record }),
+        appendEvent: (record) => enqueue({ kind: "event", record }),
+        appendToolCall: (record) => enqueue({ kind: "tool", record }),
+        appendUsage: (record) => enqueue({ kind: "usage", record }),
+        flush,
+        status,
+        async dispose(disposeOptions = {}) {
+            disposed = true;
+            cancelTimer();
+            if (disposeOptions.flush !== false)
+                await flush();
+            else {
+                await flushChain;
+                queue.length = 0;
+                bufferedBytes = 0;
+            }
+        },
+    };
+}
+export function isFlushableRunLedger(ledger) {
+    return "flush" in ledger && typeof ledger.flush === "function";
+}
+//# sourceMappingURL=run-ledger.js.map

package/docs/a2a.md

@@ -1,75 +1,94 @@
-# A2A interoperability
+# A2A 1.0 interoperability
 
 ## What it does
 
-`@arnilo/prism-supervisor` implements a bounded text-only subset of Agent2Agent (A2A) protocol 1.0: Agent Cards, JSON-RPC `SendMessage`, `SendStreamingMessage`, `GetExtendedAgentCard`, SSE task updates, ES256 JWS card signatures, and an explicit remote client.
+`@arnilo/prism-supervisor` implements bounded A2A 1.0 over the JSON-RPC/HTTPS binding. Supported operations: `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification-config create/get/list/delete, and `GetExtendedAgentCard`. Agent Cards retain explicit ES256 verification. gRPC, HTTP+JSON, discovery registries, automatic JWK/OAuth fetching, and an internal task worker/store are absent.
 
 ## When to use it
 
-Use it to expose one explicitly selected Prism agent at an A2A endpoint or call a known remote A2A agent. Do not use it as endpoint discovery, a generic proxy, credential forwarding, or a replacement for local workflows.
+Use it to expose a selected Prism agent or host-owned durable agent/workflow lifecycle to known A2A peers. Use direct `exposure` for backward-compatible text invocation. Supply `tasks` for durable/rich/reconnect operations and `push` only when host persistence and webhook delivery policy already exist.
 
 ## Inputs / request
 
-| API/field | Meaning |
-| --- | --- |
-| `createA2AAgentCard(card)` | Validates/freeze a JSONRPC protocol-1.0 HTTPS text card. |
-| `signA2AAgentCard(card, { privateKey, keyId, expiresAt })` | Adds detached-payload ES256 JWS signature using WebCrypto. |
-| `verifyA2AAgentCard(card, { publicKey, keyId?, now?, maxAgeMs? })` | Pins ES256/key/expiry and verifies canonical unsigned card. |
-| `createA2AHandler({ card, exposure, authorize })` | Web-standard card/JSON-RPC/SSE `Request` to `Response` handler. |
-| `createA2AClient({ endpoint, allowedOrigins })` | Explicit HTTPS remote client with optional card verifier/auth callback. |
-| `A2ALimits` | Request 64 KiB, response 1 MiB, event 64 KiB, stream 10 MiB/10k events, concurrency 16, timeout 120s, card 64 KiB defaults; finite hard caps apply. |
+```ts
+const handler = createA2AHandler({
+  card,
+  exposure: { sessionFactory }, // text fallback
+  authorize: authenticateEveryOperation,
+  tasks: durableTaskAdapter,    // host-owned start/get/list/cancel/subscribe
+  push: pushConfigAdapter,      // host-owned config persistence/delivery integration
+  parts: {
+    allowRaw: true,
+    allowData: true,
+    allowUrl: true,
+    validateUrl: validatePinnedPublicHttpsUrl, // validation only; never fetched
+  },
+});
+```
 
-## Outputs / response / events
+`A2ATaskLifecycle` receives validated messages, exact `A2AAuthorization`, abort signals, bounded pagination, and reconnect cursor. Adapter must map existing durable agent/workflow/checkpoint/persistence operations; Prism creates no worker, queue, task map, or database table. Unknown-owner task/config lookups return `undefined`, producing non-disclosing `TaskNotFoundError` (`-32001`). Missing task/push capability returns `UnsupportedOperationError` (`-32004`).
 
-The handler serves `GET /.well-known/agent-card.json` and its configured POST endpoint. JSON-RPC returns `{ result: { task } }` or a bounded error. Streaming returns backpressure-driven SSE task envelopes. Client `send()` maps a terminal remote task to `AgentRunResult`; `stream()` incrementally yields validated/redacted text artifacts. Client SSE accepts LF, CRLF, mixed blank-line separators, comments/unknown fields, and multiline `data:` joined with LF.
+`A2APart` is an exact one-of:
 
-## Request/response example
+| Part | Default | Rule |
+| --- | --- | --- |
+| `{ text }` | enabled | bounded UTF-8 text |
+| `{ raw, mediaType?, filename? }` | disabled | strict base64 and decoded-byte cap |
+| `{ data }` | disabled | bounded finite JSON, depth 64/properties 10,000 |
+| `{ url, mediaType?, filename? }` | disabled | credential/fragment-free HTTPS plus required host URL policy; never dereferenced |
 
-```json
-{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"role":"user","messageId":"m1","parts":[{"text":"Check sources"}]}}}
-```
+Parts, messages, artifacts, histories, metadata, and aggregate responses are untrusted. Rich content remains in A2A task/message/artifact contracts for host mapping; it is never promoted to system instructions or automatically loaded as a Prism resource.
 
 ## Implementation example
 
 ```ts
-import { createA2AClient, createA2AHandler, verifyA2AAgentCard } from "@arnilo/prism-supervisor";
-
-const handler = createA2AHandler({
-  card,
-  exposure: { sessionFactory: ({ ownership }) => agent.createSession({ metadata: ownership }) },
-  authorize: ({ request }) => authenticate(request),
-});
-
 const client = createA2AClient({
   endpoint: "https://agent.example/a2a/v1",
   allowedOrigins: ["https://agent.example"],
-  authorize: () => ({ authorization: `Bearer ${resolveOwnedToken()}` }),
-  verifyCard: (remoteCard) => verifyA2AAgentCard(remoteCard, { publicKey, keyId: "agent-key" }),
+  authorize: ownedAuthHeaders,
+  verifyCard: (card) => verifyA2AAgentCard(card, { publicKey, keyId: "agent-key" }),
 });
+const task = await client.getTask("task-1");
+for await (const event of client.subscribeToTask(task.id, { afterEventId: savedCursor })) persistCursor(event.eventId);
+```
+
+## Outputs / response / events
+
+Streams use ordered SSE frames with `id:` and JSON-RPC `result` containing one `A2ATaskEvent`: full `task`, `statusUpdate`, or `artifactUpdate`. `SubscribeToTask({ id, afterEventId })` passes cursor to durable adapter for authorized bounded replay. Duplicate event IDs are rejected/server-bounded; client de-duplicates repeated IDs. Terminal, `INPUT_REQUIRED`, and `AUTH_REQUIRED` states close streams. String-oriented `client.stream()` reports interrupted states as `ERR_PRISM_A2A_INTERRUPTED`; task APIs preserve status for continuation.
 
-const result = await client.send("Check sources");
+Client APIs:
+
+- `send()` / `stream()` preserve text-to-`AgentRunResult` compatibility.
+- `sendMessage()` returns rich/durable `A2ATask`.
+- `getTask()`, `listTasks()`, `cancelTask()`, `subscribeToTask()` operate on durable tasks.
+- `createPushConfig()`, `getPushConfig()`, `listPushConfigs()`, `deletePushConfig()` expose declared push config operations.
+
+Every protocol request sends/negotiates `A2A-Version: 1.0`. Client endpoint/card URLs require exact allow-listed HTTPS and `redirect: "error"`. Cards are parsed then optionally verified against host-pinned keys; no key URL is fetched.
+
+## Request/response example
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"SubscribeToTask","params":{"id":"task-1","afterEventId":"event-42"}}
 ```
 
 ## Extension and configuration notes
 
-The package owns no listener or credential store. Mount the handler in a host server and resolve authentication/authorization on every request. Client auth executes only after body/card validation and serialization. Injectable `fetch` supports host transports/tests; redirects are disabled.
+Handler requires `card.capabilities.pushNotifications` to exactly match supplied `push`; mismatch fails construction, preserving signed-card integrity and preventing false capability claims. Streaming remains available for direct text invocation. Push adapter owns exact-owner persistence, signing/auth credentials, and network transport. Host explicitly calls `deliverA2APushEvent()` from its durable update path; helper bounds event, timeout (10s default/60s hard), attempts (1 default/3 hard), and passes stable event ID as idempotency key to host `A2APushDelivery`. It starts no hidden sender and performs no network itself. Config handling validates IDs/count/bytes and requires same explicit URL policy used for URL parts. Returned push configs omit token and authentication credentials.
 
-Only `text` parts are accepted. File/data parts, push notifications, task persistence/query/cancel, gRPC, HTTP+JSON binding, automatic JWK fetching, and endpoint discovery are intentionally absent.
+Defaults/hard caps include: request 64 KiB/1 MiB; response 1/8 MiB; event 64 KiB/1 MiB; stream 10/64 MiB and 10k/100k events; replay 1k/10k events; concurrency 16/256; timeout 120s/30m; IDs 256/4096 B; parts 32/256; part/raw 1/8 MiB; data 256 KiB/4 MiB; artifacts 32/256; history/page 100/1000; cursor 4/16 KiB; push configs 10/100. Hosts may narrow limits.
 
 ## Security and performance notes
 
-- Endpoints and card URLs must be HTTPS and exactly origin-allow-listed before fetch; `redirect: "error"` prevents redirect SSRF.
-- Treat every remote card, error, task, status, artifact, and SSE frame as untrusted. Shape/count/byte/time limits apply before mapping. Streaming keeps raw stream bytes, current frame bytes, and event count as separate existing limits.
-- One fatal streaming UTF-8 decoder is reused across every body chunk and flushed once at EOF. Split multibyte code points are preserved; malformed/truncated UTF-8 fails rather than inserting `U+FFFD` into JSON. A small coalesced line buffer keeps one-byte chunk handling incremental.
-- SSE frames require a terminating blank line. A non-whitespace final partial frame, malformed JSON, missing terminal task, failed/canceled task, or any event after a completed task fails with bounded package-owned text. Existing request/response/event/stream/count/timeout hard caps are unchanged.
-- Card verification pins `alg=ES256`, optional key ID, issue/expiry, optional maximum age, and canonical unsigned-card payload. Hosts provision trusted public keys; remote `jku` is never fetched automatically.
-- Card discovery is public; extended-card and invoke methods call host authorization. Use TLS, rate limits, and replay controls at the host edge.
-- Credentials remain in the client auth callback or server authorizer and never enter cards, messages, events, or metrics.
-- Offline conformance is authoritative. Live endpoints are optional operator smoke tests.
+- Authorize every operation; lifecycle/push adapters enforce exact owner again at durable storage boundary. Missing and foreign tasks/configs share `-32001`.
+- URL policy must reject private, loopback, link-local, rebound, redirected, or otherwise disallowed destinations. Package never fetches file URLs. Host push delivery must repeat equivalent checks for every attempt/redirect and process event IDs idempotently.
+- Push token/auth credentials are accepted only into host adapter input and removed from protocol reads/responses. Keep them out of task parts, events, telemetry, ledgers, and errors.
+- Known-secret redaction applies before handler JSON/SSE output. Client redacts mapped text/errors. Raw/data/url content remains explicitly untrusted.
+- Canceled/closed streams abort adapter signal, return iterator, clear timeout, and release concurrency slot. Task/push durability and replay retention belong to host adapter and must remain finite.
+- Default tests use in-memory lifecycle/fake fetch only; no public network.
 
 ## Related APIs
 
-- [Supervisor delegation](supervisors.md): local child boundary.
-- [Web-standard server](server.md): non-A2A Prism routes.
-- [Host security](host-security.md): authentication, SSRF, and untrusted-output policy.
-- [Agent/session runtime](agent-session-runtime.md): mapped local execution/result.
+- [Supervisor delegation](supervisors.md)
+- [Agent/session runtime](agent-session-runtime.md)
+- [Workflows](workflows.md)
+- [Host security](host-security.md)

package/docs/agent-events.md

@@ -112,7 +112,7 @@ Artifact validation/refinement events (emitted only by `generateValidateReviseLo
 | `artifact_validation_finished` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` |
 | `artifact_revision_started` | `sessionId`, `runId`, `turn`, `attempt`, `failure: ArtifactValidation` |
 | `artifact_finished` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (loop ended successfully) |
-| `artifact_failed` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (candidate budget exhausted, or `result.metadata.reason === "tool_round_limit"`) |
+| `artifact_failed` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (candidate budget exhausted, `result.metadata.reason === "tool_round_limit"`, or `result.metadata.reason === "parse_error"` when the budget was consumed by artifact parse failures) |
 
 ### Artifact event ordering
 
@@ -208,6 +208,6 @@ for await (const event of session.stream("draft", { loop: { strategy: "generate-
 - [Agent loops](agent-loops.md): `singleShotLoop` and `generateValidateReviseLoop` emit the artifact events.
 - [Structured output](structured-output.md): `ArtifactValidation` shape threaded through parser/validator/repairer.
 - [Public contracts](public-contracts.md): full `AgentEvent` union and `ArtifactValidation` contract.
-- [Observability](observability.md): `ProviderTurnMetadata`, OpenTelemetry adapter package.
+- [Observability](observability.md): `ProviderTurnMetadata`; optional adapter builds one parented GenAI span tree from metadata-only lifecycle events and ignores message/progress deltas.
 - [Tools](tools.md): `tool_execution_*` variants.
 - [Compaction and retry policies](compaction-and-retry.md): `compaction_*` and `retry_scheduled` variants.

package/docs/agent-loops.md

@@ -89,7 +89,7 @@ Host callback contracts (all generic over host `T`):
 
 | Contract | Shape |
 | --- | --- |
-| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. |
+| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. A parse failure (`ok: false` or missing `value`) consumes revision budget exactly like a validation failure: the repairer receives `value: undefined` plus a synthetic failure (`errors[0].message` = the parse error, `metadata.reason: "parse_error"`), and budget exhaustion ends with terminal `artifact_failed`. |
 | `ArtifactValidator<T>` | `(value: T, ctx: ArtifactContext) => ArtifactValidation \| Promise<...>` — return `{ ok: true }` or `{ ok: false, errors }`. |
 | `ArtifactRepairer<T>` | `(value: T \| undefined, failure: ArtifactValidation, ctx: ArtifactContext) => AgentInput \| Promise<...>` — build the revision follow-up input. |
 | `ArtifactValidation` | `{ ok: boolean; errors?: readonly { path?: string; message: string }[]; metadata?: ... }`. |

package/docs/agent-session-runtime.md

@@ -204,6 +204,7 @@ Per-run options may narrow `limits` and append `guardrails`; they cannot replace
 - [Middleware hooks](middleware-hooks.md): hooks that configured assembly/runtime can run.
 - [CLI/RPC](cli-rpc.md): terminal and JSONL adapters over this runtime.
 - [Workflows](workflows.md): optional DAG orchestration that calls `AgentSession.run()` for agent nodes.
+- [A2A interoperability](a2a.md): direct text exposure calls `AgentSession.run()`; durable/rich/reconnect behavior uses host `A2ATaskLifecycle` over existing checkpoints/persistence, never an in-memory runtime cache.
 
 `AgentConfig.loop` and `RunOptions.loop` select a replaceable per-run control loop (`singleShotLoop` default, or `generate-validate-revise` with host callbacks); see [Agent loops](agent-loops.md). `RunOptions.loop` wins over `AgentConfig.loop`. Built-in loops emit the same normal turn/message envelope around provider turns, and both add the first run input to live history once after the first provider turn so later turns see the same transcript shape.
 

package/docs/credential-storage.md

@@ -218,9 +218,18 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Never log passphrases, derived keys, or decrypted credential payloads.
 - Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
 
+## MCP authentication boundary
+
+MCP credentials remain host inputs: resolve them before constructing client `requestInit` or inside server `resolveAuthInfo`. Stateful server `resolveIdentity` receives validated SDK auth metadata only to derive a stable non-secret principal ID. Never copy access/refresh tokens into MCP resource/prompt/sampling/elicitation payloads, telemetry, errors, or session bindings; Prism does not refresh or persist MCP OAuth automatically.
+
+## Web adapter credential boundary
+
+`@arnilo/prism-web-tools` accepts explicit callbacks or `CredentialResolver`. Brave resolves `subscription_token`; Exa and Firecrawl resolve `api_key` immediately before each fixed-origin request. Keys never enter tool arguments/results, URLs, provider metadata, errors, telemetry, or prompts. Use separate least-privilege credentials and do not forward MCP/provider tokens between adapters.
+
 ## Related APIs
 
 - [Credentials and redaction](credentials-and-redaction.md): core resolver helpers and `refreshOAuthCredential()`
+- [Web search, fetch, and extraction](web-tools.md): late-bound Brave/Exa/Firecrawl credentials
 - [Security/auth/trust](settings-auth-trust-security.md): host-owned settings/credentials boundaries
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 threat model and conformance matrix rows 7–10
 - `@arnilo/prism`: `CredentialResolver`, `OAuthCredentialStore`, `createMemoryCredentialStore()`

package/docs/database-persistence.md

@@ -241,7 +241,7 @@ Minimum production guidance:
 
 - **Branch context:** implement `SessionStore.readBranchPath(query)` with an ancestor query / recursive CTE. Treat `SessionStore.list(sessionId)` as an O(n) development fallback only.
 - **Cursor pagination:** every `query*` method should honor `cursor`, `limit`, and `order`. Encode cursors from indexed columns such as `(timestamp, id)`, `(started_at, id)`, `(recorded_at, id)`, or `(run_id, sequence)`; never use offset pagination for long sessions.
-- **Batch appends:** `SessionStore.append()` is single-entry because the runtime advances one branch leaf at a time. Hosts may batch inside their DB/ledger adapters for `RunLedger` rows, but the adapter must preserve per-run event order and must not acknowledge writes before durable enqueue/commit.
+- **Batch appends:** `SessionStore.append()` stays single-entry because runtime advances one branch leaf at a time. Optional `createBatchedRunLedger()` wraps any ledger with bounded FIFO/backpressure and explicit `write_through`, `flush_on_terminal`, or crash-loss-capable `buffered` acknowledgement semantics; SQLite/PostgreSQL defaults remain direct durable writes.
 - **Event sequence allocation:** allocate a monotonic `sequence` per `run_id` when inserting `prism_agent_events`. Use it with `run_id` for stable event timeline pagination when timestamps collide.
 - **Run/event/usage query shapes:** runs page by `(session_id, started_at, id)` or `(branch_id, started_at, id)`; events page by `(run_id, sequence)` or `(session_id, timestamp, id)`; usage pages by `(run_id, recorded_at, id)` or `(session_id, recorded_at, id)`.
 - **Host-owned sizing:** hosts own connection pools, transaction timeouts, page-size caps, queue/batch size, retention jobs, partitioning, and tenant/account/user isolation. Prism does not guess production limits.