@theokit/sdk 4.48.0 → 4.50.0

package/dist/index.d.cts

@@ -1263,6 +1263,63 @@ declare class Tool {
     static create<T extends ZodType, O extends ZodType = never>(spec: DefineToolSpec<T, O>): CustomTool;
 }
 
+/**
+ * Audit whether every configuration key can be set from the environment, or says why not.
+ *
+ * A key settable only by editing a file cannot be set in CI, in a container, or for a single
+ * invocation. That is usually an oversight rather than a decision, and it is invisible — nothing
+ * fails, the key simply has no environment path, and nobody notices until someone needs one.
+ *
+ * The opposite failure rots more quietly. An opt-out written for a key that has since gained an
+ * environment path, or for a key that no longer exists, still reads as a considered decision while
+ * exempting nothing. Both questions are answered by one call so a consumer cannot check the gap and
+ * forget the rot: they fail for opposite reasons, and a suite that asks only one looks complete.
+ *
+ * ## Why the framework owns the rule and not the keys
+ *
+ * A framework cannot enumerate a consumer's configuration keys, and should not try. Which keys exist
+ * is that product's vocabulary — the same reason the security floor takes its permissiveness order
+ * as data and the trust posture takes its capability list. So the consumer ranges over its own keys
+ * with this, rather than registering them here.
+ *
+ * That is a narrower claim than "reachability is checked in the framework", and it is the honest
+ * one: the failure still surfaces in the consumer's own suite. What the consumer no longer writes is
+ * the detector, which is where the subtlety lives — the stale-opt-out half is the part everyone
+ * forgets.
+ *
+ * @public
+ */
+/** A key deliberately left off the environment, with the reason and what would reverse it. @public */
+interface EnvOptOut {
+    readonly key: string;
+    /** Why an environment variable is the wrong shape for this key. */
+    readonly reason: string;
+    /** What would make this opt-out obsolete. An opt-out with no exit is a permanent excuse. */
+    readonly exitCriterion: string;
+}
+/** @public */
+interface EnvReachabilityInput {
+    /** Every configuration key the product declares. */
+    readonly keys: readonly string[];
+    /** The subset that an environment variable can set. */
+    readonly reachable: readonly string[];
+    /** Documented exemptions for keys that deliberately have no environment path. */
+    readonly optOuts: readonly EnvOptOut[];
+}
+/** @public */
+interface EnvReachabilityAudit {
+    /** Keys with neither an environment path nor a documented opt-out. */
+    readonly unreachable: readonly string[];
+    /** Opt-outs that exempt nothing: the key gained an environment path, or no longer exists. */
+    readonly staleOptOuts: readonly string[];
+}
+/**
+ * @returns both axes, in the order the caller declared them — a stable order so a failure message
+ *   does not change between runs for reasons unrelated to the code.
+ * @public
+ */
+declare function auditEnvReachability(input: EnvReachabilityInput): EnvReachabilityAudit;
+
 /**
  * `EventBus` — typed EventEmitter wrapper.
  *
@@ -1962,6 +2019,87 @@ type MutableEnv = Record<string, string | undefined>;
  */
 declare function loadProjectEnv(env?: MutableEnv, load?: (() => void) | undefined): void;
 
+/**
+ * Decide which session artifacts may be deleted — and never delete them.
+ *
+ * This package creates session artifacts (transcripts, locks, temp files) and cleans up only what is
+ * in flight in the operation doing the cleaning: a lock it just released, a `.tmp` from a failed
+ * atomic write. Nothing collects the rest, so every consumer either writes its own collector or lets
+ * the directory grow without bound — and a hand-rolled collector on the path that deletes a user's
+ * transcript is the worst place for each product to learn the same lessons separately.
+ *
+ * ## Planning is not deleting, deliberately
+ *
+ * A function that decided AND deleted could not be tested without a filesystem, and the case that
+ * matters most — "we could not establish whether this session is live" — would have to be simulated
+ * rather than asserted. Here the decision is pure: the plan IS the dry run, and executing it is a
+ * separate act on a value someone can read first. That separation is the dry-run guarantee, rather
+ * than a flag that has to be remembered.
+ *
+ * ## The tri-state
+ *
+ * `keep`, `reap`, `undetermined`. An artifact whose liveness could not be established is never
+ * reaped and never quietly counted as dead. Collapsing "could not determine" into "not there" is how
+ * a collector deletes a session running on another machine, or behind a mount that answered slowly.
+ * The third bucket costs a branch and buys the only guarantee worth having on this path.
+ *
+ * @public
+ */
+
+/** Raised when a retention policy cannot be honoured as written. @public */
+declare class RetentionPolicyError extends TheokitAgentError {
+    readonly name = "RetentionPolicyError";
+}
+/** @public */
+interface ReapableArtifact {
+    readonly id: string;
+    /** Epoch milliseconds. Compared against an injected `nowMs`, never against a read clock. */
+    readonly lastModifiedMs: number;
+    /**
+     * Whether a writer still holds this artifact. `"unknown"` when the caller could not establish it —
+     * a stale lock behind a slow mount, a PID on another host — and it is honoured as a third answer
+     * rather than folded into `false`.
+     */
+    readonly live: boolean | "unknown";
+}
+/** @public */
+interface RetentionPolicy {
+    /** Artifacts strictly older than this are candidates. The boundary itself is kept. */
+    readonly maxAgeMs: number;
+    /**
+     * A FLOOR on how many artifacts survive: "you will always have your last N sessions". When
+     * liveness and the retention window already spare N or more, this changes nothing; when they
+     * spare fewer, the newest of the remainder are spared until the count reaches N.
+     *
+     * Undetermined artifacts do NOT count toward the floor. Their liveness was never established, so
+     * counting them would let a transient mount failure satisfy the floor with artifacts nobody
+     * confirmed exist as sessions — and quietly delete the ones that do.
+     */
+    readonly keepLast: number;
+}
+/** Why an artifact survived. @public */
+type KeepReason = "live" | "within-retention" | "keep-last";
+/** @public */
+interface KeptArtifact extends ReapableArtifact {
+    readonly reason: KeepReason;
+}
+/** @public */
+interface ReapPlan {
+    /** Safe to delete. Everything here was decided, not defaulted. */
+    readonly reap: readonly ReapableArtifact[];
+    readonly keep: readonly KeptArtifact[];
+    /** Liveness could not be established. Never deleted, never counted as kept. */
+    readonly undetermined: readonly ReapableArtifact[];
+}
+/** @public */
+interface ReapPlanInput {
+    readonly artifacts: readonly ReapableArtifact[];
+    readonly retention: RetentionPolicy;
+    /** Injected so the plan is reproducible and testable; this module never reads a clock. */
+    readonly nowMs: number;
+}
+declare function planReaping(input: ReapPlanInput): ReapPlan;
+
 /** The internal JSON-Schema shape the synthetic `output` tool consumes. */
 type NormalizedJsonSchema = Record<string, unknown>;
 /**
@@ -2835,4 +2973,4 @@ interface WiringRecordInput<K extends string> {
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, applySecurityFloor, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withCwdMutex };

package/dist/index.d.ts

@@ -1263,6 +1263,63 @@ declare class Tool {
     static create<T extends ZodType, O extends ZodType = never>(spec: DefineToolSpec<T, O>): CustomTool;
 }
 
+/**
+ * Audit whether every configuration key can be set from the environment, or says why not.
+ *
+ * A key settable only by editing a file cannot be set in CI, in a container, or for a single
+ * invocation. That is usually an oversight rather than a decision, and it is invisible — nothing
+ * fails, the key simply has no environment path, and nobody notices until someone needs one.
+ *
+ * The opposite failure rots more quietly. An opt-out written for a key that has since gained an
+ * environment path, or for a key that no longer exists, still reads as a considered decision while
+ * exempting nothing. Both questions are answered by one call so a consumer cannot check the gap and
+ * forget the rot: they fail for opposite reasons, and a suite that asks only one looks complete.
+ *
+ * ## Why the framework owns the rule and not the keys
+ *
+ * A framework cannot enumerate a consumer's configuration keys, and should not try. Which keys exist
+ * is that product's vocabulary — the same reason the security floor takes its permissiveness order
+ * as data and the trust posture takes its capability list. So the consumer ranges over its own keys
+ * with this, rather than registering them here.
+ *
+ * That is a narrower claim than "reachability is checked in the framework", and it is the honest
+ * one: the failure still surfaces in the consumer's own suite. What the consumer no longer writes is
+ * the detector, which is where the subtlety lives — the stale-opt-out half is the part everyone
+ * forgets.
+ *
+ * @public
+ */
+/** A key deliberately left off the environment, with the reason and what would reverse it. @public */
+interface EnvOptOut {
+    readonly key: string;
+    /** Why an environment variable is the wrong shape for this key. */
+    readonly reason: string;
+    /** What would make this opt-out obsolete. An opt-out with no exit is a permanent excuse. */
+    readonly exitCriterion: string;
+}
+/** @public */
+interface EnvReachabilityInput {
+    /** Every configuration key the product declares. */
+    readonly keys: readonly string[];
+    /** The subset that an environment variable can set. */
+    readonly reachable: readonly string[];
+    /** Documented exemptions for keys that deliberately have no environment path. */
+    readonly optOuts: readonly EnvOptOut[];
+}
+/** @public */
+interface EnvReachabilityAudit {
+    /** Keys with neither an environment path nor a documented opt-out. */
+    readonly unreachable: readonly string[];
+    /** Opt-outs that exempt nothing: the key gained an environment path, or no longer exists. */
+    readonly staleOptOuts: readonly string[];
+}
+/**
+ * @returns both axes, in the order the caller declared them — a stable order so a failure message
+ *   does not change between runs for reasons unrelated to the code.
+ * @public
+ */
+declare function auditEnvReachability(input: EnvReachabilityInput): EnvReachabilityAudit;
+
 /**
  * `EventBus` — typed EventEmitter wrapper.
  *
@@ -1962,6 +2019,87 @@ type MutableEnv = Record<string, string | undefined>;
  */
 declare function loadProjectEnv(env?: MutableEnv, load?: (() => void) | undefined): void;
 
+/**
+ * Decide which session artifacts may be deleted — and never delete them.
+ *
+ * This package creates session artifacts (transcripts, locks, temp files) and cleans up only what is
+ * in flight in the operation doing the cleaning: a lock it just released, a `.tmp` from a failed
+ * atomic write. Nothing collects the rest, so every consumer either writes its own collector or lets
+ * the directory grow without bound — and a hand-rolled collector on the path that deletes a user's
+ * transcript is the worst place for each product to learn the same lessons separately.
+ *
+ * ## Planning is not deleting, deliberately
+ *
+ * A function that decided AND deleted could not be tested without a filesystem, and the case that
+ * matters most — "we could not establish whether this session is live" — would have to be simulated
+ * rather than asserted. Here the decision is pure: the plan IS the dry run, and executing it is a
+ * separate act on a value someone can read first. That separation is the dry-run guarantee, rather
+ * than a flag that has to be remembered.
+ *
+ * ## The tri-state
+ *
+ * `keep`, `reap`, `undetermined`. An artifact whose liveness could not be established is never
+ * reaped and never quietly counted as dead. Collapsing "could not determine" into "not there" is how
+ * a collector deletes a session running on another machine, or behind a mount that answered slowly.
+ * The third bucket costs a branch and buys the only guarantee worth having on this path.
+ *
+ * @public
+ */
+
+/** Raised when a retention policy cannot be honoured as written. @public */
+declare class RetentionPolicyError extends TheokitAgentError {
+    readonly name = "RetentionPolicyError";
+}
+/** @public */
+interface ReapableArtifact {
+    readonly id: string;
+    /** Epoch milliseconds. Compared against an injected `nowMs`, never against a read clock. */
+    readonly lastModifiedMs: number;
+    /**
+     * Whether a writer still holds this artifact. `"unknown"` when the caller could not establish it —
+     * a stale lock behind a slow mount, a PID on another host — and it is honoured as a third answer
+     * rather than folded into `false`.
+     */
+    readonly live: boolean | "unknown";
+}
+/** @public */
+interface RetentionPolicy {
+    /** Artifacts strictly older than this are candidates. The boundary itself is kept. */
+    readonly maxAgeMs: number;
+    /**
+     * A FLOOR on how many artifacts survive: "you will always have your last N sessions". When
+     * liveness and the retention window already spare N or more, this changes nothing; when they
+     * spare fewer, the newest of the remainder are spared until the count reaches N.
+     *
+     * Undetermined artifacts do NOT count toward the floor. Their liveness was never established, so
+     * counting them would let a transient mount failure satisfy the floor with artifacts nobody
+     * confirmed exist as sessions — and quietly delete the ones that do.
+     */
+    readonly keepLast: number;
+}
+/** Why an artifact survived. @public */
+type KeepReason = "live" | "within-retention" | "keep-last";
+/** @public */
+interface KeptArtifact extends ReapableArtifact {
+    readonly reason: KeepReason;
+}
+/** @public */
+interface ReapPlan {
+    /** Safe to delete. Everything here was decided, not defaulted. */
+    readonly reap: readonly ReapableArtifact[];
+    readonly keep: readonly KeptArtifact[];
+    /** Liveness could not be established. Never deleted, never counted as kept. */
+    readonly undetermined: readonly ReapableArtifact[];
+}
+/** @public */
+interface ReapPlanInput {
+    readonly artifacts: readonly ReapableArtifact[];
+    readonly retention: RetentionPolicy;
+    /** Injected so the plan is reproducible and testable; this module never reads a clock. */
+    readonly nowMs: number;
+}
+declare function planReaping(input: ReapPlanInput): ReapPlan;
+
 /** The internal JSON-Schema shape the synthetic `output` tool consumes. */
 type NormalizedJsonSchema = Record<string, unknown>;
 /**
@@ -2835,4 +2973,4 @@ interface WiringRecordInput<K extends string> {
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, applySecurityFloor, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withCwdMutex };

package/dist/index.js

@@ -664,6 +664,17 @@ var SkillReadTool = class {
   }
 };
 
+// src/env-reachability.ts
+function auditEnvReachability(input) {
+  const reachable = new Set(input.reachable);
+  const exempt = new Set(input.optOuts.map((o) => o.key));
+  const declared = new Set(input.keys);
+  return {
+    unreachable: input.keys.filter((k) => !reachable.has(k) && !exempt.has(k)),
+    staleOptOuts: input.optOuts.filter((o) => !declared.has(o.key) || reachable.has(o.key)).map((o) => o.key)
+  };
+}
+
 // src/event-bus.ts
 var EventBus = class {
   handlers = /* @__PURE__ */ new Map();
@@ -1563,6 +1574,60 @@ function loadProjectEnv(env = process.env, load = typeof process.loadEnvFile ===
   }
 }
 
+// src/reap-plan.ts
+var RetentionPolicyError = class extends TheokitAgentError {
+  name = "RetentionPolicyError";
+};
+function assertPolicy(retention) {
+  const { maxAgeMs, keepLast } = retention;
+  if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0) {
+    throw new RetentionPolicyError(
+      `retention.maxAgeMs must be a non-negative number of milliseconds, got ${String(maxAgeMs)}`
+    );
+  }
+  if (!Number.isInteger(keepLast) || keepLast < 0) {
+    throw new RetentionPolicyError(
+      `retention.keepLast must be a non-negative integer, got ${String(keepLast)}`
+    );
+  }
+}
+function classifyByOwnReason(input) {
+  const keep = [];
+  const atRisk = [];
+  for (const artifact of input.artifacts) {
+    if (artifact.live === "unknown") continue;
+    if (artifact.live === true) {
+      keep.push({ ...artifact, reason: "live" });
+      continue;
+    }
+    if (input.nowMs - artifact.lastModifiedMs <= input.retention.maxAgeMs) {
+      keep.push({ ...artifact, reason: "within-retention" });
+      continue;
+    }
+    atRisk.push(artifact);
+  }
+  return { keep, atRisk };
+}
+function applyFloor(kept, atRisk, keepLast) {
+  const shortfall = Math.max(0, keepLast - kept.length);
+  const newestFirst = [...atRisk].sort((a, b) => b.lastModifiedMs - a.lastModifiedMs);
+  const spared = new Set(newestFirst.slice(0, shortfall).map((a) => a.id));
+  const rescued = [];
+  const reap = [];
+  for (const artifact of atRisk) {
+    if (spared.has(artifact.id)) rescued.push({ ...artifact, reason: "keep-last" });
+    else reap.push(artifact);
+  }
+  return { rescued, reap };
+}
+function planReaping(input) {
+  assertPolicy(input.retention);
+  const undetermined = input.artifacts.filter((a) => a.live === "unknown");
+  const { keep, atRisk } = classifyByOwnReason(input);
+  const { rescued, reap } = applyFloor(keep, atRisk, input.retention.keepLast);
+  return { reap, keep: [...keep, ...rescued], undetermined };
+}
+
 // src/schema-normalizer.ts
 function isJsonSchemaObject(s) {
   if (typeof s !== "object" || s === null) return false;
@@ -2223,6 +2288,6 @@ function recordWiring(input) {
   return record;
 }
 
-export { AgentFactory, Budget, EventBus, JobQueue, LayerOrderError, Memory, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, SOVEREIGN_ENV_KEYS, Security, Skill, SkillReadTool, Squad, Task, Theokit, TokenLimiter, UngatedCapabilityError, UnicodeNormalizer, applyMode, applySecurityFloor, chargeAndCheckThresholds, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, inferApiMode, loadProjectEnv, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, verifyLayerOrdering };
+export { AgentFactory, Budget, EventBus, JobQueue, LayerOrderError, Memory, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, RetentionPolicyError, SOVEREIGN_ENV_KEYS, Security, Skill, SkillReadTool, Squad, Task, Theokit, TokenLimiter, UngatedCapabilityError, UnicodeNormalizer, applyMode, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, inferApiMode, loadProjectEnv, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, verifyLayerOrdering };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map