@diegopetrucci/pi-extensions 0.1.61 → 0.1.63

package/extensions/dynamic-context-pruning/index.ts

@@ -165,10 +165,16 @@ export interface PruneProtections {
 
 export interface PruneThresholds {
 	/**
-	 * Minimum characters a prune must remove to be worth persisting. Reserved
-	 * for a future minimum-size filter; NOT used by the net-benefit gate
-	 * (see `PruneGateConfig`/`gate`), which uses break-even token math instead.
-	 * Not enforced by this pipeline yet.
+	 * Minimum raw text characters a fresh AUTOMATIC prune proposal must remove
+	 * (original text chars minus placeholder chars) to be considered at all
+	 * (pe-qdzb). Enforced by `runDynamicContextPruningPipeline` BEFORE the
+	 * net-benefit gate (see `PruneGateConfig`/`gate`, which uses break-even token
+	 * math and is a separate, later check): text-only candidates below this floor
+	 * are dropped up front and never reach gate/batch consideration. Image-bearing
+	 * tool-result candidates bypass this raw-text floor (images receive no
+	 * synthetic character count) and proceed to the token-based gate. Manual
+	 * prunes and already-persisted/replayed decisions always bypass this floor,
+	 * same as the gate. A value of 0 disables the floor (no filtering).
 	 */
 	minCharsSaved: number;
 }
@@ -194,19 +200,42 @@ export type GateMode = "on" | "off" | "always-apply";
  * making tool calls) vs idle (waiting on the user). Both states default to
  * the same threshold today.
  *
- * pe-c5n9 evidence update: the representative-corpus benchmark shows
- * mid_loop candidates carry ~all realized net benefit while idle candidates
- * carry ~none (literally 0 at r=0.1). That would argue for a stricter idle
- * default. However, the only live runtime caller (the `context` event
- * handler below) does not yet perform real mid-loop/idle detection — it
- * always passes agentState:"idle". Defaulting idle to a much stricter
- * threshold today would therefore silently disable most automatic pruning
- * for everyone (100% of live evaluations run as "idle"), which is a far
- * bigger behavior change than a threshold recalibration. So the per-state
- * split is intentionally left at parity for now; a follow-up ticket should
- * wire real agent-state detection through `ctx` and then apply the
- * idle-vs-mid_loop split (idle stricter, mid_loop at DEFAULT_BREAK_EVEN_THRESHOLD)
- * once mid_loop is actually reachable.
+ * pe-c5n9 evidence (turn-END definition, since superseded -- see below):
+ * the representative-corpus benchmark showed mid_loop candidates carrying
+ * ~all realized net benefit while idle candidates carried ~none. That would
+ * have argued for a stricter idle default. However, the only live runtime
+ * caller (the `context` event handler below) did not yet perform real
+ * mid-loop/idle detection at the time, so no default change was made.
+ *
+ * pe-zy4s update (2026-07-08): real runtime mid_loop/idle detection is now
+ * wired through the `context` event handler (`classifyAgentStateFromMessages`),
+ * using a turn-START definition (idle = this is the first LLM call of a turn;
+ * mid_loop = the agent already made a call or received a tool result this
+ * turn) -- see that function's doc comment for the exact runtime-observable
+ * semantics. The benchmark's candidate labeling was aligned to this SAME
+ * definition (retiring the old turn-END definition above, which was never
+ * runtime-observable), and the state-split was re-derived on the
+ * representative corpus (~/.the-last-harness/agent/sessions, 460 candidates)
+ * under it.
+ *
+ * The result REVERSES the earlier (turn-END) finding: at r=0.1 the
+ * turn-START "idle" population (calls made at the start of a turn) carries
+ * essentially ALL the realized net benefit (idle-optimal T=22, total realized
+ * net benefit ~20,594 token-units), while "mid_loop" carries essentially NONE
+ * (mid_loop-optimal T=1, total realized net benefit ~0.0 -- i.e. no mid_loop
+ * candidate is ever worth accepting at r=0.1 under this definition). This is
+ * the OPPOSITE of what the pe-c5n9 evidence (measured under the old,
+ * non-runtime-observable turn-END definition) suggested.
+ *
+ * Per the pe-zy4s decision rule (stricter idle default only if idle itself is
+ * shown to be ~worthless): idle is NOT worthless here -- it is the ONLY state
+ * carrying value at r=0.1 -- so no state-conditioned strictness is justified
+ * in either direction. The per-state split is therefore kept at PARITY
+ * (`breakEvenThresholdByState: { idle: DEFAULT_BREAK_EVEN_THRESHOLD, mid_loop:
+ * DEFAULT_BREAK_EVEN_THRESHOLD }`), both config-overridable. A future ticket
+ * could consider a stricter mid_loop default given this evidence, but that is
+ * a new, unreviewed direction outside this ticket's authorized decision rule
+ * and is left for a follow-up.
  */
 export type AgentState = "idle" | "mid_loop";
 
@@ -397,6 +426,41 @@ export function estimateTokensForContent(content: string | (MinimalTextContent |
 
 export type TokenEstimator = (text: string) => number;
 
+/**
+ * Classify the agent's current state from the message payload alone (pe-zy4s):
+ * this is the runtime-observable definition used both by the live `context`
+ * event handler and (via re-export) by the offline benchmark, so the two can
+ * never drift apart.
+ *
+ * Walk backwards from the end of `messages`, skipping any message that is
+ * neither `user`, `assistant`, nor `toolResult` (e.g. system-role bookkeeping
+ * entries). The first such message found determines the state:
+ *  - `user` (a plain user turn message) => "idle": this call is the FIRST LLM
+ *    call of a turn, i.e. the decision is being made from a turn-start state.
+ *  - `assistant` or `toolResult` (mid-chain) => "mid_loop": the agent is
+ *    iterating (already made at least one call this turn, or is reacting to a
+ *    tool result).
+ *  - No such message found (empty history, or system-only) => "idle" (safe
+ *    default: nothing suggests an in-progress loop).
+ *
+ * The benchmark (scripts/benchmark.mjs) reclassifies its candidate labels to
+ * this SAME definition (pe-zy4s), reusing this function directly, so the
+ * defaults below rest on evidence measured with the exact definition the
+ * runtime observes. (An earlier turn-end-based benchmark definition -- "idle"
+ * meant "this IS the turn's last assistant message", only knowable in
+ * hindsight -- has been retired: the runtime cannot know in advance whether a
+ * call is a turn's last one, so that definition was never runtime-observable.)
+ */
+export function classifyAgentStateFromMessages(messages: MinimalMessage[]): AgentState {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const role = messages[i].role;
+		if (role === "user") return "idle";
+		if (role === "assistant" || role === "toolResult") return "mid_loop";
+		// Any other role (e.g. "system") is skipped: keep walking further back.
+	}
+	return "idle";
+}
+
 /** Resolve which break-even threshold applies for a given agent state (pe-s2ho state-conditioning hook). */
 export function resolveBreakEvenThreshold(gateConfig: PruneGateConfig, agentState: AgentState): number {
 	const override = gateConfig.breakEvenThresholdByState[agentState];
@@ -892,6 +956,20 @@ function contentTextLength(content: (MinimalTextContent | MinimalImageContent)[]
 	return content.reduce((sum, block) => (block.type === "text" ? sum + block.text.length : sum), 0);
 }
 
+/** Return true when a decision targets a tool result containing one or more images. */
+function isImageBearingToolResultTarget(
+	messages: MinimalMessage[],
+	decision: PruneDecisionRecord,
+	pairIndex?: Map<string, ToolCallPairIndices>,
+): boolean {
+	if (decision.kind !== "tool_result_content" || decision.correlation.type !== "toolCallId") return false;
+	const pair = findToolCallPairIndices(messages, decision.correlation.toolCallId, pairIndex);
+	if (pair.resultIndex === undefined) return false;
+	const target = messages[pair.resultIndex];
+	if (target?.role !== "toolResult") return false;
+	return (target as MinimalToolResultMessage).content.some((block) => block.type === "image");
+}
+
 export interface ApplyResult {
 	applied: boolean;
 	charsRemoved: number;
@@ -1050,6 +1128,55 @@ export function estimateDecisionSavings(
 	return undefined;
 }
 
+/**
+ * Estimate the character savings of a single decision (pe-qdzb), i.e. the
+ * same before/after delta basis as `estimateDecisionSavings` but measured in
+ * raw characters rather than estimated tokens. Used by the pipeline to
+ * enforce `thresholds.minCharsSaved` against fresh automatic proposals
+ * *before* they reach the net-benefit gate. Returns undefined under the same
+ * conditions as `estimateDecisionSavings` (target absent / would not apply).
+ * Mirrors `estimateDecisionSavings`'s `Math.max(0, ...)` clamp, so a
+ * decision whose placeholder text would be LONGER than the original content
+ * (negative savings) is reported as 0 chars saved, not a negative number.
+ */
+export function estimateDecisionCharsSaved(
+	messages: MinimalMessage[],
+	decision: PruneDecisionRecord,
+	pairIndex?: Map<string, ToolCallPairIndices>,
+): number | undefined {
+	if (decision.correlation.type !== "toolCallId") return undefined;
+	const pair = findToolCallPairIndices(messages, decision.correlation.toolCallId, pairIndex);
+
+	// Same non-mutating preview approach as `estimateDecisionSavings`.
+	const preview = messages.slice();
+	const result = applyPruneDecision(preview, decision, pairIndex);
+	if (!result.applied) return undefined;
+
+	if (decision.kind === "tool_result_content") {
+		if (pair.resultIndex === undefined) return undefined;
+		const before = messages[pair.resultIndex] as MinimalToolResultMessage;
+		const after = preview[pair.resultIndex] as MinimalToolResultMessage;
+		const charsBefore = contentTextLength(before.content);
+		const charsAfter = contentTextLength(after.content);
+		return Math.max(0, charsBefore - charsAfter);
+	}
+
+	if (decision.kind === "tool_call_input") {
+		if (pair.assistantIndex === undefined || pair.toolCallBlockIndex === undefined) return undefined;
+		const beforeBlock = (messages[pair.assistantIndex] as MinimalAssistantMessage).content[
+			pair.toolCallBlockIndex
+		] as MinimalToolCallContent;
+		const afterBlock = (preview[pair.assistantIndex] as MinimalAssistantMessage).content[
+			pair.toolCallBlockIndex
+		] as MinimalToolCallContent;
+		const charsBefore = JSON.stringify(beforeBlock.arguments ?? {}).length;
+		const charsAfter = JSON.stringify(afterBlock.arguments ?? {}).length;
+		return Math.max(0, charsBefore - charsAfter);
+	}
+
+	return undefined;
+}
+
 /**
  * Cache-aware cost model (pe-s2ho ticket NOTES, binding over the looser prose
  * in the ticket body): prompt caches are prefix-based, so pruning at message
@@ -1877,7 +2004,29 @@ export function runDynamicContextPruningPipeline(input: PipelineInput): Pipeline
 	// against the pre-mutation `messages` clone, before the apply loop below
 	// mutates anything.
 	const freshManual = dedupedFresh.filter((decision) => decision.source === "manual");
-	const freshAutomatic = dedupedFresh.filter((decision) => decision.source !== "manual");
+	const freshAutomaticUnfiltered = dedupedFresh.filter((decision) => decision.source !== "manual");
+
+	// Minimum-size floor (pe-qdzb): drop fresh automatic proposals whose
+	// character savings (original content chars minus placeholder chars) fall
+	// below `thresholds.minCharsSaved`, BEFORE gate evaluation so dropped
+	// candidates never consume batch/earliest-position gate consideration.
+	// Applies to automatic proposals only; manual (`freshManual` above) and
+	// already-persisted decisions (`input.persistedDecisions`, applied later)
+	// bypass this floor entirely, same as the net-benefit gate. Tool-result
+	// candidates containing images also bypass this raw-text floor because
+	// images have no character count; their token savings still go through the
+	// existing net-benefit gate. A floor of 0 (the config default before
+	// pe-c5n9's DEFAULT_MIN_CHARS_SAVED constant was introduced) is a no-op:
+	// every non-negative delta clears it.
+	const minCharsSaved = input.config.thresholds.minCharsSaved;
+	const freshAutomatic =
+		minCharsSaved <= 0
+			? freshAutomaticUnfiltered
+			: freshAutomaticUnfiltered.filter((decision) => {
+					if (isImageBearingToolResultTarget(messages, decision, pairIndex)) return true;
+					const charsSaved = estimateDecisionCharsSaved(messages, decision, pairIndex);
+					return charsSaved !== undefined && charsSaved >= minCharsSaved;
+				});
 
 	// Collapse fresh AUTOMATIC candidates that target the same (kind,
 	// correlation) down to a single decision (pe-j7sb). Two strategies (e.g.
@@ -2360,9 +2509,10 @@ export default function dynamicContextPruningExtension(pi: ExtensionAPI) {
 			persistedDecisions,
 			knownIdempotencyKeys,
 			restoredIdempotencyKeys,
-			// Real mid-loop/idle agent-state detection lands in a follow-up ticket;
-			// "idle" is the safe default until it's wired through ctx.
-			agentState: "idle",
+			// Real mid-loop/idle agent-state detection (pe-zy4s): derived straight from
+			// the message payload via classifyAgentStateFromMessages -- see its doc
+			// comment for the exact runtime-observable definition.
+			agentState: classifyAgentStateFromMessages(event.messages as unknown as MinimalMessage[]),
 			cwd: ctx.sessionManager.getCwd(),
 		});
 

package/extensions/dynamic-context-pruning/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-dynamic-context-pruning",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "A pi extension that dynamically prunes stale context to keep sessions lean.",
   "keywords": [

package/extensions/fast/.pi-fleet-tested-version

@@ -0,0 +1 @@
+0.83.0

package/extensions/fast/README.md

@@ -0,0 +1,119 @@
+# fast
+
+A pi extension that provides one `/fast` toggle for supported OpenAI Codex and Anthropic Claude models. It selects the provider-specific Fast-mode request shape from the currently selected model.
+
+For eligible OpenAI Codex models it injects:
+
+```json
+{
+  "service_tier": "priority"
+}
+```
+
+For eligible Anthropic Claude models it injects:
+
+```json
+{
+  "speed": "fast"
+}
+```
+
+It also adds the required Anthropic beta header value:
+
+```text
+anthropic-beta: fast-mode-2026-02-01
+```
+
+## Eligibility
+
+OpenAI Fast mode requires all of the following:
+
+- Provider `openai-codex`.
+- API `openai-codex-responses`.
+- Model `gpt-5.4`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, or `gpt-5.6-luna`.
+- ChatGPT OAuth/subscription auth, not API-key auth.
+- No existing `service_tier` field in the request payload.
+
+Anthropic Fast mode requires all of the following:
+
+- Provider `anthropic`.
+- API `anthropic-messages`.
+- Model `claude-opus-4-6`, `claude-opus-4-7`, or `claude-opus-4-8`.
+- No existing `speed` field in the request payload.
+
+Anthropic Fast mode supports both API-key and Claude Code OAuth access when the account has access to the research preview.
+
+## Commands
+
+```text
+/fast
+```
+
+Run `/fast` to toggle Fast mode for the current session/runtime. The enabled state follows model changes: switching between eligible OpenAI and Anthropic models automatically changes the request format without resetting the toggle. The footer shows `fast` only while the selected model is eligible and Fast mode is enabled.
+
+The extension defaults to off so installing the full collection does not accidentally spend Fast-mode credits.
+
+## Config
+
+Optional global config:
+
+```text
+~/<pi-config-dir>/agent/extensions/fast.json
+```
+
+Optional project config:
+
+```text
+<project>/<pi-config-dir>/fast.json
+```
+
+Here `<pi-config-dir>` is Pi's runtime config directory name (`CONFIG_DIR_NAME`; `.pi` by default). Project config overrides global config after Pi reports that the project is trusted.
+
+```json
+{
+  "enabled": false,
+  "showStatus": true
+}
+```
+
+- `enabled`: default Fast-mode state when there is no session override.
+- `showStatus`: show a compact `fast` status when Fast mode is active for the selected model.
+
+The unified extension intentionally does not read `openai-fast.json` or `claude-fast.json`; those files belong to the provider-specific standalone packages and may contain conflicting defaults.
+
+## Install
+
+### Standalone npm package
+
+```bash
+pi install npm:@diegopetrucci/pi-fast
+```
+
+### Collection package
+
+```bash
+pi install npm:@diegopetrucci/pi-extensions
+```
+
+### GitHub package
+
+```bash
+pi install git:github.com/diegopetrucci/pi-extensions
+```
+
+Then reload pi:
+
+```text
+/reload
+```
+
+## Legacy provider-specific packages
+
+The collection package loads this unified extension instead of `openai-fast` and `claude-fast`. Both provider-specific packages remain available as standalone alternatives. Do not load them together with this extension: independent Fast-mode state and duplicate `/fast` registrations can produce conflicting behavior.
+
+## Notes
+
+- Anthropic Fast mode has separate rate limits, costs more than standard speed, and does not share prompt-cache prefixes with standard-speed requests.
+- OpenAI Fast mode intentionally does not affect API-key models.
+- Existing `speed` and `service_tier` fields are never overwritten.
+- Cost accounting still depends on the provider reporting the effective tier in its streamed response.

package/extensions/fast/fast.example.json

@@ -0,0 +1,4 @@
+{
+  "enabled": false,
+  "showStatus": true
+}