@arnilo/prism 0.6.0 → 0.7.0

package/dist/host-composition.js

@@ -0,0 +1,248 @@
+import { isAbsolute, relative } from "node:path";
+import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.js";
+export class HostCompositionError extends Error {
+    code;
+    constructor(message, code = "ERR_PRISM_HOST_COMPOSITION") {
+        super(message);
+        this.code = code;
+        this.name = "HostCompositionError";
+    }
+}
+function resolveAgentConfig(input) {
+    if (!input)
+        return undefined;
+    if ("config" in input && typeof input.config === "object" && input.config !== null) {
+        return input.config;
+    }
+    return input;
+}
+function normalizeProfile(profile) {
+    if (!profile)
+        return "personal";
+    if (profile === "business" || profile === "business-worker" || profile === "multi-tenant-worker") {
+        return "business";
+    }
+    return "personal";
+}
+function extractTools(toolsConfig) {
+    if (!toolsConfig)
+        return [];
+    if (Array.isArray(toolsConfig))
+        return toolsConfig;
+    if (typeof toolsConfig.list === "function") {
+        return toolsConfig.list();
+    }
+    return [];
+}
+function sanitizeCredentialRefs(refs = [], redactor) {
+    const sanitized = [];
+    for (const ref of refs) {
+        if (!ref || typeof ref !== "string")
+            continue;
+        const trimmed = ref.trim();
+        if (!trimmed)
+            continue;
+        // Credential references must be identifier names (env vars or vault keys), never raw secrets.
+        if (/^(?:sk-|ghp_|ey|Bearer\s+)/i.test(trimmed)) {
+            sanitized.push("[REDACTED_SECRET_VALUE]");
+            continue;
+        }
+        if (redactor && typeof redactor.redact === "function") {
+            sanitized.push(redactor.redact(trimmed));
+        }
+        else {
+            sanitized.push(trimmed);
+        }
+    }
+    return Object.freeze(sanitized);
+}
+function isContainedPath(parent, child) {
+    const rel = relative(parent, child);
+    return !rel.startsWith("..") && !isAbsolute(rel);
+}
+function resolveStorage(store, checkpoints) {
+    const target = store ?? checkpoints;
+    if (!target || typeof target !== "object") {
+        return { kind: "none", durable: false };
+    }
+    const record = target;
+    const constructorName = target.constructor?.name ?? "";
+    const declaredKind = typeof record.kind === "string" ? record.kind.toLowerCase() : "";
+    // Explicit in-memory implementations are NEVER durable.
+    if (constructorName.includes("Memory") ||
+        declaredKind.includes("memory") ||
+        record.durable === false ||
+        record.durability === "ephemeral") {
+        return { kind: declaredKind || "memory", durable: false };
+    }
+    // Postgres, SQLite, or explicitly durable stores
+    if (record.durable === true ||
+        record.durability === "durable" ||
+        constructorName.includes("Postgres") ||
+        constructorName.includes("Sqlite") ||
+        declaredKind.includes("postgres") ||
+        declaredKind.includes("sqlite")) {
+        return { kind: declaredKind || constructorName.toLowerCase() || "durable", durable: true };
+    }
+    // Any store with saveCheckpoint / appendEntry / queryEntries without explicit durable: true is in-memory
+    if (typeof record.saveCheckpoint === "function" ||
+        typeof record.appendEntry === "function" ||
+        typeof record.queryEntries === "function" ||
+        typeof record.append === "function") {
+        return { kind: declaredKind || "memory", durable: false };
+    }
+    // Unknown store without explicit durable flag is treated as non-durable memory
+    return { kind: declaredKind || "memory", durable: false };
+}
+/**
+ * Inspects a host composition in an inert, bounded, and secret-redacting manner.
+ * Performs zero network calls by default.
+ */
+export function inspectHostComposition(options) {
+    const normalizedProfile = normalizeProfile(options.profile);
+    const config = resolveAgentConfig(options.agent);
+    const redactor = options.redactor ?? config?.redactor;
+    // 1. Effective tools
+    const rawTools = extractTools(config?.tools);
+    const effectiveTools = rawTools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        hasParameters: Boolean(tool.parameters && Object.keys(tool.parameters).length > 0),
+    }));
+    // 2. Credential references (identifier references only, raw values redacted)
+    const credRefs = sanitizeCredentialRefs(options.credentialRefs, redactor);
+    // 3. Ownership
+    const rawOwnership = config?.ownership;
+    const ownership = {
+        tenantId: typeof rawOwnership?.tenantId === "string" ? rawOwnership.tenantId.trim() : undefined,
+        accountId: typeof rawOwnership?.accountId === "string" ? rawOwnership.accountId.trim() : undefined,
+        userId: typeof rawOwnership?.userId === "string" ? rawOwnership.userId.trim() : undefined,
+    };
+    // 4. Storage durability
+    const storage = resolveStorage(options.store, options.checkpoints ?? config?.runState?.checkpoints);
+    // 5. Sandbox capabilities
+    const workspaceRoot = options.workspaceRoot;
+    const sandboxRoots = options.sandboxRoots ?? [];
+    let isolated = true;
+    if (workspaceRoot && sandboxRoots.length > 0) {
+        for (const root of sandboxRoots) {
+            if (!isContainedPath(workspaceRoot, root)) {
+                isolated = false;
+                break;
+            }
+        }
+    }
+    // 6. Governance coverage
+    const hasValidator = Boolean((config && "validator" in config && typeof config.validator === "function") ||
+        (config &&
+            "toolArgumentValidator" in config &&
+            typeof config.toolArgumentValidator?.validate === "function"));
+    const isSecure = Boolean(config?.secure);
+    const governance = {
+        permission: Boolean(config?.permission && typeof config.permission.check === "function"),
+        trust: Boolean(config?.trust && typeof config.trust.check === "function"),
+        redactor: Boolean(redactor && typeof redactor.redact === "function"),
+        validator: hasValidator,
+        modelRouting: Boolean(options.governance?.modelRouter || config?.modelRouter),
+        secure: isSecure,
+    };
+    // 7. Readiness analysis
+    const errors = [];
+    const warnings = [];
+    // Required redactor check
+    if (!governance.redactor) {
+        errors.push("Missing required secret redactor");
+    }
+    // Required provider or model configuration
+    const hasProvider = Boolean(config?.provider);
+    const hasModel = Boolean(config?.model);
+    if (!hasProvider && !hasModel) {
+        errors.push("Missing required provider or model configuration");
+    }
+    // Ownership presence
+    const hasAnyOwner = Boolean(ownership.tenantId || ownership.userId || ownership.accountId);
+    if (!hasAnyOwner) {
+        errors.push("Ownership scope is required");
+    }
+    // Profile-specific readiness
+    if (normalizedProfile === "personal") {
+        if (!ownership.userId) {
+            errors.push("Personal composition requires userId in ownership");
+        }
+        if (!isolated) {
+            errors.push("Sandbox roots must be contained within workspaceRoot");
+        }
+    }
+    else {
+        // business composition
+        if (!ownership.tenantId) {
+            errors.push("Business worker requires non-empty tenantId in ownership");
+        }
+        // Verified identity verification
+        const identity = config?.identity;
+        if (identity) {
+            if (!identity.principal?.id || !identity.tenantId) {
+                errors.push("Business worker identity cannot be empty or fabricated");
+            }
+            else {
+                try {
+                    assertIdentityActive(identity);
+                    if (rawOwnership) {
+                        assertIdentityMatchesOwnership(identity, rawOwnership);
+                    }
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error.message : String(error));
+                }
+            }
+        }
+        // Storage durability verification (memory-only persistence is NOT permitted in business readiness)
+        if (!storage.durable) {
+            errors.push("Business composition requires durable storage; in-memory storage is not permitted in production readiness");
+        }
+        // Sandbox isolation verification
+        if (!isolated || (sandboxRoots.length > 0 && !workspaceRoot)) {
+            errors.push("Mixed sandbox workspace detected; business worker requires strict workspace containment");
+        }
+        // Governance coverage
+        if (options.governance?.supported === false) {
+            errors.push("Unsupported governance configuration");
+        }
+        if (!governance.permission) {
+            errors.push("Business composition requires a permission policy");
+        }
+        if (!governance.trust) {
+            errors.push("Business composition requires a trust policy");
+        }
+    }
+    return {
+        profile: normalizedProfile,
+        effectiveTools: Object.freeze(effectiveTools),
+        credentialReferences: credRefs,
+        ownership: Object.freeze(ownership),
+        storage: Object.freeze(storage),
+        sandbox: Object.freeze({
+            ...(workspaceRoot ? { workspaceRoot } : {}),
+            roots: Object.freeze([...sandboxRoots]),
+            isolated,
+        }),
+        governance: Object.freeze(governance),
+        readiness: Object.freeze({
+            ok: errors.length === 0,
+            errors: Object.freeze(errors),
+            warnings: Object.freeze(warnings),
+        }),
+    };
+}
+/**
+ * Asserts that a host composition meets all readiness requirements for its profile.
+ * Throws HostCompositionError on failure.
+ */
+export function assertHostCompositionReadiness(options) {
+    const report = inspectHostComposition(options);
+    if (!report.readiness.ok) {
+        throw new HostCompositionError(report.readiness.errors.join("; "));
+    }
+    return report;
+}
+//# sourceMappingURL=host-composition.js.map

package/dist/index.d.ts

@@ -7,8 +7,10 @@ export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
 export type { PendingToolCall, StoredAgentRunState } from "./agent-run-state.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
-export type { ArtifactApproval, ArtifactApprovalState, ArtifactBodyErrorCode, ArtifactBodyPresignOptions, ArtifactBodyRef, ArtifactBodyStore, ArtifactBodyTransferOptions, ArtifactCitation, ArtifactDecisionState, ArtifactDeliveryToken, ArtifactRecord, ArtifactRevision, } from "./artifacts.js";
-export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, artifactApprovalState, artifactCheckpointKey, } from "./artifacts.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 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";
@@ -26,8 +28,8 @@ export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMe
 export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission, ContextBudgetOmissionKind, ContextBudgetReport, TokenEstimator, } from "./context-budget.js";
 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 type * from "./contracts.js";
-export type { ApprovalOutcome, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, ResumeNestedRun, RunDecision, RunLimitCounters, RunLimitName, SecureAgentOptions, StickyDecision, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
-export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, DEFAULT_SNAPSHOT_CACHE_TTL_MS, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
+export type { ApprovalOutcome, AttentionCompiler, AttentionCompilerContext, AttentionCompilerOptions, AttentionCompilerSetting, AttentionInputCapOptions, AttentionReport, CompactionTrigger, CompactionTriggerContext, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, ResolveShouldCompactInput, ResolveShouldCompactOptions, ResumeNestedRun, RunDecision, RunLimitCounters, RunLimitName, SecureAgentOptions, StickyDecision, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertCompactionTrigger, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, DEFAULT_SNAPSHOT_CACHE_TTL_MS, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, resolveShouldCompact, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions, } from "./contributions.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
@@ -89,7 +91,8 @@ 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";
 export { createRunLimitTracker, DEFAULT_RUN_LIMITS, HARD_RUN_LIMITS, RunLimitError, RunLimitTracker, resolveRunLimits, } from "./run-limits.js";
-export { createSecureAgent } from "./secure-agent.js";
+export type { HostCompositionGovernance, HostCompositionOptions, HostCompositionProfile, HostCompositionReport, HostCompositionToolReport, } from "./secure-agent.js";
+export { assertHostCompositionReadiness, createSecureAgent, HostCompositionError, inspectHostComposition, } from "./secure-agent.js";
 export type { PermissionDecision, PermissionPolicy, PermissionRequest, TrustDecision, TrustPolicy, TrustRequest } from "./security.js";
 export { assertPermission, assertTrusted, checkPermission, createStaticPermissionPolicy, createStaticTrustPolicy, denialToErrorInfo, isTrusted, PermissionDeniedError, TrustDeniedError, } from "./security.js";
 export type { CreateMemorySessionStoreOptions, CreateSessionEntryOptions, MemorySessionSearchMode, SessionBranch, SessionBranchOptions, SessionContextSnapshot, } from "./session-stores.js";
@@ -119,5 +122,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.6.0";
+export declare const version = "0.7.0";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -4,7 +4,8 @@ export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOption
 export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
-export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, artifactApprovalState, artifactCheckpointKey, } 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 { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, resolveBreakpoint, sanitizeCacheKey, systemCacheControlField, } from "./cache-helpers.js";
 export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, createCacheTelemetry, DEFAULT_CACHE_TELEMETRY_CAP, } from "./cache-telemetry.js";
 export { createProviderCapture } from "./capture.js";
@@ -13,7 +14,7 @@ export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compac
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
 export { 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 { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, DEFAULT_SNAPSHOT_CACHE_TTL_MS, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertBatchJobsSupported, assertCompactionTrigger, assertEmbeddingsSupported, assertImageGenerationSupported, assertModerationSupported, assertSessionMetadataKey, assertSpeechSupported, assertTranscriptionSupported, assertVideoGenerationSupported, BatchJobsError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, DEFAULT_SNAPSHOT_CACHE_TTL_MS, EmbeddingsError, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_STICKY_DECISIONS, ImageGenerationError, isBatchJobTerminal, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, ModerationError, modelSupportsBatchJobs, modelSupportsEmbeddings, modelSupportsImageGeneration, modelSupportsModeration, modelSupportsSpeech, modelSupportsTranscription, modelSupportsVideoGeneration, pollBatch, resolveSessionSearchQuery, resolveShouldCompact, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, SpeechError, TranscriptionError, VideoGenerationError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
@@ -48,7 +49,7 @@ export { loadBinaryResource, loadJsonResource, loadManifestResource, loadTextRes
 export { createDefaultRetryPolicy, isTransientErrorInfo, waitForRetry } from "./retry.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 { createSecureAgent } from "./secure-agent.js";
+export { assertHostCompositionReadiness, createSecureAgent, HostCompositionError, inspectHostComposition, } from "./secure-agent.js";
 export { assertPermission, assertTrusted, checkPermission, createStaticPermissionPolicy, createStaticTrustPolicy, denialToErrorInfo, isTrusted, PermissionDeniedError, TrustDeniedError, } from "./security.js";
 export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, listSessionBranches, rebuildSessionContext, } from "./session-stores.js";
 export { createChainedSettingsProvider, createStaticSettingsProvider } from "./settings.js";
@@ -66,6 +67,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.6.0";
+export const version = "0.7.0";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/input.d.ts

@@ -1,5 +1,6 @@
+import { type AttentionStickyFrontier } from "./attention-compiler.js";
 import { type ContextBudget } from "./context-budget.js";
-import type { ContentBlock, ContextBlock, ContextProvider, ContextResolutionContext, InputBuildContext, InputBuilder, InstructionInjector, JsonObject, Message, ModelConfig, PromptBuilder, PromptBuildRequest, ProviderRequest, ProviderRequestOptions, ResourceLoader, Skill, ToolDefinition, ToolResult } from "./contracts.js";
+import type { AttentionCompiler, AttentionCompilerOptions, AttentionReport, ContentBlock, ContextBlock, ContextProvider, ContextResolutionContext, InputBuildContext, InputBuilder, InstructionInjector, JsonObject, Message, ModelConfig, PromptBuilder, PromptBuildRequest, ProviderRequest, ProviderRequestOptions, ResourceLoader, Skill, ToolDefinition, ToolResult } from "./contracts.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillSet, type SkillsDisclosure } from "./skill-disclosure.js";
@@ -77,6 +78,17 @@ export interface AssembleProviderInputOptions extends DefaultInputBuildContext {
     readonly contextBudget?: ContextBudget;
     /** Resolved tool-result fold; projection-only, store untouched. */
     readonly toolResultFold?: ResolvedToolResultFoldOptions;
+    /**
+     * Opt-in attention compiler: options are validated here (per call) or pass an existing
+     * `AttentionCompiler` to reuse one validation. Mutually exclusive with `contextBudget`,
+     * which would otherwise evict as a silent last resort after the compiler's stages.
+     */
+    readonly attentionCompiler?: AttentionCompilerOptions | AttentionCompiler;
+    /** Per-session-leaf sticky frontier; omit for one-shot assemblies (no cross-turn stickiness). */
+    readonly attentionSticky?: AttentionStickyFrontier;
+    /** Called once per *mutated* turn with the report, so a host can emit telemetry: under-ratio
+     *  turns never call it, and it runs before `input_assembly` middleware. */
+    readonly onAttentionReport?: (report: AttentionReport) => void;
 }
 export declare function createDefaultInputBuilder(): DefaultInputBuilder;
 export declare function resolveContextProviders(options: ResolveContextOptions): Promise<readonly ContextBlock[]>;

package/dist/input.js

@@ -1,3 +1,4 @@
+import { compileAttention, createAttentionCompiler } from "./attention-compiler.js";
 import { assertMessagesSupportModelCapabilities } from "./content.js";
 import { applyContextBudget, CONTEXT_BUDGET_REPORT_METADATA_KEY } from "./context-budget.js";
 import { runInstructionInjectors } from "./instruction-injection.js";
@@ -133,7 +134,41 @@ export async function assembleProviderInput(options) {
     }
     let demotedSkillBodies;
     let budgetReport;
-    if (options.contextBudget) {
+    if (options.attentionCompiler) {
+        if (options.contextBudget) {
+            throw new TypeError("attentionCompiler and contextBudget are mutually exclusive: the compiler raises AttentionBudgetError instead of evicting");
+        }
+        // Same default-groups path as the budget branch: the compiler needs the assembled groups
+        // (and the provider context blocks) to measure one cost for the whole request.
+        const groups = await buildDefaultInputMessageGroups(options.input, buildContext);
+        context = await resolveContextProviders({
+            providers: options.contextProviders,
+            messages: flattenInputGroups(groups, layout),
+            injectedBlocks: injectorContribs.contextBlocks.length ? injectorContribs.contextBlocks : undefined,
+            middleware: options.middleware,
+            ...baseContext,
+        });
+        const compiled = await compileAttention({
+            compiler: resolveAttentionCompiler(options.attentionCompiler, options.model),
+            groups,
+            context,
+            skills,
+            tools,
+            fold: options.toolResultFold,
+            frontier: options.attentionSticky,
+            redactor: options.redactor,
+            signal: options.signal,
+            turn,
+            sessionId: options.sessionId,
+            runId: options.runId,
+        });
+        if (compiled.mutated)
+            options.onAttentionReport?.(compiled.report);
+        messages = flattenInputGroups(compiled.groups, layout);
+        if (buildContext.middleware)
+            messages = await buildContext.middleware.run("input_assembly", messages);
+    }
+    else if (options.contextBudget) {
         // ponytail: budget path always uses default groups so eviction kinds stay deterministic;
         // custom inputBuilder still honored when contextBudget is absent.
         const groups = await buildDefaultInputMessageGroups(options.input, buildContext);
@@ -217,6 +252,10 @@ export async function assembleProviderInput(options) {
         signal: options.signal,
     }, { sessionId: options.sessionId });
 }
+/** A resolved handle is reused as-is; raw options are validated for this call only. */
+function resolveAttentionCompiler(value, model) {
+    return "inputCap" in value ? value : createAttentionCompiler(value, { model });
+}
 async function buildDefaultInputMessageGroups(input, context) {
     return {
         instructions: [

package/dist/secure-agent.d.ts

@@ -1,3 +1,5 @@
 import type { Agent, SecureAgentOptions } from "./contracts.js";
+import { assertHostCompositionReadiness, HostCompositionError, type HostCompositionGovernance, type HostCompositionOptions, type HostCompositionProfile, type HostCompositionReport, type HostCompositionToolReport, inspectHostComposition } from "./host-composition.js";
+export { assertHostCompositionReadiness, HostCompositionError, type HostCompositionGovernance, type HostCompositionOptions, type HostCompositionProfile, type HostCompositionReport, type HostCompositionToolReport, inspectHostComposition, };
 /** Build an opt-in agent whose security-critical defaults cannot be replaced per run. */
 export declare function createSecureAgent(options: SecureAgentOptions): Agent;

package/dist/secure-agent.js

@@ -1,8 +1,10 @@
 import { validateRunStateOptions } from "./agent-run-state.js";
 import { createAgent } from "./agents.js";
+import { assertHostCompositionReadiness, HostCompositionError, inspectHostComposition, } from "./host-composition.js";
 import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.js";
 import { resolveRunLimits } from "./run-limits.js";
 import { createToolParameterValidator, createToolRegistry } from "./tools.js";
+export { assertHostCompositionReadiness, HostCompositionError, inspectHostComposition, };
 /** Build an opt-in agent whose security-critical defaults cannot be replaced per run. */
 export function createSecureAgent(options) {
     if (!options.id.trim())
@@ -32,6 +34,9 @@ export function createSecureAgent(options) {
         assertIdentityActive(options.identity);
         assertIdentityMatchesOwnership(options.identity, options.ownership);
     }
+    if (options.composition) {
+        assertHostCompositionReadiness({ ...options.composition, agent: options });
+    }
     const runState = Object.freeze({ ...options.runState, definitionRevision: options.definitionRevision, interruptBeforeTool: true });
     validateRunStateOptions(runState);
     const config = Object.freeze({
@@ -52,7 +57,7 @@ export function createSecureAgent(options) {
     return createAgent(config);
 }
 function withoutSecureFields(options) {
-    const { tools: _tools, toolArgumentValidator: _validator, redactor: _redactor, permission: _permission, trust: _trust, ownership: _ownership, identity: _identity, limits: _limits, guardrails: _guardrails, definitionRevision: _revision, runState: _runState, ...config } = options;
+    const { tools: _tools, toolArgumentValidator: _validator, redactor: _redactor, permission: _permission, trust: _trust, ownership: _ownership, identity: _identity, limits: _limits, guardrails: _guardrails, definitionRevision: _revision, runState: _runState, composition: _composition, ...config } = options;
     return config;
 }
 function freezeGuardrails(guardrails) {

package/dist/tool-result-fold.d.ts

@@ -38,3 +38,15 @@ export declare function foldToolResultHistory(history: readonly Message[], optio
 export declare function foldToolResults(results: readonly ToolResult[], options: ResolvedToolResultFoldOptions, context: FoldToolResultsContext): Promise<readonly ToolResult[]>;
 export declare function formatFoldedToolResult(summary: string): string;
 export declare function foldedToolResultHeader(toolName: string, toolCallId: string, summary: string): string;
+/** Text the fold summarizes for one tool result: the payload JSON, then any text blocks.
+ *  Shared with the attention compiler so both hash/summarize the same bytes. */
+export declare function toolResultFoldText(result: unknown, error: unknown, extra?: readonly {
+    readonly type: string;
+}[]): string;
+/** UTF-8 cap that never splits a multi-byte character. Shared with the attention
+ *  compiler's host-summarize path so both cap host text identically. */
+export declare function capToolResultSummary(summary: string, maxBytes: number): string;
+/** Provider turn per history index: assistant messages advance the turn, tool rows use
+ *  their `prismToolResultTurn` stamp when present and the last assistant turn otherwise.
+ *  Shared with the attention compiler so age gates match the fold exactly. */
+export declare function inferToolResultTurns(history: readonly Message[]): readonly number[];

package/dist/tool-result-fold.js

@@ -58,7 +58,7 @@ async function foldToolResultMessage(message, options, context) {
     const block = message.content.find((part) => part.type === "tool_result");
     if (block?.type !== "tool_result")
         return message;
-    const text = toolResultText(block.result, block.error, message.content);
+    const text = toolResultFoldText(block.result, block.error, message.content);
     const folded = await maybeFold({
         options,
         context,
@@ -80,7 +80,7 @@ async function foldToolResultMessage(message, options, context) {
     return folded ?? message;
 }
 async function foldToolResultValue(result, options, context) {
-    const text = toolResultText(result.value, result.error, result.content);
+    const text = toolResultFoldText(result.value, result.error, result.content);
     const folded = await maybeFold({
         options,
         context,
@@ -112,7 +112,7 @@ async function maybeFold(input) {
             toolName: input.toolName,
             text: input.text,
         });
-        return input.apply(capSummaryBytes(String(summary), input.options.maxSummaryBytes));
+        return input.apply(capToolResultSummary(String(summary), input.options.maxSummaryBytes));
     }
     catch {
         return undefined;
@@ -124,7 +124,9 @@ export function formatFoldedToolResult(summary) {
 export function foldedToolResultHeader(toolName, toolCallId, summary) {
     return `Tool result ${toolName} [${toolCallId}]: ${summary}`;
 }
-function toolResultText(result, error, extra) {
+/** Text the fold summarizes for one tool result: the payload JSON, then any text blocks.
+ *  Shared with the attention compiler so both hash/summarize the same bytes. */
+export function toolResultFoldText(result, error, extra) {
     const parts = [JSON.stringify(error ?? result ?? null)];
     for (const block of extra ?? []) {
         if (block.type === "text" && "text" in block && typeof block.text === "string")
@@ -132,7 +134,9 @@ function toolResultText(result, error, extra) {
     }
     return parts.join("\n");
 }
-function capSummaryBytes(summary, maxBytes) {
+/** UTF-8 cap that never splits a multi-byte character. Shared with the attention
+ *  compiler's host-summarize path so both cap host text identically. */
+export function capToolResultSummary(summary, maxBytes) {
     const bytes = estimateTextBytes(summary);
     if (bytes <= maxBytes)
         return summary;
@@ -143,7 +147,10 @@ function capSummaryBytes(summary, maxBytes) {
         end--;
     return `${new TextDecoder().decode(encoded.slice(0, end))}…`;
 }
-function inferToolResultTurns(history) {
+/** Provider turn per history index: assistant messages advance the turn, tool rows use
+ *  their `prismToolResultTurn` stamp when present and the last assistant turn otherwise.
+ *  Shared with the attention compiler so age gates match the fold exactly. */
+export function inferToolResultTurns(history) {
     const turns = new Array(history.length).fill(1);
     let providerTurn = 0;
     let toolTurn = 1;

package/dist/tools.d.ts

@@ -56,5 +56,15 @@ export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
 }
 export declare function createToolRegistry(tools?: readonly ToolDefinition[], options?: ToolRegistryOptions): ToolRegistry;
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
+/** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
+export declare const HARD_RUN_TOOL_NAMES = 1024;
+/**
+ * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
+ * Fresh unknown names fail closed; resume drops names the current registry no longer has.
+ */
+export declare function selectRunTools(listed: readonly ToolDefinition[], requested: readonly string[] | undefined, checkpoint?: readonly string[]): {
+    readonly tools: readonly ToolDefinition[];
+    readonly grant: readonly string[] | undefined;
+};
 export declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>;
 export declare function resolveToolEffectDeclaration(tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext): ToolEffectDeclaration | undefined;

package/dist/tools.js

@@ -58,6 +58,47 @@ export function filterTools(tools, filter) {
         .filter((item) => Boolean(item));
     return tools.filter((tool) => !denied.has(tool.name) && allows.every((allow) => allow.has(tool.name)));
 }
+/** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
+export const HARD_RUN_TOOL_NAMES = 1024;
+const MAX_RUN_TOOL_NAME_CHARS = 256;
+function assertRunToolNames(names) {
+    if (names.length > HARD_RUN_TOOL_NAMES) {
+        throw new TypeError(`RunOptions.toolNames exceeds ${HARD_RUN_TOOL_NAMES} entries`);
+    }
+    const out = [];
+    const seen = new Set();
+    for (const name of names) {
+        if (typeof name !== "string" || name.length === 0 || name.length > MAX_RUN_TOOL_NAME_CHARS) {
+            throw new TypeError(`RunOptions.toolNames entries must be non-empty strings of at most ${MAX_RUN_TOOL_NAME_CHARS} characters`);
+        }
+        if (!seen.has(name)) {
+            seen.add(name);
+            out.push(name);
+        }
+    }
+    return out;
+}
+/**
+ * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
+ * Fresh unknown names fail closed; resume drops names the current registry no longer has.
+ */
+export function selectRunTools(listed, requested, checkpoint) {
+    const req = requested === undefined ? undefined : assertRunToolNames(requested);
+    const grant = checkpoint === undefined ? req : req === undefined ? checkpoint : req.filter((name) => checkpoint.includes(name));
+    if (grant === undefined)
+        return { tools: listed, grant };
+    if (grant.length === 0)
+        return { tools: [], grant };
+    const available = new Set(listed.map((tool) => tool.name));
+    if (checkpoint === undefined) {
+        for (const name of grant) {
+            if (!available.has(name))
+                throw new TypeError(`Unknown run tool: ${name}`);
+        }
+        return { tools: filterTools(listed, { allow: grant }), grant };
+    }
+    return { tools: filterTools(listed, { allow: grant.filter((name) => available.has(name)) }), grant };
+}
 function toolExecutionMetadata(startedAt, status) {
     return { durationMs: Math.max(0, Date.now() - Date.parse(startedAt)), status };
 }