@arnilo/prism 0.0.11 → 0.0.13

package/dist/providers/openai-compatible.js

@@ -16,13 +16,22 @@ export function createOpenAICompatibleProvider(options) {
             const secrets = [apiKey];
             const tools = new Map();
             try {
-                const response = await fetchImpl(`${options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                const url = typeof options.chatCompletionsUrl === "function"
+                    ? options.chatCompletionsUrl(request)
+                    : options.chatCompletionsUrl
+                        ?? `${options.baseUrl.replace(/\/$/, "")}/chat/completions`;
+                const authStyle = options.authStyle ?? "bearer";
+                const headers = {
+                    ...Object.fromEntries(Object.entries(request.options?.headers ?? {}).filter((entry) => typeof entry[1] === "string")),
+                    "content-type": "application/json",
+                };
+                if (apiKey && authStyle === "api-key")
+                    headers["api-key"] = apiKey;
+                if (apiKey && authStyle === "bearer")
+                    headers.authorization = `Bearer ${apiKey}`;
+                const response = await fetchImpl(url, {
                     method: "POST",
-                    headers: {
-                        ...request.options?.headers,
-                        "content-type": "application/json",
-                        ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
-                    },
+                    headers,
                     body: JSON.stringify(toOpenAIRequest(request)),
                     signal: request.signal,
                 });

package/dist/secure-agent.js

@@ -1,5 +1,6 @@
 import { createAgent } from "./agents.js";
 import { validateRunStateOptions } from "./agent-run-state.js";
+import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.js";
 import { resolveRunLimits } from "./run-limits.js";
 import { createToolParameterValidator, createToolRegistry } from "./tools.js";
 /** Build an opt-in agent whose security-critical defaults cannot be replaced per run. */
@@ -27,6 +28,10 @@ export function createSecureAgent(options) {
             throw new TypeError(`Secure agent tool ${tool.name} requires a non-empty parameters schema`);
     }
     resolveRunLimits(options.limits);
+    if (options.identity) {
+        assertIdentityActive(options.identity);
+        assertIdentityMatchesOwnership(options.identity, options.ownership);
+    }
     const runState = Object.freeze({ ...options.runState, definitionRevision: options.definitionRevision, interruptBeforeTool: true });
     validateRunStateOptions(runState);
     const config = Object.freeze({
@@ -38,6 +43,7 @@ export function createSecureAgent(options) {
         permission: options.permission,
         trust: options.trust,
         ownership: Object.freeze({ ...options.ownership }),
+        ...(options.identity ? { identity: Object.freeze({ ...options.identity, scopes: Object.freeze([...options.identity.scopes]) }) } : {}),
         limits: Object.freeze({ ...options.limits }),
         guardrails: freezeGuardrails(options.guardrails),
         runState,
@@ -46,7 +52,7 @@ export function createSecureAgent(options) {
     return createAgent(config);
 }
 function withoutSecureFields(options) {
-    const { tools: _tools, toolArgumentValidator: _validator, redactor: _redactor, permission: _permission, trust: _trust, ownership: _ownership, limits: _limits, guardrails: _guardrails, definitionRevision: _revision, runState: _runState, ...config } = options;
+    const { tools: _tools, toolArgumentValidator: _validator, redactor: _redactor, permission: _permission, trust: _trust, ownership: _ownership, identity: _identity, limits: _limits, guardrails: _guardrails, definitionRevision: _revision, runState: _runState, ...config } = options;
     return config;
 }
 function freezeGuardrails(guardrails) {

package/dist/testing/persistence-schema.d.ts

@@ -1,7 +1,7 @@
 import type { PersistencePage, SessionEntry, SessionEntryQuery } from "../contracts.js";
 /** Current shared persistence schema version for production database adapters. */
-export declare const PERSISTENCE_SCHEMA_VERSION = 4;
-export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_migrations";
+export declare const PERSISTENCE_SCHEMA_VERSION = 5;
+export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
 export type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {
     readonly name: string;

package/dist/testing/persistence-schema.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 4;
+export const PERSISTENCE_SCHEMA_VERSION = 5;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -258,6 +258,33 @@ export function createPersistenceSchemaModel() {
                     { name: "metadata", type: "json", nullable: true },
                 ],
             },
+            {
+                name: "prism_legal_holds",
+                primaryKey: ["id"],
+                columns: [
+                    { name: "id", type: "text" },
+                    ...TENANT_COLUMNS,
+                    { name: "resource_kind", type: "text" },
+                    { name: "resource_id", type: "text" },
+                    { name: "reason", type: "text" },
+                    { name: "created_at", type: "timestamp" },
+                    { name: "created_by", type: "text", nullable: true },
+                    { name: "metadata", type: "json", nullable: true },
+                ],
+            },
+            {
+                name: "prism_tenant_quotas",
+                primaryKey: ["id"],
+                columns: [
+                    { name: "id", type: "text" },
+                    ...TENANT_COLUMNS,
+                    { name: "resource_kind", type: "text" },
+                    { name: "limit_count", type: "integer" },
+                    { name: "used_count", type: "integer" },
+                    { name: "updated_at", type: "timestamp" },
+                ],
+                uniqueKeys: [["tenant_id", "account_id", "user_id", "resource_kind"]],
+            },
             {
                 name: "prism_migrations",
                 primaryKey: ["id"],
@@ -298,6 +325,9 @@ export function createPersistenceSchemaModel() {
             { name: "prism_run_feedback_run_created_idx", table: "prism_run_feedback", columns: ["run_id", "created_at", "id"], purpose: "run feedback lookup" },
             { name: "prism_run_feedback_trace_created_idx", table: "prism_run_feedback", columns: ["trace_id", "created_at", "id"], purpose: "trace feedback lookup" },
             { name: "prism_agent_definitions_name_version_idx", table: "prism_agent_definitions", columns: ["name", "version"], purpose: "definition lookup" },
+            { name: "prism_legal_holds_owner_resource_idx", table: "prism_legal_holds", columns: ["tenant_id", "account_id", "user_id", "resource_kind", "resource_id"], purpose: "hold lookup by owned resource" },
+            { name: "prism_legal_holds_created_id_idx", table: "prism_legal_holds", columns: ["created_at", "id"], purpose: "hold export pagination" },
+            { name: "prism_tenant_quotas_owner_kind_idx", table: "prism_tenant_quotas", columns: ["tenant_id", "account_id", "user_id", "resource_kind"], purpose: "tenant quota lookup" },
             { name: "prism_migrations_name_version_idx", table: "prism_migrations", columns: ["name", "version"], purpose: "applied-migration lookup (table constraint enforces uniqueness)" },
         ],
     };
@@ -320,7 +350,9 @@ function migrationStep(version, name, description) {
                 : version === 4
                     // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
                     ? { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
-                    : (() => { throw new Error(`Unknown migration version ${version}`); })();
+                    : version === 5
+                        ? { tables: ["prism_legal_holds", "prism_tenant_quotas"], indexes: ["prism_legal_holds_owner_resource_idx", "prism_legal_holds_created_id_idx", "prism_tenant_quotas_owner_kind_idx"] }
+                        : (() => { throw new Error(`Unknown migration version ${version}`); })();
     return {
         version,
         name,
@@ -338,6 +370,7 @@ export function createPersistenceMigrationContract() {
             migrationStep(2, "002_usage_scope", "Distinguish provider-turn usage from aggregate run totals."),
             migrationStep(3, "003_run_feedback", "Add immutable ownership-scoped run/trace feedback and evaluation links."),
             migrationStep(4, "004_session_search", "Add bounded session search indexes and adapter-local FTS objects."),
+            migrationStep(5, "005_lifecycle_hold_quota", "Add legal-hold and tenant-quota tables for retention lifecycle."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",

package/dist/tools.d.ts

@@ -43,6 +43,8 @@ export interface DispatchToolCallOptions {
     readonly redactor?: SecretRedactor;
     readonly ledger?: RunLedger;
     readonly ownership?: OwnershipScope;
+    /** Host-verified identity; asserted active before tool side effects when present. */
+    readonly identity?: import("./identity.js").AgentIdentity;
     /** Tool stages run after middleware normalization and before side effects/exposure. */
     readonly guardrails?: Guardrails;
     /** Shared run tracker; direct hosts may supply one for their call scope. */

package/dist/tools.js

@@ -1,6 +1,7 @@
 import { isJsonObject } from "./config.js";
 import { createId } from "./ids.js";
 import { GuardrailError, runGuardrails } from "./guardrails.js";
+import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
 import { assertPermission, assertTrusted } from "./security.js";
@@ -89,6 +90,7 @@ export async function dispatchToolCall(options) {
     const context = {
         ...options.context,
         toolCallId: mediatedCall.id,
+        identity: options.identity ?? options.context.identity,
         progress: async (progress, metadata) => {
             await options.context.progress?.(progress, metadata);
             await options.emit?.({
@@ -108,6 +110,10 @@ export async function dispatchToolCall(options) {
         },
     };
     try {
+        if (context.identity) {
+            assertIdentityActive(context.identity);
+            assertIdentityMatchesOwnership(context.identity, options.ownership);
+        }
         await assertTrusted(options.trust, { kind: "tool", target: mediatedCall.name, capability: "execute", metadata: options.context.metadata });
         await assertPermission(options.permission, { kind: "tool", action: "execute", target: mediatedCall.name, metadata: options.context.metadata });
     }

package/docs/a2a.md

@@ -80,6 +80,7 @@ Defaults/hard caps include: request 64 KiB/1 MiB; response 1/8 MiB; event 64 KiB
 ## Security and performance notes
 
 - Authorize every operation; lifecycle/push adapters enforce exact owner again at durable storage boundary. Missing and foreign tasks/configs share `-32001`.
+- Optional `A2AAuthorization.identity` is host-verified; the handler asserts activity/ownership match and forwards identity into `session.run`. Cross-tenant or widened scopes fail closed.
 - 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.
@@ -88,7 +89,9 @@ Defaults/hard caps include: request 64 KiB/1 MiB; response 1/8 MiB; event 64 KiB
 
 ## Related APIs
 
+- [Agent identity](agent-identity.md)
 - [Supervisor delegation](supervisors.md)
 - [Agent/session runtime](agent-session-runtime.md)
 - [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.

package/docs/ag-ui.md

@@ -0,0 +1,123 @@
+# Frontend interoperability (AG-UI and ACP)
+
+## 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.57** events and offers `createAgUiHandler()` (`Request` → SSE `Response`) plus `createPersistenceAgUiReplay()`.
+- `@arnilo/prism-ag-ui/acp` uses stable `@agentclientprotocol/sdk` **1.3.0** root exports for `createAcpEventMapper()` and `createPrismAcpAgent()`.
+- Core remains protocol-free. `resumeAgentRunStream()` / `AgentRunLifecycle.resumeStream()` are generic durable-resume streams shared by adapters.
+
+This is not an app TUI, desktop shell, conversation database, terminal/filesystem bridge, A2A implementation, or frontend tool registry.
+
+## When to use it
+
+Use AG-UI when a host already authenticates users, owns sessions and durable run correlation, and needs a bounded Web endpoint for a browser/TUI/desktop client. Use ACP when an editor client already supplies an ACP transport and needs text, safe tool status, usage, and approval updates from a Prism session.
+
+Use [A2A interoperability](a2a.md) for remote agent-to-agent JSON-RPC/HTTPS tasks. AG-UI/ACP are frontend/client protocol adapters; neither replaces A2A task lifecycle or storage.
+
+## Inputs / request
+
+Install the optional package beside the core runtime (it becomes publishable with the 0.0.12 release graph):
+
+```bash
+npm install @arnilo/prism @arnilo/prism-ag-ui
+```
+
+`createAgUiHandler()` takes host-owned callbacks:
+
+| Input | Purpose |
+| --- | --- |
+| `authorize` | Rebinds untrusted AG-UI thread/run selectors to host ownership on every request. `false` returns 403. |
+| `sessionFactory` | Returns an authorized Prism `AgentSession`; client input never selects tools or capabilities. |
+| `lifecycle` + `resolveRun` | Optional durable status/resume path. Required only for a resumed interruption. |
+| `replay` | Optional `createPersistenceAgUiReplay(store, options)` adapter for ownership-scoped durable pages. |
+| `projection` | Explicit safe tool args/results, paths, or state projection. Omit it for default deny. |
+| `redactor`, `limits` | Host redaction and narrowing-only finite caps. |
+
+The handler accepts only `POST` JSON validated with AG-UI `RunAgentInputSchema`. IDs are bounded URL-safe values; it uses only the last text user message. Frontend tools and non-empty frontend state are rejected before authorization or session lookup. Start a run with no `resume` and no `?cursor=`; resume has exactly one entry; replay supplies `?cursor=`.
+
+## Outputs / response / events
+
+The handler returns `text/event-stream`, one `data: <AG-UI event>\n\n` frame per output. Mapper lifecycle is ordered: Prism `agent_started`/assistant text/tool events map to `RUN_STARTED`, `TEXT_MESSAGE_*`, and `TOOL_CALL_*`; terminal success maps to `RUN_FINISHED`; runtime errors map to `RUN_ERROR`. Active AG-UI message/tool sequences close before an error, interruption, or finish.
+
+A Prism durable `agent_suspended` returns `RUN_FINISHED` with interrupt id `${runId}:${version}` and a strict `{ decision: "approve" | "deny" }` schema. A client must address that exact current id. `cancelled` means deny; a resolved resume payload must contain only that decision. The adapter checks host authorization, selected run, suspended status, and checkpoint version, then calls `AgentRunLifecycle.resumeStream()` once. Claimed/dispatched tools are never replayed.
+
+`createPersistenceAgUiReplay()` queries only the host-resolved run with ownership and ascending bounded pagination. Every record must already be redacted. Events carry `prismEventId` for at-least-once page-boundary de-duplication; a nonterminal final page may attach a filtered live subscriber. Terminal pages never create a session or rerun a provider/tool.
+
+ACP maps assistant text to `agent_message_chunk`, safe tool lifecycle to `tool_call`/`tool_call_update`, provider usage to `usage_update`, and durable suspension to `session/request_permission`. Only `allow_once` approves; reject, cancellation, unknown outcomes, and request failure deny. It advertises only close-session capability—no terminal, filesystem, MCP, editor state, location, diff, or raw input/output capability.
+
+## Request/response example
+
+```json
+{
+  "threadId": "thread-1",
+  "runId": "run-1",
+  "messages": [{ "id": "message-1", "role": "user", "content": "Summarize this" }],
+  "tools": [],
+  "state": {}
+}
+```
+
+A suspended response includes this resumable interrupt shape:
+
+```json
+{
+  "type": "RUN_FINISHED",
+  "threadId": "thread-1",
+  "runId": "run-1",
+  "outcome": {
+    "type": "interrupt",
+    "interrupts": [{ "id": "run-1:4", "responseSchema": { "required": ["decision"] } }]
+  }
+}
+```
+
+Resume the same host thread/run with `resume: [{ "interruptId": "run-1:4", "status": "resolved", "payload": { "decision": "approve" } }]`. Do not send a copied session transcript, tool definitions, or mutable application state.
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { createAgUiHandler } from "@arnilo/prism-ag-ui";
+
+const agent = createAgent({
+  model: { provider: "mock", model: "offline" },
+  provider: createMockProvider([providerTextDelta("ready"), providerDone()]),
+});
+
+const handle = createAgUiHandler({
+  authorize: ({ request }) => request.headers.get("authorization") === "Bearer host-checked"
+    ? { ownership: { userId: "user-1" } }
+    : false,
+  sessionFactory: () => agent.createSession({ id: "host-owned-thread" }),
+  projection: { toolArguments: () => undefined, toolResult: () => undefined },
+});
+
+const response = await handle(request); // adapt this Web Response in host framework
+```
+
+See runnable network-free [`examples/ag-ui-server.ts`](../examples/ag-ui-server.ts). For ACP, construct `createPrismAcpAgent({ authorize, sessionFactory, lifecycle })` and connect the returned stable SDK agent through the host's ACP transport.
+
+## Extension and configuration notes
+
+All identity, authorization, session/thread mapping, durable checkpoint lookup, persistence selection, replay cursor persistence, transport adaptation, and optional projection are host-owned. The adapter owns no listener, database, background reconnect loop, credential resolver, or UI state.
+
+`AgUiProjection` is an allow-list. Without a callback, raw tool arguments/results/progress, paths, arbitrary state, raw Prism events, ACP locations/diffs/terminals/raw I/O, and frontend-supplied tools remain absent. Use a projector that returns a redacted display value, not a host filesystem path or tool payload.
+
+## Security and performance notes
+
+Authorize every start, replay, resume, ACP new/prompt/cancel/close request. Treat thread IDs, run IDs, cursors, client messages, resume payloads, and protocol output as untrusted. Persist run ↔ protocol correlation before exposing an interrupt. Keep `SecretRedactor` active for streaming and ledger writes.
+
+Defaults / hard caps: request 64 KiB / 1 MiB; input 128 / 1024 messages and 64 KiB / 1 MiB text; projected event 64 KiB / 1 MiB; error 8 KiB / 64 KiB; cursor 4 / 16 KiB; replay page 100 / 500 records; queue 128 / 4096 events; stream 10,000 / 100,000 events and 10 / 64 MiB; wall time 120 seconds / 30 minutes. Overflow yields a bounded error/closed stream, not an unbounded queue. Reconnect is at-least-once, so clients de-duplicate stable event/message/tool IDs.
+
+Benchmark command/result placeholder: Task 8 adds `node scripts/benchmark-0.0.12.mjs` for mapper throughput, replay/handler latency, queue/heap, bytes, and coding-compaction preparation. No 0.0.12 timing result is claimed before that gate.
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md): `session.stream()`, `resumeAgentRunStream()`, and durable lifecycle.
+- [Agent events](agent-events.md): normalized source events and ledger redaction.
+- [Runs and usage ledger](runs-and-usage.md): durable `AgentEventRecord` query source.
+- [Web-standard server handler](server.md): generic Prism HTTP API, separate from AG-UI.
+- [A2A interoperability](a2a.md): remote agent-to-agent tasks, not frontend protocol mapping.
+- [Host security guide](host-security.md): authorization, ownership, redaction, and credential boundaries.

package/docs/agent-events.md

@@ -191,7 +191,7 @@ for await (const event of session.stream("draft", { loop: { strategy: "generate-
 
 - All events flow through `redactAgentEvent(event, activeRedactor)` before subscribers observe them. Configure `AgentConfig.redactor` / `RunOptions.redactor` via `createSecretRedactor([...knownSecretStrings])` so secret values are redacted in `message` content, `errors[].message`, `metadata`, and artifact `result`/`failure` payloads.
 - The artifact variants are emitted only by `generateValidateReviseLoop`. `singleShotLoop` (the default when no `AgentConfig.loop` / `RunOptions.loop` is set) emits zero artifact events. See [Agent loops](agent-loops.md).
-- Subscribers are in-process; the broadcaster is in-memory and live-only. Multiple `subscribe()` calls receive the same stream.
+- Subscribers are in-process; the broadcaster is in-memory and live-only. Multiple `subscribe()` calls receive the same stream. `resumeAgentRunStream()` and `AgentRunLifecycle.resumeStream()` subscribe before resumed execution and yield only their selected durable `runId`; approval emits the normal `agent_started` then `agent_resumed` envelope, denial emits only `agent_denied`.
 - `session.subscribe(options)` accepts `maxQueuedEvents` (default `1024`, minimum `1`) and `overflow` (default `"close"`). The `close` policy clears queued payload events, queues one `event_subscriber_overflow` notice for that subscriber, then closes it. `drop_oldest` keeps the newest queued events; `drop_newest` ignores new events while full.
 - The union is additive: new variants are appended without renumbering; subscribers should handle unknown `event.type` gracefully.
 
@@ -212,3 +212,4 @@ for await (const event of session.stream("draft", { loop: { strategy: "generate-
 - [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.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional redacted mapping of this stream; durable replay is ledger-backed and at-least-once, never a live-subscriber substitute.

package/docs/agent-identity.md

@@ -0,0 +1,111 @@
+# Agent identity
+
+## What it does
+
+Authenticated `Principal` / `AgentIdentity` contracts let hosts attach verified tenant, sponsor/owner, delegated actor, scopes, credential references, issued/expiry, and revocation metadata to runs and tools. Core helpers assert activity, narrow scopes for delegation, project onto `OwnershipScope`, refuse silent widening, and emit redacted telemetry attributes. Prism does not store identities or verify tokens itself — hosts supply an `IdentityVerifier`.
+
+## When to use it
+
+Use these APIs when embedding Prism in multi-tenant or enterprise hosts that already authenticate callers (for example Microsoft Entra Agent ID governance). Use them before tools, providers, MCP, A2A, workflows, or persistence that must carry attributable identity.
+
+Do not treat optional `ownership` strings as identity provenance. Do not accept caller-asserted identity headers without a host verifier. Do not put JWTs or secret credential material on identity records.
+
+## Inputs / request
+
+| Field | Meaning |
+| --- | --- |
+| `Principal` | Actor id/kind (user, service, agent) plus optional display name |
+| `AgentIdentity` | Verified context: required `tenantId`, optional account/user, principal, sponsor/owner, scopes, credential refs, issued/expiry/revocation, `verified: true` |
+| `IdentityVerifier.verify(input)` | Host-owned authentication → `AgentIdentity` |
+| `RunOptions.identity` / `AgentConfig.identity` | Optional verified identity for a run or agent default |
+| Server/MCP/A2A `authorization.identity` | Optional verified identity on authorize results |
+
+Frozen caps (defaults / hard): scopes `64 / 256`, scope bytes `128 / 512`, metadata `4 KiB / 16 KiB`, credential ref / principal id `256 B / 2 KiB`.
+
+## Outputs / response / events
+
+- `assertIdentityActive` — fail closed on unverified/expired/revoked/wrong-tenant/over-limit shapes (sync, no network).
+- `narrowIdentity` — child scopes ⊆ parent; tenant and ownership ids immutable; expiry cannot extend.
+- `ownershipFromIdentity` — projects tenant/account/user onto existing ownership seams.
+- `assertIdentityMatchesOwnership` / `assertIdentityPropagation` — refuse widen across ownership or boundary hop.
+- `identityTelemetryAttributes` — redacted refs for metadata/OTel (`prism.identity.*`); never includes credential secrets or raw tokens.
+- Tool `ToolExecutionContext.identity` — set when a run carries verified identity.
+
+## Request/response example
+
+```json
+{
+  "tenantId": "tenant-1",
+  "userId": "user-1",
+  "principal": { "kind": "agent", "id": "agent-42" },
+  "sponsor": { "kind": "user", "id": "sponsor-7" },
+  "scopes": ["mail.read", "mail.draft"],
+  "credentialRefs": ["m365:tenant-1:user-1"],
+  "issuedAt": "2026-07-23T00:00:00.000Z",
+  "expiresAt": "2026-07-23T01:00:00.000Z",
+  "verified": true
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  assertIdentityActive,
+  createAgent,
+  identityTelemetryAttributes,
+  narrowIdentity,
+  ownershipFromIdentity,
+  type AgentIdentity,
+  type IdentityVerifier,
+} from "@arnilo/prism";
+
+const verifier: IdentityVerifier = {
+  async verify(request) {
+    // Host validates JWT/session, then returns AgentIdentity with verified: true
+    return hostVerifiedIdentityFrom(request);
+  },
+};
+
+const identity = await verifier.verify(incomingRequest);
+assertIdentityActive(identity);
+const child = narrowIdentity(identity, { scopes: ["mail.read"] });
+
+const agent = createAgent({
+  model,
+  provider,
+  ownership: ownershipFromIdentity(identity),
+  identity,
+});
+
+await agent.createSession().run("Summarize inbox", {
+  identity: child,
+  ownership: ownershipFromIdentity(child),
+  metadata: identityTelemetryAttributes(child),
+});
+```
+
+Server / MCP / A2A authorize callbacks may include the same `identity` beside `ownership`. Handlers assert activity and ownership match before admitting work.
+
+## Extension and configuration notes
+
+Identity is optional. Hosts that only set `ownership` keep prior behavior. When identity is present, run start and tool dispatch assert it before side effects. Workflows forward `RunWorkflowOptions.identity` into agent nodes. Credential values stay behind `CredentialResolver` keys listed in `credentialRefs`.
+
+## Security and performance notes
+
+- Caller-asserted identity without `IdentityVerifier` is unsupported at trust boundaries.
+- Delegation only narrows scopes; tenant/account/user cannot widen on propagation.
+- Credential refs never expand to secrets in events, ledgers, or telemetry attributes.
+- Checks are O(fields) and network-free in core; remote auth stays in the host verifier.
+- Raising hard caps requires updating `docs/review-coverage-2026-07-23-phase-8.md`, tests, and docs.
+
+## Related APIs
+
+- [Policy and audit](policy-and-audit.md)
+- [Host security guide](host-security.md)
+- [Public contracts](public-contracts.md)
+- [Server](server.md)
+- [Supervisors](supervisors.md) / [A2A](a2a.md)
+- [MCP tools](mcp-tools.md)
+- [Observability](observability.md)
+- [Runs and usage ledger](runs-and-usage.md)

package/docs/agent-session-runtime.md

@@ -19,6 +19,7 @@ The agent/session runtime adds the minimal shared SDK surface for running provid
 - `session.fork(options?)`
 - `session.clone(options?)`
 - `resumeAgentRun(agent, ref, decision, options)`
+- `resumeAgentRunStream(agent, ref, decision, options)` → owned durable-resume `AsyncIterable<AgentEvent>`
 - `createAgentRunLifecycle({ checkpoints, resolveAgent })` for host-selected remote status/resume adapters
 
 The runtime streams provider text/tool-call content into `AgentEvent` values. Complete `tool_call` events are dispatched through the active host `ToolRegistry`, then returned as tool-result messages on the next provider turn. When a store is supplied, user, assistant, tool-result, and model-change entries are appended under the current branch leaf. Abort propagation and run exclusivity use native `AbortController`.
@@ -56,6 +57,8 @@ string | Message | readonly Message[]
 
 `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`.
 
+`resumeAgentRunStream(agent, ref, resume, options?)` does the same for one existing suspended durable run. It validates checkpoint ownership, revision/fingerprint, and `expectedVersion`, then subscribes before emitting `agent_started` / `agent_resumed` and resumed message/tool/terminal events. `AgentRunResumeStreamOptions` combines existing resume options with `signal`, `maxQueuedEvents`, and `overflow`; early return aborts only resumed execution. It does not replay a claimed/dispatched tool, poll a ledger, or retain a worker. `createAgentRunLifecycle().resumeStream(ref, resume, request?)` adds the same behavior after host agent-capability resolution.
+
 `session.subscribe(options?)` remains available for hosts that want a long-lived subscriber across runs. Subscribe before `run()` to observe that run's events. The consumer loop and `session.run()` must run concurrently (e.g. start the `for await` consumer, then `await Promise.all([consumer, session.run("Hi")])`): events are only emitted during a live run, so awaiting the subscribe loop before calling `run()` deadlocks. Prefer `session.stream()` when you only need one run's events. `SubscribeOptions.maxQueuedEvents` defaults to `1024` (minimum `1`) and caps events queued while the consumer is not awaiting `next()`. `SubscribeOptions.overflow` defaults to `"close"`; it clears queued payload events, delivers one `event_subscriber_overflow` notice to that subscriber, then closes it. `"drop_oldest"` keeps newest events; `"drop_newest"` ignores new events while full.
 
 For a text-only provider turn, the runtime emits:
@@ -184,7 +187,7 @@ if (result.status === "suspended") {
 }
 ```
 
-Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. Only built-in loop options are durable; custom `AgentLoopStrategy` rejects before provider work.
+Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. `resumeStream()` uses that same claim path and bounded subscriber, so adapters do not poll or duplicate resume logic. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. Only built-in loop options are durable; custom `AgentLoopStrategy` rejects before provider work.
 
 ## Secure composition
 
@@ -209,6 +212,7 @@ Per-run options may narrow `limits` and append `guardrails`; they cannot replace
 - [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.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional adapters use `session.stream()` and `resumeAgentRunStream()` / `AgentRunLifecycle.resumeStream()`; protocol/UI state remains outside core.
 
 `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/coding-agent-tools.md

@@ -379,6 +379,7 @@ const remoteWrite = createWriteTool("/repo", {
 
 ## Extension and configuration notes
 
+- **Long coding sessions.** Use `createCodingCompactionStrategy()` from optional `@arnilo/prism-compaction-llm` when history needs a bounded coding handoff. It is selected explicitly through normal `session.compact()` / agent compaction configuration, preserves raw session entries, and prioritizes file paths, patch intent, checks, plan/todo state, blockers, and verification steps. It does not read files, retain full diffs, or create a second coding runtime.
 - **Pluggable operation backends.** Every tool accepts an `operations` seam. Custom `ReadOperations` must implement bounded `readText` plus `statFile`; custom `EditOperations` must implement `statFile`; read/write methods receive caps/signals. `BashOperations` must stream through `onData` and honor `signal`/`timeout`. Custom `RepositoryOperations` must honor depth/entry/file/match/scan/time caps and abort. A hostile custom backend can still violate its host-owned contract, so isolate it separately.
 - **Per-tool options.** `ShellToolOptions` adds `timeout` and `maxTotalOutputBytes`; `ReadToolOptions` adds `maxScanBytes`; `WriteToolOptions` adds `maxInputBytes`; `EditToolOptions` adds `maxFileBytes`, `maxInputBytes`, and `maxEdits`; list/search accept `repository` limits and shared aggregator `ToolsOptions.repository`.
 - **Aggregator options.** `ToolsOptions` (`{ executionPolicy?, shell?, read?, write?, edit?, list?, search?, repository? }`) threads each sub-object to the matching tool. `createCodingTools()`, `createAllTools()`, and `createReadOnlyTools()` apply the shared policy unless that tool has an explicit per-tool override. Read-only membership is deliberately `read` + `repo_list` + `repo_search` (0.0.9 behavior change).
@@ -425,3 +426,4 @@ Every configurable value is a positive safe integer (context may be zero); Prism
 - [Public contracts](public-contracts.md): `ToolDefinition`, `ToolResult`, `ToolExecutionContext`, `ContentBlock`, and `JsonObject` shapes.
 - [Host security guide](host-security.md): fail-closed checklist for permission policies, tool validation, and trust boundaries that must gate these tools.
 - [Tool conformance](tool-conformance.md): assertions for the tool-dispatch blocked-reason matrix these tools participate in.
+- [LLM compaction package](compaction-llm.md): optional `createCodingCompactionStrategy()` retains bounded paths, patch intent, checks, plan/todo state, blockers, and next verification—not complete diffs or raw command output.

package/docs/compaction-and-retry.md

@@ -149,7 +149,7 @@ Retry policies are ordinary `RetryPolicy` implementations and can be registered
 
 Compaction strategies are ordinary `CompactionStrategy` implementations. Extensions can register strategies through the existing compaction strategy contribution registry, but registration is inert until a host explicitly selects and passes a strategy to runtime code. Extensions can also register `compaction` middleware; the runtime calls it only when the agent/session has that middleware registry configured.
 
-The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-compaction-llm` package](compaction-llm.md); its `maxOutputTokens`/`maxSummaryTokens` budget is passed through `model.parameters.maxTokens` and first-party providers serialize that to provider output-token fields. Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-compaction-observational-memory`](compaction-observational-memory.md).
+The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-compaction-llm` package](compaction-llm.md); its `maxOutputTokens`/`maxSummaryTokens` budget is passed through `model.parameters.maxTokens` and first-party providers serialize that to provider output-token fields. Coding sessions can select that package's `createCodingCompactionStrategy()` preset for paths, patch intent, checks, plans/todos, blockers, and next verification steps; it remains an ordinary `CompactionStrategy` and does not retain complete diffs or add a coding runtime. Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-compaction-observational-memory`](compaction-observational-memory.md).
 
 ## Security and performance notes
 
@@ -173,5 +173,6 @@ The default strategy does not call a provider. Hosts that need model-generated s
 - [Configuration and manifests](configuration-and-manifests.md): `compactionStrategy` and `retryPolicy` manifest contribution kinds.
 - [Provider layer](provider-layer.md): safe provider error codes used by retry classification.
 - [Credentials and redaction](credentials-and-redaction.md): exact secret redaction helper used by default compaction and retry error handling.
+- [LLM compaction package](compaction-llm.md): `createCodingCompactionStrategy()` is the thin coding-focused preset; see `examples/coding-compaction.ts` for a network-free mock.
 
 Runtime redaction composes with compaction and retry secret lists: configured redactors apply at session serialization boundaries, while compaction/retry `secrets` still redact their local summaries and errors.

package/docs/compaction-llm.md

@@ -12,6 +12,7 @@ Key exports:
 | Export | Purpose |
 | --- | --- |
 | `createLlmCompactionStrategy(options)` | Returns a provider-backed `CompactionStrategy`. |
+| `createCodingCompactionStrategy(options)` | Fixed `coding` preset over the LLM strategy: prioritizes file paths, patch intent, commands/checks, plan/todos, blockers, and next verification while retaining normal limits and raw history. |
 | `createLlmCompactionExtension(options)` | Registers the strategy into an explicit extension kernel compaction registry. |
 | `prepareLlmCompaction(context, options?)` | Splits branch entries into summary input, kept suffix, optional split-turn prefix, file details, and compaction data. |
 | `findLlmCompactionCutPoint(entries, options?)` | Finds the last entry covered by a summary using approximate token budgets. |
@@ -76,6 +77,23 @@ const strategy = createLlmCompactionStrategy({
 await session.compact({ strategy, secrets: [apiKey] });
 ```
 
+Coding-session example:
+
+```ts
+import { createCodingCompactionStrategy } from "@arnilo/prism-compaction-llm";
+
+const strategy = createCodingCompactionStrategy({
+  provider: summaryProvider,
+  summaryModel: { provider: "openai", model: "gpt-4.1-mini" },
+  keepRecentTokens: 20_000,
+  maxSummaryTokens: 800,
+  customInstructions: "Keep migration blockers prominent.",
+});
+await session.compact({ strategy });
+```
+
+The preset always uses strategy name `coding` and enables existing read/modified-file retention. It adds no provider call, parser, worker, filesystem access, or complete-diff retention beyond `createLlmCompactionStrategy()`.
+
 Credential factory example:
 
 ```ts
@@ -108,7 +126,7 @@ Preparation is O(n) over branch entries and uses only arrays, strings, and JSON
 
 Provider deltas are redacted while retained and stop at `maxSummaryTokens * 4` UTF-16 code units without splitting a surrogate pair. Provider iteration is closed/aborted on overflow. A derived finite event ceiling also stops endless empty/non-text deltas. Final history/turn/file composition receives the same cap. Provider error events, generator throws, provider-factory failures, and policy failures expose only bounded redacted detail; host abort remains authoritative.
 
-The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
+The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. The coding preset makes the same calls and uses the same bounded file-operation preparation. Neither discovers credentials, reads files, starts background jobs, or adds provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history, paths, instructions, or provider output.
 
 ## Related APIs
 
@@ -119,3 +137,4 @@ The strategy makes only the needed provider call(s): one history summary plus on
 - [Agent/session runtime](agent-session-runtime.md): `AgentSession.compact()` and opt-in auto-compaction.
 - [Provider layer](provider-layer.md): mock providers and provider request contracts.
 - [Credentials and redaction](credentials-and-redaction.md): exact known-secret redaction behavior.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): separate optional frontend transport; coding compaction adds no UI protocol dependency.

package/docs/credential-storage.md

@@ -205,7 +205,8 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Use distinct `namespace` or vault paths per tenant/environment.
 - Keychain `list()` / `listOAuth()` are intentionally unsupported — enumerate credentials through host configuration instead of scanning the OS store.
 - Combine with `createExplicitCredentialResolver()` so runtime overrides still win over stored values.
-- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` so refreshed tokens persist durably.
+- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` only for an OAuth flow explicitly selected by the host and authorized by that provider. In 0.0.12 that means OpenAI Codex; Anthropic and Google packages accept API keys only. Never import or migrate Claude Code/Gemini CLI credential files, setup tokens, browser sessions, or CLI OAuth rows into this store.
+- Enterprise cloud providers (`azure` / `bedrock` / `vertex`) expect host workload-identity callbacks (Entra / IAM / ADC), not this local encrypted/keychain store as a cloud token minting service. Store may hold opaque refresh material only when the host already owns the cloud auth flow.
 
 ## Security and performance notes
 
@@ -216,6 +217,8 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Keychain operations use `@napi-rs/keyring`'s abort-aware `AsyncEntry`, so native work runs outside the JavaScript event loop. A main-loop timer aborts and rejects at `timeoutMs`; native cancellation remains OS/backend-dependent and may briefly retain one libuv worker after rejection.
 - Keychain payloads are bytes rather than password strings and are zeroed after parse/write. Unknown native errors are mapped to sanitized typed errors; no native message or secret value is echoed.
 - Never log passphrases, derived keys, or decrypted credential payloads.
+- Optional host KMS: `encryptWithHostKms` / `decryptWithHostKms` wrap a random AES-256-GCM DEK via host `HostKms.wrapKey`/`unwrapKey` (timeout ≤ 60 s). Envelope sizes reuse vault/file caps. Keys are never logged. `createMemoryHostKms` is for tests only.
+- Storage is not OAuth eligibility. A durable store may persist credentials for a provider only after the host selects a provider-authorized flow; it must not be used to piggyback on a vendor CLI or consumer subscription.
 - Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
 
 ## MCP authentication boundary
@@ -229,6 +232,7 @@ MCP credentials remain host inputs: resolve them before constructing client `req
 ## Related APIs
 
 - [Credentials and redaction](credentials-and-redaction.md): core resolver helpers and `refreshOAuthCredential()`
+- [Azure OpenAI / Foundry](providers/azure.md) / [Amazon Bedrock](providers/bedrock.md) / [Google Vertex AI](providers/vertex.md): enterprise workload-identity credential callbacks
 - [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