@arnilo/prism 0.0.96 → 0.1.0

package/dist/devices.js

@@ -0,0 +1,138 @@
+import { redactSecrets } from "./redaction.js";
+/** Audio / screenshot / stream chunk: 1 MiB default / 8 MiB hard. */
+export const DEFAULT_DEVICE_MAX_CHUNK_BYTES = 1 * 1024 * 1024;
+export const HARD_DEVICE_MAX_CHUNK_BYTES = 8 * 1024 * 1024;
+/** Concurrent device sessions per identity: 1 default / 4 hard. */
+export const DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS = 1;
+export const HARD_DEVICE_MAX_CONCURRENT_SESSIONS = 4;
+export class DevicePolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DevicePolicyError";
+    }
+}
+function validateCap(name, value, def, hard) {
+    const resolved = value ?? def;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > hard) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_INPUT", `${name} must be a positive safe integer at most ${hard}`);
+    }
+    return resolved;
+}
+export function resolveDevicePolicy(adapter, options = {}) {
+    if (!adapter || (adapter.kind !== "voice" && adapter.kind !== "desktop-control")) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_INPUT", "device kind must be 'voice' or 'desktop-control'");
+    }
+    return {
+        kind: adapter.kind,
+        // Deny-by-default: anything but an explicit `true` resolves to disabled.
+        enabled: adapter.enabled === true,
+        // Approval is required unless the host explicitly opts out (it should not).
+        requireApproval: adapter.requireApproval !== false,
+        maxChunkBytes: validateCap("maxChunkBytes", options.maxChunkBytes ?? adapter.limits?.maxChunkBytes, DEFAULT_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CHUNK_BYTES),
+        maxConcurrentSessions: validateCap("maxConcurrentSessions", options.maxConcurrentSessions ?? adapter.limits?.maxConcurrentSessions, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, HARD_DEVICE_MAX_CONCURRENT_SESSIONS),
+        ...(adapter.sandbox ? { sandbox: adapter.sandbox } : {}),
+        ...(adapter.network ? { network: adapter.network } : {}),
+        ...(options.runLimits ? { runLimits: options.runLimits } : {}),
+    };
+}
+/**
+ * Fail-closed admission gate. Denies unless the device is explicitly enabled,
+ * sandboxed, approved (when required), under the concurrent-session budget, and
+ * bound to shared run accounting. Side effects never replay after reconnect:
+ * hosts must re-admit on every resume.
+ */
+export function assertDeviceAdmit(policy, request) {
+    if (!policy.enabled) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_DISABLED", `${policy.kind} device is disabled by default`);
+    }
+    if (!policy.sandbox) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_DISABLED", `${policy.kind} device requires an explicit sandbox`);
+    }
+    if (policy.requireApproval && !request.approved) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_APPROVAL", `${policy.kind} device side effect requires approval`);
+    }
+    if (!Number.isSafeInteger(request.activeSessions) || request.activeSessions < 0) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_INPUT", "activeSessions must be a non-negative safe integer");
+    }
+    if (request.activeSessions >= policy.maxConcurrentSessions) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_SESSIONS", `concurrent ${policy.kind} sessions capped at ${policy.maxConcurrentSessions}`);
+    }
+    if (!policy.runLimits) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_RUN_LIMITS", `${policy.kind} device must consume shared RunLimits`);
+    }
+}
+/** Stream bound: oversize audio/screenshot/stream chunks are dropped with a marker, never forwarded. */
+export function acceptDeviceChunk(policy, bytes) {
+    if (!Number.isSafeInteger(bytes) || bytes < 0) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_CHUNK", "chunk bytes must be a non-negative safe integer");
+    }
+    if (bytes > policy.maxChunkBytes) {
+        return { accepted: false, bytes, marker: "dropped_oversize" };
+    }
+    return { accepted: true, bytes };
+}
+/** Telemetry must be metadata-safe: apply the host redactor before any emit/persist. */
+export function redactDeviceTelemetry(redactor, telemetry) {
+    return redactor ? redactor.redact(telemetry) : telemetry;
+}
+/**
+ * Conformance pair for future voice / desktop-control adapters. Runs the
+ * deny-by-default fixtures (denial, approval, stream bounds, session budget,
+ * run accounting, redaction) against a resolved policy and throws on any
+ * regression. Tested in 0.0.14 via fixtures only.
+ */
+export function runDevicePolicyConformance(adapter, options = {}) {
+    const runLimits = options.runLimits ?? { maxTurns: 1 };
+    const expectThrow = (code, fn) => {
+        let threw = false;
+        try {
+            fn();
+        }
+        catch (error) {
+            threw = error instanceof DevicePolicyError && error.code === code;
+        }
+        if (!threw)
+            throw new DevicePolicyError(code, `conformance: expected ${code}`);
+    };
+    const passed = [];
+    // 1. Denial by default: a disabled adapter never admits.
+    const disabled = resolveDevicePolicy({ ...adapter, enabled: false }, { ...options, runLimits });
+    expectThrow("ERR_PRISM_DEVICE_DISABLED", () => assertDeviceAdmit(disabled, { approved: true, activeSessions: 0 }));
+    passed.push("denial-by-default");
+    // 2. Approval gate: enabled+sandboxed but unapproved denies; approved admits.
+    const enabled = resolveDevicePolicy({ ...adapter, enabled: true, requireApproval: true, sandbox: adapter.sandbox ?? "sandbox" }, { ...options, runLimits });
+    expectThrow("ERR_PRISM_DEVICE_APPROVAL", () => assertDeviceAdmit(enabled, { approved: false, activeSessions: 0 }));
+    assertDeviceAdmit(enabled, { approved: true, activeSessions: 0 });
+    passed.push("approval-gate");
+    // 3. Session budget: at/over the concurrent cap denies.
+    expectThrow("ERR_PRISM_DEVICE_SESSIONS", () => assertDeviceAdmit(enabled, { approved: true, activeSessions: enabled.maxConcurrentSessions }));
+    passed.push("session-budget");
+    // 4. Run accounting: no shared RunLimits denies.
+    const unaccounted = resolveDevicePolicy({ ...adapter, enabled: true, sandbox: "sandbox" }, { ...options, runLimits: undefined });
+    expectThrow("ERR_PRISM_DEVICE_RUN_LIMITS", () => assertDeviceAdmit(unaccounted, { approved: true, activeSessions: 0 }));
+    passed.push("run-accounting");
+    // 5. Stream bounds: oversize chunk dropped with marker; in-bound accepted.
+    const over = acceptDeviceChunk(enabled, enabled.maxChunkBytes + 1);
+    if (over.accepted || over.marker !== "dropped_oversize") {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_CHUNK", "conformance: oversize chunk must be dropped");
+    }
+    if (!acceptDeviceChunk(enabled, enabled.maxChunkBytes).accepted) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_CHUNK", "conformance: in-bound chunk must accept");
+    }
+    passed.push("stream-bounds");
+    // 6. Redaction: telemetry passes through the host redactor (secrets stripped), passthrough when absent.
+    const secret = "super-secret-device-token";
+    const redactor = { redact: (value) => redactSecrets(value, [secret]) };
+    const redacted = redactDeviceTelemetry(redactor, { note: `leak ${secret}` });
+    if (redacted.note.includes(secret)) {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_INPUT", "conformance: telemetry secret must be redacted");
+    }
+    if (redactDeviceTelemetry(undefined, { note: "ok" }).note !== "ok") {
+        throw new DevicePolicyError("ERR_PRISM_DEVICE_INPUT", "conformance: telemetry must pass through without a redactor");
+    }
+    passed.push("redaction");
+    return { passed };
+}
+//# sourceMappingURL=devices.js.map

package/dist/event-multiplexer.js

@@ -13,10 +13,21 @@ export function createEventMultiplexer(options = {}) {
         isClosed = true;
     else
         options.signal?.addEventListener("abort", abort, { once: true });
+    // With compare set, publish always enqueues and the parked consumer is woken with
+    // this token instead of a value, so every event drains through the sorted queue —
+    // delivery order follows the comparator even when the consumer is caught up.
+    const WAKE = Symbol("wake");
+    const wakeWaiter = () => {
+        if (!waiter)
+            return;
+        const resolve = waiter;
+        waiter = undefined;
+        resolve({ value: WAKE, done: false });
+    };
     function publish(event) {
         if (isClosed)
             return;
-        if (waiter) {
+        if (!options.compare && waiter) {
             const resolve = waiter;
             waiter = undefined;
             resolve({ value: event, done: false });
@@ -24,12 +35,11 @@ export function createEventMultiplexer(options = {}) {
         }
         if (queue.length < maxQueuedEvents) {
             queue.push(event);
+            wakeWaiter();
             return;
         }
         droppedEvents += 1;
-        const notice = !overflowNotified && options.overflowEvent
-            ? options.overflowEvent({ droppedEvents, maxQueuedEvents, policy: overflow })
-            : undefined;
+        const notice = !overflowNotified && options.overflowEvent ? options.overflowEvent({ droppedEvents, maxQueuedEvents, policy: overflow }) : undefined;
         overflowNotified = true;
         if (overflow === "close") {
             queue.length = 0;
@@ -43,6 +53,7 @@ export function createEventMultiplexer(options = {}) {
         if (overflow === "drop_newest") {
             if (notice !== undefined)
                 queue[queue.length - 1] = notice;
+            wakeWaiter();
             return;
         }
         queue.shift();
@@ -52,6 +63,7 @@ export function createEventMultiplexer(options = {}) {
                 queue.shift();
         }
         queue.push(event);
+        wakeWaiter();
     }
     function observe(source, map) {
         if (isClosed)
@@ -117,6 +129,8 @@ export function createEventMultiplexer(options = {}) {
             });
             if (next.done)
                 return;
+            if (next.value === WAKE)
+                continue;
             yield next.value;
         }
     }

package/dist/extensions.d.ts

@@ -4,22 +4,39 @@ import { type MiddlewareRegistry } from "./middleware.js";
 import { type PermissionPolicy } from "./security.js";
 export type ExtensionEventHandler = (event: ExtensionEvent) => void | Promise<void>;
 export type ExtensionErrorPolicy = "event" | "throw";
+export interface ExtensionLoadPolicy {
+    /** When set, only listed extension names may load. */
+    readonly allowList?: readonly string[];
+    /**
+     * Host signature / attestation check. Return false or throw to deny.
+     * Unsigned extensions fail closed when this callback is provided.
+     */
+    readonly verifySignature?: (extension: Extension) => boolean | Promise<boolean>;
+}
 export interface ExtensionKernelOptions {
     readonly registries?: ContributionRegistries;
     readonly middleware?: MiddlewareRegistry;
     readonly errorPolicy?: ExtensionErrorPolicy;
     readonly secrets?: readonly (string | undefined)[];
     readonly permission?: PermissionPolicy;
+    /** Optional allow-list / signature policy evaluated before `setup`. */
+    readonly loadPolicy?: ExtensionLoadPolicy;
 }
 export interface ExtensionEventBus {
     on(type: ExtensionLifecycleEventName | string, handler: ExtensionEventHandler): () => void;
     emit(event: ExtensionEvent): Promise<void>;
 }
+export interface LoadedExtension {
+    readonly name: string;
+    /** Remove this extension's registry contributions and middleware/event subscriptions.
+     *  Best-effort and idempotent; side effects outside the registries are NOT unwound. */
+    dispose(): void;
+}
 export interface ExtensionKernel {
     readonly registries: ContributionRegistries;
     readonly middleware: MiddlewareRegistry;
     readonly events: ExtensionEventBus;
-    load(extensions: readonly Extension[]): Promise<void>;
+    load(extensions: readonly Extension[]): Promise<LoadedExtension[]>;
 }
 export declare function createExtensionEventBus(options?: Pick<ExtensionKernelOptions, "errorPolicy" | "secrets">): ExtensionEventBus;
 export declare function createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel;

package/dist/extensions.js

@@ -45,90 +45,163 @@ export function createExtensionKernel(options = {}) {
     const middleware = options.middleware ?? createMiddlewareRegistry({ ...options, onError: events.emit });
     const errorPolicy = options.errorPolicy ?? "event";
     const secrets = options.secrets ?? [];
-    const api = {
+    // Per-extension tracked API: every registration records an undo so a dispose handle
+    // (or a failed setup) can unwind exactly what that extension added.
+    const createApi = (track) => ({
         registries,
         middleware,
-        on: events.on,
+        on(type, handler) {
+            const off = events.on(type, handler);
+            track?.(off);
+            return off;
+        },
         emit: events.emit,
-        use: middleware.use,
+        use(hook, mw) {
+            const off = middleware.use(hook, mw);
+            track?.(off);
+            return off;
+        },
         registerProvider(provider) {
             registries.providers.register(provider);
+            track?.(() => registries.providers.unregister(provider.id));
         },
         registerModel(model) {
             registries.models.register(model);
+            track?.(() => registries.models.unregister(model.provider, model.model));
         },
         registerTool(tool) {
             registries.tools.register(tool.name, tool);
+            track?.(() => registries.tools.unregister(tool.name));
         },
         registerContextProvider(provider) {
             registries.contextProviders.register(provider.name, provider);
+            track?.(() => registries.contextProviders.unregister(provider.name));
         },
         registerSkill(skill) {
             registries.skills.register(skill.name, skill);
+            track?.(() => registries.skills.unregister(skill.name));
         },
         registerCommand(command) {
             registries.commands.register(command.name, command);
+            track?.(() => registries.commands.unregister(command.name));
         },
         registerAgent(agent) {
             registries.agents.register(agent.name, agent);
+            track?.(() => registries.agents.unregister(agent.name));
         },
         registerInputBuilder(builder) {
             registries.inputBuilders.register(builder.name, builder);
+            track?.(() => registries.inputBuilders.unregister(builder.name));
         },
         registerPromptBuilder(builder) {
             registries.promptBuilders.register(builder.name, builder);
+            track?.(() => registries.promptBuilders.unregister(builder.name));
         },
         registerCompactionStrategy(strategy) {
             registries.compactionStrategies.register(strategy.name, strategy);
+            track?.(() => registries.compactionStrategies.unregister(strategy.name));
         },
         registerRetryPolicy(policy) {
             registries.retryPolicies.register(policy.name, policy);
+            track?.(() => registries.retryPolicies.unregister(policy.name));
         },
         registerStoreFactory(factory) {
             registries.storeFactories.register(factory.name, factory);
+            track?.(() => registries.storeFactories.unregister(factory.name));
         },
         registerResourceLoader(key, loader) {
             registries.resourceLoaders.register(key, loader);
+            track?.(() => registries.resourceLoaders.unregister(key));
         },
         registerSettingsProvider(key, provider) {
             registries.settingsProviders.register(key, provider);
+            track?.(() => registries.settingsProviders.unregister(key));
         },
         registerCredentialResolver(key, resolver) {
             registries.credentialResolvers.register(key, resolver);
+            track?.(() => registries.credentialResolvers.unregister(key));
         },
         registerProviderPackage(providerPackage) {
             registries.providerPackages.register(providerPackage.name, providerPackage);
+            track?.(() => registries.providerPackages.unregister(providerPackage.name));
         },
         registerAuthMethod(method) {
-            registries.authMethods.register(authMethodKey(method), method);
+            const key = authMethodKey(method);
+            registries.authMethods.register(key, method);
+            track?.(() => registries.authMethods.unregister(key));
         },
         registerProviderRequestPolicy(policy) {
             registries.providerRequestPolicies.register(policy.name, policy);
+            track?.(() => registries.providerRequestPolicies.unregister(policy.name));
         },
         registerSystemPromptContribution(contribution) {
-            registries.systemPromptContributions.register(systemPromptContributionKey(contribution), contribution);
+            const key = systemPromptContributionKey(contribution);
+            registries.systemPromptContributions.register(key, contribution);
+            track?.(() => registries.systemPromptContributions.unregister(key));
         },
         registerInstructionInjector(injector) {
             registries.instructionInjectors.register(injector.name, injector);
+            track?.(() => registries.instructionInjectors.unregister(injector.name));
         },
+    });
+    const unwind = (undo) => {
+        for (const fn of undo.reverse()) {
+            try {
+                fn();
+            }
+            catch {
+                // best-effort: one stuck undo must not block the rest
+            }
+        }
     };
     return {
         registries,
         middleware,
         events,
         async load(extensions) {
+            const loaded = [];
             for (const extension of extensions) {
+                const undo = [];
                 try {
                     await assertPermission(options.permission, { kind: "extension", action: "setup", target: extension.name });
-                    await extension.setup(api);
+                    await assertExtensionLoadPolicy(options.loadPolicy, extension);
+                    await extension.setup(createApi((fn) => undo.push(fn)));
                 }
                 catch (error) {
+                    // A failed setup must not leave partial contributions behind.
+                    unwind(undo);
                     if (errorPolicy === "throw")
                         throw error;
                     await events.emit(extensionError(error, extension.name, secrets));
+                    continue;
                 }
+                let disposed = false;
+                loaded.push({
+                    name: extension.name,
+                    dispose() {
+                        if (disposed)
+                            return;
+                        disposed = true;
+                        unwind(undo);
+                    },
+                });
             }
+            return loaded;
         },
     };
 }
+async function assertExtensionLoadPolicy(policy, extension) {
+    if (!policy)
+        return;
+    if (policy.allowList && !policy.allowList.includes(extension.name)) {
+        throw new Error(`Extension "${extension.name}" is not allow-listed`);
+    }
+    if (policy.verifySignature) {
+        if (!extension.signature)
+            throw new Error(`Extension "${extension.name}" is unsigned`);
+        const ok = await policy.verifySignature(extension);
+        if (!ok)
+            throw new Error(`Extension "${extension.name}" failed signature verification`);
+    }
+}
 //# sourceMappingURL=extensions.js.map

package/dist/feedback.js

@@ -48,10 +48,14 @@ export async function prepareRunFeedback(input, options) {
     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) {
+    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 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);
@@ -121,18 +125,16 @@ 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)) {
+    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;
+    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)) {
@@ -214,7 +216,7 @@ function freezeRecord(record) {
     });
 }
 function cloneFrozenJsonObject(value) {
-    const cloned = JSON.parse(JSON.stringify(value));
+    const cloned = structuredClone(value);
     if (!cloned || typeof cloned !== "object" || Array.isArray(cloned))
         throw new RunFeedbackError("metadata must be a JSON object");
     return deepFreeze(cloned);

package/dist/guardrails.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, GuardrailContext, GuardrailRecord, Guardrails, GuardrailStage, GuardrailValue } from "./contracts.js";
+import type { AgentEvent, GuardrailContext, GuardrailRecord, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.js";
 export declare const MAX_GUARDRAIL_CONCURRENCY = 16;
 export declare class GuardrailError extends Error {

package/dist/guardrails.js

@@ -5,11 +5,11 @@ export class GuardrailError extends Error {
     code;
     record;
     constructor(record) {
-        super(record.action === "interrupt" ? "Guardrail interruption is unavailable" : "Guardrail blocked run");
+        super(record.action === "interrupt"
+            ? `Guardrail interruption is unavailable at stage "${record.stage}"; interrupt suspends only at the input stage of durable runs`
+            : "Guardrail blocked run");
         this.name = "GuardrailError";
-        this.code = record.action === "interrupt"
-            ? "ERR_PRISM_GUARDRAIL_INTERRUPT_UNAVAILABLE"
-            : "ERR_PRISM_GUARDRAIL_BLOCKED";
+        this.code = record.action === "interrupt" ? "ERR_PRISM_GUARDRAIL_INTERRUPT_UNAVAILABLE" : "ERR_PRISM_GUARDRAIL_BLOCKED";
         this.record = record;
     }
 }
@@ -20,9 +20,7 @@ export async function runGuardrails(options) {
         return { records: [] };
     const maxConcurrency = resolveConcurrency(options.guardrails?.maxConcurrency);
     const controller = new AbortController();
-    const signal = options.context.signal
-        ? AbortSignal.any([options.context.signal, controller.signal])
-        : controller.signal;
+    const signal = options.context.signal ? AbortSignal.any([options.context.signal, controller.signal]) : controller.signal;
     const records = new Array(guards.length);
     let next = 0;
     let stopped = false;
@@ -66,14 +64,23 @@ function stageGuards(guardrails, stage) {
     if (!guardrails)
         return [];
     switch (stage) {
-        case "input": return (guardrails.input ?? []);
-        case "output": return (guardrails.output ?? []);
-        case "tool_input": return (guardrails.toolInput ?? []);
-        case "tool_output": return (guardrails.toolOutput ?? []);
+        case "input":
+            return (guardrails.input ?? []);
+        case "output":
+            return (guardrails.output ?? []);
+        case "tool_input":
+            return (guardrails.toolInput ?? []);
+        case "tool_output":
+            return (guardrails.toolOutput ?? []);
     }
 }
 async function evaluate(guardrail, options, signal) {
-    if (!guardrail || typeof guardrail.name !== "string" || !guardrail.name || guardrail.name.length > 128 || guardrail.stage !== options.stage || typeof guardrail.evaluate !== "function") {
+    if (!guardrail ||
+        typeof guardrail.name !== "string" ||
+        !guardrail.name ||
+        guardrail.name.length > 128 ||
+        guardrail.stage !== options.stage ||
+        typeof guardrail.evaluate !== "function") {
         return record(guardrail?.name ?? "invalid", options.stage, "tripwire", "guardrail_invalid", undefined, options.redactor);
     }
     try {
@@ -83,8 +90,12 @@ async function evaluate(guardrail, options, signal) {
         }
         return record(guardrail.name, options.stage, decision.action, decision.reason, decision.metadata, options.redactor);
     }
-    catch {
-        return record(guardrail.name, options.stage, "tripwire", "guardrail_failed", undefined, options.redactor);
+    catch (error) {
+        // Keep the cause diagnosable without leaking internals: message only, bounded and
+        // passed through the same redact+bound metadata path as guardrail-provided metadata.
+        const message = error instanceof Error ? error.message : String(error);
+        const redacted = options.redactor?.redact(message) ?? message;
+        return record(guardrail.name, options.stage, "tripwire", "guardrail_failed", { error: boundText(redacted, MAX_REASON_BYTES) }, options.redactor);
     }
 }
 function resolveConcurrency(value) {
@@ -115,9 +126,7 @@ function boundedMetadata(value, redactor) {
         if (!json || byteLength(json) > MAX_METADATA_BYTES)
             return { truncated: true };
         const parsed = JSON.parse(json);
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : undefined;
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
     }
     catch {
         return { invalid: true };

package/dist/identity.d.ts

@@ -0,0 +1,92 @@
+import type { OwnershipScope } from "./contracts.js";
+/** Host-authenticated actor (user, service, or agent principal). */
+export interface Principal {
+    readonly kind: "user" | "service" | "agent" | string;
+    readonly id: string;
+    readonly displayName?: string;
+}
+/**
+ * Host-verified identity context. Projects onto {@link OwnershipScope}.
+ * `verified: true` marks host-verifier output; trust boundaries must obtain this
+ * via {@link IdentityVerifier}, never by accepting caller-asserted claims alone.
+ */
+export interface AgentIdentity {
+    readonly tenantId: string;
+    readonly accountId?: string;
+    readonly userId?: string;
+    /** Acting principal for this run/tool/delegation. */
+    readonly principal: Principal;
+    /** Human sponsor accountable for the agent lifecycle (Entra-style). */
+    readonly sponsor?: Principal;
+    /** Resource owner when distinct from sponsor. */
+    readonly owner?: Principal;
+    /** Parent principal when this identity is a narrowed delegation. */
+    readonly delegatedFrom?: Principal;
+    readonly scopes: readonly string[];
+    /** Late-bound credential resolver keys — never secret material. */
+    readonly credentialRefs?: readonly string[];
+    readonly issuedAt: string;
+    readonly expiresAt?: string;
+    readonly revokedAt?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly verified: true;
+}
+export interface IdentityVerifier {
+    verify(input: unknown): AgentIdentity | Promise<AgentIdentity>;
+}
+export interface AssertIdentityActiveOptions {
+    readonly now?: number;
+    /** When set, identity.tenantId must equal this value. */
+    readonly expectedTenantId?: string;
+    readonly limits?: IdentityLimits;
+}
+export interface NarrowIdentityOptions {
+    readonly scopes: readonly string[];
+    readonly principal?: Principal;
+    readonly credentialRefs?: readonly string[];
+    readonly expiresAt?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly limits?: IdentityLimits;
+}
+export interface IdentityLimits {
+    readonly maxScopes?: number;
+    readonly maxScopeBytes?: number;
+    readonly maxMetadataBytes?: number;
+    readonly maxCredentialRefBytes?: number;
+    readonly maxPrincipalIdBytes?: number;
+}
+export interface ResolvedIdentityLimits {
+    readonly maxScopes: number;
+    readonly maxScopeBytes: number;
+    readonly maxMetadataBytes: number;
+    readonly maxCredentialRefBytes: number;
+    readonly maxPrincipalIdBytes: number;
+}
+export declare const DEFAULT_IDENTITY_LIMITS: ResolvedIdentityLimits;
+export declare const HARD_IDENTITY_LIMITS: ResolvedIdentityLimits;
+export declare class IdentityError extends Error {
+    readonly reason: string;
+    readonly code = "ERR_PRISM_IDENTITY";
+    constructor(message: string, reason: string);
+}
+export declare function resolveIdentityLimits(input?: IdentityLimits): ResolvedIdentityLimits;
+/** Project verified identity onto ownership scope fields used by persistence/server. */
+export declare function ownershipFromIdentity(identity: AgentIdentity): OwnershipScope;
+/**
+ * Fail closed on shape/limits/expiry/revocation/tenant mismatch.
+ * Sync and network-free — host {@link IdentityVerifier} owns remote checks.
+ */
+export declare function assertIdentityActive(identity: AgentIdentity, options?: AssertIdentityActiveOptions): void;
+/** Delegation may only narrow scopes; tenant and ownership ids stay immutable. */
+export declare function narrowIdentity(parent: AgentIdentity, options: NarrowIdentityOptions): AgentIdentity;
+/** Refuse ownership that widens or conflicts with a verified identity. */
+export declare function assertIdentityMatchesOwnership(identity: AgentIdentity, ownership?: OwnershipScope): void;
+/**
+ * Propagation check: child must share tenant, not widen scopes, and remain active.
+ * Used by supervisor/A2A/MCP/server when forwarding identity across a boundary.
+ */
+export declare function assertIdentityPropagation(parent: AgentIdentity, child: AgentIdentity, options?: AssertIdentityActiveOptions): void;
+/** Redacted identity refs safe for telemetry/ledger metadata (no secrets, no raw JWT). */
+export declare function identityTelemetryAttributes(identity: AgentIdentity): Readonly<Record<string, string>>;
+/** Resolve run identity: explicit option wins; otherwise agent default. Assert when present. */
+export declare function resolveRunIdentity(runIdentity: AgentIdentity | undefined, agentIdentity: AgentIdentity | undefined, ownership: OwnershipScope | undefined, options?: AssertIdentityActiveOptions): AgentIdentity | undefined;