@arnilo/prism 0.7.0 → 0.9.0

package/dist/agent-session/session.d.ts

@@ -1,8 +1,8 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
-import { ActiveDurableRun } from "../agent-approval.js";
+import { ActiveDurableRun, ActiveDurableRunExtras } from "../agent-approval.js";
 import type { PendingToolCall, StoredAgentRunState } from "../agent-run-state.js";
-import { type AttentionStickyFrontier, type PersistedAttentionStickyFrontier } from "../attention-compiler.js";
-import type { Agent, AgentEvent, AgentRunResult, AgentRunState, AgentRunStateOptions, AgentSession, AgentSessionConfig, AIProvider, CompactionOptions, CompactionResult, ErrorInfo, Message, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunDecision, RunOptions, SessionEntry, Skill, SteerOptions, SubscribeOptions, ToolDefinition, ToolEffectStore, Usage } from "../contracts.js";
+import { type AttentionFoldLedger, type AttentionStickyFrontier, type PersistedAttentionFoldLedger, type PersistedAttentionStickyFrontier } from "../attention-compiler.js";
+import type { Agent, AgentEvent, AgentRunResult, AgentRunState, AgentRunStateOptions, AgentSession, AgentSessionConfig, AIProvider, CompactionOptions, CompactionResult, ContextMeter, ErrorInfo, Guardrails, Message, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunDecision, RunOptions, SessionEntry, Skill, SteerOptions, SubscribeOptions, ToolCallSummary, ToolDefinition, ToolEffectStore, Usage } from "../contracts.js";
 import type { AgentIdentity } from "../identity.js";
 import type { AgentInput } from "../input.js";
 import type { RunLimitTracker } from "../run-limits.js";
@@ -30,9 +30,21 @@ export declare class RuntimeAgentSession implements AgentSession {
     activeIdentity?: AgentIdentity;
     private activeIdempotencyKey?;
     private activeGuardrails?;
+    /** Plan 092 Task 2: guardrail packs compiled once in the constructor; merged into every run's `activeGuardrails`. */
+    readonly packGuardrails?: Guardrails;
+    /** Original pack refs, carried into `fork()`/`clone()` so a branch cannot silently lose its policy. */
+    private readonly guardrailPackRefs?;
     activeMetadata?: Readonly<Record<string, unknown>>;
     activePromptVersion?: PromptVersionRef;
     activeLimits?: RunLimitTracker;
+    /** Plan 091 T2: input tokens of the latest provider turn plus whether the provider reported
+     *  them; set by the usage seam, read by `contextMeter()`. */
+    activeInputMeter?: {
+        readonly tokens: number;
+        readonly source: "reported" | "estimated";
+    };
+    /** Bounded last-N tool-call summaries of the active run (plan 087 T2): ids, names, arg hashes. */
+    activeRecentToolCalls?: ToolCallSummary[];
     activeLimitOutputBuffer: boolean;
     activeDurable?: ActiveDurableRun;
     activeLoop?: import("../contracts.js").AgentLoopStrategy;
@@ -43,6 +55,8 @@ export declare class RuntimeAgentSession implements AgentSession {
     }>;
     activeLoopTurn: number;
     private readonly loadedSkills;
+    /** Run-owned only: loaded bodies and URI resources retain first insertion order within one provider loop. */
+    readonly tailSegments: Map<string, Message>;
     /** Tools activated via `search_tools` this session (plan 041); names-only in persistence. */
     readonly activatedTools: import("../tool-search.js").ActiveToolSet;
     /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
@@ -62,6 +76,17 @@ export declare class RuntimeAgentSession implements AgentSession {
     /** 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: PersistedAttentionStickyFrontier): void;
+    /** Session-owned folded bodies (plan 086 T3); created on first use like the frontier, so a
+     *  compiler-off session allocates nothing. */
+    private attentionFold?;
+    /** Set per run from the resolved compiler: `durable: true` opts the fold ledger and its
+     *  frontier into checkpoints even when `persistSessionState` is off. */
+    attentionDurable: boolean;
+    attentionFoldFor(): AttentionFoldLedger;
+    /** Plan 086 T3: bounded ledger snapshot for a durable checkpoint; `undefined` before any fold. */
+    serializedAttentionFold(): PersistedAttentionFoldLedger | undefined;
+    /** Plan 086 T3: adopt a ledger validated at checkpoint load, so a resumed fold is byte-identical. */
+    restoreAttentionFold(ledger: AttentionFoldLedger): void;
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names: readonly string[]): void;
     /** Plan 041: re-add persisted activated-tool names (names only; inert for absent tools). */
@@ -79,10 +104,19 @@ export declare class RuntimeAgentSession implements AgentSession {
         readonly agent: Agent;
     });
     get leafId(): string | undefined;
+    /**
+     * Context-fill read (plan 091 T2): the latest provider turn's input tokens —
+     * provider-reported when it reported, else a labeled estimate — plus the
+     * per-request cap and cumulative run input budget, resolved exactly as
+     * `provider_turn_finished.budgets` resolves them. Before any provider turn in
+     * this session it estimates stored history, so a non-reporting model still
+     * shows a working meter instead of zero. Never billing; estimates are labeled.
+     */
+    contextMeter(): ContextMeter;
     subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
     run(input: AgentInput, options?: RunOptions): Promise<AgentRunResult>;
     steer(input: AgentInput, options?: SteerOptions): void;
-    resumeDurable(state: StoredAgentRunState, runState: AgentRunStateOptions, ownership?: OwnershipScope, signal?: AbortSignal, decisions?: ReadonlyMap<string, RunDecision>): Promise<AgentRunResult>;
+    resumeDurable(state: StoredAgentRunState, runState: AgentRunStateOptions, ownership?: OwnershipScope, signal?: AbortSignal, decisions?: ReadonlyMap<string, RunDecision>, extras?: ActiveDurableRunExtras): Promise<AgentRunResult>;
     recordDurableResumption(runId: string, interruption: import("../contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
     recordDurableDenial(runId: string, interruption: import("../contracts.js").AgentRunInterruption, version: number, ownership?: OwnershipScope): Promise<void>;
     private runInternal;
@@ -95,6 +129,8 @@ export declare class RuntimeAgentSession implements AgentSession {
         readonly limit?: import("../contracts.js").RunLimitBreach;
         readonly error?: ErrorInfo;
         readonly abortReason?: string;
+        readonly stopReason?: import("../contracts.js").AgentFinishReason;
+        readonly stopDetail?: string;
         readonly runState?: AgentRunState;
         readonly interruption?: import("../contracts.js").AgentRunInterruption;
     }): AgentRunResult;

package/dist/agent-session/session.js

@@ -1,10 +1,10 @@
 /** 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 { createAttentionFoldLedger, createAttentionStickyFrontier, resolveInputCap, restoreAttentionStickyFrontier, serializeAttentionFoldLedger, serializeAttentionStickyFrontier, } from "../attention-compiler.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.js";
-import { estimateAssemblyTokens, estimateTextTokens } from "../context-budget.js";
+import { estimateAssemblyTokens, estimateMessageTokens, 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 { compileGuardrailPacks, GuardrailError, runGuardrails } from "../guardrails.js";
 import { applyDefaultProviderRequestOptions, createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult, } from "../provider-request-policy.js";
 import { redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "../redaction.js";
 import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext } from "../session-stores.js";
@@ -39,9 +39,18 @@ export class RuntimeAgentSession {
     activeIdentity;
     activeIdempotencyKey;
     activeGuardrails;
+    /** Plan 092 Task 2: guardrail packs compiled once in the constructor; merged into every run's `activeGuardrails`. */
+    packGuardrails;
+    /** Original pack refs, carried into `fork()`/`clone()` so a branch cannot silently lose its policy. */
+    guardrailPackRefs;
     activeMetadata;
     activePromptVersion;
     activeLimits;
+    /** Plan 091 T2: input tokens of the latest provider turn plus whether the provider reported
+     *  them; set by the usage seam, read by `contextMeter()`. */
+    activeInputMeter;
+    /** Bounded last-N tool-call summaries of the active run (plan 087 T2): ids, names, arg hashes. */
+    activeRecentToolCalls;
     activeLimitOutputBuffer = false;
     activeDurable;
     activeLoop;
@@ -49,6 +58,8 @@ export class RuntimeAgentSession {
     activeGatedRound;
     activeLoopTurn = 1;
     loadedSkills = createLoadedSkillSet();
+    /** Run-owned only: loaded bodies and URI resources retain first insertion order within one provider loop. */
+    tailSegments = new Map();
     /** Tools activated via `search_tools` this session (plan 041); names-only in persistence. */
     activatedTools = createActiveToolSet();
     /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
@@ -77,6 +88,24 @@ export class RuntimeAgentSession {
     restoreAttentionSticky(persisted) {
         this.attentionSticky = restoreAttentionStickyFrontier(persisted);
     }
+    /** Session-owned folded bodies (plan 086 T3); created on first use like the frontier, so a
+     *  compiler-off session allocates nothing. */
+    attentionFold;
+    /** Set per run from the resolved compiler: `durable: true` opts the fold ledger and its
+     *  frontier into checkpoints even when `persistSessionState` is off. */
+    attentionDurable = false;
+    attentionFoldFor() {
+        this.attentionFold ??= createAttentionFoldLedger();
+        return this.attentionFold;
+    }
+    /** Plan 086 T3: bounded ledger snapshot for a durable checkpoint; `undefined` before any fold. */
+    serializedAttentionFold() {
+        return this.attentionFold && this.attentionFold.bodies.size > 0 ? serializeAttentionFoldLedger(this.attentionFold) : undefined;
+    }
+    /** Plan 086 T3: adopt a ledger validated at checkpoint load, so a resumed fold is byte-identical. */
+    restoreAttentionFold(ledger) {
+        this.attentionFold = ledger;
+    }
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names) {
         for (const name of names)
@@ -110,10 +139,46 @@ export class RuntimeAgentSession {
         this.store = config.store ?? config.agent.config.store ?? createMemorySessionStore();
         this.currentLeafId = config.leafId;
         this.snapshotCacheTtlMs = resolveSnapshotCacheTtlMs(config.snapshotCacheTtlMs);
+        this.packGuardrails = compileGuardrailPacks(config.guardrailPacks);
+        this.guardrailPackRefs = config.guardrailPacks;
+        const usageEstimation = config.agent.config.usageEstimation;
+        if (usageEstimation !== undefined && usageEstimation !== "fallback" && usageEstimation !== "off") {
+            throw new TypeError('usageEstimation must be "fallback" or "off"');
+        }
     }
     get leafId() {
         return this.currentLeafId;
     }
+    /**
+     * Context-fill read (plan 091 T2): the latest provider turn's input tokens —
+     * provider-reported when it reported, else a labeled estimate — plus the
+     * per-request cap and cumulative run input budget, resolved exactly as
+     * `provider_turn_finished.budgets` resolves them. Before any provider turn in
+     * this session it estimates stored history, so a non-reporting model still
+     * shows a working meter instead of zero. Never billing; estimates are labeled.
+     */
+    contextMeter() {
+        const model = this.agent.config.model;
+        const inputTokens = this.activeInputMeter?.tokens ?? estimateMessageTokens(this.history, model.model).tokens;
+        const source = this.activeInputMeter?.source ?? "estimated";
+        let inputCap;
+        try {
+            const setting = this.agent.config.attentionCompiler;
+            const options = typeof setting === "object" && setting !== null ? setting : undefined;
+            inputCap = resolveInputCap(options ? { maxInputTokens: options.maxInputTokens, reserveTokens: options.reserveTokens } : {}, model);
+        }
+        catch {
+            inputCap = undefined; // undialed model: omit instead of throwing a state read
+        }
+        const runInputBudget = this.activeLimits?.limits.maxInputTokens ?? undefined;
+        return {
+            inputTokens,
+            source,
+            ...(inputCap === undefined ? {} : { inputCap }),
+            ...(runInputBudget == null ? {} : { runInputBudget }),
+            ...(inputCap === undefined ? {} : { usedRatio: inputTokens / inputCap }),
+        };
+    }
     subscribe(options = {}) {
         const subscriber = new EventSubscriber(this.id, options, () => this.subscribers.delete(subscriber));
         this.subscribers.add(subscriber);
@@ -147,12 +212,13 @@ export class RuntimeAgentSession {
                 this.pendingSoftInterrupt = true;
         }
     }
-    async resumeDurable(state, runState, ownership, signal, decisions) {
+    async resumeDurable(state, runState, ownership, signal, decisions, extras) {
         return this.runInternal(state.input ?? [], { runState, ownership, signal }, state.runId, {
             options: runState,
             state,
             version: state.version,
             decisions,
+            ...extras,
         });
     }
     async recordDurableResumption(runId, interruption, version, ownership) {
@@ -232,6 +298,8 @@ export class RuntimeAgentSession {
             limit: input.limit,
             error: input.error,
             abortReason: input.abortReason,
+            stopReason: input.stopReason,
+            stopDetail: input.stopDetail,
             runState: input.runState,
             interruption: input.interruption,
         };
@@ -239,7 +307,10 @@ export class RuntimeAgentSession {
     async compact(options = {}) {
         if (this.activeRun)
             throw new Error("Agent session already has an active run");
-        return this.compactBranch(options, undefined, options.signal, "manual");
+        const result = await this.compactBranch(options, undefined, options.signal, "manual");
+        // Plan 091 T2: history changed, so a pre-compaction meter reading would overstate the context.
+        this.activeInputMeter = undefined;
+        return result;
     }
     abort(reason) {
         this.activeRun?.abort(reason);
@@ -262,6 +333,7 @@ export class RuntimeAgentSession {
             store: this.store,
             leafId: options.leafId ?? this.currentLeafId,
             metadata: this.metadata,
+            ...(this.guardrailPackRefs ? { guardrailPacks: this.guardrailPackRefs } : {}),
         });
     }
     async clone(options = {}) {
@@ -284,6 +356,7 @@ export class RuntimeAgentSession {
             store: this.store,
             leafId: branch.length ? remap.get(branch[branch.length - 1].id) : undefined,
             metadata: this.metadata,
+            ...(this.guardrailPackRefs ? { guardrailPacks: this.guardrailPackRefs } : {}),
         });
     }
     branchReader() {

package/dist/attention-compiler.d.ts

@@ -5,7 +5,7 @@
  *  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 { AttentionCompiler, AttentionCompilerContext, AttentionCompilerOptions, AttentionCompilerSetting, AttentionInputCapOptions, AttentionReport, AttentionTrigger, AttentionTriggerDecision, AttentionTriggerState, 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";
@@ -25,13 +25,29 @@ 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;
+/**
+ * Build the frozen per-turn state the axes read: the compiler supplies the cap and the run budget
+ * (so a caller cannot silently drop the budget and fall back to the input cap), the caller
+ * supplies what only the turn knows.
+ */
+export declare function attentionTriggerState(compiler: Pick<AttentionCompiler, "inputCap" | "runInputBudget">, turn: {
+    readonly estimatedInputTokens: number;
+    readonly runInputTokens?: number;
+    readonly turn?: number;
+}): AttentionTriggerState;
+/**
+ * Evaluate the fold axes in order against one turn's state; the first axis that fires wins, and
+ * its `targetTokens` (when it has one) is what the stages fold to. Called at most twice per turn —
+ * once at turn start, once after the stages — so a host predicate never runs per row.
+ */
+export declare function evaluateAttentionTrigger(axes: readonly AttentionTrigger[], state: AttentionTriggerState): AttentionTriggerDecision;
 /** 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;
+export declare function resolveRunAttentionCompiler(agent: AttentionCompilerSetting | undefined, run: AttentionCompilerSetting | undefined, model: AttentionCompilerContext["model"], runInputBudget?: number | null): 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. */
@@ -53,9 +69,15 @@ export interface AttentionCompileOptions {
      *  decide fold-eligibility. Omitted → the deterministic stub and `keepLast` alone. */
     readonly fold?: ResolvedToolResultFoldOptions;
     readonly frontier?: AttentionStickyFrontier;
+    /** Session-owned folded bodies (plan 086 T3): a body stored here is re-applied instead of
+     *  re-summarized, so a sticky row stays byte-identical and the host `summarize` runs once per
+     *  row instead of once per turn. Omit for one-shot assemblies. */
+    readonly attentionFold?: AttentionFoldLedger;
     readonly redactor?: SecretRedactor;
     readonly signal?: AbortSignal;
     readonly turn?: number;
+    /** Run input tokens already charged this run; the `run_input_ratio` axis projects onto it. */
+    readonly runInputTokens?: number;
     readonly sessionId?: string;
     readonly runId?: string;
 }
@@ -90,6 +112,33 @@ export declare function serializeAttentionStickyFrontier(frontier: AttentionStic
 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;
+/** Session-owned folded bodies, keyed by tool call id. A row is summarized once: every later
+ *  turn re-applies the stored body, so a sticky row stays byte-identical for the provider cache
+ *  and the host `summarize` is not called again for it. Bodies are already redacted and capped by
+ *  the fold that produced them, so nothing here needs redaction at persistence time. */
+export interface AttentionFoldLedger {
+    /** toolCallId → stub body (never the payload); insertion order is fold order, oldest first. */
+    readonly bodies: Map<string, string>;
+}
+export declare function createAttentionFoldLedger(): AttentionFoldLedger;
+/** Serialized fold ledger (plan 086 T3). Stub bodies only — no payload, and every entry was
+ *  already capped and redacted when it was folded, so a durable resume restores it verbatim. */
+export interface PersistedAttentionFoldLedger {
+    readonly v: 1;
+    /** Oldest-first, so a restored ledger is the tail of the folds the session made. */
+    readonly bodies: readonly {
+        readonly id: string;
+        readonly body: string;
+    }[];
+}
+/** Bounded snapshot of a live ledger; caller-owned (the runtime persists it, the compiler never
+ *  writes anywhere). */
+export declare function serializeAttentionFoldLedger(ledger: AttentionFoldLedger): PersistedAttentionFoldLedger;
+/** Validate a persisted ledger from an untrusted store (plan 086 T3). Malformed *entries* are
+ *  dropped one by one — a body the compiler cannot trust simply re-summarizes on the next turn —
+ *  while a malformed *shape* yields `undefined` so the caller starts from an empty ledger.
+ *  Never throws: a resume must not fail because a checkpoint was hand-edited. */
+export declare function restoreAttentionFoldLedger(value: unknown): AttentionFoldLedger | undefined;
 /** Consecutive `truncated` turns that arm compaction by default. */
 export declare const DEFAULT_ATTENTION_TRUNCATION_THRESHOLD = 2;
 export interface AttentionTruncationTriggerOptions {