@arnilo/prism 0.0.4 → 0.0.5

package/dist/feedback.js

@@ -0,0 +1,230 @@
+export const DEFAULT_MAX_FEEDBACK_COMMENT_BYTES = 4096;
+export const HARD_MAX_FEEDBACK_COMMENT_BYTES = 16384;
+export const DEFAULT_MAX_FEEDBACK_TAGS = 16;
+export const HARD_MAX_FEEDBACK_TAGS = 64;
+export const DEFAULT_MAX_FEEDBACK_LINKS = 16;
+export const HARD_MAX_FEEDBACK_LINKS = 64;
+export const DEFAULT_MAX_FEEDBACK_METADATA_BYTES = 16384;
+export const HARD_MAX_FEEDBACK_METADATA_BYTES = 65536;
+export const DEFAULT_FEEDBACK_PAGE_SIZE = 100;
+export const HARD_FEEDBACK_PAGE_SIZE = 500;
+export const MAX_FEEDBACK_TAG_LENGTH = 64;
+export const MAX_FEEDBACK_ID_LENGTH = 128;
+export class RunFeedbackError extends Error {
+    code;
+    constructor(message, code = "ERR_PRISM_RUN_FEEDBACK") {
+        super(message);
+        this.name = "RunFeedbackError";
+        this.code = code;
+    }
+}
+/** Validate, ownership-check, redact, bound, and freeze one feedback record. */
+export async function prepareRunFeedback(input, options) {
+    input.signal?.throwIfAborted();
+    const ownership = requireOwnership(input);
+    const id = requireId(input.id, "feedback id");
+    const runId = requireId(input.runId, "runId");
+    const run = await options.resolveRun({ runId, ownership, signal: input.signal });
+    input.signal?.throwIfAborted();
+    if (!run || run.runId !== runId || !sameOwnership(ownership, run)) {
+        throw new RunFeedbackError("Run not found", "ERR_PRISM_RUN_FEEDBACK_RUN_NOT_FOUND");
+    }
+    if (input.sessionId !== undefined && input.sessionId !== run.sessionId) {
+        throw new RunFeedbackError("Run not found", "ERR_PRISM_RUN_FEEDBACK_RUN_NOT_FOUND");
+    }
+    if (input.traceId !== undefined && run.traceId !== undefined && input.traceId !== run.traceId) {
+        throw new RunFeedbackError("Run not found", "ERR_PRISM_RUN_FEEDBACK_RUN_NOT_FOUND");
+    }
+    if (input.comment !== undefined && !input.comment.trim()) {
+        throw new RunFeedbackError("comment must not be empty", "ERR_PRISM_RUN_FEEDBACK_VALIDATION");
+    }
+    if (input.rating !== undefined && (!Number.isFinite(input.rating) || input.rating < -1 || input.rating > 1)) {
+        throw new RunFeedbackError("rating must be a finite number in [-1, 1]", "ERR_PRISM_RUN_FEEDBACK_BOUNDS");
+    }
+    const maxCommentBytes = boundedLimit(options.maxCommentBytes, DEFAULT_MAX_FEEDBACK_COMMENT_BYTES, HARD_MAX_FEEDBACK_COMMENT_BYTES, "maxCommentBytes");
+    const maxTags = boundedLimit(options.maxTags, DEFAULT_MAX_FEEDBACK_TAGS, HARD_MAX_FEEDBACK_TAGS, "maxTags");
+    const maxLinks = boundedLimit(options.maxLinks, DEFAULT_MAX_FEEDBACK_LINKS, HARD_MAX_FEEDBACK_LINKS, "maxLinks");
+    const maxMetadataBytes = boundedLimit(options.maxMetadataBytes, DEFAULT_MAX_FEEDBACK_METADATA_BYTES, HARD_MAX_FEEDBACK_METADATA_BYTES, "maxMetadataBytes");
+    const tags = normalizeList(input.tags, maxTags, MAX_FEEDBACK_TAG_LENGTH, "tag");
+    const scorerIds = normalizeList(input.scorerIds, maxLinks, MAX_FEEDBACK_ID_LENGTH, "scorer id", true);
+    const evaluationIds = normalizeList(input.evaluationIds, maxLinks, MAX_FEEDBACK_ID_LENGTH, "evaluation id", true);
+    if (input.rating === undefined && input.comment === undefined && tags.length === 0 && scorerIds.length === 0 && evaluationIds.length === 0) {
+        throw new RunFeedbackError("feedback requires rating, comment, tag, scorer, or evaluation", "ERR_PRISM_RUN_FEEDBACK_EMPTY");
+    }
+    const redact = (value) => options.redactor ? options.redactor.redact(value) : value;
+    const comment = input.comment === undefined ? undefined : redact(input.comment);
+    const safeTags = Object.freeze(normalizeList(redact(tags), maxTags, MAX_FEEDBACK_TAG_LENGTH, "tag"));
+    const metadata = input.metadata === undefined ? undefined : redact(input.metadata);
+    assertBytes(comment, maxCommentBytes, "comment");
+    assertBytes(metadata, maxMetadataBytes, "metadata");
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    if (!Number.isFinite(Date.parse(createdAt)))
+        throw new RunFeedbackError("createdAt must be an ISO timestamp", "ERR_PRISM_RUN_FEEDBACK_VALIDATION");
+    return Object.freeze({
+        id,
+        runId,
+        sessionId: run.sessionId,
+        traceId: input.traceId ?? run.traceId,
+        rating: input.rating,
+        comment,
+        tags: safeTags,
+        scorerIds: Object.freeze(scorerIds),
+        evaluationIds: Object.freeze(evaluationIds),
+        createdAt,
+        createdBy: input.createdBy === undefined ? undefined : requireId(input.createdBy, "createdBy"),
+        metadata: metadata === undefined ? undefined : cloneFrozenJsonObject(metadata),
+        ...ownership,
+    });
+}
+/** In-memory implementation with the same validation/ownership semantics as durable adapters. */
+export function createMemoryRunFeedbackStore(options) {
+    const records = new Map();
+    for (const record of options.initial ?? [])
+        records.set(record.id, freezeRecord(record));
+    const maxPageSize = boundedLimit(options.maxPageSize, DEFAULT_FEEDBACK_PAGE_SIZE, HARD_FEEDBACK_PAGE_SIZE, "maxPageSize");
+    return {
+        async append(input) {
+            if (records.has(input.id))
+                throw new RunFeedbackError("Duplicate feedback id", "ERR_PRISM_RUN_FEEDBACK_DUPLICATE");
+            const record = await prepareRunFeedback(input, options);
+            records.set(record.id, record);
+            return record;
+        },
+        async query(query) {
+            query.signal?.throwIfAborted();
+            const ownership = requireOwnership(query);
+            const limit = pageLimit(query.limit, maxPageSize);
+            const order = query.order === "desc" ? -1 : 1;
+            const sorted = [...records.values()]
+                .filter((record) => sameOwnership(ownership, record) && matchesQuery(record, query))
+                .sort((a, b) => order * (a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)));
+            const start = query.cursor ? sorted.findIndex((record) => record.id === query.cursor) + 1 : 0;
+            if (query.cursor && start === 0)
+                throw new RunFeedbackError("Unknown feedback cursor", "ERR_PRISM_RUN_FEEDBACK_CURSOR");
+            const items = sorted.slice(start, start + limit);
+            return { items, nextCursor: start + items.length < sorted.length ? items.at(-1)?.id : undefined, total: sorted.length };
+        },
+        async delete(input) {
+            input.signal?.throwIfAborted();
+            const ownership = requireOwnership(input);
+            const current = records.get(input.id);
+            if (!current || !sameOwnership(ownership, current))
+                return false;
+            return records.delete(input.id);
+        },
+    };
+}
+export function requireRunFeedbackOwnership(input) {
+    return requireOwnership(input);
+}
+export function runFeedbackPageLimit(limit, maximum = HARD_FEEDBACK_PAGE_SIZE) {
+    return pageLimit(limit, maximum);
+}
+function requireOwnership(input) {
+    if (!input.tenantId?.trim()
+        || (input.accountId !== undefined && !input.accountId.trim())
+        || (input.userId !== undefined && !input.userId.trim())
+        || (!input.accountId && !input.userId)) {
+        throw new RunFeedbackError("tenantId and non-empty accountId or userId are required", "ERR_PRISM_RUN_FEEDBACK_OWNERSHIP");
+    }
+    return { tenantId: input.tenantId, accountId: input.accountId, userId: input.userId };
+}
+function sameOwnership(expected, actual) {
+    return expected.tenantId === actual.tenantId
+        && expected.accountId === actual.accountId
+        && expected.userId === actual.userId;
+}
+function requireId(value, label) {
+    if (!value || value.length > MAX_FEEDBACK_ID_LENGTH || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value)) {
+        throw new RunFeedbackError(`${label} is invalid`, "ERR_PRISM_RUN_FEEDBACK_VALIDATION");
+    }
+    return value;
+}
+function normalizeList(values, maximum, maxLength, label, ids = false) {
+    if (!values)
+        return [];
+    if (values.length > maximum)
+        throw new RunFeedbackError(`Too many ${label}s`, "ERR_PRISM_RUN_FEEDBACK_BOUNDS");
+    const result = values.map((value) => {
+        if (typeof value !== "string" || !value.trim() || value.length > maxLength || /[\r\n]/.test(value)) {
+            throw new RunFeedbackError(`${label} is invalid`, "ERR_PRISM_RUN_FEEDBACK_VALIDATION");
+        }
+        return ids ? requireId(value, label) : value;
+    });
+    if (new Set(result).size !== result.length)
+        throw new RunFeedbackError(`Duplicate ${label}`, "ERR_PRISM_RUN_FEEDBACK_VALIDATION");
+    return result;
+}
+function boundedLimit(value, fallback, hard, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > hard) {
+        throw new RunFeedbackError(`${label} must be an integer in [1, ${hard}]`, "ERR_PRISM_RUN_FEEDBACK_BOUNDS");
+    }
+    return resolved;
+}
+function pageLimit(value, maximum) {
+    if (value === undefined)
+        return Math.min(DEFAULT_FEEDBACK_PAGE_SIZE, maximum);
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RunFeedbackError("limit must be a positive integer", "ERR_PRISM_RUN_FEEDBACK_BOUNDS");
+    return Math.min(value, maximum);
+}
+function assertBytes(value, maximum, label) {
+    if (value === undefined)
+        return;
+    let encoded;
+    try {
+        encoded = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    catch {
+        throw new RunFeedbackError(`${label} must be JSON serializable`, "ERR_PRISM_RUN_FEEDBACK_VALIDATION");
+    }
+    if (new TextEncoder().encode(encoded).byteLength > maximum) {
+        throw new RunFeedbackError(`${label} exceeds ${maximum} bytes`, "ERR_PRISM_RUN_FEEDBACK_BOUNDS");
+    }
+}
+function matchesQuery(record, query) {
+    if (query.runId !== undefined && record.runId !== query.runId)
+        return false;
+    if (query.sessionId !== undefined && record.sessionId !== query.sessionId)
+        return false;
+    if (query.traceId !== undefined && record.traceId !== query.traceId)
+        return false;
+    if (query.rating !== undefined && record.rating !== query.rating)
+        return false;
+    if (query.scorerId !== undefined && !record.scorerIds.includes(query.scorerId))
+        return false;
+    if (query.evaluationId !== undefined && !record.evaluationIds.includes(query.evaluationId))
+        return false;
+    if (query.tag !== undefined && !record.tags.includes(query.tag))
+        return false;
+    if (query.fromCreatedAt !== undefined && record.createdAt < query.fromCreatedAt)
+        return false;
+    if (query.toCreatedAt !== undefined && record.createdAt > query.toCreatedAt)
+        return false;
+    return true;
+}
+function freezeRecord(record) {
+    return Object.freeze({
+        ...record,
+        tags: Object.freeze([...record.tags]),
+        scorerIds: Object.freeze([...record.scorerIds]),
+        evaluationIds: Object.freeze([...record.evaluationIds]),
+        metadata: record.metadata ? cloneFrozenJsonObject(record.metadata) : undefined,
+    });
+}
+function cloneFrozenJsonObject(value) {
+    const cloned = JSON.parse(JSON.stringify(value));
+    if (!cloned || typeof cloned !== "object" || Array.isArray(cloned))
+        throw new RunFeedbackError("metadata must be a JSON object");
+    return deepFreeze(cloned);
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+//# sourceMappingURL=feedback.js.map

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export type * from "./contracts.js";
-export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict } from "./contracts.js";
+export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError } from "./contracts.js";
 export { createAgent, createAgentSession } from "./agents.js";
+export { createMemoryRunFeedbackStore, prepareRunFeedback, requireRunFeedbackOwnership, runFeedbackPageLimit, RunFeedbackError, } from "./feedback.js";
+export type { MemoryRunFeedbackStoreOptions, PrepareRunFeedbackOptions, RunFeedbackLimits, RunFeedbackRun, RunFeedbackRunResolver, } from "./feedback.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
 export type { MemoryCheckpointStoreOptions } from "./checkpoints.js";
 export { LEASE_CONFLICT_CODE, LeaseConflictError, createMemoryLeaseStore } from "./leases.js";
@@ -33,8 +35,8 @@ export type { ComposeSystemPromptOptions } from "./system-prompts.js";
 export type { ModelRegistry, ModelRegistryOptions } from "./models.js";
 export { definePrismManifest, parsePrismManifest } from "./manifests.js";
 export type { ManifestContributionDeclaration, ManifestContributionKind, ManifestResourceDeclaration, PrismManifest } from "./manifests.js";
-export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
-export type { AudioContent, DocumentContent, FileContent, MediaContentBlock, MediaContentBounds, MediaMimePolicy, ModelInputCapability, ResolvedMediaContent, ResolveMediaContentOptions, SsrfPolicy, } from "./content.js";
+export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
+export type { AudioContent, DocumentContent, FileContent, MediaContentBlock, MediaContentBounds, MediaHostAddress, MediaHostnameResolver, MediaMimePolicy, MediaUrlRequest, MediaUrlRequester, ModelInputCapability, ResolvedMediaContent, ResolveMediaContentOptions, SsrfPolicy, } from "./content.js";
 export { loadBinaryResource, loadJsonResource, loadManifestResource, loadTextResource } from "./resources.js";
 export type { LoadBinaryResourceOptions } from "./resources.js";
 export { createChainedSettingsProvider, createStaticSettingsProvider } from "./settings.js";
@@ -65,5 +67,5 @@ export type { DispatchToolCallOptions, ToolArgumentValidationError, ToolArgument
 export type { DuplicateRegistrationOptions, DuplicateRegistrationPolicy } from "./registry-options.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export declare const name = "prism";
-export declare const version = "0.0.4";
+export declare const version = "0.0.5";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -1,5 +1,6 @@
-export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict } from "./contracts.js";
+export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError } from "./contracts.js";
 export { createAgent, createAgentSession } from "./agents.js";
+export { createMemoryRunFeedbackStore, prepareRunFeedback, requireRunFeedbackOwnership, runFeedbackPageLimit, RunFeedbackError, } from "./feedback.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
 export { LEASE_CONFLICT_CODE, LeaseConflictError, createMemoryLeaseStore } from "./leases.js";
 export { createEventMultiplexer } from "./event-multiplexer.js";
@@ -19,7 +20,7 @@ export { createProviderTurnMetadata, readProviderHttpStatus } from "./observabil
 export { createProviderRequestPolicyChain, createSessionCachePolicy, mergeProviderRequestOptions } from "./provider-request-policy.js";
 export { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 export { definePrismManifest, parsePrismManifest } from "./manifests.js";
-export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
+export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
 export { loadBinaryResource, loadJsonResource, loadManifestResource, loadTextResource } from "./resources.js";
 export { createChainedSettingsProvider, createStaticSettingsProvider } from "./settings.js";
 export { createMiddlewareRegistry } from "./middleware.js";
@@ -36,6 +37,6 @@ export { resolveInstructionInjectors, runInstructionInjectors } from "./instruct
 export { createToolRegistry, dispatchToolCall, filterTools, createToolParameterValidator } from "./tools.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export const name = "prism";
-export const version = "0.0.4";
+export const version = "0.0.5";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/providers/media.d.ts

@@ -1,4 +1,4 @@
-import type { AudioContent, ContentBlock, DocumentContent, FileContent, JsonObject, ModelCapabilities, ModelConfig } from "../contracts.js";
+import type { AudioContent, ContentBlock, DocumentContent, FileContent, JsonObject, Message, ModelCapabilities, ModelConfig } from "../contracts.js";
 import { type MediaContentBlock, type ModelInputCapability, type ResolveMediaContentOptions, type ResolvedMediaContent } from "../content.js";
 /** Default upload-cache entry cap per provider media session. */
 export declare const DEFAULT_PROVIDER_UPLOAD_CACHE_ENTRIES = 32;
@@ -38,5 +38,7 @@ export declare function serializePdfDocumentWireBlock(options: {
     readonly title?: string;
 }): JsonObject;
 export declare function resolveProviderMediaBlock(block: AudioContent | FileContent | DocumentContent, options?: ResolveMediaContentOptions): Promise<ResolvedMediaContent>;
+/** Resolve every media block once and enforce aggregate request bounds before provider I/O. */
+export declare function resolveProviderMediaMessages(messages: readonly Message[], model: ModelConfig, options?: ResolveMediaContentOptions): Promise<ReadonlyMap<MediaContentBlock, ResolvedMediaContent>>;
 export declare function defaultProviderFilename(block: MediaContentBlock, fallback: string): string;
 export declare const DEFAULT_PROVIDER_MEDIA_ITEM_BYTES = 10000000;

package/dist/providers/media.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { contentBlockInputModality, DEFAULT_MAX_MEDIA_ITEM_BYTES, resolveMediaContentBlock, UnsupportedModalityError, } from "../content.js";
+import { assertMessagesSupportModelCapabilities, contentBlockInputModality, DEFAULT_MAX_MEDIA_ITEM_BYTES, resolveMediaContentBlock, resolveMediaContentBlocks, UnsupportedModalityError, } from "../content.js";
 /** Default upload-cache entry cap per provider media session. */
 export const DEFAULT_PROVIDER_UPLOAD_CACHE_ENTRIES = 32;
 /** Inline OpenAI file_data ceiling before preferring Files API upload. */
@@ -96,6 +96,16 @@ export function serializePdfDocumentWireBlock(options) {
 export async function resolveProviderMediaBlock(block, options = {}) {
     return resolveMediaContentBlock(block, options);
 }
+/** Resolve every media block once and enforce aggregate request bounds before provider I/O. */
+export async function resolveProviderMediaMessages(messages, model, options = {}) {
+    assertMessagesSupportModelCapabilities(model, messages);
+    const blocks = messages.flatMap((message) => message.content.filter(isMediaContentBlock));
+    const resolved = await resolveMediaContentBlocks(blocks, options);
+    return new Map(blocks.map((block, index) => [block, resolved[index]]));
+}
+function isMediaContentBlock(block) {
+    return contentBlockInputModality(block) !== undefined;
+}
 export function defaultProviderFilename(block, fallback) {
     if ("name" in block && block.name)
         return block.name;

package/dist/testing/feedback.d.ts

@@ -0,0 +1,6 @@
+import type { RunFeedbackStore } from "../contracts.js";
+export interface RunFeedbackConformanceFactory {
+    (): RunFeedbackStore | Promise<RunFeedbackStore>;
+}
+/** Shared minimum behavior for memory and production feedback stores. */
+export declare function runFeedbackConformance(factory: RunFeedbackConformanceFactory): Promise<void>;

package/dist/testing/feedback.js

@@ -0,0 +1,37 @@
+/** Shared minimum behavior for memory and production feedback stores. */
+export async function runFeedbackConformance(factory) {
+    const store = await factory();
+    const owner = { tenantId: "feedback-tenant", userId: "feedback-user" };
+    await store.append({
+        id: "feedback-1",
+        runId: "feedback-run-a",
+        rating: 1,
+        comment: "useful",
+        tags: ["reviewed"],
+        evaluationIds: ["eval-1"],
+        createdAt: "2026-01-01T00:00:00.000Z",
+        ...owner,
+    });
+    await store.append({
+        id: "feedback-2",
+        runId: "feedback-run-a",
+        rating: 0,
+        createdAt: "2026-01-01T00:00:01.000Z",
+        ...owner,
+    });
+    const first = await store.query({ ...owner, runId: "feedback-run-a", limit: 1 });
+    if (first.items.length !== 1 || !first.nextCursor)
+        throw new Error("feedback first page is invalid");
+    const second = await store.query({ ...owner, runId: "feedback-run-a", cursor: first.nextCursor, limit: 1 });
+    if (second.items.length !== 1 || second.items[0]?.id === first.items[0]?.id)
+        throw new Error("feedback cursor did not advance");
+    const linked = await store.query({ ...owner, evaluationId: "eval-1" });
+    if (linked.items.length !== 1 || linked.items[0]?.id !== "feedback-1")
+        throw new Error("feedback evaluation filter failed");
+    if (await store.delete({ id: "feedback-1", tenantId: "feedback-tenant", userId: "other" })) {
+        throw new Error("cross-owner feedback deletion succeeded");
+    }
+    if (!await store.delete({ id: "feedback-1", ...owner }))
+        throw new Error("owned feedback deletion failed");
+}
+//# sourceMappingURL=feedback.js.map

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

@@ -1,8 +1,8 @@
 import type { PersistencePage, SessionEntry, SessionEntryQuery } from "../contracts.js";
 /** Current shared persistence schema version for production database adapters. */
-export declare const PERSISTENCE_SCHEMA_VERSION = 1;
-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_retention_policies" | "prism_migrations";
-export type PersistenceColumnType = "text" | "integer" | "boolean" | "json" | "timestamp";
+export declare const PERSISTENCE_SCHEMA_VERSION = 3;
+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 type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {
     readonly name: string;
     readonly type: PersistenceColumnType;

package/dist/testing/persistence-schema.js

@@ -3,7 +3,7 @@
 // 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 = 1;
+export const PERSISTENCE_SCHEMA_VERSION = 3;
 /** 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 = [
@@ -210,6 +210,9 @@ export function createPersistenceSchemaModel() {
                     { name: "session_id", type: "text" },
                     { name: "run_id", type: "text", nullable: true },
                     { name: "entry_id", type: "text", nullable: true },
+                    { name: "scope", type: "text" },
+                    { name: "turn", type: "integer", nullable: true },
+                    { name: "attempt", type: "integer", nullable: true },
                     { name: "usage", type: "json" },
                     { name: "recorded_at", type: "timestamp" },
                     ...TENANT_COLUMNS,
@@ -217,6 +220,26 @@ export function createPersistenceSchemaModel() {
                 ],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
+            {
+                name: "prism_run_feedback",
+                primaryKey: ["id"],
+                columns: [
+                    { name: "id", type: "text" },
+                    { name: "run_id", type: "text" },
+                    { name: "session_id", type: "text" },
+                    { name: "trace_id", type: "text", nullable: true },
+                    { name: "rating", type: "number", nullable: true },
+                    { name: "comment", type: "text", nullable: true },
+                    { name: "tags", type: "json" },
+                    { name: "scorer_ids", type: "json" },
+                    { name: "evaluation_ids", type: "json" },
+                    { name: "created_at", type: "timestamp" },
+                    { name: "created_by", type: "text", nullable: true },
+                    ...TENANT_COLUMNS,
+                    { name: "metadata", type: "json", nullable: true },
+                ],
+                foreignKeys: [{ columns: ["run_id"], referencesTable: "prism_runs", referencesColumns: ["id"] }],
+            },
             {
                 name: "prism_retention_policies",
                 primaryKey: ["id"],
@@ -268,6 +291,10 @@ export function createPersistenceSchemaModel() {
             { name: "prism_tool_calls_run_started_idx", table: "prism_tool_calls", columns: ["run_id", "started_at"], purpose: "run tool-call listing" },
             { name: "prism_usage_run_recorded_idx", table: "prism_usage", columns: ["run_id", "recorded_at", "id"], purpose: "run usage pagination" },
             { name: "prism_usage_session_recorded_idx", table: "prism_usage", columns: ["session_id", "recorded_at"], purpose: "usage aggregation" },
+            { name: "prism_usage_session_scope_recorded_idx", table: "prism_usage", columns: ["session_id", "scope", "recorded_at"], purpose: "scope-safe usage aggregation" },
+            { name: "prism_run_feedback_owner_created_idx", table: "prism_run_feedback", columns: ["tenant_id", "account_id", "user_id", "created_at", "id"], purpose: "ownership-scoped feedback pagination" },
+            { 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_migrations_name_version_idx", table: "prism_migrations", columns: ["name", "version"], unique: true, purpose: "applied-migration uniqueness" },
         ],
@@ -280,6 +307,8 @@ export function createPersistenceMigrationContract() {
         appliedMigrationsTable: "prism_migrations",
         steps: [
             { version: 1, name: "001_init", description: "Create core session, branch, entry, idempotency, run, ledger, and migration tables." },
+            { version: 2, name: "002_usage_scope", description: "Distinguish provider-turn usage from aggregate run totals." },
+            { version: 3, name: "003_run_feedback", description: "Add immutable ownership-scoped run/trace feedback and evaluation links." },
         ],
         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.",
@@ -294,6 +323,7 @@ export function getPersistencePaginationCursors() {
         { table: "prism_agent_events", columns: ["session_id", "timestamp", "id"], supportsOrder: ["asc", "desc"], purpose: "session event stream" },
         { table: "prism_usage", columns: ["run_id", "recorded_at", "id"], supportsOrder: ["asc", "desc"], purpose: "run usage totals" },
         { table: "prism_tool_calls", columns: ["run_id", "started_at"], supportsOrder: ["asc", "desc"], purpose: "run tool-call listing" },
+        { table: "prism_run_feedback", columns: ["tenant_id", "account_id", "user_id", "created_at", "id"], supportsOrder: ["asc", "desc"], purpose: "owned feedback listing" },
     ];
 }
 /** Build a tenant-scoped unique key column list for adapter DDL. */
@@ -326,7 +356,7 @@ export function assertPersistenceSchemaModel(model) {
         throw new Error("Runs table must include tenant-scoped tenant_id");
     }
     const indexTables = new Set(model.indexes.map((index) => index.table));
-    for (const requiredIndex of ["prism_session_append_idempotency", "prism_session_entries", "prism_agent_events", "prism_runs"]) {
+    for (const requiredIndex of ["prism_session_append_idempotency", "prism_session_entries", "prism_agent_events", "prism_runs", "prism_run_feedback"]) {
         if (!indexTables.has(requiredIndex)) {
             throw new Error(`Persistence schema missing indexes for ${requiredIndex}`);
         }

package/dist/testing/run-ledger-conformance.js

@@ -71,6 +71,9 @@ export async function assertRunLedgerConforms(fixture, options = {}) {
         id: "usage-1",
         sessionId,
         runId,
+        scope: "provider_turn",
+        turn: 1,
+        attempt: 2,
         usage: { inputTokens: 3, outputTokens: 5, totalTokens: 8 },
         recordedAt: "2026-01-01T00:00:01.000Z",
         ...scope,
@@ -114,8 +117,11 @@ export async function assertRunLedgerConforms(fixture, options = {}) {
     }
     if (fixture.readUsage) {
         const usageRows = await fixture.readUsage();
-        if (!usageRows.some((row) => row.id === "usage-1")) {
+        const storedUsage = usageRows.find((row) => row.id === "usage-1");
+        if (!storedUsage)
             throw new Error("RunLedger must persist UsageRecord rows");
+        if (storedUsage.scope !== "provider_turn" || storedUsage.turn !== 1 || storedUsage.attempt !== 2) {
+            throw new Error("RunLedger must preserve UsageRecord scope, turn, and attempt");
         }
     }
     if (options.exerciseTenantIsolation && fixture.readRuns) {

package/docs/a2a.md

@@ -0,0 +1,73 @@
+# A2A interoperability
+
+## What it does
+
+`@arnilo/prism-supervisor` implements a bounded text-only subset of Agent2Agent (A2A) protocol 1.0: Agent Cards, JSON-RPC `SendMessage`, `SendStreamingMessage`, `GetExtendedAgentCard`, SSE task updates, ES256 JWS card signatures, and an explicit remote client.
+
+## When to use it
+
+Use it to expose one explicitly selected Prism agent at an A2A endpoint or call a known remote A2A agent. Do not use it as endpoint discovery, a generic proxy, credential forwarding, or a replacement for local workflows.
+
+## Inputs / request
+
+| API/field | Meaning |
+| --- | --- |
+| `createA2AAgentCard(card)` | Validates/freeze a JSONRPC protocol-1.0 HTTPS text card. |
+| `signA2AAgentCard(card, { privateKey, keyId, expiresAt })` | Adds detached-payload ES256 JWS signature using WebCrypto. |
+| `verifyA2AAgentCard(card, { publicKey, keyId?, now?, maxAgeMs? })` | Pins ES256/key/expiry and verifies canonical unsigned card. |
+| `createA2AHandler({ card, exposure, authorize })` | Web-standard card/JSON-RPC/SSE `Request` to `Response` handler. |
+| `createA2AClient({ endpoint, allowedOrigins })` | Explicit HTTPS remote client with optional card verifier/auth callback. |
+| `A2ALimits` | Request 64 KiB, response 1 MiB, event 64 KiB, stream 10 MiB/10k events, concurrency 16, timeout 120s, card 64 KiB defaults; finite hard caps apply. |
+
+## Outputs / response / events
+
+The handler serves `GET /.well-known/agent-card.json` and its configured POST endpoint. JSON-RPC returns `{ result: { task } }` or a bounded error. Streaming returns backpressure-driven SSE task envelopes. Client `send()` maps a terminal remote task to `AgentRunResult`; `stream()` yields validated/redacted text artifacts.
+
+## Request/response example
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"role":"user","messageId":"m1","parts":[{"text":"Check sources"}]}}}
+```
+
+## Implementation example
+
+```ts
+import { createA2AClient, createA2AHandler, verifyA2AAgentCard } from "@arnilo/prism-supervisor";
+
+const handler = createA2AHandler({
+  card,
+  exposure: { sessionFactory: ({ ownership }) => agent.createSession({ metadata: ownership }) },
+  authorize: ({ request }) => authenticate(request),
+});
+
+const client = createA2AClient({
+  endpoint: "https://agent.example/a2a/v1",
+  allowedOrigins: ["https://agent.example"],
+  authorize: () => ({ authorization: `Bearer ${resolveOwnedToken()}` }),
+  verifyCard: (remoteCard) => verifyA2AAgentCard(remoteCard, { publicKey, keyId: "agent-key" }),
+});
+
+const result = await client.send("Check sources");
+```
+
+## Extension and configuration notes
+
+The package owns no listener or credential store. Mount the handler in a host server and resolve authentication/authorization on every request. Client auth executes only after body/card validation and serialization. Injectable `fetch` supports host transports/tests; redirects are disabled.
+
+Only `text` parts are accepted. File/data parts, push notifications, task persistence/query/cancel, gRPC, HTTP+JSON binding, automatic JWK fetching, and endpoint discovery are intentionally absent.
+
+## Security and performance notes
+
+- Endpoints and card URLs must be HTTPS and exactly origin-allow-listed before fetch; `redirect: "error"` prevents redirect SSRF.
+- Treat every remote card, error, task, status, artifact, and SSE frame as untrusted. Shape/count/byte/time limits apply before mapping.
+- Card verification pins `alg=ES256`, optional key ID, issue/expiry, optional maximum age, and canonical unsigned-card payload. Hosts provision trusted public keys; remote `jku` is never fetched automatically.
+- Card discovery is public; extended-card and invoke methods call host authorization. Use TLS, rate limits, and replay controls at the host edge.
+- Credentials remain in the client auth callback or server authorizer and never enter cards, messages, events, or metrics.
+- Offline conformance is authoritative. Live endpoints are optional operator smoke tests.
+
+## Related APIs
+
+- [Supervisor delegation](supervisors.md): local child boundary.
+- [Web-standard server](server.md): non-A2A Prism routes.
+- [Host security](host-security.md): authentication, SSRF, and untrusted-output policy.
+- [Agent/session runtime](agent-session-runtime.md): mapped local execution/result.

package/docs/agent-events.md

@@ -8,7 +8,7 @@ Events are emitted by the runtime and by loops through `LoopContext.emit`, both
 
 ## When to use it
 
-Subscribe via `session.subscribe()` whenever a host needs to observe run progress: render streamed assistant text in a UI, react to tool execution, drive observability/telemetry, or audit artifact validation outcomes. Do not parse provider stream events directly for these — `AgentEvent` is the stable, normalized surface across providers and loops.
+Subscribe via `session.stream()` for a single owned run, or `session.subscribe()` when a host needs a long-lived observer across runs: render streamed assistant text in a UI, react to tool execution, drive observability/telemetry, or audit artifact validation outcomes. Do not parse provider stream events directly for these — `AgentEvent` is the stable, normalized surface across providers and loops.
 
 Do not use `AgentEvent` for durable replay (use a `SessionStore`) or for cross-session coordination (the broadcaster is per-session and live-only).
 
@@ -58,7 +58,7 @@ Agent / turn / message events:
 | Variant | Fields |
 | --- | --- |
 | `agent_started` | `sessionId`, `runId` |
-| `agent_finished` | `sessionId`, `runId`, `usage?: Usage` |
+| `agent_finished` | `sessionId`, `runId`, `usage?: Usage` (aggregate of all usage-bearing provider turns) |
 | `turn_started` / `turn_finished` | `sessionId`, `runId`, `turn: number` |
 | `message_started` / `message_finished` | `sessionId`, `runId`, `message: Message` |
 | `message_delta` | `sessionId`, `runId`, `content: ContentBlock` (`tool_call_delta` fragments may appear here for live UI streaming; stored messages use final `tool_call` blocks) |
@@ -173,12 +173,10 @@ const session = createAgent({
   provider: createMockProvider([providerTextDelta("ok"), providerDone()]),
 }).createSession();
 
-for await (const event of session.subscribe()) {
+for await (const event of session.stream("draft", { loop: { strategy: "generate-validate-revise", validator, maxRevisions: 3 } })) {
   if (event.type === "artifact_finished") console.log("artifact ok", event.attempt);
   if (event.type === "artifact_failed") console.log("artifact exhausted", event.attempt, event.result.errors);
 }
-
-await session.run("draft", { loop: { strategy: "generate-validate-revise", validator, maxRevisions: 3 } });
 ```
 
 ## Extension and configuration notes
@@ -199,7 +197,7 @@ await session.run("draft", { loop: { strategy: "generate-validate-revise", valid
 - Runtime events contain messages/content only; do not put secrets in prompts, metadata, provider events, session entries, tool results, or artifact validation payloads.
 
 ## Related APIs
-- [Agent/session runtime](agent-session-runtime.md): `session.subscribe()` and the live event broadcaster.
+- [Agent/session runtime](agent-session-runtime.md): `session.stream()`, `session.subscribe()`, and the live event broadcaster.
 - [Agent loops](agent-loops.md): `singleShotLoop` and `generateValidateReviseLoop` emit the artifact events.
 - [Structured output](structured-output.md): `ArtifactValidation` shape threaded through parser/validator/repairer.
 - [Public contracts](public-contracts.md): full `AgentEvent` union and `ArtifactValidation` contract.

package/docs/agent-loops.md

@@ -108,7 +108,7 @@ Host callback contracts (all generic over host `T`):
 
 ## Outputs / response / events
 
-`AgentLoopStrategy.run(ctx)` returns `Promise<Usage | undefined>` — the last provider usage, handed back to the runtime which emits `agent_finished` with it.
+`AgentLoopStrategy.run(ctx)` returns `Promise<Usage | undefined>` as a fallback for custom loops. Core runtime independently accumulates every usage-bearing provider turn in O(turns), persists scoped turn/run rows, and emits `agent_finished` with the aggregate.
 
 Events during a loop run are the existing `AgentEvent`s (`turn_started`, `message_started`, `message_delta`, `message_finished`, `turn_finished`, tool-execution events when the loop dispatches tools, `error` on real failures). Both built-in loops emit `turn_started` before each provider turn, `message_finished` for every assistant draft, and `turn_finished` after the assistant draft is appended. First-turn input is appended to live history once, matching the already-persisted user message.