@arnilo/prism 0.7.0 → 0.8.0

package/dist/host-composition.js

@@ -56,11 +56,37 @@ function sanitizeCredentialRefs(refs = [], redactor) {
     }
     return Object.freeze(sanitized);
 }
+const HARD_MAX_CONNECTED_APPS = 32;
+const MAX_CONNECTED_APP_IDENTIFIER_BYTES = 128;
+function copyConnectedApps(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object")
+        throw new HostCompositionError("Connected apps must provide identifier arrays");
+    return Object.freeze({
+        appIds: copyConnectedAppIdentifiers(value.appIds, "appIds"),
+        serverIds: copyConnectedAppIdentifiers(value.serverIds, "serverIds"),
+    });
+}
+function copyConnectedAppIdentifiers(value, name) {
+    if (!Array.isArray(value) || value.length > HARD_MAX_CONNECTED_APPS) {
+        throw new HostCompositionError(`Connected app ${name} must contain at most ${HARD_MAX_CONNECTED_APPS} identifiers`);
+    }
+    return Object.freeze(value.map((identifier) => {
+        if (typeof identifier !== "string" ||
+            !identifier.trim() ||
+            Buffer.byteLength(identifier, "utf8") > MAX_CONNECTED_APP_IDENTIFIER_BYTES) {
+            throw new HostCompositionError(`Connected app ${name} must contain 1..${MAX_CONNECTED_APP_IDENTIFIER_BYTES} byte identifiers`);
+        }
+        return identifier;
+    }));
+}
 function isContainedPath(parent, child) {
     const rel = relative(parent, child);
     return !rel.startsWith("..") && !isAbsolute(rel);
 }
-function resolveStorage(store, checkpoints) {
+/** Classifies a store by declared kind/durability and constructor name — never reads contents or connection strings (plan 084 Task 4 reuses it for run-bundle snapshots). */
+export function describeStorage(store, checkpoints) {
     const target = store ?? checkpoints;
     if (!target || typeof target !== "object") {
         return { kind: "none", durable: false };
@@ -111,6 +137,7 @@ export function inspectHostComposition(options) {
     }));
     // 2. Credential references (identifier references only, raw values redacted)
     const credRefs = sanitizeCredentialRefs(options.credentialRefs, redactor);
+    const connectedApps = copyConnectedApps(options.connectedApps);
     // 3. Ownership
     const rawOwnership = config?.ownership;
     const ownership = {
@@ -119,7 +146,7 @@ export function inspectHostComposition(options) {
         userId: typeof rawOwnership?.userId === "string" ? rawOwnership.userId.trim() : undefined,
     };
     // 4. Storage durability
-    const storage = resolveStorage(options.store, options.checkpoints ?? config?.runState?.checkpoints);
+    const storage = describeStorage(options.store, options.checkpoints ?? config?.runState?.checkpoints);
     // 5. Sandbox capabilities
     const workspaceRoot = options.workspaceRoot;
     const sandboxRoots = options.sandboxRoots ?? [];
@@ -180,6 +207,9 @@ export function inspectHostComposition(options) {
         }
         // Verified identity verification
         const identity = config?.identity;
+        if (connectedApps !== undefined && identity?.verified !== true) {
+            errors.push("Business connected apps require a verified identity");
+        }
         if (identity) {
             if (!identity.principal?.id || !identity.tenantId) {
                 errors.push("Business worker identity cannot be empty or fabricated");
@@ -219,6 +249,7 @@ export function inspectHostComposition(options) {
         profile: normalizedProfile,
         effectiveTools: Object.freeze(effectiveTools),
         credentialReferences: credRefs,
+        ...(connectedApps === undefined ? {} : { connectedApps }),
         ownership: Object.freeze(ownership),
         storage: Object.freeze(storage),
         sandbox: Object.freeze({

package/dist/index.d.ts

@@ -9,8 +9,8 @@ export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerp
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export type { ArtifactApproval, ArtifactApprovalState, ArtifactBodyErrorCode, ArtifactBodyPresignOptions, ArtifactBodyRef, ArtifactBodyStore, ArtifactBodyTransferOptions, ArtifactCitation, ArtifactDecisionState, ArtifactDeliveryToken, ArtifactRecord, ArtifactRevision, CitationIntegrityReason, CitationIntegrityResult, CitationLiveSource, CitationSupport, } from "./artifacts.js";
 export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, approvalEvidenceIntact, artifactApprovalState, artifactCheckpointKey, checkCitationIntegrity, citationBindingDigest, HARD_CITATION_EXCERPT_BYTES, } from "./artifacts.js";
-export { ATTENTION_BUDGET_ERROR_CODE, AttentionBudgetError, createAttentionCompiler, createAttentionTruncationTrigger, DEFAULT_ATTENTION_COMPACT_RATIO, DEFAULT_ATTENTION_KEEP_LAST, DEFAULT_ATTENTION_RESERVE_TOKENS, DEFAULT_ATTENTION_THINKING_KEEP_TURNS, DEFAULT_ATTENTION_TRIGGER_RATIO, DEFAULT_ATTENTION_TRUNCATION_THRESHOLD, isAttentionBudgetError, resolveAttentionReserveTokens, resolveInputCap, resolveRunAttentionCompiler, } from "./attention-compiler.js";
 export type { AttentionTruncationTrigger, AttentionTruncationTriggerOptions, PersistedAttentionStickyFrontier, } from "./attention-compiler.js";
+export { ATTENTION_BUDGET_ERROR_CODE, AttentionBudgetError, createAttentionCompiler, createAttentionTruncationTrigger, DEFAULT_ATTENTION_COMPACT_RATIO, DEFAULT_ATTENTION_KEEP_LAST, DEFAULT_ATTENTION_RESERVE_TOKENS, DEFAULT_ATTENTION_THINKING_KEEP_TURNS, DEFAULT_ATTENTION_TRIGGER_RATIO, DEFAULT_ATTENTION_TRUNCATION_THRESHOLD, isAttentionBudgetError, resolveAttentionReserveTokens, resolveInputCap, resolveRunAttentionCompiler, } from "./attention-compiler.js";
 export type { ApplyCacheControlOptions, CacheControlledContentBlock, CacheControlledMessage, CacheControlValue, CacheUsageReport, } from "./cache-helpers.js";
 export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, resolveBreakpoint, sanitizeCacheKey, systemCacheControlField, } from "./cache-helpers.js";
 export type { CacheTelemetry, CacheTelemetryOptions, CacheTelemetryReport, CacheTelemetrySample, } from "./cache-telemetry.js";
@@ -43,6 +43,8 @@ export type { DeviceAdapter, DeviceAdmitRequest, DeviceChunkResult, DeviceConfor
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, EventOverflowPolicy } from "./event-multiplexer.js";
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
+export type { ClaimGroundingEvidence, ClaimGroundingEvidenceExtractor, ClaimGroundingEvidenceExtractorContext, ClaimGroundingGuardrailOptions, } from "./evidence-grounding.js";
+export { createClaimGroundingGuardrail } from "./evidence-grounding.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export type { ActivatedKernelConfig, ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
@@ -87,6 +89,8 @@ export type { LoadBinaryResourceOptions } from "./resources.js";
 export { loadBinaryResource, loadJsonResource, loadManifestResource, loadTextResource } from "./resources.js";
 export type { DefaultRetryPolicyOptions } from "./retry.js";
 export { createDefaultRetryPolicy, isTransientErrorInfo, waitForRetry } from "./retry.js";
+export type { RunBundleSnapshot, RunBundleSnapshotInput } from "./run-bundle.js";
+export { RUN_BUNDLE_SCHEMA_VERSION, snapshotRunBundle } from "./run-bundle.js";
 export type { BatchedRunLedgerOptions } from "./run-ledger.js";
 export { createBatchedRunLedger, DEFAULT_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_ENTRIES, isFlushableRunLedger, } from "./run-ledger.js";
 export type { RunLimitTrackerOptions } from "./run-limits.js";
@@ -122,5 +126,5 @@ export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.7.0";
+export declare const version = "0.8.0";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -22,6 +22,7 @@ export { createChainedCredentialResolver, createEnvCredentialResolver, createExp
 export { createDelegatedAgentStep, DelegatedAgentStepError, MAX_DELEGATED_AGENT_DURATION_MS, MAX_DELEGATED_AGENT_EVENT_BYTES, MAX_DELEGATED_AGENT_ID_BYTES, MAX_DELEGATED_AGENT_NAME_BYTES, MAX_DELEGATED_AGENT_STEP_INDEX, MAX_DELEGATED_AGENT_TOKEN_COUNT, } from "./delegated-agent-step.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
+export { createClaimGroundingGuardrail } from "./evidence-grounding.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export { activateKernel, createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
@@ -47,6 +48,7 @@ export { createProviderRegistry, createProviderResolver } from "./providers.js";
 export { createSecretRedactor, errorToErrorInfo, redactAgentEvent, redactMessage, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry, resolveRedactor, } from "./redaction.js";
 export { loadBinaryResource, loadJsonResource, loadManifestResource, loadTextResource } from "./resources.js";
 export { createDefaultRetryPolicy, isTransientErrorInfo, waitForRetry } from "./retry.js";
+export { RUN_BUNDLE_SCHEMA_VERSION, snapshotRunBundle } from "./run-bundle.js";
 export { createBatchedRunLedger, DEFAULT_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_ENTRIES, isFlushableRunLedger, } from "./run-ledger.js";
 export { createRunLimitTracker, DEFAULT_RUN_LIMITS, HARD_RUN_LIMITS, RunLimitError, RunLimitTracker, resolveRunLimits, } from "./run-limits.js";
 export { assertHostCompositionReadiness, createSecureAgent, HostCompositionError, inspectHostComposition, } from "./secure-agent.js";
@@ -67,6 +69,6 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.7.0";
+export const version = "0.8.0";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/provider-events.d.ts

@@ -14,7 +14,9 @@ export declare function providerContinuationRequired(cursor: string, reason?: st
 export declare function reconstructToolCallDeltas(events: readonly ProviderEvent[]): readonly ToolCallContent[];
 export declare function providerUsage(usage: Usage): ProviderEvent;
 export declare function providerDone(usage?: Usage): ProviderEvent;
-export declare function providerError(error: unknown, secrets?: readonly (string | undefined)[]): ProviderEvent;
+export declare function providerError(error: unknown, secrets?: readonly (string | undefined)[]): Extract<ProviderEvent, {
+    type: "error";
+}>;
 export declare function toolCallContent(id: string, name: string, args?: JsonObject): ToolCallContent;
 /** Build a tool call from streamed arguments text; malformed JSON becomes a blocked call (no throw). */
 export declare function toolCallFromArgumentsText(id: string, name: string, argumentsText: string): ToolCallContent;

package/dist/provider-events.js

@@ -1,4 +1,4 @@
-import { ProviderTransportError, tryParseJsonObjectArguments } from "./providers/transport.js";
+import { classifyProviderFailure, ProviderTransportError, tryParseJsonObjectArguments } from "./providers/transport.js";
 import { errorToErrorInfo } from "./redaction.js";
 export function providerTextDelta(text) {
     return { type: "content_delta", content: { type: "text", text } };
@@ -51,7 +51,7 @@ export function providerDone(usage) {
 }
 export function providerError(error, secrets = []) {
     const info = errorToErrorInfo(error, secrets);
-    return { type: "error", error: info };
+    return { type: "error", error: info.failureClass ? info : { ...info, failureClass: classifyProviderFailure(error) } };
 }
 export function toolCallContent(id, name, args = {}) {
     return { type: "tool_call", id, name, arguments: args };

package/dist/providers/transport.d.ts

@@ -1,4 +1,4 @@
-import type { JsonObject } from "../contracts.js";
+import type { JsonObject, ProviderFailureClass } from "../contracts.js";
 export declare const DEFAULT_MAX_EVENT_BYTES = 262144;
 export declare const DEFAULT_MAX_BUFFER_BYTES = 524288;
 export declare const DEFAULT_MAX_RESPONSE_BODY_BYTES = 65536;
@@ -15,6 +15,8 @@ export interface SseEvent {
     readonly comments?: readonly string[];
 }
 export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta" | "response_body_shape";
+/** Maps already-captured provider transport evidence to advisory outcome metadata. */
+export declare function classifyProviderFailure(error: unknown): ProviderFailureClass;
 export declare class ProviderTransportError extends Error {
     readonly code: ProviderTransportErrorCode;
     readonly limitBytes?: number;

package/dist/providers/transport.js

@@ -3,6 +3,22 @@ export const DEFAULT_MAX_EVENT_BYTES = 262_144;
 export const DEFAULT_MAX_BUFFER_BYTES = 524_288;
 export const DEFAULT_MAX_RESPONSE_BODY_BYTES = 65_536;
 export const DEFAULT_MAX_ARGUMENT_BYTES = 262_144;
+const QUOTA_BODY = /quota|usage[\s_-]*limit|insufficient[\s_-]*(?:quota|credit|balance)|billing[\s_-]*(?:limit|quota)/i;
+const TRANSIENT_NETWORK_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ENETUNREACH", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT"]);
+/** Maps already-captured provider transport evidence to advisory outcome metadata. */
+export function classifyProviderFailure(error) {
+    const status = readHttpStatus(error);
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return QUOTA_BODY.test(errorMessage(error)) ? "quota" : "rate_limited";
+    if (status !== undefined)
+        return status >= 500 ? "transient" : status >= 400 ? "permanent" : "unknown";
+    const cause = readField(error, "cause");
+    if (isTransientNetworkCode(readField(error, "code")) || isTransientNetworkCode(readField(cause, "code")))
+        return "transient";
+    return "unknown";
+}
 export class ProviderTransportError extends Error {
     code;
     limitBytes;
@@ -22,8 +38,28 @@ export function httpStatusError(prefix, response, bodyText) {
     const hint = parseRetryAfterMs(response.headers.get("retry-after"));
     if (hint !== undefined)
         error.retryAfterMs = hint;
+    Object.defineProperty(error, "failureClass", { value: classifyProviderFailure(error), enumerable: true });
     return error;
 }
+function readHttpStatus(error) {
+    for (const key of ["code", "status", "statusCode"]) {
+        const value = readField(error, key);
+        const status = typeof value === "number" ? value : typeof value === "string" && /^\d{3}$/.test(value) ? Number(value) : undefined;
+        if (status !== undefined && status >= 100 && status <= 599)
+            return status;
+    }
+    return undefined;
+}
+function readField(error, key) {
+    return error && typeof error === "object" && key in error ? error[key] : undefined;
+}
+function isTransientNetworkCode(value) {
+    return typeof value === "string" && TRANSIENT_NETWORK_CODES.has(value.toUpperCase());
+}
+function errorMessage(error) {
+    const cause = readField(error, "cause");
+    return [readField(error, "message"), readField(cause, "message")].filter((value) => typeof value === "string").join(" ");
+}
 /** Parse a `Retry-After` header (delay-seconds or HTTP-date) into milliseconds. */
 export function parseRetryAfterMs(value, now = Date.now()) {
     if (!value)

package/dist/redaction.js

@@ -167,19 +167,22 @@ export function errorToErrorInfo(error, secrets = []) {
     const code = readErrorCode(error);
     const retry = readRetryAfterMs(error);
     const retryAfter = retry !== undefined ? { retryAfterMs: retry } : {};
+    const failureClass = readProviderFailureClass(error);
+    const failure = failureClass === undefined ? {} : { failureClass };
     if (error instanceof Error) {
         return {
             name: error.name,
             message: redactSecrets(error.message, secrets),
             code,
+            ...failure,
             ...retryAfter,
             cause: error.cause ? redactSecrets(String(error.cause), secrets) : undefined,
         };
     }
     if (error && typeof error === "object" && "message" in error) {
-        return { message: redactSecrets(String(error.message), secrets), code, ...retryAfter };
+        return { message: redactSecrets(String(error.message), secrets), code, ...failure, ...retryAfter };
     }
-    return { message: redactSecrets(String(error), secrets), code, ...retryAfter };
+    return { message: redactSecrets(String(error), secrets), code, ...failure, ...retryAfter };
 }
 function readErrorCode(error) {
     if (!error || typeof error !== "object" || !("code" in error))
@@ -193,4 +196,17 @@ function readRetryAfterMs(error) {
     const value = error.retryAfterMs;
     return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
+function readProviderFailureClass(error) {
+    if (!error || typeof error !== "object" || !("failureClass" in error))
+        return undefined;
+    const value = error.failureClass;
+    return value === "quota" ||
+        value === "auth" ||
+        value === "rate_limited" ||
+        value === "transient" ||
+        value === "permanent" ||
+        value === "unknown"
+        ? value
+        : undefined;
+}
 //# sourceMappingURL=redaction.js.map

package/dist/run-bundle.d.ts

@@ -0,0 +1,89 @@
+import type { Agent, AgentSessionConfig, GuardrailStage, RunOptions } from "./contracts.js";
+/** Report format revision. Any shape change bumps this so pinned digests cannot compare across formats. */
+export declare const RUN_BUNDLE_SCHEMA_VERSION = 1;
+/** Inspectable projection of the inputs a run actually resolves to. Frozen JSON, safe to persist and diff. */
+export interface RunBundleSnapshot {
+    readonly schemaVersion: number;
+    /** `sha256:<64 hex>` over the canonicalized, redacted snapshot (this field excluded). */
+    readonly digest: string;
+    /** `agentFingerprint()` of the same agent/revision: the durable-resume identity behind this snapshot. */
+    readonly fingerprint: string;
+    readonly agent: {
+        readonly id: string;
+        readonly definitionRevision: string | null;
+    };
+    readonly systemPrompt: {
+        readonly disabled: boolean;
+        /** Digest of `AgentConfig.instructions`; the body never leaves the process. */
+        readonly instructionsDigest: string | null;
+        readonly contributions: readonly {
+            readonly id: string;
+            readonly mode: string | null;
+            readonly source: string | null;
+            readonly digest: string;
+        }[];
+    };
+    readonly skills: readonly {
+        readonly name: string;
+        readonly instructionsDigest: string | null;
+        readonly toolNames: readonly string[];
+    }[];
+    /** Effective tool set: `run.toolNames` narrowing already applied, schemas reduced to digests. */
+    readonly tools: readonly {
+        readonly name: string;
+        readonly schemaDigest: string;
+        readonly exclusive: boolean;
+        readonly effect: string | null;
+    }[];
+    readonly activeSkills: readonly string[] | null;
+    readonly guardrails: readonly {
+        readonly name: string;
+        readonly stage: GuardrailStage;
+        readonly revision: string | null;
+    }[];
+    readonly loop: {
+        readonly strategy: string;
+        readonly revision: string | null;
+    };
+    readonly thinkingLevel: string | null;
+    readonly limits: Readonly<import("./contracts.js").ResolvedRunLimits>;
+    /** Host-shaped JSON as configured (`true`/`false`/options); `null` when unset. */
+    readonly attentionCompiler: unknown;
+    readonly model: {
+        readonly provider: string | null;
+        readonly model: string | null;
+    };
+    readonly requestPolicies: readonly string[];
+    /** Kinds only — never a connection string, path, or credential. */
+    readonly storage: {
+        readonly sessionStore: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+        readonly checkpoints: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+        readonly effectStore: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+        readonly memory: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+    };
+}
+export interface RunBundleSnapshotInput {
+    readonly agent: Agent;
+    /** Session-level inputs (store, leaf, cache TTL) that change what the run reads and writes. */
+    readonly config?: AgentSessionConfig;
+    readonly run?: RunOptions;
+    /** Optional memory store instance; only its kind/durability label is read, never its contents. */
+    readonly memory?: unknown;
+}
+/**
+ * Snapshots the effective run bundle: synchronous, in-memory, zero network and zero store reads.
+ * The counterpart of `agentFingerprint` for humans — same inputs, named fields, one stable digest to pin.
+ */
+export declare function snapshotRunBundle(input: RunBundleSnapshotInput): RunBundleSnapshot;

package/dist/run-bundle.js

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { agentFingerprint, BUILT_IN_LOOP_REVISIONS } from "./agent-run-state.js";
+import { describeStorage } from "./host-composition.js";
+import { canonicalizeJsonSchema } from "./providers/schema.js";
+import { resolveRunLimits } from "./run-limits.js";
+import { selectRunTools } from "./tools.js";
+/** Report format revision. Any shape change bumps this so pinned digests cannot compare across formats. */
+export const RUN_BUNDLE_SCHEMA_VERSION = 1;
+/** Bounded by construction; a bundle larger than this is a host bug, not a snapshot to retain. */
+const MAX_RUN_BUNDLE_BYTES = 512 * 1024;
+/**
+ * Snapshots the effective run bundle: synchronous, in-memory, zero network and zero store reads.
+ * The counterpart of `agentFingerprint` for humans — same inputs, named fields, one stable digest to pin.
+ */
+export function snapshotRunBundle(input) {
+    const config = input.agent.config;
+    const run = input.run;
+    const redactor = run?.redactor ?? config.redactor;
+    const definitionRevision = run?.runState?.definitionRevision ?? config.runState?.definitionRevision ?? null;
+    const tools = selectRunTools(listTools(config.tools), run?.toolNames).tools;
+    const skills = listSkills(config.skills, run?.skills);
+    const model = run?.model ?? config.model;
+    const effectiveLoop = run?.loop ?? config.loop;
+    const systemPrompt = run?.systemPrompt ?? config.systemPrompt;
+    const policies = run?.providerRequestPolicies ?? config.providerRequestPolicies;
+    const snapshot = {
+        schemaVersion: RUN_BUNDLE_SCHEMA_VERSION,
+        fingerprint: agentFingerprint(input.agent, definitionRevision ?? ""),
+        agent: { id: agentId(input.agent), definitionRevision },
+        systemPrompt: {
+            disabled: systemPrompt === false,
+            instructionsDigest: hashText(config.instructions),
+            contributions: systemPrompt === false || systemPrompt === undefined
+                ? []
+                : (Array.isArray(systemPrompt) ? systemPrompt : [systemPrompt]).map((contribution) => ({
+                    id: contribution.id,
+                    mode: contribution.mode ?? null,
+                    source: contribution.source ?? null,
+                    digest: hashText(contribution.text) ?? "",
+                })),
+        },
+        skills: skills.map((skill) => ({
+            name: skill.name,
+            instructionsDigest: hashText(skill.instructions),
+            toolNames: skill.toolNames ?? [],
+        })),
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            schemaDigest: hashJson(canonicalizeJsonSchema(tool.parameters ?? { type: "object" })),
+            exclusive: tool.exclusive === true,
+            effect: tool.effect === undefined ? null : typeof tool.effect === "function" ? "classifier" : tool.effect.kind,
+        })),
+        activeSkills: run?.activeSkills ?? null,
+        guardrails: guardrailRows(config.guardrails, run?.guardrails),
+        loop: loopIdentity(effectiveLoop),
+        thinkingLevel: run?.thinkingLevel ?? config.thinkingLevel ?? null,
+        limits: resolveRunLimits(config.limits, run?.limits),
+        attentionCompiler: run?.attentionCompiler ?? config.attentionCompiler ?? null,
+        model: {
+            provider: typeof model === "string" ? (config.provider?.id ?? null) : (model?.provider ?? null),
+            model: typeof model === "string" ? model : (model?.model ?? null),
+        },
+        requestPolicies: policies === undefined ? [] : (Array.isArray(policies) ? policies : [policies]).map((policy) => policy.name),
+        storage: {
+            sessionStore: kindOf(describeStorage(input.config?.store ?? config.store, undefined)),
+            checkpoints: kindOf(describeStorage(undefined, (run?.runState ?? config.runState)?.checkpoints)),
+            effectStore: kindOf(describeStorage(run?.effectStore ?? config.effectStore, undefined)),
+            memory: kindOf(describeStorage(input.memory, undefined)),
+        },
+    };
+    const redacted = redactStrings(snapshot, redactor);
+    const bundle = deepFreeze({ ...redacted, digest: hashJson(canonicalizeJsonSchema(redacted)) });
+    const bytes = Buffer.byteLength(JSON.stringify(bundle), "utf8");
+    if (bytes > MAX_RUN_BUNDLE_BYTES) {
+        throw new TypeError(`Run bundle snapshot exceeds ${MAX_RUN_BUNDLE_BYTES} bytes`);
+    }
+    return bundle;
+}
+/** Keeps a store label a label: a declared `kind` that is really a connection string or path becomes `custom`. */
+function kindOf(described) {
+    const raw = described.kind.toLowerCase();
+    return { kind: /^[a-z0-9_.-]{1,64}$/.test(raw) ? raw : "custom", durable: described.durable };
+}
+function agentId(agent) {
+    return agent.config.id ?? agent.config.name ?? "agent";
+}
+function listTools(tools) {
+    if (!tools)
+        return [];
+    return "list" in tools ? tools.list() : tools;
+}
+function listSkills(skills, runSkills) {
+    const listed = !skills ? [] : "list" in skills ? skills.list() : skills;
+    const byName = new Map(listed.map((skill) => [skill.name, skill]));
+    for (const skill of runSkills ?? [])
+        byName.set(skill.name, skill);
+    return [...byName.values()];
+}
+function guardrailRows(configGuardrails, runGuardrails) {
+    const rows = [];
+    for (const guardrails of [configGuardrails, runGuardrails]) {
+        if (!guardrails)
+            continue;
+        for (const stage of ["input", "output", "tool_input", "tool_output"]) {
+            const key = stage === "tool_input" ? "toolInput" : stage === "tool_output" ? "toolOutput" : stage;
+            for (const guardrail of guardrails[key] ?? []) {
+                rows.push({ name: guardrail.name, stage, revision: guardrail.revision ?? null });
+            }
+        }
+    }
+    return rows;
+}
+function loopIdentity(loop) {
+    if (typeof loop === "object" && loop && "strategy" in loop) {
+        return { strategy: loop.strategy, revision: BUILT_IN_LOOP_REVISIONS[loop.strategy] ?? null };
+    }
+    return {
+        strategy: loop?.name ?? "single-shot",
+        revision: loop?.revision ?? BUILT_IN_LOOP_REVISIONS["single-shot"] ?? null,
+    };
+}
+/** `sha256:<64 hex>` over UTF-8 text — the same convention as `hashPromptBody` in `@arnilo/prism-core`. */
+function hashText(text) {
+    if (text === undefined)
+        return null;
+    return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+function hashJson(value) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(value), "utf8").digest("hex")}`;
+}
+/** Redacts every string field so a pinned snapshot can never carry a secret. */
+function redactStrings(value, redactor) {
+    if (typeof value === "string")
+        return redactor ? redactor.redact(value) : value;
+    if (!value || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => redactStrings(item, redactor));
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactStrings(item, redactor)]));
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreeze(item);
+    }
+    return value;
+}
+//# sourceMappingURL=run-bundle.js.map

package/dist/testing/state-concurrency-conformance.js

@@ -68,7 +68,11 @@ async function checkpointCasProbe(checkpoints) {
     const loaded = await checkpoints.loadCheckpoint(key);
     assert.equal(loaded?.version, 4, "winning version must persist");
     assert.equal(loaded?.fencingToken, 6, "winning fence must persist");
-    await assertRejects(() => checkpoints.loadCheckpoint({ ...key, tenantId: "tenant-b" }), /ownership|tenant/i, "foreign checkpoint access must fail closed");
+    const foreign = await checkpoints.loadCheckpoint({ ...key, tenantId: "tenant-b" });
+    assert.equal(foreign, null, "a foreign checkpoint lands as a miss, not an ownership-shaped existence oracle");
+    await assertRejectsCode(() => checkpoints.saveCheckpoint({ ...key, tenantId: "tenant-b", version: 99, expectedVersion: 0, value: { evil: true } }), "ERR_PRISM_CHECKPOINT_CONFLICT", "a foreign checkpoint save must fail closed as a CAS conflict");
+    const intact = await checkpoints.loadCheckpoint(key);
+    assert.equal(intact?.version, 4, "a foreign writer must not disturb the owner's record");
 }
 /**
  * Approval determinism: concurrent approve/deny of the same pending decision
@@ -334,15 +338,4 @@ async function assertRejectsCode(action, code, message) {
     }
     throw new Error(`${message}; expected a rejection with code ${code}`);
 }
-async function assertRejects(action, pattern, message) {
-    try {
-        await action();
-    }
-    catch (error) {
-        if (pattern.test(String(error)))
-            return;
-        throw new Error(`${message}; rejection did not match ${pattern}: ${String(error)}`);
-    }
-    throw new Error(`${message}; expected a rejection matching ${pattern}`);
-}
 //# sourceMappingURL=state-concurrency-conformance.js.map

package/docs/ag-ui.md

@@ -31,6 +31,7 @@ npm install @arnilo/prism @arnilo/prism-ag-ui
 | `authorize` | Rebinds untrusted AG-UI thread/run selectors to host ownership on every request. `false` returns 403. |
 | `sessionFactory` | Returns an authorized Prism `AgentSession`; it receives only host-approved `AgUiPreparedInput`, never raw client tools/state. |
 | `input.project` | Opts into full `RunAgentInput`; turns bounded, still-untrusted history, state, context, forwarded props, media, and lineage into host-selected Prism `Message` values. Omit for legacy final-text mode. |
+| `inputPolicy.clientState` (`AgUiInputPolicyOptions`) | `"honor"` (default) passes validated client `state`/`tools` to `input.project`. `"ignore"` validates the same envelope for shape and bounds, then discards both fields, so input comes only from the server session and projector; an unknown value fails at construction with `ERR_PRISM_AG_UI_INPUT` instead of silently honoring the client. |
 | `input.frontendTools` | Explicitly selects client-side handoffs. Returned names must be request-tool subset; adapter never turns JSON tool declarations into Prism `ToolDefinition`s. |
 | `mcp` | Optional `createAgUiMcpAdapter({ bridge, select })`; host selects reviewed `bridge.tools`, then `sessionFactory` receives them as `input.serverTools`. Normal Prism dispatch/loop remains sole executor. |
 | `a2a` | Optional `createAgUiA2AAdapter({ client, select, correlate })`; verified remote A2A task stream replaces this handler's local session only. Host selection/correlation binds each remote task to ownership. |
@@ -44,6 +45,10 @@ npm install @arnilo/prism @arnilo/prism-ag-ui
 
 The handler accepts only `POST` JSON validated with official AG-UI `RunAgentInputSchema`. Every aggregate is bounded before a callback runs. With no `input.project`, it preserves compatibility: final text user message only; non-empty state or frontend tools fail before authorization/session lookup. With a projector, all current roles/history, context, state, forwarded props, multimodal parts, parent lineage, and tool-result continuations are available as untrusted input. The projector must apply Prism media URL/SSRF/MIME policy before forwarding media. Start a run with no `resume` and no `?cursor=`; replay supplies `?cursor=`.
 
+### Server-authoritative input (`inputPolicy.clientState: "ignore"`)
+
+An official browser client posts its own projection: `initialState` becomes the request `state` and `runAgent({ tools })` supplies a tool list. Hosts that keep projection and tools on the server had two options — relay/rewrite every request, or reject state posts and break every browser run. `inputPolicy: { clientState: "ignore" }` is the third: the posted envelope is still schema-validated and bounded (so malformed, oversized, and poisonous payloads fail exactly as before, `400`/`413`), and then client `state` and `tools` are dropped before authorization, `coWorkContext`, `mcp.prepare`, `input.project`, and `defaultAgUiInput` see the input. Input is derived solely from the server session and the host projector, so a browser posting full state gets a normal run whose projection and tool list are the server's own. `AgUiPreparedInput.clientState` reports which policy produced the payload, `frontendTools` stays empty, and `capabilities.tools.clientProvided` is refused under `"ignore"` because the handler never hands client tools to a session. `state`, `context`, and `forwardedProps` reaching the projector under `"honor"` remain untrusted: the projector is still the only authority.
+
 ## Outputs / response / events
 
 The handler returns `text/event-stream`, one `data: <AG-UI event>\n\n` frame per output. Mapper lifecycle is ordered: `RUN_*`, `STEP_*`, `TEXT_MESSAGE_*`, and `TOOL_CALL_*` are deterministic Prism mappings. Host projectors may additionally prove and emit `STATE_SNAPSHOT`/`STATE_DELTA`, `MESSAGES_SNAPSHOT`, `ACTIVITY_*`, current `REASONING_*`, `RAW`, and named `CUSTOM` values.

package/docs/agent-loops.md

@@ -130,6 +130,39 @@ The snapshot is stored as `loopState: { name, revision, snapshot }` on the durab
 
 A strategy returned by `generateValidateReviseLoop()` is safe to reuse across sequential runs. Its built-in state is scoped to `(sessionId, runId)`; a new non-restored run resets attempts, artifact phase, saved schema, and pending repair messages, while a restored run keeps the checkpointed state. Arbitrary custom strategies are not cloned or reset automatically.
 
+## Turn policy
+
+`RunOptions.turnPolicy` (`TurnPolicyOptions`) lets a host end a run **cleanly** at a provider-turn boundary — after the previous turn's tool results are persisted, before the next provider request (the same point `checkpointPolicy: "every-turn"` checkpoints at). This is the "stop when the agent has done enough" seam: an investigation that should stop at the first plan paint, a desk that stops after N turns, a policy that stops once a tool budget is spent.
+
+```ts
+await session.run("Investigate the churn spike", {
+  turnPolicy: {
+    // Clean turn cap: reaching it stops the run instead of failing it.
+    maxTurns: 4,
+    // Consulted once per boundary; a stop ends the run as `succeeded`.
+    stop: (ctx) =>
+      ctx.turns >= 1 && ctx.toolCalls >= 1
+        ? { action: "stop", reason: "l1-first-plan-paint" }
+        : { action: "continue" },
+  },
+});
+```
+
+| `TurnBoundaryContext` field | Meaning |
+| --- | --- |
+| `sessionId`, `runId` | Run correlation. |
+| `turn` | 1-based index of the provider turn this boundary precedes. |
+| `turns` | Provider turns already completed (`turn - 1`; `0` at the first boundary). |
+| `toolCalls` | Host tool calls dispatched so far in this run. |
+| `usage` | Run-total usage so far, when the provider reported any. |
+| `metadata` | Run metadata (never prompt text, tool arguments, or results). |
+
+A `stop` decision is a **clean terminal outcome**, not an error or a limit breach: the run returns `status: "succeeded"` with `stopReason: "host_policy"` and `stopDetail` (the host's `reason`, ≤256 UTF-8 bytes, redacted). The same pair rides `agent_finished.finishReason`/`stopDetail`, the finish `RunRecord`, and the projected `ExecutionTimeline`. `turnPolicy.maxTurns` is a *clean* cap: it reports `stopReason: "turn_limit"` and, unlike a `limits.maxTurns` breach, never throws `AgentRunLimitError`. A run overlay may only narrow `limits.maxTurns` — widening throws before the first provider turn.
+
+A policy stop stays **resumable**: with `runState: { checkpointPolicy: "every-turn" }` the terminal state keeps the run frontier, so `resumeAgentRun(..., { decision: "continue" })` continues from the boundary. Steers queued before the stop are already in the session history and reach the resumed leg exactly once. A `turnPolicy.maxTurns` stop is the exception — resuming it would re-stop on the first boundary. Resumed runs carry no `turnPolicy` (resume options are not run options), so a continued leg runs to its natural end unless the host stops it again.
+
+The callback is synchronous and bounded, and is never called when `turnPolicy` is omitted: a run without a policy keeps its exact request stream. A callback that throws or returns a malformed decision fails the run closed with `ERR_PRISM_TURN_POLICY` (the boundary makes no provider call and the checkpoint stays fail-closed); a stopped run is never recorded as failed.
+
 ## Outputs / response / events
 
 `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.