@arnilo/prism 0.0.13 → 0.0.15

package/dist/devices.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Device adapter contract (realtime voice / desktop OS control) — 0.0.14.
+ *
+ * Contracts + deny-by-default policy ONLY. No vendor voice or desktop-control
+ * implementation ships in 0.0.14 (demand-gated to 0.1.x). This module composes
+ * over the existing `PermissionPolicy` / `RunLimits` / redactor seams; it adds
+ * no second approval runtime and no device framework. Hosts implement
+ * `DeviceAdapter`, resolve a policy, and admit sessions through the fail-closed
+ * gate below. Conformance fixtures (denial/approval/stream-bounds/redaction)
+ * live in `runDevicePolicyConformance` for future vendor adapters to run.
+ */
+import type { RunLimits } from "./contracts.js";
+import { type SecretRedactor } from "./redaction.js";
+/** Audio / screenshot / stream chunk: 1 MiB default / 8 MiB hard. */
+export declare const DEFAULT_DEVICE_MAX_CHUNK_BYTES: number;
+export declare const HARD_DEVICE_MAX_CHUNK_BYTES: number;
+/** Concurrent device sessions per identity: 1 default / 4 hard. */
+export declare const DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS = 1;
+export declare const HARD_DEVICE_MAX_CONCURRENT_SESSIONS = 4;
+export type DeviceKind = "voice" | "desktop-control";
+export type DevicePolicyErrorCode = "ERR_PRISM_DEVICE_INPUT" | "ERR_PRISM_DEVICE_DISABLED" | "ERR_PRISM_DEVICE_APPROVAL" | "ERR_PRISM_DEVICE_SESSIONS" | "ERR_PRISM_DEVICE_CHUNK" | "ERR_PRISM_DEVICE_RUN_LIMITS";
+export declare class DevicePolicyError extends Error {
+    readonly code: DevicePolicyErrorCode;
+    constructor(code: DevicePolicyErrorCode, message: string);
+}
+export interface DeviceStreamLimits {
+    readonly maxChunkBytes?: number;
+    readonly maxConcurrentSessions?: number;
+}
+/**
+ * Host-declared device adapter. `enabled` is deny-by-default: a device is
+ * admitted only when the host explicitly sets it `true` AND supplies a sandbox
+ * AND (when `requireApproval`) explicit per-side-effect approval.
+ */
+export interface DeviceAdapter {
+    readonly kind: DeviceKind;
+    readonly enabled: boolean;
+    readonly requireApproval: boolean;
+    readonly limits?: DeviceStreamLimits;
+    /** Host-owned sandbox identifier; admission fails closed without it. */
+    readonly sandbox?: string;
+    /** Host-owned network/egress policy identifier. */
+    readonly network?: string;
+}
+export interface ResolvedDevicePolicy {
+    readonly kind: DeviceKind;
+    readonly enabled: boolean;
+    readonly requireApproval: boolean;
+    readonly maxChunkBytes: number;
+    readonly maxConcurrentSessions: number;
+    readonly sandbox?: string;
+    readonly network?: string;
+    /** Shared run accounting the device session must consume. */
+    readonly runLimits?: RunLimits;
+}
+export interface DevicePolicyOptions {
+    readonly maxChunkBytes?: number;
+    readonly maxConcurrentSessions?: number;
+    readonly runLimits?: RunLimits;
+}
+export declare function resolveDevicePolicy(adapter: DeviceAdapter, options?: DevicePolicyOptions): ResolvedDevicePolicy;
+export interface DeviceAdmitRequest {
+    /** Explicit host approval for this device side effect. */
+    readonly approved: boolean;
+    /** Currently active device sessions for this identity. */
+    readonly activeSessions: number;
+}
+/**
+ * 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 declare function assertDeviceAdmit(policy: ResolvedDevicePolicy, request: DeviceAdmitRequest): void;
+export interface DeviceChunkResult {
+    readonly accepted: boolean;
+    readonly bytes: number;
+    /** Present when the chunk exceeded the stream bound and was dropped. */
+    readonly marker?: "dropped_oversize";
+}
+/** Stream bound: oversize audio/screenshot/stream chunks are dropped with a marker, never forwarded. */
+export declare function acceptDeviceChunk(policy: ResolvedDevicePolicy, bytes: number): DeviceChunkResult;
+/** Telemetry must be metadata-safe: apply the host redactor before any emit/persist. */
+export declare function redactDeviceTelemetry<T>(redactor: SecretRedactor | undefined, telemetry: T): T;
+export interface DeviceConformanceResult {
+    readonly passed: readonly string[];
+}
+/**
+ * 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 declare function runDevicePolicyConformance(adapter: DeviceAdapter, options?: DevicePolicyOptions): DeviceConformanceResult;

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/index.d.ts

@@ -1,6 +1,6 @@
 export type * from "./contracts.js";
-export type { RunLimitCounters, RunLimitName, SecureAgentOptions } from "./contracts.js";
-export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError, AgentRunStateError, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SESSION_SEARCH_UNSUPPORTED_CODE, SessionSearchUnsupportedError, isSessionSearchUnsupported, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LIMIT, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, resolveSessionSearchQuery, DEFAULT_MAX_PENDING_STEERS, HARD_MAX_PENDING_STEERS, DEFAULT_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEER_BYTES } from "./contracts.js";
+export type { RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, } from "./contracts.js";
+export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError, AgentRunStateError, assertSessionMetadataKey, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SESSION_SEARCH_UNSUPPORTED_CODE, SessionSearchUnsupportedError, isSessionSearchUnsupported, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LIMIT, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, resolveSessionSearchQuery, DEFAULT_MAX_PENDING_STEERS, HARD_MAX_PENDING_STEERS, DEFAULT_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEER_BYTES } from "./contracts.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export { createBatchedRunLedger, isFlushableRunLedger, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_ENTRIES, DEFAULT_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_DELAY_MS, } from "./run-ledger.js";
 export type { BatchedRunLedgerOptions } from "./run-ledger.js";
@@ -30,10 +30,10 @@ export { createDefaultRetryPolicy, isTransientErrorInfo, waitForRetry } from "./
 export type { DefaultRetryPolicyOptions } from "./retry.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions } from "./contributions.js";
-export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue } from "./credentials.js";
+export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, revokeOAuthCredential, resolveCredentialValue } from "./credentials.js";
 export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export type { ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy } from "./extensions.js";
-export type { CredentialRecord, CredentialValueSource, MemoryCredentialStore } from "./credentials.js";
+export type { CredentialRecord, CredentialValueSource, MemoryCredentialStore, RevocableOAuthCredentialStore } from "./credentials.js";
 export { createModelRegistry } from "./models.js";
 export { authMethodKey, defineProviderPackage, systemPromptContributionKey } from "./provider-packages.js";
 export { assertStructuredOutputRequestSupported, artifactStructuredOutputRequest, DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH, DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES, modelSupportsStructuredOutput, resolveRunProviderOptions, StructuredOutputError, validateStructuredOutputOptions, withoutStructuredOutput, } from "./structured-output.js";
@@ -62,9 +62,15 @@ export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission,
 export type { AgentInput, AssembleProviderInputOptions, DefaultInputBuilder, DefaultInputBuildContext, DefaultPromptBuilder, InputAttachment, PromptInstruction, PromptTemplateOptions, ResolveContextOptions } from "./input.js";
 export { createMockProvider } from "./mock-provider.js";
 export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, listSessionBranches, rebuildSessionContext } from "./session-stores.js";
+export { CONVERSATION_METADATA_KEY, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, HARD_MAX_CONVERSATION_CURSOR_BYTES, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, decodeConversationReplayCursor, encodeConversationReplayCursor, } from "./conversations.js";
+export type { ConversationBranchRef, ConversationReplayCursor, ConversationThread, ConversationThreadState, } from "./conversations.js";
+export { ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactError, artifactApprovalState, artifactCheckpointKey, } from "./artifacts.js";
+export type { ArtifactApproval, ArtifactApprovalState, ArtifactCitation, ArtifactDecisionState, ArtifactDeliveryToken, ArtifactRecord, ArtifactRevision, } from "./artifacts.js";
+export { DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, acceptDeviceChunk, assertDeviceAdmit, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
+export type { DeviceAdapter, DeviceAdmitRequest, DeviceChunkResult, DeviceConformanceResult, DeviceKind, DevicePolicyErrorCode, DevicePolicyOptions, DeviceStreamLimits, ResolvedDevicePolicy, } from "./devices.js";
 export type { CreateMemorySessionStoreOptions, CreateSessionEntryOptions, MemorySessionSearchMode, SessionBranch, SessionBranchOptions, SessionContextSnapshot } from "./session-stores.js";
 export type { MockProviderOptions } from "./mock-provider.js";
-export { providerContentDelta, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, toolCallFromArgumentsText, } from "./provider-events.js";
+export { providerContentDelta, providerContinuationRequired, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, toolCallFromArgumentsText, } from "./provider-events.js";
 export type { ProviderResolver } from "./contracts.js";
 export { createProviderRegistry, createProviderResolver } from "./providers.js";
 export type { ProviderRegistry, ProviderRegistryOptions } from "./providers.js";
@@ -89,5 +95,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.13";
+export declare const version = "0.0.15";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError, AgentRunStateError, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SESSION_SEARCH_UNSUPPORTED_CODE, SessionSearchUnsupportedError, isSessionSearchUnsupported, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LIMIT, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, resolveSessionSearchQuery, DEFAULT_MAX_PENDING_STEERS, HARD_MAX_PENDING_STEERS, DEFAULT_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEER_BYTES } from "./contracts.js";
+export { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, isSessionAppendConflict, AgentRunError, AgentRunStateError, assertSessionMetadataKey, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SESSION_SEARCH_UNSUPPORTED_CODE, SessionSearchUnsupportedError, isSessionSearchUnsupported, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LIMIT, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, resolveSessionSearchQuery, DEFAULT_MAX_PENDING_STEERS, HARD_MAX_PENDING_STEERS, DEFAULT_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEER_BYTES } from "./contracts.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export { createBatchedRunLedger, isFlushableRunLedger, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_ENTRIES, DEFAULT_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_DELAY_MS, } from "./run-ledger.js";
 export { createSecureAgent } from "./secure-agent.js";
@@ -16,7 +16,7 @@ export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } f
 export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
 export { createDefaultRetryPolicy, isTransientErrorInfo, waitForRetry } from "./retry.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
-export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue } from "./credentials.js";
+export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, revokeOAuthCredential, resolveCredentialValue } from "./credentials.js";
 export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export { createModelRegistry } from "./models.js";
 export { authMethodKey, defineProviderPackage, systemPromptContributionKey } from "./provider-packages.js";
@@ -35,7 +35,10 @@ export { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBu
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
 export { createMockProvider } from "./mock-provider.js";
 export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, listSessionBranches, rebuildSessionContext } from "./session-stores.js";
-export { providerContentDelta, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, toolCallFromArgumentsText, } from "./provider-events.js";
+export { CONVERSATION_METADATA_KEY, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, HARD_MAX_CONVERSATION_CURSOR_BYTES, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, decodeConversationReplayCursor, encodeConversationReplayCursor, } from "./conversations.js";
+export { ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactError, artifactApprovalState, artifactCheckpointKey, } from "./artifacts.js";
+export { DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, acceptDeviceChunk, assertDeviceAdmit, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
+export { providerContentDelta, providerContinuationRequired, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, toolCallFromArgumentsText, } from "./provider-events.js";
 export { createProviderRegistry, createProviderResolver } from "./providers.js";
 export { createSecretRedactor, errorToErrorInfo, redactAgentEvent, redactMessage, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "./redaction.js";
 export { assertPermission, assertTrusted, checkPermission, createStaticPermissionPolicy, createStaticTrustPolicy, denialToErrorInfo, isTrusted, PermissionDeniedError, TrustDeniedError } from "./security.js";
@@ -48,6 +51,6 @@ export { assertGuardrailsAllowed, GuardrailError, MAX_GUARDRAIL_CONCURRENCY, run
 export { createRunLimitTracker, DEFAULT_RUN_LIMITS, HARD_MAX_RUN_COST, HARD_RUN_LIMITS, RunLimitError, RunLimitTracker, resolveRunLimits } from "./run-limits.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export const name = "prism";
-export const version = "0.0.13";
+export const version = "0.0.15";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/provider-events.d.ts

@@ -10,6 +10,7 @@ export declare function providerToolCallDelta(delta: {
     readonly argumentsText?: string;
 }): ProviderEvent;
 export declare function providerToolCallDeltaContent(delta: Omit<ToolCallDeltaContent, "type">): ToolCallDeltaContent;
+export declare function providerContinuationRequired(cursor: string, reason?: string): ProviderEvent;
 export declare function reconstructToolCallDeltas(events: readonly ProviderEvent[]): readonly ToolCallContent[];
 export declare function providerUsage(usage: Usage): ProviderEvent;
 export declare function providerDone(usage?: Usage): ProviderEvent;

package/dist/provider-events.js

@@ -18,6 +18,9 @@ export function providerToolCallDelta(delta) {
 export function providerToolCallDeltaContent(delta) {
     return { type: "tool_call_delta", ...delta };
 }
+export function providerContinuationRequired(cursor, reason) {
+    return { type: "continuation_required", cursor, reason };
+}
 export function reconstructToolCallDeltas(events) {
     const partials = new Map();
     for (const event of events) {

package/dist/providers/openai-primitives.js

@@ -115,7 +115,8 @@ export function mapOpenAIChatUsage(usage) {
         && wire.total_tokens === undefined
         && wire.prompt_cache_hit_tokens === undefined
         && wire.prompt_tokens_details?.cached_tokens === undefined
-        && wire.prompt_tokens_details?.cache_write_tokens === undefined) {
+        && wire.prompt_tokens_details?.cache_write_tokens === undefined
+        && wire.prompt_tokens_details?.cache_creation_input_tokens === undefined) {
         return undefined;
     }
     return {
@@ -123,7 +124,9 @@ export function mapOpenAIChatUsage(usage) {
         outputTokens: wire.completion_tokens,
         totalTokens: wire.total_tokens,
         cacheReadTokens: wire.prompt_tokens_details?.cached_tokens ?? wire.prompt_cache_hit_tokens,
-        cacheWriteTokens: wire.prompt_tokens_details?.cache_write_tokens,
+        // Some OpenAI-compatible vendors report cache writes as `cache_write_tokens`,
+        // others as the `cache_creation_input_tokens` variant; accept both.
+        cacheWriteTokens: wire.prompt_tokens_details?.cache_write_tokens ?? wire.prompt_tokens_details?.cache_creation_input_tokens,
     };
 }
 //# sourceMappingURL=openai-primitives.js.map

package/docs/ag-ui.md

@@ -47,6 +47,8 @@ A Prism durable `agent_suspended` returns `RUN_FINISHED` with interrupt id `${ru
 
 ACP maps assistant text to `agent_message_chunk`, safe tool lifecycle to `tool_call`/`tool_call_update`, provider usage to `usage_update`, and durable suspension to `session/request_permission`. Only `allow_once` approves; reject, cancellation, unknown outcomes, and request failure deny. It advertises only close-session capability—no terminal, filesystem, MCP, editor state, location, diff, or raw input/output capability.
 
+Co-work review (0.0.14) projects durable collaboration state over the same stream as named `CUSTOM` events, one per kind: `prism.cowork.artifact.progress`, `prism.cowork.artifact.approval.requested`, `prism.cowork.draft.connector.pending`, `prism.cowork.browser.snapshot`, and `prism.cowork.artifact.download.link`. `AgUiEventMapper.mapCoWork()` (and ACP `mapCoWork()` parity) validate, host-project (`AgUiProjection.coWork`), redact, and byte-cap each event; malformed or oversized events fail closed to nothing rather than leak. The handler accepts optional `coWorkContext` (thread/artifact/identity) and a durable `coWork` source (`createCoWorkReplay()`); one bounded, redacted page is appended after the run stream. Because projection is a pure read + map, disconnect/resume from a cursor replays co-work state without duplicate side effects. Download-link events carry an authorized, expiring token only — hosts fetch the body and never receive local paths, raw credentials, injected browser secrets, or tool-argument dumps.
+
 ## Request/response example
 
 ```json
@@ -105,6 +107,8 @@ All identity, authorization, session/thread mapping, durable checkpoint lookup,
 
 `AgUiProjection` is an allow-list. Without a callback, raw tool arguments/results/progress, paths, arbitrary state, raw Prism events, ACP locations/diffs/terminals/raw I/O, and frontend-supplied tools remain absent. Use a projector that returns a redacted display value, not a host filesystem path or tool payload.
 
+Co-work projection reuses the same allow-list: `AgUiProjection.coWork(event)` may return a curated, JSON-serializable payload for a co-work event; absent it, the redacted event fields are exposed. Wire `coWorkContext` to derive thread/artifact/identity from the authorized request (never client JSON) and `coWork` to a `createCoWorkReplay()` over your durable artifact/draft/snapshot stores. The handler projects one bounded page after the run; mount a dedicated cursor-paged co-work endpoint when full pagination is needed.
+
 ## Security and performance notes
 
 Authorize every start, replay, resume, ACP new/prompt/cancel/close request. Treat thread IDs, run IDs, cursors, client messages, resume payloads, and protocol output as untrusted. Persist run ↔ protocol correlation before exposing an interrupt. Keep `SecretRedactor` active for streaming and ledger writes.
@@ -121,3 +125,4 @@ Benchmark command/result placeholder: Task 8 adds `node scripts/benchmark-0.0.12
 - [Web-standard server handler](server.md): generic Prism HTTP API, separate from AG-UI.
 - [A2A interoperability](a2a.md): remote agent-to-agent tasks, not frontend protocol mapping.
 - [Host security guide](host-security.md): authorization, ownership, redaction, and credential boundaries.
+- [Work artifacts and review](work-artifacts-and-review.md): durable artifact service that produces the co-work approval/progress/download-link events projected here.

package/docs/browser-automation.md

@@ -106,6 +106,7 @@ await browser.close();
 - Observation (`snapshot`, `wait`, open-without-url, `close`) vs mutation/high-impact (`navigate`, click/form, dialog accept, upload, download release, popup select) is classified for `ExecutionPolicy` / `beforeSideEffect`.
 - `createSharedSandboxBrowserOptions()` aligns browser uploads/downloads with Task 1 sandbox `/workspace` and `/downloads`. `assertBrowserSandboxNetwork()` in `@arnilo/prism-coding-security` fails closed for custom Docker networks without browser egress attestation.
 - Raw CSS is absent from production defaults. Ref resolution uses Playwright’s built-in `aria-ref=` selector with a package-owned snapshot ref table for staleness checks.
+- Verified-state checkpoints (0.0.14): `createBrowserCheckpointLedger()` records navigation state — URL, a domain-state hash, and host-owned data refs — never serialized browser internals (cookies/storage/contexts), which are fragile and secret-bearing. Frozen caps: URL 8 KiB/16 KiB, domain-state hash 256 B/1 KiB, host-data ref 2 KiB/8 KiB (refs only, never bodies), 16/64 checkpoints per run (oldest evicted). After any resume/interruption `markResumed(runId)` marks state stale; `assertVerifiedBeforeSideEffect(runId)` fails closed until the host reloads + `verify()`s, so side effects never replay on stale state. Checkpoints are run-scoped: a conversation thread composes through the run it owns, reusing the manager's sandbox/egress/approval/limit policy above.
 
 ## Security and performance notes
 
@@ -121,4 +122,6 @@ Default tests use fake Playwright APIs only. Protected live gate: `PRISM_LIVE_PL
 - [Host security](host-security.md): browser endpoint, approval, egress proxy, and artifact trust boundaries.
 - [Performance and resource limits](performance.md): browser ceilings and charging points.
 - [Coding execution approval and sandboxing](coding-security.md): optional shared disposable sandbox for coding+browser.
+- [Conversations](conversations.md): durable threads that own the runs browser checkpoints scope to.
+- [Device adapters](device-adapters.md): deny-by-default voice/desktop-control contracts (no vendor package in 0.0.14).
 - [Migration](migration.md): additive optional package activation.

package/docs/conversations.md

@@ -0,0 +1,135 @@
+# Conversations
+
+## What it does
+
+`@arnilo/prism-server` ships a durable, user-scoped conversation service: create/list/get/continue/branch/archive/export/delete conversation threads on top of the existing session and event-ledger seams. A thread **is** an ownership-scoped session branch plus a `prismConversation` marker in `SessionRecord.metadata`; content stays in session entries and the redacted event ledger. Reconnectable replay pages durable redacted events without ever rerunning a provider or tool.
+
+Core (`@arnilo/prism`) exports only conversation **types and pure helpers** (`ConversationThread`, `ConversationError`, `CONVERSATION_METADATA_KEY`, thread-bound replay cursor codec, `conversationThreadFromRecord`, `conversationMarkerMetadata`). The service and optional HTTP handler live in `@arnilo/prism-server`.
+
+## When to use it
+
+Use it when a host needs persistent personal/work-agent conversations with reconnect, branch, archive, export, and deletion semantics without building a second session/event system. Hosts own authentication, agent selection, UI, transport chrome, and blob storage.
+
+Do not use it as a chat UI, a push/always-on daemon, or a file store. Slack/Teams channels, realtime voice, and desktop-control vendors are deferred (0.1.x); device adapters are contract + deny-by-default conformance only in 0.0.14.
+
+## Inputs / request
+
+```ts
+import { createConversationService, createConversationHandler } from "@arnilo/prism-server";
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+
+const persistence = createSqlitePersistence({ filename }); // implements ConversationServiceStore
+const service = createConversationService(persistence, {
+  redactor,                    // required: replay/export serve redacted rows only; continue runs with it
+  sessionFactory: ({ thread, leafId, ownership, signal }) =>
+    agent.createSession({ id: thread.id, ...(leafId ? { leafId } : {}) }), // host binds agent/store/leaf
+  runOptions?,                 // narrowable RunOptions minus ownership/identity/signal/redactor/idempotencyKey
+  limits?: ConversationLimits, // frozen defaults/caps below
+});
+
+await service.create({ ownership, title?, id?, requestId?, metadata? });
+await service.list({ ownership, cursor?, limit? });
+await service.get({ ownership, threadId });
+await service.continue({ ownership, threadId, message, requestId?, leafId? });
+await service.branch({ ownership, threadId, leafId });
+await service.archive({ ownership, threadId });
+await service.export({ ownership, threadId, cursor? });
+await service.delete({ ownership, threadId });
+await service.replay({ ownership, threadId, cursor?, limit? });
+
+const handler = createConversationHandler({ service, authorize, basePath?: "/prism/conversations", redactor?, limits? });
+```
+
+`ConversationServiceStore` is a narrow `Pick` of `ProductionPersistenceStore`: `querySessions`, `queryEvents`, optional `appendSession` (required at factory time; sqlite/postgres implement it), and optional `lifecycle.applyRetention` (required for delete). Stores without `appendSession` fail closed at construction.
+
+## Outputs / response / events
+
+- `create`/`get`/`branch`/`archive` → `ConversationThread` (`id`, `title?`, `state: "active" | "archived"`, `branches`, timestamps, ownership projection, host metadata).
+- `list` → ownership-scoped `PersistencePage<ConversationThread>` (newest first), marker-filtered; non-conversation sessions never appear.
+- `continue` → `AgentRunResult` from one agent turn on the thread session; history rebuilds from durable entries, so the agent sees prior turns.
+- `replay` → `{ records: AgentEventRecord[], nextCursor?, terminal }`; records are durable redacted ledger rows ordered by `(timestamp, id)`; `terminal` marks `agent_finished`/`agent_denied`/`error`.
+- `export` → `{ thread, events, nextCursor?, truncated }`; redacted, byte/page-capped, cursor-resumable.
+- `delete` → `{ deleted, held }` via persistence lifecycle; legal holds always win.
+- HTTP handler routes: `POST {base}` create · `GET {base}` list · `GET {base}/{id}` · `DELETE {base}/{id}` · `POST {base}/{id}/continue|branch|archive|export` · `GET {base}/{id}/events?cursor=&limit=` replay.
+
+## Request/response example
+
+```http
+POST /prism/conversations HTTP/1.1
+content-type: application/json
+
+{ "title": "Q3 planning" }
+```
+
+```json
+{ "id": "conv_9b0f…", "title": "Q3 planning", "state": "active", "branches": [], "createdAt": "…", "updatedAt": "…", "tenantId": "t1", "userId": "u1" }
+```
+
+Reconnect after a dropped connection: `GET {base}/{id}/events` (optionally with the last `nextCursor`) pages the same durable events; clients dedupe by stable record `id` (at-least-once across the page boundary). No provider or tool call is re-executed by replay/export.
+
+## Implementation example
+
+```ts
+const thread = await service.create({ ownership, title: "draft review" });
+await service.continue({ ownership, threadId: thread.id, message: "summarize the attached plan", requestId: "ui-req-1" });
+
+// Branch from a known leaf (e.g. last entry id), then fork a continue from it.
+const branched = await service.branch({ ownership, threadId: thread.id, leafId });
+await service.continue({ ownership, threadId: thread.id, message: "try a shorter version", leafId });
+
+// Reconnectable replay.
+let cursor: string | undefined;
+do {
+  const page = await service.replay({ ownership, threadId: thread.id, ...(cursor ? { cursor } : {}) });
+  render(page.records);
+  cursor = page.nextCursor;
+} while (cursor);
+
+await service.archive({ ownership, threadId: thread.id });
+const result = await service.delete({ ownership, threadId: thread.id }); // { deleted: true, held: false }
+```
+
+## Extension and configuration notes
+
+Frozen limits (default / hard cap; hosts may tighten, never raise past hard caps):
+
+| Resource | Default / hard cap |
+| --- | ---: |
+| Thread list page | 50 / 200 |
+| Replay/export page rows | 100 / 500 |
+| Replay/export cursor | 4 KiB / 16 KiB |
+| Thread title | 256 B / 2 KiB |
+| Client request id | 256 B / 2 KiB |
+| Active branches per thread | 16 / 64 |
+| Export payload per request | 8 MiB / 32 MiB |
+| Export pages per request | 100 / 500 |
+| Handler request body | 64 KiB / 1 MiB |
+
+Behavior notes:
+
+- `create` with an explicit `id` is idempotent get-or-create; generated ids are `conv_<uuid>`.
+- `continue` `requestId` flows into session-append idempotency (`RunRecord.idempotencyKey` + append dedup), so exact retries deduplicate.
+- `continue` on an archived thread fails closed (`thread_archived`); `leafId` must be a branch ref recorded by `branch()`.
+- Replay cursors are thread-bound: a cursor minted for one thread is rejected on another (`cursor_thread_mismatch`).
+- Ledger rows from runs that had no redactor are never served by replay/export (fail-closed skip).
+- Export truncates at page granularity when the next page would exceed `exportBytes`; a single page larger than `exportBytes` cannot be exported (raise the cap or page via `replay`).
+- Branch refs live in thread metadata (read-modify-write); concurrent `branch()` calls can lose a ref, so the cap is approximate and the entry tree remains the content source of truth.
+- Deletion purges the whole session ledger (entries, runs, events, tool calls, usage, branches, search rows) through `lifecycle.applyRetention`; legal holds block deletion and report `held: true`.
+
+## Security and performance notes
+
+- Every operation starts from host-verified ownership (and optional `AgentIdentity`, which must project onto ownership without widening); wrong-user access returns not-found, never leaked existence.
+- `appendSession` upserts set ownership columns only on create; metadata/`updatedAt` on update — ownership is immutable after create.
+- Replay/export serve `redacted: true` ledger rows only and pass through the service redactor; no local paths, raw tool payloads, or secrets are emitted.
+- All loops are bounded by the frozen caps above; review/agent turns consume shared `RunLimits` via the host's `runOptions`.
+- No new permission surface: conversations reuse session/event/identity/redaction/lifecycle seams (roadmap gate 8).
+
+## Related APIs
+
+- [Web-standard server handler](server.md): authorized agent/workflow routes; the conversation handler mounts beside it.
+- [Session stores](session-stores.md): branch/append/checkout semantics a thread builds on.
+- [Database persistence](database-persistence.md): `ProductionPersistenceStore`, `appendSession`, `SessionQuery` id/metadataKey filters, retention/legal-hold lifecycle.
+- [Agents and sessions](agent-identity.md): verified identity and ownership projection.
+- [Credentials and redaction](credentials-and-redaction.md): `SecretRedactor` used by replay/export/continue.
+- [Browser automation](browser-automation.md): verified-state checkpoints scope to the runs a thread owns; reload/verify before side effect.
+- [Device adapters](device-adapters.md): deny-by-default voice/desktop sessions bind to a thread's run and consume shared `RunLimits`.

package/docs/credential-storage.md

@@ -146,6 +146,33 @@ await refreshOAuthCredential({
 });
 ```
 
+Workload OAuth providers (0.0.14) — Microsoft 365 / Google Workspace over the shared OAuth2 seam (PKCE + device code + refresh + revoke), least-privilege scopes per read/mutation bundle:
+
+```ts
+import { revokeOAuthCredential } from "@arnilo/prism";
+import {
+  createMicrosoft365OAuthProvider,
+  createGoogleWorkspaceOAuthProvider,
+  createOAuthWorkTokenProvider,
+  createOAuthCredentialStoreAdapter,
+} from "@arnilo/prism-credentials-node";
+
+// Read-only mail/calendar (no mutation scopes requested).
+const m365 = createMicrosoft365OAuthProvider({ clientId: "<app-id>", capabilities: ["mail", "calendar"], access: "read" });
+const creds = await m365.login({ onDeviceCode: ({ userCode, verificationUri }) => host.showCode(userCode, verificationUri) });
+await createOAuthCredentialStoreAdapter(store).set("microsoft365", creds);
+
+// Late-bound, per-identity token for a work-tools connector (env var, never argv/model context).
+const tokenProvider = createOAuthWorkTokenProvider({
+  provider: m365,
+  store: createOAuthCredentialStoreAdapter(store),
+  envVar: "M365_ACCESSTOKEN",
+});
+
+// Revocation: best-effort upstream (GWS supports RFC 7009; M365 does not) + mandatory local delete.
+await revokeOAuthCredential({ provider: m365, credentials: creds, store: createOAuthCredentialStoreAdapter(store) });
+```
+
 Passphrase rotation:
 
 ```ts
@@ -205,7 +232,7 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Use distinct `namespace` or vault paths per tenant/environment.
 - Keychain `list()` / `listOAuth()` are intentionally unsupported — enumerate credentials through host configuration instead of scanning the OS store.
 - Combine with `createExplicitCredentialResolver()` so runtime overrides still win over stored values.
-- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` only for an OAuth flow explicitly selected by the host and authorized by that provider. In 0.0.12 that means OpenAI Codex; Anthropic and Google packages accept API keys only. Never import or migrate Claude Code/Gemini CLI credential files, setup tokens, browser sessions, or CLI OAuth rows into this store.
+- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` only for an OAuth flow explicitly selected by the host and authorized by that provider. In 0.0.12 that means OpenAI Codex; in 0.0.14 the Microsoft 365 / Google Workspace workload providers (`createMicrosoft365OAuthProvider` / `createGoogleWorkspaceOAuthProvider`) are added over the same seam with least-privilege read/mutation scope bundles. Anthropic and Google *model* packages still accept API keys only. Never import or migrate Claude Code/Gemini CLI credential files, setup tokens, browser sessions, or CLI OAuth rows into this store.
 - Enterprise cloud providers (`azure` / `bedrock` / `vertex`) expect host workload-identity callbacks (Entra / IAM / ADC), not this local encrypted/keychain store as a cloud token minting service. Store may hold opaque refresh material only when the host already owns the cloud auth flow.
 
 ## Security and performance notes

package/docs/credentials-and-redaction.md

@@ -8,6 +8,7 @@ Prism provides small helpers for host-owned credentials and known-secret redacti
 - `createExplicitCredentialResolver()`: tries named resolver sources in caller-provided order, such as runtime override → stored → env object → fallback.
 - `createEnvCredentialResolver()`: reads only a caller-supplied env-like object and map.
 - `refreshOAuthCredential()`: calls a provider OAuth refresh function and writes the result to a caller-owned store when supplied.
+- `revokeOAuthCredential()`: best-effort upstream revocation (`OAuthProvider.revoke?`) followed by a mandatory caller-owned store delete, so a revoked token fails closed locally even if the provider has no revocation endpoint.
 - `CredentialValueSource`: the accepted source type for `resolveCredentialValue()`.
 - `redactSecrets()`: replaces known secret string values inside strings, arrays, and plain objects.
 - `errorToErrorInfo()`: converts unknown errors into `ErrorInfo` and redacts known secret values from error text.
@@ -41,6 +42,7 @@ resolveCredentialValue(
 createExplicitCredentialResolver(sources: readonly CredentialResolverSource[]): CredentialResolver
 createEnvCredentialResolver(env: Readonly<Record<string, string | undefined>>, map: Readonly<Record<string, string>>): CredentialResolver
 refreshOAuthCredential(options: { provider: OAuthProvider; credentials: OAuthCredentials; store?: OAuthCredentialStore }): Promise<OAuthCredentials>
+revokeOAuthCredential(options: { provider: OAuthProvider; credentials: OAuthCredentials; store?: RevocableOAuthCredentialStore }): Promise<void>
 redactSecrets<T>(value: T, secrets: readonly (string | undefined)[]): T
 errorToErrorInfo(error: unknown, secrets?: readonly (string | undefined)[]): ErrorInfo
 ```