import { type PersistedAttentionFoldLedger, type PersistedAttentionStickyFrontier } from "./attention-compiler.js"; import type { Agent, AgentRunCheckpointMetadata, AgentRunCheckpointMetadataSource, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, GuardrailRule, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js"; import type { SecretRedactor } from "./redaction.js"; import { type LoadedSkillBodiesEntry } from "./skill-load.js"; export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run"; export declare const AGENT_RUN_STATE_SCHEMA_VERSION: 1; export declare const DEFAULT_MAX_AGENT_RUN_STATE_BYTES: number; export declare const HARD_MAX_AGENT_RUN_STATE_BYTES: number; /** Sidecar metadata ceiling per checkpoint record (not the run-state value). */ export declare const MAX_AGENT_RUN_METADATA_BYTES: number; /** One gated tool call awaiting or holding a decision inside a suspended durable run. */ export interface PendingToolCall { readonly call: ToolCallContent; readonly status: "ready" | "dispatched"; readonly approvalId: string; /** Decision persisted by a partial batch; applied when the run finally resumes. */ readonly decision?: RunDecision; } export interface StoredAgentRunState extends AgentRunState { readonly input?: readonly Message[]; /** Legacy single gated call (pre-0.0.25 checkpoints). New states write `pendingCalls`. */ readonly pending?: { readonly call: ToolCallContent; readonly status: "ready" | "dispatched"; }; /** Gated calls of the current suspension, in provider-turn order. */ readonly pendingCalls?: readonly PendingToolCall[]; /** Suspended nested runs (supervisor children) whose pending decisions surface at this root. */ readonly nestedRuns?: readonly NestedRunRef[]; /** Run-scoped sticky decisions; exact scope match, dropped at any terminal status. */ readonly stickyDecisions?: readonly StickyDecision[]; readonly interruptBeforeTool?: boolean; readonly counters: RunLimitCounters; /** Wall deadline; absent when the run has no wall limit. Old snapshots with a deadline still parse. */ readonly deadlineAt?: string; /** Loop-local durable state captured by the strategy's snapshot hook at suspension. */ readonly loopState?: { readonly name: string; readonly revision: string; readonly snapshot: JsonValue; }; /** * Opt-in session-level state (plan 015 Task 4): loaded-skill names only; bodies are * never persisted and reload on demand from the live registry via `load_skill`. * Absent by default (0.1.x checkpoints parse unchanged). */ readonly sessionState?: { readonly loadedSkillNames?: readonly string[]; readonly loadedSkillBodies?: readonly LoadedSkillBodiesEntry[]; /** Plan 041: tools activated via `search_tools` (names only; inert for absent tools on restore). */ readonly activatedToolNames?: readonly string[]; /** Plan 074 P3: sticky attention mutations (thinking hashes + tool-call ids), so a durable * resume keeps its stubs instead of re-deciding on the first turn. Validated on load. */ readonly attentionSticky?: PersistedAttentionStickyFrontier; /** Plan 086 T3: folded bodies (`attention.compiler.durable`), so a resumed fold re-applies * the same stub bytes instead of re-summarizing. Written and restored independently of * `persistSessionState`. Validated on load. */ readonly attentionFold?: PersistedAttentionFoldLedger; /** Plan 104 T2: compiled pack refs plus pack-owned state, so a resume re-enforces exactly what * the suspended run enforced. Written only with `persistSessionState`; validated on load. */ readonly guardrailPacks?: PersistedGuardrailPacks; }; /** Per-run allow-list (Task 21). Absent = full registered set (legacy checkpoints). */ readonly toolNames?: readonly string[]; /** * Recorded checkpoint cadence (plan 084 Task 1). Present only for `"every-turn"` runs, so * default checkpoints stay byte-identical. A resume of such a state keeps checkpointing each * turn without the host repeating the option. */ readonly checkpointPolicy?: "every-turn"; /** * Set when a terminal state was written by a clean run-end stop that leaves the frontier intact: * a `RunOptions.turnPolicy` stop (`host_policy`, plan 084 Task 2) or a stop-hook continuation cap * (`hook_limit`, plan 106 R1). The run succeeded but `decision: "continue"` may resume it. Absent * on every other state — a naturally finished run is never continuable. */ readonly stopReason?: "host_policy" | "hook_limit"; } /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */ export declare const MAX_PERSISTED_SKILL_NAMES = 64; export declare const MAX_PERSISTED_SKILL_NAME_CHARS = 256; /** Plan 041: activated-tool names ride the same budget discipline (cap 128; multiple searches accumulate). */ export declare const MAX_PERSISTED_ACTIVATED_TOOL_NAMES = 128; /** Plan 104 T2: one replayable pack row — the id, the version it was compiled at, and host options. */ interface PersistedGuardrailPackRef { readonly id: string; readonly version: number; readonly options?: Readonly>; /** Inline pattern rules; closures and `RegExp` patterns never reach a checkpoint (refused at save). */ readonly rules?: readonly GuardrailRule[]; } /** * Plan 104 T2: the checkpoint-side pack block written with `persistSessionState`. Rows replay a * registered pack by `id`/`version` or an inline pack by its pattern `rules` (plan 104 T3). */ export interface PersistedGuardrailPacks { readonly packs: readonly PersistedGuardrailPackRef[]; readonly state?: Readonly>>>; } /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */ export declare const BUILT_IN_LOOP_REVISIONS: Readonly>; /** Validate a strategy snapshot as JSON-compatible and package it for the durable envelope. */ export declare function boundedLoopSnapshot(name: string, revision: string, snapshot: JsonValue): StoredAgentRunState["loopState"]; export declare function agentFingerprint(agent: Agent, revision: string): string; export declare function agentId(agent: Agent): string; export declare function validateRunStateOptions(options: AgentRunStateOptions): void; export declare function loadAgentRunState(checkpoints: CheckpointStore, ref: AgentRunRef, ownership?: OwnershipScope): Promise<{ readonly record: CheckpointRecord; readonly state: StoredAgentRunState; readonly metadata?: AgentRunCheckpointMetadata; }>; /** Resolve a host metadata source. A throwing provider fails the checkpoint write (fail closed). */ export declare function resolveCheckpointMetadata(source: AgentRunCheckpointMetadataSource | undefined): AgentRunCheckpointMetadata | undefined; /** * Redact + bound a sidecar metadata map for a checkpoint write. Values must be strings; * redaction runs first so a replacement marker is still charged against the 4 KiB ceiling. */ export declare function boundCheckpointMetadata(metadata: AgentRunCheckpointMetadata, redactor?: SecretRedactor): AgentRunCheckpointMetadata; /** * Read-side normalization (legacy tolerance): absent, oversize, or non-string entries are * dropped, never thrown — a malformed sidecar must not block a resume. */ export declare function readCheckpointMetadata(metadata: unknown): AgentRunCheckpointMetadata | undefined; export declare function saveAgentRunState(input: { readonly checkpoints: CheckpointStore; readonly state: StoredAgentRunState; readonly expectedVersion: number; readonly ownership?: OwnershipScope; readonly fencingToken?: number; readonly redactor?: SecretRedactor; readonly maxStateBytes?: number; readonly metadata?: AgentRunCheckpointMetadata; }): Promise<{ readonly record: CheckpointRecord; readonly state: StoredAgentRunState; }>; export declare function publicState(state: StoredAgentRunState): AgentRunState; export declare function initialAgentRunState(input: { readonly agent: Agent; readonly options: AgentRunStateOptions; readonly runId: string; readonly sessionId: string; readonly leafId?: string; readonly model: ModelConfig; readonly counters: RunLimitCounters; readonly deadlineAt?: string; readonly status: "suspended" | "running"; readonly interruption?: AgentRunInterruption; readonly messages?: readonly Message[]; readonly pending?: StoredAgentRunState["pending"]; readonly pendingCalls?: StoredAgentRunState["pendingCalls"]; readonly interruptBeforeTool?: boolean; }): StoredAgentRunState; export declare function parseAgentRunState(value: unknown, version?: number): StoredAgentRunState; export {};