@arnilo/prism 0.5.6 → 0.7.0

package/dist/agent-session/session.js

@@ -1,7 +1,9 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { policyList } from "../agent-tool-dispatch.js";
+import { createAttentionStickyFrontier, resolveInputCap, restoreAttentionStickyFrontier, serializeAttentionStickyFrontier, } from "../attention-compiler.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.js";
-import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS } from "../contracts.js";
+import { estimateAssemblyTokens, estimateTextTokens } from "../context-budget.js";
+import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, resolveShouldCompact, } from "../contracts.js";
 import { GuardrailError, runGuardrails } from "../guardrails.js";
 import { applyDefaultProviderRequestOptions, createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult, } from "../provider-request-policy.js";
 import { redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "../redaction.js";
@@ -53,6 +55,28 @@ export class RuntimeAgentSession {
     restoredSkillBodies = [];
     /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
     activeRunSkills = [];
+    /** Per-run tool allow-list (Task 21); undefined means the full registered set. */
+    activeToolNames;
+    /** Sticky frontier for this session (plan 074 C10); created on first use, so a session whose
+     *  agents never enable the compiler allocates nothing. Mutations stay applied once made, so a
+     *  later under-ratio turn re-applies them instead of rewriting the prompt-cache prefix. */
+    attentionSticky;
+    attentionStickyFor() {
+        this.attentionSticky ??= createAttentionStickyFrontier();
+        return this.attentionSticky;
+    }
+    /** Plan 074 P3: bounded snapshot for a durable checkpoint; `undefined` when the session never
+     *  mutated anything, so a compiler-off (or never-over-ratio) session persists nothing extra. */
+    serializedAttentionSticky() {
+        return this.attentionSticky && this.attentionSticky.thinking.size + this.attentionSticky.toolCallIds.size > 0
+            ? serializeAttentionStickyFrontier(this.attentionSticky)
+            : undefined;
+    }
+    /** Plan 074 P3: restore a frontier validated at checkpoint load, so a resumed run keeps its
+     *  stubs instead of re-deciding its first turn from the ratio. */
+    restoreAttentionSticky(persisted) {
+        this.attentionSticky = restoreAttentionStickyFrontier(persisted);
+    }
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names) {
         for (const name of names)
@@ -78,12 +102,14 @@ export class RuntimeAgentSession {
     ledgerFailure;
     snapshotGeneration = 0;
     snapshotCache;
+    snapshotCacheTtlMs;
     constructor(config) {
         this.id = config.id ?? randomId("session");
         this.agent = config.agent;
         this.metadata = config.metadata;
         this.store = config.store ?? config.agent.config.store ?? createMemorySessionStore();
         this.currentLeafId = config.leafId;
+        this.snapshotCacheTtlMs = resolveSnapshotCacheTtlMs(config.snapshotCacheTtlMs);
     }
     get leafId() {
         return this.currentLeafId;
@@ -391,10 +417,23 @@ export class RuntimeAgentSession {
     }
     async autoCompact(runId, options, signal, inputMessages) {
         const compaction = mergeCompaction(this.agent.config.compaction, options.compaction);
-        if (!compaction || compaction.thresholdEntries === undefined)
+        if (!compaction || (compaction.trigger === undefined && compaction.thresholdEntries === undefined))
             return;
         const snapshot = await this.snapshot();
-        if (snapshot.entries.length <= compaction.thresholdEntries || snapshot.entries.at(-1)?.kind === "compaction")
+        // A branch that just compacted keeps its fresh summary: no second pass over the same entries.
+        if (snapshot.entries.at(-1)?.kind === "compaction")
+            return;
+        const shouldCompact = await resolveShouldCompact({ trigger: compaction.trigger, thresholdEntries: compaction.thresholdEntries }, {
+            sessionId: this.id,
+            entryCount: snapshot.entries.length,
+            // Estimates of the branch the run is about to send: messages plus carried summaries.
+            estimateInputTokens: () => estimateAssemblyTokens(snapshot.messages) + snapshot.summaries.reduce((sum, summary) => sum + estimateTextTokens(summary), 0),
+            // Same cap helper the attention compiler resolves its `inputCap` with.
+            resolveInputCapTokens: () => resolveInputCap(undefined, options.model ?? this.agent.config.model),
+            metadata: compaction.metadata,
+            signal,
+        });
+        if (!shouldCompact)
             return;
         await this.compactBranch(compaction, runId, signal, "auto");
         const compacted = await this.snapshot();
@@ -470,8 +509,24 @@ export class RuntimeAgentSession {
         const value = reader
             ? await rebuildSessionContext(reader, { sessionId: this.id, leafId: this.currentLeafId })
             : rebuildSessionContext(await this.store.list(this.id), { leafId: this.currentLeafId });
-        this.snapshotCache = { leafId: this.currentLeafId, generation: this.snapshotGeneration, expiresAt: now + 1_000, value };
+        this.snapshotCache = {
+            leafId: this.currentLeafId,
+            generation: this.snapshotGeneration,
+            expiresAt: now + this.snapshotCacheTtlMs,
+            value,
+        };
         return value;
     }
 }
+/**
+ * `snapshotCacheTtlMs` resolution: `0` disables the branch cache (a host that needs a
+ * fresh store read per snapshot), otherwise a safe integer up to the hard cap.
+ */
+function resolveSnapshotCacheTtlMs(value) {
+    const ttl = value ?? DEFAULT_SNAPSHOT_CACHE_TTL_MS;
+    if (!Number.isSafeInteger(ttl) || ttl < 0 || ttl > HARD_MAX_SNAPSHOT_CACHE_TTL_MS) {
+        throw new TypeError(`AgentSessionConfig.snapshotCacheTtlMs must be a safe integer from 0 to ${HARD_MAX_SNAPSHOT_CACHE_TTL_MS}`);
+    }
+    return ttl;
+}
 //# sourceMappingURL=session.js.map

package/dist/agent-tool-dispatch.js

@@ -51,8 +51,9 @@ export async function validateElicitationPayload(agent, state, target, payload,
     // Tool-declared answer-shape validation, re-derived from the current registry (never persisted).
     const call = state.pendingCalls?.find((entry) => entry.call.id === target.toolCallId)?.call;
     const tool = call ? activeTools(agent.config.tools).registry.get(call.name) : undefined;
-    const validate = tool?.elicitation && call
-        ? safeToolElicitationValidate(tool, call.arguments, {
+    const elicitation = tool?.elicitation;
+    const validate = elicitation && call
+        ? safeToolElicitationValidate(elicitation, call.arguments, {
             sessionId: state.sessionId,
             runId: state.runId,
             toolCallId: target.toolCallId ?? "elicitation",
@@ -68,9 +69,9 @@ export async function validateElicitationPayload(agent, state, target, payload,
         }
     }
 }
-function safeToolElicitationValidate(tool, args, context) {
+function safeToolElicitationValidate(elicitation, args, context) {
     try {
-        return tool.elicitation(args, context)?.validate;
+        return elicitation(args, context)?.validate;
     }
     catch {
         return undefined;

package/dist/artifacts.d.ts

@@ -8,12 +8,26 @@ import type { OwnershipScope } from "./contracts.js";
 export type ArtifactApprovalState = "pending" | "approved" | "rejected";
 /** A resolved decision on one revision (pending is the absence of a decision). */
 export type ArtifactDecisionState = Exclude<ArtifactApprovalState, "pending">;
+/** Optional host semantic verdict. Never treated as citation integrity or proof. */
+export type CitationSupport = "unverified" | "supported" | "unsupported" | "uncertain";
 /** Bounded citation / data-source reference. Host resolves the body; Prism stores the ref only. */
 export interface ArtifactCitation {
     readonly uri: string;
     readonly title?: string;
-    /** Data-source kind (e.g. "web", "database", "upload"); host-defined, bounded. */
+    /** Data-source kind (e.g. "web", "database", "upload", "rag"); host-defined, bounded. */
     readonly kind?: string;
+    readonly sourceId?: string;
+    readonly revision?: string;
+    /** SHA-256 hex of the retrieved source snapshot (optional `sha256:` prefix). */
+    readonly contentHash?: string;
+    readonly retrievedAt?: string;
+    readonly excerpt?: string;
+    readonly span?: {
+        readonly start: number;
+        readonly end: number;
+    };
+    readonly tenantId?: string;
+    readonly support?: CitationSupport;
 }
 /** One immutable revision of an artifact. `uri`/`hash` reference host-owned content. */
 export interface ArtifactRevision {
@@ -43,6 +57,8 @@ export interface ArtifactApproval {
     /** Change-request / rejection note. */
     readonly note?: string;
     readonly decidedAt: string;
+    /** SHA-256 of bound citation sourceId/revision/contentHash tuples at decision time. */
+    readonly evidenceDigest?: string;
 }
 /**
  * Durable artifact record. Stored as a versioned checkpoint value; the checkpoint version
@@ -130,3 +146,25 @@ export declare class ArtifactError extends Error {
 export declare function artifactCheckpointKey(threadId: string, artifactId: string): string;
 /** Current review state: the decision on the latest revision, or pending when undecided. */
 export declare function artifactApprovalState(record: ArtifactRecord): ArtifactApprovalState;
+export declare const HARD_CITATION_EXCERPT_BYTES = 8192;
+export type CitationIntegrityReason = "ok" | "missing_source" | "hash_mismatch" | "span_mismatch" | "revoked_acl" | "revision_changed" | "excerpt_too_large" | "cross_tenant";
+export interface CitationLiveSource {
+    readonly contentHash: string;
+    readonly revision: string;
+    readonly body?: string;
+    readonly tenantId?: string;
+    readonly authorized?: boolean;
+}
+export interface CitationIntegrityResult {
+    readonly ok: boolean;
+    readonly reason: CitationIntegrityReason;
+}
+/** Deterministic source existence / hash / span / ACL check. Ignores `support`. */
+export declare function checkCitationIntegrity(citation: ArtifactCitation, live?: CitationLiveSource, options?: {
+    readonly boundRevision?: string;
+    readonly maxExcerptBytes?: number;
+}): CitationIntegrityResult;
+/** Stable digest of citation identity tuples. Source body changes after approval fail this digest only when citations themselves change; live hash is `checkCitationIntegrity`. */
+export declare function citationBindingDigest(citations: readonly ArtifactCitation[] | undefined): string;
+/** True when the approval digest still matches the revision and (if given) live sources pass integrity. */
+export declare function approvalEvidenceIntact(approval: ArtifactApproval, revision: ArtifactRevision, liveSources?: Readonly<Record<string, CitationLiveSource>>): CitationIntegrityResult;

package/dist/artifacts.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 /** Well-known error codes for ArtifactBodyStore failures. */
 export const ARTIFACT_BODY_ERROR_CODES = {
     OWNERSHIP: "ERR_PRISM_ARTIFACT_BODY_OWNERSHIP",
@@ -41,4 +42,76 @@ export function artifactApprovalState(record) {
     const decision = record.approvals.find((approval) => approval.version === latest.version);
     return decision?.state ?? "pending";
 }
+export const HARD_CITATION_EXCERPT_BYTES = 8192;
+function normalizeCitationHash(value) {
+    const raw = value.startsWith("sha256:") ? value.slice("sha256:".length) : value;
+    return raw.trim().toLowerCase();
+}
+/** Deterministic source existence / hash / span / ACL check. Ignores `support`. */
+export function checkCitationIntegrity(citation, live, options) {
+    const maxExcerpt = options?.maxExcerptBytes ?? HARD_CITATION_EXCERPT_BYTES;
+    if (citation.excerpt !== undefined && Buffer.byteLength(citation.excerpt, "utf8") > maxExcerpt) {
+        return { ok: false, reason: "excerpt_too_large" };
+    }
+    if (!live)
+        return { ok: false, reason: "missing_source" };
+    if (live.authorized === false)
+        return { ok: false, reason: "revoked_acl" };
+    if (citation.tenantId && live.tenantId && citation.tenantId !== live.tenantId) {
+        return { ok: false, reason: "cross_tenant" };
+    }
+    if (!citation.contentHash)
+        return { ok: false, reason: "missing_source" };
+    if (normalizeCitationHash(citation.contentHash) !== normalizeCitationHash(live.contentHash)) {
+        return { ok: false, reason: "hash_mismatch" };
+    }
+    if (citation.revision !== undefined && citation.revision !== live.revision) {
+        return { ok: false, reason: "revision_changed" };
+    }
+    if (options?.boundRevision !== undefined && options.boundRevision !== live.revision) {
+        return { ok: false, reason: "revision_changed" };
+    }
+    if (citation.span) {
+        const { start, end } = citation.span;
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end <= start) {
+            return { ok: false, reason: "span_mismatch" };
+        }
+        if (live.body !== undefined) {
+            const sliced = live.body.slice(start, end);
+            if (citation.excerpt !== undefined && sliced !== citation.excerpt) {
+                return { ok: false, reason: "span_mismatch" };
+            }
+        }
+    }
+    else if (citation.excerpt !== undefined && live.body !== undefined && citation.excerpt !== live.body) {
+        return { ok: false, reason: "span_mismatch" };
+    }
+    return { ok: true, reason: "ok" };
+}
+/** Stable digest of citation identity tuples. Source body changes after approval fail this digest only when citations themselves change; live hash is `checkCitationIntegrity`. */
+export function citationBindingDigest(citations) {
+    const rows = (citations ?? [])
+        .map((citation) => `${citation.sourceId ?? ""}|${citation.revision ?? ""}|${citation.contentHash ? normalizeCitationHash(citation.contentHash) : ""}`)
+        .sort();
+    return createHash("sha256").update(JSON.stringify(rows)).digest("hex");
+}
+/** True when the approval digest still matches the revision and (if given) live sources pass integrity. */
+export function approvalEvidenceIntact(approval, revision, liveSources) {
+    if (approval.evidenceDigest !== undefined && approval.evidenceDigest !== citationBindingDigest(revision.citations)) {
+        return { ok: false, reason: "revision_changed" };
+    }
+    if (liveSources === undefined)
+        return { ok: true, reason: "ok" };
+    for (const citation of revision.citations ?? []) {
+        if (!citation.sourceId && !citation.contentHash)
+            continue;
+        const live = citation.sourceId ? liveSources[citation.sourceId] : undefined;
+        const result = checkCitationIntegrity(citation, live, {
+            ...(citation.revision === undefined ? {} : { boundRevision: citation.revision }),
+        });
+        if (!result.ok)
+            return result;
+    }
+    return { ok: true, reason: "ok" };
+}
 //# sourceMappingURL=artifacts.js.map

package/dist/attention-compiler.d.ts

@@ -0,0 +1,121 @@
+/** Attention Compiler (plan 074 Tasks 2–3): frozen contracts, the ratio gate, and the two
+ *  sticky stages (thinking strip, then old tool-result stubs). Creation is synchronous and
+ *  fails closed; `compileAttention` measures the assembled request once, rewrites only the
+ *  `history` / `toolResults` groups, and never touches the store, the om ledger, or the
+ *  frozen prefix. The assembly branch lives in `input.ts`; opt-in agent wiring (Task 5) is not
+ *  part of this module. */
+import { type ContextBudgetMessageGroups } from "./context-budget.js";
+import type { AttentionCompiler, AttentionCompilerContext, AttentionCompilerOptions, AttentionCompilerSetting, AttentionInputCapOptions, AttentionReport, ContextBlock, Skill, ToolDefinition } from "./contracts.js";
+import { type CompactionTrigger } from "./contracts-core/compaction.js";
+import type { SecretRedactor } from "./redaction.js";
+import { type ResolvedToolResultFoldOptions } from "./tool-result-fold.js";
+export declare const ATTENTION_BUDGET_ERROR_CODE: "attention_budget_exceeded";
+/** C9: still over `triggerRatio` after every eligible stage — host should compact, not delete. */
+export declare class AttentionBudgetError extends Error {
+    readonly code: "attention_budget_exceeded";
+    constructor(message?: string);
+}
+export declare function isAttentionBudgetError(error: unknown): error is AttentionBudgetError;
+export declare const DEFAULT_ATTENTION_TRIGGER_RATIO = 0.75;
+export declare const DEFAULT_ATTENTION_COMPACT_RATIO = 0.9;
+export declare const DEFAULT_ATTENTION_THINKING_KEEP_TURNS = 1;
+export declare const DEFAULT_ATTENTION_KEEP_LAST = 3;
+export declare const DEFAULT_ATTENTION_RESERVE_TOKENS = 1024;
+export declare function resolveAttentionReserveTokens(value: unknown): number;
+/** C2: host `maxInputTokens` wins; otherwise `contextWindow - (maxOutputTokens ?? 0) - reserve`.
+ *  Shared with the `input_ratio` compaction trigger (Task 4). Throws when no cap can be derived. */
+export declare function resolveInputCap(options?: AttentionInputCapOptions, model?: AttentionCompilerContext["model"]): number;
+/** Validate compiler options + resolve the input cap. No provider I/O; unknown or
+ *  unresolvable input throws here rather than on the first turn. */
+export declare function createAttentionCompiler(options?: AttentionCompilerOptions, context?: AttentionCompilerContext): AttentionCompiler;
+/** Resolve the run's compiler from the agent setting plus an optional run overlay, validating
+ *  both eagerly (no provider I/O) so a typo fails at run start, not on some later turn (C12).
+ *  Returns `undefined` when the compiler is off — the assembly path then allocates nothing. */
+export declare function resolveRunAttentionCompiler(agent: AttentionCompilerSetting | undefined, run: AttentionCompilerSetting | undefined, model: AttentionCompilerContext["model"]): AttentionCompiler | undefined;
+/** Caller-owned sticky frontier: what this session leaf already mutated (C10). Mutations are
+ *  monotonic, so a stubbed call stays stubbed and stripped thinking stays stripped even on a
+ *  later under-ratio turn — restoring either would rewrite the prompt-cache prefix. */
+export interface AttentionStickyFrontier {
+    /** SHA-256 keys of assistant messages whose thinking blocks were stripped. */
+    readonly thinking: Set<string>;
+    /** Tool call ids whose results were stubbed. */
+    readonly toolCallIds: Set<string>;
+}
+export declare function createAttentionStickyFrontier(): AttentionStickyFrontier;
+export interface AttentionCompileOptions {
+    readonly compiler: AttentionCompiler;
+    /** The exact groups the assembler will send; only `history` and `toolResults` are rewritten. */
+    readonly groups: ContextBudgetMessageGroups;
+    readonly context?: readonly ContextBlock[];
+    readonly skills?: readonly Skill[];
+    readonly tools?: readonly ToolDefinition[];
+    /** Host fold: its `summarize` wins for the rows the compiler picks, and its age/byte gates
+     *  decide fold-eligibility. Omitted → the deterministic stub and `keepLast` alone. */
+    readonly fold?: ResolvedToolResultFoldOptions;
+    readonly frontier?: AttentionStickyFrontier;
+    readonly redactor?: SecretRedactor;
+    readonly signal?: AbortSignal;
+    readonly turn?: number;
+    readonly sessionId?: string;
+    readonly runId?: string;
+}
+export interface AttentionCompilation {
+    /** The input groups unchanged when nothing was mutated; otherwise a new object with the
+     *  rewritten `history` / `toolResults` arrays. The input groups are never mutated. */
+    readonly groups: ContextBudgetMessageGroups;
+    readonly mutated: boolean;
+    readonly report: AttentionReport;
+}
+/**
+ * Measure once, then mutate oldest-first until back under `triggerRatio` (C4), or throw
+ * `AttentionBudgetError` when every eligible row is exhausted (C9). Front-of-frozen-prefix
+ * (instructions, summaries, input) is never touched, and neither are the caller's arrays.
+ */
+export declare function compileAttention(options: AttentionCompileOptions): Promise<AttentionCompilation>;
+/** Serialized sticky frontier (plan 074 P3). Hashes and tool-call ids only: no model output,
+ *  no payload, nothing that needs redaction, so a durable resume can restore it verbatim. */
+export interface PersistedAttentionStickyFrontier {
+    readonly v: 1;
+    /** Newest-last, so a restored frontier is the tail of the mutations the session made. */
+    readonly thinking: readonly string[];
+    readonly toolCallIds: readonly string[];
+}
+/** Bounded snapshot of a live frontier; caller-owned (the runtime persists it, the compiler
+ *  never writes anywhere). */
+export declare function serializeAttentionStickyFrontier(frontier: AttentionStickyFrontier): PersistedAttentionStickyFrontier;
+/** Validate a persisted frontier from an untrusted store (plan 074 P3). Malformed *entries* are
+ *  dropped one by one — a key the compiler cannot trust simply re-decides on the next turn —
+ *  while a malformed *shape* yields `undefined` so the caller starts from an empty frontier.
+ *  Never throws: a resume must not fail because a checkpoint was hand-edited. */
+export declare function parseAttentionStickyFrontier(value: unknown): PersistedAttentionStickyFrontier | undefined;
+/** Rebuild a frontier from a restored snapshot; callers hold the session that owns it. */
+export declare function restoreAttentionStickyFrontier(persisted: PersistedAttentionStickyFrontier): AttentionStickyFrontier;
+/** Consecutive `truncated` turns that arm compaction by default. */
+export declare const DEFAULT_ATTENTION_TRUNCATION_THRESHOLD = 2;
+export interface AttentionTruncationTriggerOptions {
+    /** Truncated turns in a row before the trigger fires (default 2). */
+    readonly threshold?: number;
+}
+/**
+ * Host-side follow-up policy for `truncated` turns (plan 074 P4). `truncated: true` means the
+ * gate ran out of *eligible* rows: stubs cannot hold the request under the ratio, so the honest
+ * answer is a new prefix at the next task boundary rather than a silent eviction.
+ *
+ * Wire it by feeding every `attention_compiled` event to `observe` and handing `trigger` to
+ * `CompactionOptions.trigger` (agent config or run options). It fires **once per armed streak**,
+ * so a branch is compacted once and then left alone until new truncated turns arrive; a mutated
+ * turn that was not truncated clears the streak because the pressure was relieved.
+ */
+export interface AttentionTruncationTrigger {
+    /** Drop-in `CompactionOptions.trigger`. */
+    readonly trigger: CompactionTrigger;
+    /** Feed an `attention_compiled` event or an `AttentionReport`; returns the resulting streak. */
+    observe(report: {
+        readonly truncated?: unknown;
+    }): number;
+    /** Truncated turns in a row since the last fire or relief. */
+    readonly streak: () => number;
+    /** Clear the streak (host compacted for its own reasons). */
+    reset(): void;
+}
+export declare function createAttentionTruncationTrigger(options?: AttentionTruncationTriggerOptions): AttentionTruncationTrigger;