@caupulican/pi-adaptative 0.80.75 → 0.80.76

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.80.76] - 2026-06-28
+
+### Added
+
+- Proactive per-turn cost guard (opt-in): set `costGuard.maxTurnUsd` to estimate the dollar cost of each
+  turn before it is submitted and, when it exceeds the ceiling, surface a warning or (with
+  `costGuard.action: "downgrade"`) automatically step reasoning effort down once to curb a runaway
+  billing spike. Disabled by default.
+
+### Changed
+
+- Background reflection now uses a static system prompt with the variable memory/turn content moved to the
+  user message, so repeated reflection passes reuse the provider prompt-cache prefix instead of re-billing
+  it — and added guidance to avoid persisting transient/environment-specific noise as memory.
+
 ## [0.80.75] - 2026-06-28
 
 ### Changed

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

@@ -13,10 +13,11 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "@caupulican/pi-agent-core";
-import type { ImageContent, Message, Model, StopReason, TextContent, Usage } from "@caupulican/pi-ai";
+import type { CacheRetention, ImageContent, Message, Model, StopReason, TextContent, Usage } from "@caupulican/pi-ai";
 import { type BashResult } from "./bash-executor.ts";
 import { type CompactionResult } from "./compaction/index.ts";
 import { type ContextGcReport } from "./context-gc.ts";
+import { type CostGuardDecision } from "./cost-guard.ts";
 import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionContext, type ExtensionErrorListener, ExtensionRunner, type ExtensionUIContext, type InputSource, type ReplacedSessionContext, type SessionStartEvent, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.ts";
 import { type ChannelProvider, GatewayRegistry, type JobSchedulerProvider } from "./gateways/channel-provider.ts";
 import { type DemandSignals, type ReflectionResult } from "./learning/reflection-engine.ts";
@@ -225,6 +226,12 @@ export interface IsolatedCompletionOptions {
     maxTokens?: number;
     /** Abort signal. */
     signal?: AbortSignal;
+    /**
+     * Prompt-cache retention for this isolated call. Defaults to `"none"` (no caching — preserves full
+     * isolation). Callers whose `systemPrompt` is STATIC across calls (e.g. reflection, #33) can pass
+     * `"short"`/`"long"` so the provider reuses the cached prefix and bills only the variable tail.
+     */
+    cacheRetention?: CacheRetention;
 }
 /** Result of an isolated completion: the text, the usage spent, and the stop reason. */
 export interface IsolatedCompletionResult {
@@ -281,6 +288,10 @@ export declare class AgentSession {
     private readonly _gatewayRegistry;
     /** Cache for getSpawnedUsage(), keyed by session entry count (Bug #22 — avoid O(N) per render frame). */
     private _spawnedUsageCache?;
+    /** Latest proactive cost-guard decision (#34), for the host UI to surface. Undefined when disabled. */
+    private _lastCostGuardDecision?;
+    /** One-shot latch so the cost guard downgrades reasoning once per over-threshold episode, not every call. */
+    private _costGuardDowngraded;
     /** Set on dispose so in-flight background reflection bails instead of writing to a dead session (Bug #21). */
     private _disposed;
     /** Aborts in-flight background reflection completions on dispose (Bug #21). */
@@ -328,6 +339,16 @@ export declare class AgentSession {
      * happens here instead of in wrappers.
      */
     private _installAgentContextTransform;
+    /**
+     * Proactive per-turn cost guard (#34): estimate the USD cost of the about-to-be-submitted turn and,
+     * when it exceeds the user's ceiling, record a warning decision (for the host UI to surface) and —
+     * if configured to `downgrade` — step reasoning effort down ONCE per over-threshold episode to curb a
+     * runaway billing spike. Disabled by default (`maxTurnUsd<=0`), so it never alters behavior unless the
+     * user opts in. Best-effort: never throws into the turn.
+     */
+    private _applyCostGuard;
+    /** Latest cost-guard decision (for the host footer/UI to surface a warning). Undefined if disabled. */
+    getLastCostGuardDecision(): CostGuardDecision | undefined;
     private _installAgentTurnRefresh;
     private _createAgentContextSnapshot;
     private _contextGcStorageDir;