@arnilo/prism 0.0.12 → 0.0.13

package/dist/persistence-lifecycle.d.ts

@@ -0,0 +1,103 @@
+import type { OwnershipScope, PersistencePage, PersistenceQuery, RetentionPolicy } from "./contracts.js";
+/** Resource classes covered by holds, quotas, and retention sweeps. */
+export type PersistenceResourceKind = "session" | "entry" | "run" | "event" | "tool_call" | "usage" | "checkpoint" | "feedback" | "audit" | "work_artifact" | "connector_operation";
+export declare const DEFAULT_LIFECYCLE_PAGE_SIZE = 100;
+export declare const HARD_LIFECYCLE_PAGE_SIZE = 500;
+export declare const DEFAULT_MAX_HOLD_REASON_BYTES = 1024;
+export declare const HARD_MAX_HOLD_REASON_BYTES: number;
+export declare class PersistenceLifecycleError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export interface LegalHoldRecord extends OwnershipScope {
+    readonly id: string;
+    readonly resourceKind: PersistenceResourceKind;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly createdAt: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface PutLegalHoldInput extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly id?: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+export interface ReleaseLegalHoldInput extends OwnershipScope {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+export interface LegalHoldQuery extends PersistenceQuery, OwnershipScope {
+    readonly resourceKind?: PersistenceResourceKind;
+    readonly resourceId?: string;
+    readonly holdId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ApplyRetentionInput extends OwnershipScope {
+    readonly policy: RetentionPolicy;
+    /** When omitted, adapters discover expired/over-limit session ids for this ownership page. */
+    readonly candidates?: readonly string[];
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ApplyRetentionResult {
+    readonly deleted: readonly string[];
+    readonly skippedHeld: readonly string[];
+    readonly nextCursor?: string;
+}
+export interface LegalHoldExportItem {
+    readonly holdId: string;
+    readonly resourceKind: PersistenceResourceKind;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly createdAt: string;
+    readonly redacted: true;
+}
+export interface ExportUnderHoldInput extends OwnershipScope {
+    readonly holdId?: string;
+    readonly resourceKind?: PersistenceResourceKind;
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+export interface TenantQuota extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    readonly limit: number;
+    readonly used: number;
+    readonly updatedAt: string;
+}
+export interface SetTenantQuotaInput extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    readonly limit: number;
+    readonly signal?: AbortSignal;
+}
+export interface ConsumeTenantQuotaInput extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    /** Units to consume. Default 1. */
+    readonly delta?: number;
+    readonly signal?: AbortSignal;
+}
+/** Optional persistence lifecycle capability (retention / hold / export / quota). */
+export interface PersistenceLifecycleStore {
+    putLegalHold(input: PutLegalHoldInput): Promise<LegalHoldRecord>;
+    releaseLegalHold(input: ReleaseLegalHoldInput): Promise<boolean>;
+    listLegalHolds(query: LegalHoldQuery): Promise<PersistencePage<LegalHoldRecord>>;
+    /** Deletes candidates not under legal hold. Hold always wins over retention. */
+    applyRetention(input: ApplyRetentionInput): Promise<ApplyRetentionResult>;
+    exportUnderHold(input: ExportUnderHoldInput): Promise<PersistencePage<LegalHoldExportItem>>;
+    setTenantQuota(input: SetTenantQuotaInput): Promise<TenantQuota>;
+    getTenantQuota(input: OwnershipScope & {
+        readonly resourceKind: PersistenceResourceKind;
+        readonly signal?: AbortSignal;
+    }): Promise<TenantQuota | null>;
+    /** Fails closed when used + delta would exceed limit. */
+    consumeTenantQuota(input: ConsumeTenantQuotaInput): Promise<TenantQuota>;
+}
+export declare function createMemoryPersistenceLifecycle(): PersistenceLifecycleStore;
+/** True when a session/resource id is under an active legal hold in the page of holds. */
+export declare function isResourceHeld(holds: readonly Pick<LegalHoldRecord, "resourceKind" | "resourceId">[], resourceKind: PersistenceResourceKind, resourceId: string): boolean;

package/dist/persistence-lifecycle.js

@@ -0,0 +1,204 @@
+export const DEFAULT_LIFECYCLE_PAGE_SIZE = 100;
+export const HARD_LIFECYCLE_PAGE_SIZE = 500;
+export const DEFAULT_MAX_HOLD_REASON_BYTES = 1024;
+export const HARD_MAX_HOLD_REASON_BYTES = 8 * 1024;
+export class PersistenceLifecycleError extends Error {
+    code;
+    constructor(message, code = "ERR_PRISM_PERSISTENCE_LIFECYCLE") {
+        super(message);
+        this.code = code;
+        this.name = "PersistenceLifecycleError";
+    }
+}
+export function createMemoryPersistenceLifecycle() {
+    const holds = new Map();
+    const quotas = new Map();
+    const deleted = new Set();
+    return {
+        async putLegalHold(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const reason = assertReason(input.reason);
+            if (!input.resourceId || !input.resourceKind) {
+                throw new PersistenceLifecycleError("resourceKind and resourceId are required", "ERR_PRISM_LIFECYCLE_HOLD");
+            }
+            const id = input.id ?? crypto.randomUUID();
+            const record = {
+                id,
+                resourceKind: input.resourceKind,
+                resourceId: input.resourceId,
+                reason,
+                createdAt: new Date().toISOString(),
+                ...(input.createdBy === undefined ? {} : { createdBy: input.createdBy }),
+                ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+                ...ownership(input),
+            };
+            holds.set(id, record);
+            return record;
+        },
+        async releaseLegalHold(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const current = holds.get(input.id);
+            if (!current)
+                return false;
+            assertSameOwnership(input, current);
+            holds.delete(input.id);
+            return true;
+        },
+        async listLegalHolds(query) {
+            throwIfAborted(query.signal);
+            assertOwnership(query);
+            const limit = pageLimit(query.limit);
+            const items = [...holds.values()]
+                .filter((hold) => sameOwnership(query, hold))
+                .filter((hold) => query.holdId === undefined || hold.id === query.holdId)
+                .filter((hold) => query.resourceKind === undefined || hold.resourceKind === query.resourceKind)
+                .filter((hold) => query.resourceId === undefined || hold.resourceId === query.resourceId)
+                .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+            const start = query.cursor ? items.findIndex((item) => item.id === query.cursor) + 1 : 0;
+            const slice = items.slice(Math.max(0, start), Math.max(0, start) + limit);
+            const next = start + limit < items.length ? slice.at(-1)?.id : undefined;
+            return { items: slice, ...(next === undefined ? {} : { nextCursor: next }) };
+        },
+        async applyRetention(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const held = new Set([...holds.values()]
+                .filter((hold) => sameOwnership(input, hold) && hold.resourceKind === "session")
+                .map((hold) => hold.resourceId));
+            const candidates = input.candidates ?? [];
+            const deletedIds = [];
+            const skippedHeld = [];
+            for (const id of candidates) {
+                if (held.has(id)) {
+                    skippedHeld.push(id);
+                    continue;
+                }
+                deleted.add(id);
+                deletedIds.push(id);
+            }
+            return { deleted: deletedIds, skippedHeld };
+        },
+        async exportUnderHold(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const page = await this.listLegalHolds({
+                ...ownership(input),
+                holdId: input.holdId,
+                resourceKind: input.resourceKind,
+                cursor: input.cursor,
+                limit: input.limit,
+                signal: input.signal,
+            });
+            return {
+                items: page.items.map((hold) => ({
+                    holdId: hold.id,
+                    resourceKind: hold.resourceKind,
+                    resourceId: hold.resourceId,
+                    reason: hold.reason,
+                    createdAt: hold.createdAt,
+                    redacted: true,
+                })),
+                ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+            };
+        },
+        async setTenantQuota(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            if (!Number.isSafeInteger(input.limit) || input.limit < 0) {
+                throw new PersistenceLifecycleError("limit must be a non-negative safe integer", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            const key = quotaKey(input, input.resourceKind);
+            const previous = quotas.get(key);
+            const record = {
+                ...ownership(input),
+                resourceKind: input.resourceKind,
+                limit: input.limit,
+                used: previous?.used ?? 0,
+                updatedAt: new Date().toISOString(),
+            };
+            if (record.used > record.limit) {
+                throw new PersistenceLifecycleError("quota already exceeded", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            quotas.set(key, record);
+            return record;
+        },
+        async getTenantQuota(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            return quotas.get(quotaKey(input, input.resourceKind)) ?? null;
+        },
+        async consumeTenantQuota(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const delta = input.delta ?? 1;
+            if (!Number.isSafeInteger(delta) || delta < 1) {
+                throw new PersistenceLifecycleError("delta must be a positive safe integer", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            const key = quotaKey(input, input.resourceKind);
+            const current = quotas.get(key);
+            if (!current) {
+                throw new PersistenceLifecycleError("tenant quota not configured", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            if (current.used + delta > current.limit) {
+                throw new PersistenceLifecycleError(`tenant quota exhausted for ${input.resourceKind}`, "ERR_PRISM_LIFECYCLE_QUOTA_EXHAUSTED");
+            }
+            const next = {
+                ...current,
+                used: current.used + delta,
+                updatedAt: new Date().toISOString(),
+            };
+            quotas.set(key, next);
+            return next;
+        },
+    };
+}
+/** True when a session/resource id is under an active legal hold in the page of holds. */
+export function isResourceHeld(holds, resourceKind, resourceId) {
+    return holds.some((hold) => hold.resourceKind === resourceKind && hold.resourceId === resourceId);
+}
+function ownership(input) {
+    return {
+        ...(input.tenantId === undefined ? {} : { tenantId: input.tenantId }),
+        ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
+        ...(input.userId === undefined ? {} : { userId: input.userId }),
+    };
+}
+function sameOwnership(a, b) {
+    return a.tenantId === b.tenantId && a.accountId === b.accountId && a.userId === b.userId;
+}
+function assertSameOwnership(expected, actual) {
+    if (!sameOwnership(expected, actual)) {
+        throw new PersistenceLifecycleError("ownership mismatch", "ERR_PRISM_LIFECYCLE_OWNERSHIP");
+    }
+}
+function assertOwnership(input) {
+    if (![input.tenantId, input.accountId, input.userId].some((value) => typeof value === "string" && value.length > 0)) {
+        throw new PersistenceLifecycleError("ownership required", "ERR_PRISM_LIFECYCLE_OWNERSHIP");
+    }
+}
+function assertReason(reason) {
+    if (typeof reason !== "string" || !reason.trim()) {
+        throw new PersistenceLifecycleError("reason is required", "ERR_PRISM_LIFECYCLE_HOLD");
+    }
+    if (Buffer.byteLength(reason, "utf8") > HARD_MAX_HOLD_REASON_BYTES) {
+        throw new PersistenceLifecycleError("reason exceeds limit", "ERR_PRISM_LIFECYCLE_HOLD");
+    }
+    return reason;
+}
+function pageLimit(limit) {
+    const resolved = limit ?? DEFAULT_LIFECYCLE_PAGE_SIZE;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > HARD_LIFECYCLE_PAGE_SIZE) {
+        throw new PersistenceLifecycleError(`limit must be 1..${HARD_LIFECYCLE_PAGE_SIZE}`, "ERR_PRISM_LIFECYCLE_LIMITS");
+    }
+    return resolved;
+}
+function quotaKey(ownership, kind) {
+    return `${ownership.tenantId ?? ""}\0${ownership.accountId ?? ""}\0${ownership.userId ?? ""}\0${kind}`;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+//# sourceMappingURL=persistence-lifecycle.js.map

package/dist/providers/openai-compatible.d.ts

@@ -1,9 +1,13 @@
-import type { AIProvider } from "../contracts.js";
+import type { AIProvider, ProviderRequest } from "../contracts.js";
 import { type CredentialValueSource } from "../credentials.js";
 export interface OpenAICompatibleProviderOptions {
     readonly id?: string;
     readonly baseUrl: string;
     readonly apiKey?: CredentialValueSource;
     readonly fetch?: typeof fetch;
+    /** Override chat-completions URL (default `${baseUrl}/chat/completions`). */
+    readonly chatCompletionsUrl?: string | ((request: ProviderRequest) => string);
+    /** Default `bearer`. Azure resource keys use `api-key`; host-signed fetches may use `none`. */
+    readonly authStyle?: "bearer" | "api-key" | "none";
 }
 export declare function createOpenAICompatibleProvider(options: OpenAICompatibleProviderOptions): AIProvider;

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,6 +89,7 @@ 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)

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)