@arnilo/prism 0.0.23 → 0.0.25

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolEffectDeclaration, ToolEffectStore, ToolRegistry, ToolResult } from "./contracts.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import { type SecretRedactor } from "./redaction.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
@@ -42,6 +42,8 @@ export interface DispatchToolCallOptions {
     readonly trust?: TrustPolicy;
     readonly redactor?: SecretRedactor;
     readonly ledger?: RunLedger;
+    /** Optional shared recovery store. Only declared optional/required effects use it. */
+    readonly effectStore?: ToolEffectStore;
     readonly ownership?: OwnershipScope;
     /** Host-verified identity; asserted active before tool side effects when present. */
     readonly identity?: import("./identity.js").AgentIdentity;
@@ -55,3 +57,4 @@ export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
 export declare function createToolRegistry(tools?: readonly ToolDefinition[], options?: ToolRegistryOptions): ToolRegistry;
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 export declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>;
+export declare function resolveToolEffectDeclaration(tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext): ToolEffectDeclaration | undefined;

package/dist/tools.js

@@ -1,10 +1,11 @@
 import { isJsonObject } from "./config.js";
 import { GuardrailError, runGuardrails } from "./guardrails.js";
-import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.js";
+import { assertIdentityActive, assertIdentityMatchesOwnership, ownershipFromIdentity } from "./identity.js";
 import { createId } from "./ids.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
 import { assertPermission, assertTrusted } from "./security.js";
+import { deriveToolEffectKey, toolEffectArgumentsHash, ToolEffectError } from "./tool-effects.js";
 /** Wrap a schema adapter as the existing `ToolValidator` seam used by dispatch and the agent runtime. */
 export function createToolParameterValidator(validator, options = {}) {
     const missingSchema = options.missingSchema ?? "allow";
@@ -89,8 +90,9 @@ export async function dispatchToolCall(options) {
     const postcheck = await checkCall(mediatedCall, options, startedAt);
     if (postcheck)
         return postcheck;
-    const context = {
-        ...options.context,
+    const { idempotencyKey: _untrustedKey, ...baseContext } = options.context;
+    let context = {
+        ...baseContext,
         toolCallId: mediatedCall.id,
         identity: options.identity ?? options.context.identity,
         progress: async (progress, metadata) => {
@@ -135,17 +137,38 @@ export async function dispatchToolCall(options) {
     const validation = await options.validate?.(tool, mediatedCall.arguments, context);
     if (validation)
         return blocked(mediatedCall, context, "validation_failed", toErrorInfo(validation, secrets), options, startedAt);
+    let effect;
+    try {
+        const prepared = await prepareToolEffect(tool, mediatedCall, context, options);
+        if (prepared.result)
+            return prepared.result;
+        context = prepared.context;
+        effect = prepared.effect;
+    }
+    catch (error) {
+        return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
+    }
     try {
         await options.beforeExecute?.(mediatedCall, tool, context);
     }
     catch (error) {
-        if (error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED")
+        await failBeforeEffect(effect, isSuspended(error) ? "failed_retryable" : "failed_terminal");
+        // Loop-state contract errors (snapshot capture) are terminal run errors, not tool errors.
+        if (isSuspended(error) || isLoopStateError(error) || isDelegationSuspended(error))
             throw error;
         return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
     }
-    await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
-    await appendToolCallRecord(options, "started", mediatedCall, startedAt, {});
+    let completedResult;
+    let dispatchAttempted = false;
     try {
+        await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
+        await appendToolCallRecord(options, "started", mediatedCall, startedAt, {});
+        if (effect) {
+            dispatchAttempted = true;
+            const record = await effect.store.markDispatched(transition(effect));
+            effect.expectedVersion = record.version;
+            effect.dispatched = true;
+        }
         const raw = await tool.execute(mediatedCall.arguments, context);
         const mediatedResult = await (options.middleware?.run("tool_result", raw) ?? raw);
         const outputGuards = await runGuardrails({
@@ -166,16 +189,51 @@ export async function dispatchToolCall(options) {
         if (outputGuards.terminal) {
             if (outputGuards.terminal.action !== "block")
                 throw new GuardrailError(outputGuards.terminal);
+            if (effect)
+                return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
             return blocked(mediatedCall, context, "guardrail_blocked", { message: "Tool result blocked by guardrail" }, options, startedAt);
         }
+        if (effect && mediatedResult.error)
+            return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
         const result = options.redactor?.redact(mediatedResult) ?? mediatedResult;
+        if (effect) {
+            try {
+                const record = await effect.store.complete({ ...transition(effect), result });
+                effect.expectedVersion = record.version;
+                effect.completed = true;
+                completedResult = record.result ?? result;
+            }
+            catch {
+                return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
+            }
+        }
+        completedResult ??= result;
         const finishedAt = new Date().toISOString();
         const metadata = toolExecutionMetadata(startedAt, "finished");
-        await options.emit?.({ type: "tool_execution_finished", sessionId: context.sessionId, runId: context.runId, result, metadata });
-        await appendToolCallRecord(options, "finished", mediatedCall, startedAt, { finishedAt, result });
-        return result;
+        await options.emit?.({
+            type: "tool_execution_finished",
+            sessionId: context.sessionId,
+            runId: context.runId,
+            result: completedResult,
+            metadata,
+        });
+        await appendToolCallRecord(options, "finished", mediatedCall, startedAt, { finishedAt, result: completedResult });
+        return completedResult;
     }
     catch (error) {
+        if (completedResult)
+            return completedResult;
+        // Nested-run suspensions must propagate to the run loop, never become tool errors.
+        if (isDelegationSuspended(error)) {
+            if (effect && (effect.dispatched || dispatchAttempted))
+                await unknownEffectResult(effect, mediatedCall);
+            else
+                await failBeforeEffect(effect, "failed_retryable");
+            throw error;
+        }
+        if (effect && (effect.dispatched || dispatchAttempted))
+            return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
+        await failBeforeEffect(effect, "failed_terminal");
         if (error instanceof GuardrailError)
             throw error;
         const info = errorToErrorInfo(error, secrets);
@@ -194,6 +252,158 @@ export async function dispatchToolCall(options) {
         return result;
     }
 }
+async function prepareToolEffect(tool, call, context, options) {
+    const identity = context.identity;
+    const declaration = resolveToolEffectDeclaration(tool, call.arguments, context);
+    if (!declaration || declaration.kind === "none" || declaration.idempotency === "none")
+        return { context };
+    if (!identity && declaration.idempotency === "unsupported")
+        return { context };
+    if (!identity)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "verified identity is required for a durable tool effect");
+    const ownership = ownershipFromIdentity(identity);
+    const argumentsHash = toolEffectArgumentsHash(call.arguments);
+    const base = {
+        identity,
+        ownership,
+        sessionId: context.sessionId,
+        runId: context.runId,
+        toolCallId: call.id,
+        toolName: call.name,
+        argumentsHash,
+    };
+    const key = { ...base, key: deriveToolEffectKey(base), signal: context.signal };
+    const keyedContext = { ...context, idempotencyKey: key.key };
+    if (declaration.idempotency === "tool_managed" || declaration.idempotency === "unsupported")
+        return { context: keyedContext };
+    const store = options.effectStore;
+    if (!store) {
+        if (declaration.idempotency === "required")
+            throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_REQUIRED", "durable tool effect store is required");
+        return { context: keyedContext };
+    }
+    let begun;
+    try {
+        begun = await store.begin(key);
+    }
+    catch (error) {
+        if (error instanceof ToolEffectError)
+            throw error;
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect claim outcome is unknown");
+    }
+    if (begun.outcome === "existing")
+        return { context: keyedContext, result: replayEffectResult(begun.record) };
+    if (!begun.record.claimToken)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect claim outcome is unknown");
+    return {
+        context: keyedContext,
+        effect: {
+            store,
+            key,
+            claimToken: begun.record.claimToken,
+            expectedVersion: begun.record.version,
+            dispatched: false,
+            completed: false,
+        },
+    };
+}
+export function resolveToolEffectDeclaration(tool, args, context) {
+    const classifierContext = Object.freeze({
+        sessionId: context.sessionId,
+        runId: context.runId,
+        toolCallId: context.toolCallId,
+        signal: context.signal,
+        metadata: context.metadata,
+    });
+    const declaration = typeof tool.effect === "function" ? tool.effect(args, classifierContext) : tool.effect;
+    if (!declaration)
+        return undefined;
+    if (!["none", "local_mutation", "external_mutation"].includes(declaration.kind) ||
+        !["none", "optional", "required", "tool_managed", "unsupported"].includes(declaration.idempotency) ||
+        (declaration.kind === "none" && declaration.idempotency !== "none")) {
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "tool effect declaration is invalid");
+    }
+    return declaration;
+}
+function replayEffectResult(record) {
+    if (record.status === "completed") {
+        if (record.result)
+            return record.result;
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_COMPLETED", "tool effect already completed without replayable result");
+    }
+    if (record.status === "dispatched" || record.status === "unknown") {
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect outcome requires reconciliation");
+    }
+    throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "tool effect is not dispatchable");
+}
+function transition(effect) {
+    return { ...effect.key, claimToken: effect.claimToken, expectedVersion: effect.expectedVersion };
+}
+async function failBeforeEffect(effect, status) {
+    if (!effect || effect.dispatched || effect.completed)
+        return;
+    try {
+        await effect.store.fail({
+            ...transition(effect),
+            status,
+            failure: { code: "ERR_PRISM_TOOL_EFFECT_PRE_DISPATCH" },
+        });
+    }
+    catch {
+        // No effect was invoked. A stale/failed pre-dispatch transition only delays a later safe retry.
+    }
+}
+async function unknownEffectResult(effect, call) {
+    try {
+        let claim = effect.dispatched
+            ? { claimToken: effect.claimToken, version: effect.expectedVersion }
+            : undefined;
+        if (!claim) {
+            const current = await effect.store.get(effect.key);
+            if (current?.status === "dispatched" && current.claimToken)
+                claim = { claimToken: current.claimToken, version: current.version };
+        }
+        if (claim) {
+            await effect.store.markUnknown({
+                ...effect.key,
+                claimToken: claim.claimToken,
+                expectedVersion: claim.version,
+                failure: { code: "ERR_PRISM_TOOL_EFFECT_UNKNOWN" },
+            });
+        }
+    }
+    catch {
+        // A post-dispatch persistence error is itself ambiguous; never expose or retry it.
+    }
+    return effectErrorResult(call, "ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect outcome requires reconciliation");
+}
+async function finishUnknownEffect(effect, call, context, options, startedAt) {
+    const result = await unknownEffectResult(effect, call);
+    const error = result.error;
+    const finishedAt = new Date().toISOString();
+    const metadata = toolExecutionMetadata(startedAt, "error");
+    try {
+        await options.emit?.({ type: "tool_execution_error", sessionId: context.sessionId, runId: context.runId, call, error, metadata });
+        await appendToolCallRecord(options, "error", call, startedAt, { finishedAt, result });
+    }
+    catch {
+        // The effect is already ambiguous; exposure/ledger failures cannot make it safe to retry.
+    }
+    return result;
+}
+function effectErrorResult(call, code, message) {
+    const error = new ToolEffectError(code, message);
+    return { toolCallId: call.id, name: call.name, error: errorToErrorInfo(error) };
+}
+function isSuspended(error) {
+    return error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED";
+}
+function isLoopStateError(error) {
+    return typeof error?.code === "string" && error.code.startsWith("ERR_PRISM_LOOP_");
+}
+function isDelegationSuspended(error) {
+    return error?.code === "ERR_PRISM_DELEGATION_SUSPENDED";
+}
 async function checkCall(call, options, startedAt) {
     const context = options.context;
     const tool = options.registry.get(call.name);

package/docs/0.1.0-readiness.md

@@ -1,12 +1,12 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.0.23** is the current release line (Phase 6 production enterprise PostgreSQL state adapters); **1.0** readiness remains operator-gated, not automatic.
+Status: **0.0.25** is the current release line (Phase 8 durable custom loops and human-in-the-loop); **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table. The
 **Last evidence** column records the 2026-07-26 **0.0.16** baseline snapshot
 (Phase 11, Node v24.18.0, Linux x86_64). Treat it as historical floor evidence,
 not the current release tag. Re-run each gate on the target release tree before
-cutting 0.0.23 / 1.0. The decision to cut 1.0 stays with the operator after
+cutting 0.0.25 / 1.0. The decision to cut 1.0 stays with the operator after
 operator-gated legs run in a protected environment and Phase 12 demand evidence
 exists.
 
@@ -14,15 +14,16 @@ Evidence trail: [`docs/review-coverage-2026-07-26-phase-11.md`](./review-coverag
 (addenda 0–9), [`docs/release-and-install.md`](./release-and-install.md),
 [`docs/migration.md`](./migration.md), [`docs/performance.md`](./performance.md).
 
-## Current line (0.0.23)
+## Current line (0.0.25)
 
 | Item | Status |
 |---|---|
-| Published graph | **47** publishable manifests at **0.0.23** (`docs/release-and-install.md`) |
-| Phase 6 enterprise state | `@arnilo/prism-enterprise-postgres`: policy/evaluation/work-idempotency/router state, checksummed migration, explicit cleanup |
-| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.22 → 0.0.23 production enterprise state adapters` documents idempotency and async-router changes |
-| Protected database evidence | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; benchmark evidence fixes 10 scenarios, 14 index plans, and 50/100 ms p95 ceilings |
-| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.23 database evidence is recorded separately |
+| Published graph | **47** publishable manifests at **0.0.25** (`docs/release-and-install.md`) |
+| Phase 8 durable loops / HITL | Custom-loop snapshot/restore, shared pending decisions, nested attributions, A2UI + standard AG-UI projectors |
+| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.24 → 0.0.25 durable custom loops and human-in-the-loop` |
+| Network-free Phase 8 evidence | `scripts/phase8-conformance.test.mjs`; `benchmark-0.0.25.json` under Task 0 ceilings |
+| Protected database evidence (Phase 7) | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; `benchmark-0.0.24.json` under prior ceilings |
+| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.25 loop/HITL evidence is recorded separately |
 
 ## Gate table
 
@@ -80,7 +81,7 @@ Deterministic budgets (CI gate, `scripts/budget-gate.test.mjs`):
 | Root unpacked bytes | 2,043,402 | +5% | 2.1 MB (within) |
 | Root file count | 270 | +5% | 270 |
 | Cold-startup import | 38 ms | ceiling 250 ms | ~38 ms |
-| Aggregate packed (47 manifests, reference only) | 1,217,694 | +10% | remeasure for the 0.0.23 graph before release |
+| Aggregate packed (47 manifests, reference only) | 1,217,694 | +10% | remeasure for the 0.0.24 graph before release |
 
 Benchmark medians (on-demand evidence, `scripts/benchmark-0.0.16.mjs`, ±25%):
 

package/docs/a2a.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@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.
+`@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`. `client.streamMessage()` additionally exposes verified rich task/message events for frontend adapters while legacy `stream()` remains text-compatible. 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
 
@@ -59,12 +59,15 @@ Streams use ordered SSE frames with `id:` and JSON-RPC `result` containing one `
 Client APIs:
 
 - `send()` / `stream()` preserve text-to-`AgentRunResult` compatibility.
+- `streamMessage(message)` exposes bounded verified `A2AStreamEvent` task/message records without discarding artifact/data parts.
 - `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.
 
+`createA2AAgentEventSource({ source, resolveTask, map })` supplies only the durable `subscribe` seam for a host-owned `A2ATaskLifecycle`. It resolves task→exact Prism run under authorization, consumes `AgentEventSource.subscribe()`, and uses each opaque source cursor as stable A2A `eventId`. With no cursor, the first mapped update must be a full Task, matching A2A streaming rules. It creates no task store or worker. Standard `SubscribeToTask` has no `afterEventId`; Prism retains that bounded field as an explicitly documented reconnect extension.
+
 ## Request/response example
 
 ```json
@@ -73,7 +76,7 @@ Every protocol request sends/negotiates `A2A-Version: 1.0`. Client endpoint/card
 
 ## Extension and configuration notes
 
-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.
+Handler requires `card.capabilities.pushNotifications` to exactly match supplied `push`; mismatch fails construction, preserving signed-card integrity and preventing false capability claims. `createAgUiA2AAdapter({ client, select, correlate, projectPart })` in `@arnilo/prism-ag-ui` fronts one host-selected verified client: host selects new/follow task mode, persists exact run/thread/task correlation before output, and may project non-text/tool/A2UI parts. It never discovers agents, opens a local session, or replaces this direct A2A API. 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.
 
 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.
 
@@ -95,3 +98,4 @@ Defaults/hard caps include: request 64 KiB/1 MiB; response 1/8 MiB; event 64 KiB
 - [Workflows](workflows.md)
 - [Host security](host-security.md)
 - [Frontend interoperability (AG-UI and ACP)](ag-ui.md): browser/editor protocol adapters over a Prism session; not an A2A card, task lifecycle, or remote-agent transport.
+- [AG-UI adoption evaluation](ag-ui-adoption.md): official AG-UI A2A fronting assessment and shipped explicit adapter.

package/docs/ag-ui-adoption.md

@@ -0,0 +1,77 @@
+# AG-UI adoption evaluation
+
+## What it does
+
+This page records Prism's compatibility review against official AG-UI `@ag-ui/core` **0.0.57** and the official repository at commit [`a40b5c0`](https://github.com/ag-ui-protocol/ag-ui/commit/a40b5c0824564eb2f9ab9edf2be43f355f42a3b8). It separates shipped transport/replay support from remaining work needed to claim full AG-UI support, including AG-UI fronting MCP and A2A agents.
+
+Official material reviewed:
+
+- [Events](https://docs.ag-ui.com/concepts/events), [messages](https://docs.ag-ui.com/concepts/messages), [tools](https://docs.ag-ui.com/concepts/tools), [state](https://docs.ag-ui.com/concepts/state), [reasoning](https://docs.ag-ui.com/concepts/reasoning), [interrupts](https://docs.ag-ui.com/concepts/interrupts), [capabilities](https://docs.ag-ui.com/concepts/capabilities), [serialization](https://docs.ag-ui.com/concepts/serialization), [server quickstart](https://docs.ag-ui.com/quickstart/server), and [protocol architecture](https://docs.ag-ui.com/concepts/architecture).
+- Official [MCP/A2A/AG-UI relationship](https://docs.ag-ui.com/agentic-protocols), [integrations](https://docs.ag-ui.com/integrations), [`@ag-ui/mcp-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-middleware), [`@ag-ui/mcp-apps-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-apps-middleware), [`@ag-ui/a2ui-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2ui-middleware) (Prism ships an in-package opt-in painter with frozen caps; no runtime dependency), [`@ag-ui/a2a`](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/a2a/typescript), and [`@ag-ui/a2a-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2a-middleware).
+- A2A [current specification](https://a2a-protocol.org/latest/specification/) and [streaming rules](https://a2a-protocol.org/latest/topics/streaming-and-async/).
+- MCP Apps [SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp) and the [`io.modelcontextprotocol/ui` draft specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx).
+
+## When to use it
+
+Use this matrix when selecting Prism for an AG-UI client or planning protocol work. Tasks 3A and 3B complete full AG-UI 0.0.57 request/event compatibility plus explicit hardened MCP, MCP Apps, and remote A2A fronting. These are opt-in adapters over existing Prism clients, not an alternate runtime or discovery path.
+
+## Inputs / request
+
+Official `RunAgentInput` fields—lineage, all message roles/history, state, tools, context, props, media, and resume—are schema/bound checked then have no authority until `input.project` returns host-selected messages. Client tools remain client handoffs; state/props/media never grant identity, ownership, or server tools. Resume is exact `${runId}:${version}` CAS; edited arguments deny.
+
+## Outputs / response / events
+
+Prism emits current standard lifecycle, step, text, tool, state, messages, activity, reasoning, raw, and custom families when its mapper or an explicit projector can prove them. Deprecated `THINKING_*` and convenience chunk output are intentionally absent. SSE is baseline; capabilities truthfully narrow to configured replay/projectors/lifecycle, and source cursors remain bounded `prismCursor` metadata for reconnect.
+
+## Request/response example
+
+```json
+{
+  "type": "TEXT_MESSAGE_CONTENT",
+  "messageId": "message-1",
+  "delta": "hello",
+  "prismEventId": "event-42",
+  "prismCursor": "opaque-owner-run-bound-cursor"
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgentEventSourceAgUiReplay, createAgUiHandler } from "@arnilo/prism-ag-ui";
+
+const replay = createAgentEventSourceAgUiReplay(persistence.events, {
+  resolveRun: hostResolveProtocolRun,
+  ownership: (authorization) => authorization.ownership,
+});
+
+const handle = createAgUiHandler({ authorize, sessionFactory, lifecycle, resolveRun, replay });
+```
+
+## Extension and configuration notes
+
+### A2A adoption
+
+A2A stays separately mounted. `createA2AAgentEventSource()` maps durable runs to task events; `afterEventId` remains Prism-only.
+
+`createAgUiA2AAdapter({ client, select, correlate, projectPart })` fronts one verified host-selected client: task text/status becomes AG-UI text/activity, correlation persists before output, and non-text/tool/A2UI needs a schema-validated projector. It uses streaming when declared; fallback accepts only a terminal task. Client origin/card/auth/bounds/abort checks remain active.
+
+### MCP adoption through AG-UI
+
+Prism adapts its hardened MCP bridge; no official middleware or second runtime. `connectMcpTools({ mcpApps: true })` requires `io.modelcontextprotocol/ui` acknowledgement, retains nested UI metadata over deprecated flat metadata, hides app-only tools, and bounds linked `ui://` HTML through `bridge.apps`. `createAgUiMcpAdapter()` selects model-visible tools for normal core dispatch; `createAgUiMcpAppHandler()` reauthorizes one-bridge initialize/ping/logging/tool/resource calls with approval and visibility; sandbox helper returns fixed iframe/CSP constraints. No generic proxy, cross-server call, raw HTML rendering, or automatic mutation retry.
+
+## Security and performance notes
+
+- Every replay/reconnect reauthorizes, then source access uses exact host ownership and host-resolved internal run IDs. Cursor content never selects ownership.
+- Durable streams are at-least-once. Clients deduplicate `prismEventId`; source cursors resume strictly after a durable record.
+- Client tools, state, context, forwarded properties, media URLs/data, remote A2A parts, MCP metadata, HTML, iframe messages, and reasoning blobs are untrusted. Projectors must use existing Prism media URL/SSRF/MIME policy before any resolution.
+- `input.project` and all output projectors are allow-lists; all generic JSON has byte/depth/property/array caps and prototype-pollution keys fail before host callbacks. Tool handoffs are client-only and cannot widen identity, ownership, permissions, or active server tools.
+- MCP Apps requires sandbox-origin separation, restrictive CSP, declared-domain ceilings, audited JSON-RPC, app/tool visibility checks, and user approval for UI-initiated mutations. The shipped proxy does not retry those mutations; Task 4 adds generic durable effect recovery.
+
+## Related APIs
+
+- [Frontend interoperability](ag-ui.md): shipped Prism AG-UI/ACP API.
+- [Agent events](agent-events.md): source events and durable delivery.
+- [Web-standard server](server.md): SSE `Last-Event-ID` reconnect route.
+- [A2A interoperability](a2a.md): separately mounted A2A lifecycle and durable source adapter.
+- [MCP bridge/server](mcp-tools.md): hardened MCP transport and capability boundary reused by future AG-UI MCP support.