pi-shake 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 K2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# pi-shake, the `/shake` extension for Pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Fold heavy context out of the model's view; undo restores every byte.
+
+`/shake` shortens old tool output, fenced code blocks, top-level XML blocks,
+images, and assistant reasoning into brief placeholders in the model's
+context. Everything stays in the session file: fold works through pi's
+`context_edit` overlays, so nothing is ever deleted and fold is always
+reversible.
+
+## Features
+
+- One command family for the three kinds of bulk: `elide` (default), `images`,
+  `thinking`
+- Undo restores everything that was folded
+- Dry-run previews a fold without applying it
+- A protected recent tail keeps the working set intact; three profiles tune it
+
+## Quick start
+
+```bash
+just install        # copies the extension into ~/.pi/agent/extensions/shake/
+```
+
+Run `/reload` in a session (or restart Pi), then:
+
+```
+/shake              # fold old tool results and fenced/XML blocks
+/shake status       # what is folded, profile, context usage
+/shake undo         # restore everything
+```
+
+Installation via the pi package manager and from git is planned.
+
+## Usage
+
+| Command | What it does |
+|---|---|
+| `/shake` | Fold tool results and fenced/XML blocks (also written `/shake elide`) |
+| `/shake images` | Remove all images from the session |
+| `/shake thinking` | Remove all assistant reasoning blocks |
+| `/shake dry-run [elide\|thinking\|images]` | Preview what that scope would do, without doing it |
+| `/shake undo` | Restore everything |
+| `/shake profile` | Choose a profile: default / conservative / aggressive |
+| `/shake status` | Current fold count, profile, context usage, last run |
+
+Fenced blocks are the sections between three backticks or three tildes
+(```` ``` ```` / `~~~`); XML blocks are top-level spans such as
+`<output>...</output>`.
+
+## Safety
+
+- Does not run while the agent is streaming.
+- The most recent ~4,000 tokens stay untouched (2,000 with `aggressive`,
+  8,000 with `conservative`).
+- Already-folded entries are left alone.
+- Entries summarized away by `/compact` are left alone.
+- Tool results from `skill` tools are left alone.
+
+## Profiles
+
+The profile steers elide's two thresholds: the protected tail and the minimum
+size of a fenced/XML block worth folding. `images` and `thinking` are not
+affected.
+
+| Profile | Protected tail | Block minimum |
+|---|---|---|
+| `default` | 4,000 tokens | ~400 tokens |
+| `conservative` | 8,000 tokens | ~800 tokens |
+| `aggressive` | 2,000 tokens | ~200 tokens |
+
+Set it with `/shake profile` (writes `shake.profile` to `.pi/settings.json`
+if present, otherwise `~/.pi/agent/settings.json`) or by editing that file.
+Resolution: project settings > agent-directory settings > `default`.
+
+## Design
+
+The reasoning behind the design (overlays, thresholds, compaction ordering,
+caching, and fork/rewind behavior) is in
+[How `/shake` works](docs/explanation.md).

package/docs/explanation.md

@@ -0,0 +1,210 @@
+# How `/shake` works
+
+Why the extension is built the way it is, and what each design choice trades
+off.
+
+## Why overlays instead of rewrites
+
+In OMP, `/shake` rewrites the transcript file in place: it deletes the
+folded content, offloads the originals to a recovery artifact, rebuilds the
+session context, and tears down provider sessions that cache message
+identity. Fold becomes destructive and expensive, and undo is hard.
+
+Pi sessions are append-only. The equivalent of a rewrite is the
+`context_edit` entry, which pi itself uses for overflow recovery:
+
+```ts
+{ type: "context_edit", targetId, replacement: { content } | null }
+```
+
+The session file is the transcript; it is never touched. What the model
+sees on each request is a **projection**: the stored entries after every
+overlay is applied. For any entry, the most recent overlay wins. A fold is
+therefore not an edit of the file, it is one more overlay stacked on top.
+
+## The placeholders
+
+A folded block becomes a short text replacement such as
+`[bash output omitted (~9,045 tokens)]`.
+
+## The two thresholds and why only elide has them
+
+Fold has two thresholds, steered by three profiles:
+
+| Profile | Tail | Block minimum |
+|---|---|---|
+| default | 4,000 tokens | ~400 tokens |
+| conservative | 8,000 tokens | ~800 tokens |
+| aggressive | 2,000 tokens | ~200 tokens |
+
+- The **tail** is measured from the newest entry backward. Whatever falls
+  inside it is the model's working set, often the exact tool output it is
+  reasoning with, so it stays untouched. The tail advances as the
+  conversation grows: each new turn pushes the boundary forward and exposes
+  the entries above it to the next fold. Already-folded entries are skipped,
+  so a fold never re-does work.
+- The **block minimum** applies to fenced blocks (the sections between three
+  backticks or three tildes inside a message) and top-level XML spans. Only
+  blocks large enough to be worth it are folded; medium-sized ones may still
+  be load-bearing.
+
+`images` and `thinking` are all-or-nothing, with no tail and no minimum:
+
+- **Thinking has little downstream value.** A reasoning block's main job is
+  producing the answer that follows it. Once the answer lands, recent
+  reasoning is near disposable as old reasoning: the model mostly
+  continues the next turns from conclusions, not chains.
+- **Images are priced high and used once.** Each image costs roughly 1,200
+  tokens by pi's estimator, and a screenshot is either the thing being worked
+  on or dead weight. You run `/shake images` as a purge after the fact.
+
+## The wall: what a fold tracks
+
+Every run appends a **log entry to the session file**: a custom entry of type
+`shake` (context-invisible, never sent to the model) listing the targets it
+folded. From these logs the extension derives two things:
+
+- **The wall** is the set of entries currently folded. Chronological, last
+  operation wins: shake adds, undo removes. It counts entries, never raw
+  `context_edit` rows, because the file accumulates superseded overlays and
+  pi's own overflow-recovery omissions. Counting rows instead of entries
+  produced phantom numbers early on.
+- **The skip-set** is which targets a shake must skip as of now, so the fold
+  frontier is monotonic: entries restored and re-folded are folded once, and
+  a repeat shake with nothing new appends zero edits.
+
+`/shake status` reads the wall; `/shake undo` reads the same logs to decide
+what to restore.
+
+## Compaction ordering: compact first, shake second
+
+`/compact` squeezes old messages into one summary and stops showing the
+model the originals. The summary is written from what the model currently
+sees (the folded view), and it becomes the model's permanent memory of that
+period: later compactions build on earlier summaries, so that memory is
+carried forward.
+
+That makes the order of operations matter. If you shake first and compact
+second, the summarizer reads placeholders like
+`[bash output omitted (~9,000 tokens)]` and can only record "outputs were
+omitted". The full text is still in the file, but the model only reads the
+summary now, so that content is gone from its memory, permanently.
+
+If you compact first and shake second, the summary is written from the full
+text and nothing is lost. The raw text that compaction stopped showing is
+now dead weight: shaking it afterwards folds it away with no loss to
+anything the model can still see.
+
+So the rule: compact while the content is still visible, then shake the
+leftovers. When compacting, pick a cheap compaction model, then `/shake
+undo`, then `/compact`; in the turns after that, `/shake` again.
+
+After a compaction, entries before the summary's `firstKeptEntryId` are no
+longer projected, so all three scopes skip them. Edits there would be inert
+and would inflate the counts dry-run and notifications report.
+
+## Caching economics
+
+Every turn, pi sends the whole conversation to the provider, and providers
+discount the part of the prompt that is byte-identical to the previous
+request: the unchanged prefix is served from cache at a lower price. The
+moment any byte in the middle differs, everything from that byte to the end
+must be re-encoded at full price, and the cache re-warms from there.
+
+That is where a fold's cost lands. A fold edits an old entry in the middle
+of the conversation, so the request right after the fold re-encodes from
+that entry to the end: one full-price turn. Then the conversation is stable
+again, and every later turn reads cache at the smaller size. One cold
+request per fold that applied, and it typically pays for itself within a
+few turns.
+
+The same applies to the other mutations: an undo or a compact also changes
+the middle of the conversation, so each costs its own single cold request.
+A no-op fold changes nothing and costs nothing; `/shake status` only reads;
+ordinary turns keep the prefix warm.
+
+Fork and rewind change the conversation too, so the first request after
+them is cold regardless of shake. Shaking before that first request means
+the cold re-encode happens once, not twice.
+
+## Lifecycle: folds across fork, rewind, import
+
+The session file keeps the whole conversation history, and that history is
+a tree: forking or rewinding creates new branches from a chosen point. A
+fold is just two things in that history, a placeholder entry and a log
+entry saying what was folded, both sitting on the branch where the shake
+ran. To pi they are ordinary history, so session operations handle them
+exactly like any other entry:
+
+| Operation | What happens to the folds |
+|---|---|
+| `/fork` at the current state | They are copied with the rest of the file. `/shake undo` and `/shake status` still work in the new file. |
+| `/fork` at an earlier message | Everything after that message is left behind, folds included. The new file starts from raw, unshaken context. |
+| `/tree` rewind | The conversation moves back to an earlier message, and the folds that came after it are simply not shown anymore: the raw text is back. The fold data stays in the file under the old branch; switch back and the folds return. |
+| Export / import | The whole file is copied verbatim, folds included. |
+
+Two things follow from folds being ordinary history. First, no orphaned
+overlays: pi copies or drops whole subtrees, so a fold and the entry it
+overlays always travel together. Second, a rewound timeline shows raw
+content by construction, because the timeline you rewind to never made the
+fold decision in the first place. Nothing has to be restored or cleaned
+up. The `session-manager` test suite verifies this: it projects the same
+session at an earlier leaf and checks that the raw text returns.
+
+## Why undo is all-or-nothing
+
+Undo restores every folded entry at once. Scoped undo (restoring one entry
+or a few) was considered and deliberately left out, for three reasons.
+
+First, it would save nothing. Restoring any entry changes bytes in the
+middle of the conversation, and the cache re-encodes everything from that
+point to the end. Restoring one entry costs the same single cold request
+as restoring all of them.
+
+Second, the real use cases are all-or-nothing anyway: before a compaction
+you want the full text back so the summary is written from real content,
+and after a fold that was too aggressive you want everything back at once.
+
+Third, when a single entry matters, undo is the wrong tool. A fold never
+deletes anything: the full original text is still stored in the session
+file, and the model can re-read it from there with the `read` tool.
+
+Undo is idempotent: a repeat `/shake undo` is a no-op.
+
+## What the dry-run is for
+
+`/shake dry-run` opens a scope popup (elide / thinking / images) and prints
+what that scope would fold, in the same wording as the real run, prefixed
+with `[dry-run]`:
+
+```
+[dry-run] · Shook 46 tool results (~7,215 tokens). Protects the last 2,000 tokens. Profile: aggressive (settings.json (agent-directory)).
+```
+
+It costs nothing (no edits are applied, so there is no cache miss) and it
+answers the question before you commit to a re-warm: how much would this
+scope actually reclaim, and is the one-time re-encode worth it. That matters
+most for `thinking`, which can strip tens of thousands of tokens in one
+strike. The explicit form `/shake dry-run thinking` skips the popup.
+
+## The rejected alternative
+
+There was a second way shake could have been built, and it was considered
+and rejected. Pi lets an extension register a `context` event that rewrites
+the message list handed to the model on each request, restoring the list
+afterward. A shake built on that would hide heavy content without ever
+touching the session file: no overlays, no undo needed, since nothing was
+changed.
+
+It was rejected because the hiding is request-local and ephemeral. The
+folded state lives in the extension's own code, not in the session: the
+moment the event stops running the content is back, and rewinding the tree
+or exporting the session shows the full raw text, because no fold was ever
+recorded. There is also nothing to undo, in the file's sense, since the
+file never changed.
+
+The chosen approach, `context_edit` overlays, persists instead: the folds
+are entries in the session file, they survive rewind and travel with
+exports, and `/shake undo` restores real stored content byte for byte. It
+also routes through the same mechanism pi itself uses for overflow
+recovery, so pi's own machinery already knows how to project it.

package/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { createShakeCommandSpec } from './src/cli.ts';
+
+export default function shakeExtension(pi: ExtensionAPI): void {
+	pi.registerCommand('shake', createShakeCommandSpec(pi));
+}

package/package.json

@@ -1,6 +1,22 @@
 {
-  "name": "pi-shake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+	"name": "pi-shake",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Elide heavy context (tool results, large blocks, images, thinking) via pi context_edit overlays",
+	"keywords": ["pi-package"],
+	"pi": {
+		"extensions": ["./index.ts"]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"files": ["index.ts", "src", "docs", "README.md"],
+	"license": "MIT",
+	"devDependencies": {
+		"fast-check": "^4.10.2",
+		"oxfmt": "0.71.0",
+		"oxlint": "1.86.0",
+		"publint": "^0.3.25",
+		"typescript": "7.0.2"
+	}
 }

package/src/cli.ts

@@ -0,0 +1,358 @@
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { LOG_TYPE, MODES, PROFILES, SCOPE_NAMES, CHARS_PER_TOKEN } from './constants.ts';
+import type { Mode, ProfileName, ScopeName } from './constants.ts';
+import {
+	activeEditTargets,
+	describePlan,
+	planElide,
+	planImages,
+	planThinking,
+	rawContent,
+	shakeLogs,
+	shakeWall,
+} from './plans.ts';
+import { resolveProfileFromFiles, writeProfileToSettings } from './settings.ts';
+import type { Entry, PlanEdit } from './types.ts';
+
+interface SessionManagerWithEdits {
+	appendContextEdit(targetId: string, replacement: { content: unknown } | null): string;
+}
+
+export interface ShakeLog {
+	action: string;
+	mode?: string;
+	targets?: string[];
+	freed?: number;
+}
+
+type ShakeCommand =
+	| {
+			mode: 'elide' | Mode;
+			dryRun: boolean;
+			allScopes?: boolean;
+	  }
+	| string;
+
+function parseRequest(args: string): ShakeCommand {
+	const tokens = args.trim().split(/\s+/).filter(Boolean);
+	const dryRun = tokens.includes('dry-run');
+	const verb = tokens.find((t) => t !== 'dry-run');
+	const sub = tokens.find((t) => t !== verb && t !== 'dry-run');
+	if (verb === undefined) return { mode: 'elide', dryRun, allScopes: true };
+	if (dryRun && (verb === 'undo' || verb === 'profile' || verb === 'status')) {
+		return `dry-run applies only to elide, thinking, or images, not ${verb}.`;
+	}
+	if (verb === 'undo') {
+		if (sub !== undefined) return `Unknown /shake undo argument "${sub}". /shake undo restores everything.`;
+		return { mode: 'undo', dryRun };
+	}
+	if ((MODES as readonly string[]).includes(verb)) {
+		if (sub !== undefined) return `Unknown /shake argument "${sub}" after ${verb}.`;
+		return { mode: verb as Mode, dryRun };
+	}
+	return `Unknown /shake mode "${verb}". Modes: ${[...MODES, 'dry-run'].join(', ')}; plain /shake elides.`;
+}
+
+/** Bare dry-run popup; undefined = cancelled (already notified). */
+async function pickDryRunScope(ctx: ExtensionCommandContext): Promise<ScopeName | undefined> {
+	const choice = await ctx.ui.select('Shake dry-run', [...SCOPE_NAMES]);
+	if (choice === undefined) {
+		ctx.ui.notify('Preview cancelled.', 'info');
+		return undefined;
+	}
+	if ((SCOPE_NAMES as readonly string[]).includes(choice)) return choice as ScopeName;
+	ctx.ui.notify('Preview cancelled.', 'info');
+	return undefined;
+}
+
+/** A single throw (pi rejects non-editable targets) must not strand the rest outside undo's reach. */
+function applyEdits(
+	ctx: ExtensionCommandContext,
+	edits: PlanEdit[],
+	pi: ExtensionAPI,
+): {
+	appliedIds: string[];
+	skipped: number;
+	logFailed: boolean;
+} {
+	const sm = ctx.sessionManager as unknown as SessionManagerWithEdits;
+	const appliedIds: string[] = [];
+	let freed = 0;
+	let skipped = 0;
+	let logFailed = false;
+	for (const edit of edits) {
+		try {
+			sm.appendContextEdit(edit.targetId, { content: edit.content });
+			appliedIds.push(edit.targetId);
+			freed += edit.freed;
+		} catch {
+			skipped++;
+		}
+	}
+	if (appliedIds.length > 0) {
+		try {
+			pi.appendEntry(LOG_TYPE, {
+				action: 'shake',
+				mode: edits[0]?.kind === 'image' ? 'images' : edits[0]?.kind === 'thinking' ? 'thinking' : 'elide',
+				targets: appliedIds,
+				freed,
+				at: Date.now(),
+			});
+		} catch {
+			logFailed = true; // applied but undo cannot reach them
+		}
+	}
+	return { appliedIds, skipped, logFailed };
+}
+
+export function buildStatusLines(input: {
+	wallSize: number;
+	profile: string;
+	source: string;
+	usage: { tokens: number; contextWindow: number; percent: number } | undefined;
+	last: ShakeLog | undefined;
+}): string[] {
+	const { wallSize, profile, source, usage, last } = input;
+	let lastLine = 'last:     no runs yet';
+	if (last) {
+		const kind = last.action === 'undo' ? 'undo' : last.mode === 'elide' ? 'elide' : (last.mode ?? 'shake');
+		const count = last.targets?.length ?? 0;
+		const noun = `${count} entr${count === 1 ? 'y' : 'ies'}`;
+		const rest = last.action === 'undo' ? 'restored' : `~${(last.freed ?? 0).toLocaleString()} tokens freed`;
+		lastLine = `last:     ${kind} · ${noun} · ${rest}`;
+	}
+	return [
+		`wall:     ${wallSize} entr${wallSize === 1 ? 'y' : 'ies'} stuck`,
+		`profile:  ${profile} (${source})`,
+		`context:  ${usage != null ? `${usage.tokens.toLocaleString()} / ${usage.contextWindow.toLocaleString()} tokens (${Math.round(usage.percent)}%)` : 'unknown'}`,
+		lastLine,
+	];
+}
+
+export function createShakeCommandSpec(pi: ExtensionAPI): {
+	description: string;
+	getArgumentCompletions: (prefix: string) => Array<{ value: string; label: string }> | null;
+	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+} {
+	return {
+		description: 'Drop heavy content from context (tool results, large blocks, images, thinking)',
+		getArgumentCompletions: (prefix) => {
+			const options = [...(MODES as readonly string[]), 'dry-run'];
+			const filtered = options.filter((m) => m.startsWith(prefix.toLowerCase()));
+			return filtered.length > 0 ? filtered.map((m) => ({ value: m, label: m })) : null;
+		},
+		handler: async (args, ctx) => {
+			if (!ctx.isIdle()) {
+				ctx.ui.notify('/shake is unavailable while streaming. Wait or abort first.', 'warning');
+				return;
+			}
+
+			const parsed = parseRequest(args);
+			if (typeof parsed === 'string') {
+				ctx.ui.notify(parsed, 'warning');
+				return;
+			}
+			const { mode, dryRun, allScopes } = parsed;
+
+			const branch = ctx.sessionManager.getBranch() as unknown as Entry[];
+			const editedTargets = activeEditTargets(branch);
+			const { profile, source } = resolveProfileFromFiles();
+			const config = PROFILES[profile];
+
+			if (mode === 'profile') {
+				const names = Object.keys(PROFILES) as ProfileName[];
+				const valueColumn = Math.max(...names.map((n) => n.length)) + 4;
+				const options = names.map((name) => {
+					const tailTokens = PROFILES[name].protectTokens.toLocaleString('en-US');
+					const blockTokens = (PROFILES[name].fenceMinChars / CHARS_PER_TOKEN).toLocaleString('en-US');
+					const label = `${name}:${' '.repeat(valueColumn - name.length - 1)}tail ${tailTokens} tokens · blocks ≥ ~${blockTokens} tokens`;
+					return { name, label };
+				});
+				const choice = await ctx.ui.select(
+					`Shake profile (current: ${profile})`,
+					options.map((o) => o.label),
+				);
+				if (choice === undefined) {
+					ctx.ui.notify('Profile unchanged.', 'info');
+					return;
+				}
+				const picked = options.find((o) => o.label === choice)?.name;
+				if (picked === undefined) {
+					ctx.ui.notify('Profile unchanged.', 'info');
+					return;
+				}
+				const written = writeProfileToSettings(picked);
+				if (written === undefined) {
+					ctx.ui.notify('Could not write settings.json. Profile not saved.', 'warning');
+					return;
+				}
+				ctx.ui.notify(`Shake profile → ${picked} (wrote ${written.tier} settings.json: ${written.path}).`, 'info');
+				return;
+			}
+
+			if (mode === 'status') {
+				const usageRaw = ctx.getContextUsage();
+				// pi may report null usage (e.g. post-compaction); print "unknown", never a fake 0%.
+				const usage =
+					usageRaw == null || usageRaw.tokens === null || usageRaw.percent === null
+						? undefined
+						: {
+								tokens: usageRaw.tokens,
+								contextWindow: usageRaw.contextWindow,
+								percent: usageRaw.percent,
+							};
+				const logs = shakeLogs(branch);
+				ctx.ui.notify(
+					buildStatusLines({
+						wallSize: shakeWall(branch).size,
+						profile,
+						source,
+						usage,
+						last: logs[logs.length - 1],
+					}).join('\n'),
+					'info',
+				);
+				return;
+			}
+
+			if (mode === 'undo') {
+				const wall = shakeWall(branch);
+				const logs = shakeLogs(branch);
+				const targets = new Set<string>();
+				for (const log of logs) {
+					if (log.action !== 'shake') continue;
+					for (const t of log.targets ?? []) if (wall.has(String(t))) targets.add(String(t));
+				}
+				let skipped = 0;
+				const restored: string[] = [];
+				const sm = ctx.sessionManager as unknown as SessionManagerWithEdits;
+				// Snapshot: appendContextEdit mutates the branch while we iterate.
+				for (const entry of branch.slice()) {
+					if (!targets.has(entry.id)) continue;
+					const content = rawContent(entry);
+					if (content === undefined) {
+						skipped++;
+						continue;
+					}
+					sm.appendContextEdit(entry.id, { content }); // last-wins overlay → exact restore
+					restored.push(entry.id);
+				}
+				if (restored.length === 0) {
+					const missing = targets.size - skipped;
+					const divergence =
+						missing > 0 ? ` (${missing} entr${missing === 1 ? 'y' : 'ies'} on the wall missing from this branch)` : '';
+					ctx.ui.notify(
+						skipped > 0
+							? `Nothing to undo (${skipped} entr${skipped === 1 ? 'y' : 'ies'} with no stored content)${divergence}.`
+							: `Nothing to undo${divergence}.`,
+						'info',
+					);
+					return;
+				}
+				try {
+					pi.appendEntry(LOG_TYPE, { action: 'undo', targets: restored, at: Date.now() });
+				} catch {
+					ctx.ui.notify(
+						`Undid ${restored.length} context edit${restored.length === 1 ? '' : 's'}, restoring original content. WARNING: could not log the undo.`,
+						'warning',
+					);
+					return;
+				}
+				const skipClause =
+					skipped > 0 ? ` Skipped ${skipped} entr${skipped === 1 ? 'y' : 'ies'} with no stored content.` : '';
+				ctx.ui.notify(
+					`Undid ${restored.length} context edit${restored.length === 1 ? '' : 's'}, restoring original content.${skipClause}`,
+					'info',
+				);
+				return;
+			}
+
+			const plan =
+				mode === 'elide'
+					? planElide(branch, editedTargets, config)
+					: mode === 'images'
+						? planImages(branch, editedTargets)
+						: planThinking(branch, editedTargets);
+
+			if (dryRun) {
+				const target = allScopes ? await pickDryRunScope(ctx) : mode;
+				if (target === undefined) return;
+
+				// Rebuild for the chosen scope (bare form's `plan` is elide's).
+				const scopedPlan =
+					target === 'elide'
+						? planElide(branch, editedTargets, config)
+						: target === 'images'
+							? planImages(branch, editedTargets)
+							: planThinking(branch, editedTargets);
+
+				if (scopedPlan.length === 0) {
+					const nothing =
+						target === 'images'
+							? 'No images found in this session.'
+							: target === 'thinking'
+								? 'No thinking blocks found in this session.'
+								: 'Nothing to shake.';
+					ctx.ui.notify(nothing, 'info');
+					return;
+				}
+
+				const described = describePlan(target, scopedPlan);
+				const protectNote =
+					target === 'elide' ? ` Protects the last ${config.protectTokens.toLocaleString()} tokens.` : '';
+				const dryVerb =
+					target === 'elide'
+						? `Shook ${described.parts.join(' + ')} (~${described.freed.toLocaleString()} tokens).`
+						: target === 'thinking'
+							? `Dropped ${described.parts.join(' ')} (~${described.freed.toLocaleString()} tokens).`
+							: `Dropped ${described.parts.join(' ')} from this session.`;
+				ctx.ui.notify(`[dry-run] · ${dryVerb}${protectNote} Profile: ${profile} (${source}).`, 'info');
+				return;
+			}
+
+			if (plan.length === 0) {
+				const nothing =
+					mode === 'images'
+						? 'No images found in this session.'
+						: mode === 'thinking'
+							? 'No thinking blocks found in this session.'
+							: 'Nothing to shake.';
+				ctx.ui.notify(nothing, 'info');
+				return;
+			}
+
+			// Wall size before this run (distinct stuck entries, not raw context_edit rows).
+			const wallBeforeSize = shakeWall(branch).size;
+			const { appliedIds, skipped, logFailed } = applyEdits(ctx, plan, pi);
+			const wallAfterSize = new Set([...shakeWall(branch), ...appliedIds]).size;
+
+			// Summaries count what actually applied, not what was planned.
+			const appliedSet = new Set(appliedIds);
+			const appliedDescribed = describePlan(
+				mode,
+				plan.filter((e) => appliedSet.has(e.targetId)),
+			);
+
+			let summary: string;
+			if (appliedIds.length === 0) {
+				summary = `Nothing applied${skipped > 0 ? ` (${skipped} skipped, not editable)` : ''}.`;
+			} else if (mode === 'images') {
+				summary = `Dropped ${appliedDescribed.parts.join(' ')} from this session.`;
+			} else if (mode === 'thinking') {
+				summary = `Dropped ${appliedDescribed.parts.join(' ')}${appliedDescribed.freed > 0 ? ` (~${appliedDescribed.freed.toLocaleString()} tokens freed)` : ''}.`;
+			} else {
+				summary = `Shook ${appliedDescribed.parts.join(' + ')} (~${appliedDescribed.freed.toLocaleString()} tokens freed).`;
+			}
+
+			const appendClause =
+				wallBeforeSize > 0 && appliedIds.length > 0
+					? ` Appended ${appliedIds.length} new context edit${appliedIds.length === 1 ? '' : 's'} to ${wallBeforeSize} shaken entr${wallBeforeSize === 1 ? 'y' : 'ies'} (${wallAfterSize} total in the wall).`
+					: '';
+			const skipClause = skipped > 0 ? ` ${skipped} skipped (not editable).` : '';
+			const logNote = logFailed ? ' WARNING: could not log this run; undo may not cover it.' : '';
+			// Teach the escape hatch once per branch (first shake only).
+			const undoHint = wallBeforeSize === 0 && mode === 'elide' ? ' Run /shake undo to restore.' : '';
+			ctx.ui.notify(`${summary}${appendClause}${skipClause}${logNote}${undoHint}`, 'info');
+		},
+	};
+}

package/src/constants.ts

@@ -0,0 +1,22 @@
+/** pi's chars-per-token heuristic; kept single-sourced so displayed estimates never drift. */
+export const CHARS_PER_TOKEN = 4;
+
+export const PROFILES = {
+	default: { protectTokens: 4_000, fenceMinChars: 400 * CHARS_PER_TOKEN },
+	conservative: { protectTokens: 8_000, fenceMinChars: 800 * CHARS_PER_TOKEN },
+	aggressive: { protectTokens: 2_000, fenceMinChars: 200 * CHARS_PER_TOKEN },
+} as const;
+
+export type ProfileName = keyof typeof PROFILES;
+
+/** Guardrail: never user-configurable. */
+export const PROTECTED_TOOL_PREFIXES = ['skill'];
+
+export const MODES = ['elide', 'images', 'thinking', 'undo', 'status', 'profile'] as const;
+export type Mode = (typeof MODES)[number];
+
+export const SCOPE_NAMES = ['elide', 'thinking', 'images'] as const;
+export type ScopeName = (typeof SCOPE_NAMES)[number];
+
+/** Logs shake runs (context-invisible); drives wall/undo/status. */
+export const LOG_TYPE = 'shake';

package/src/plans.ts

@@ -0,0 +1,267 @@
+import { getLatestCompactionEntry } from '@earendil-works/pi-coding-agent';
+import { LOG_TYPE, PROFILES } from './constants.ts';
+import {
+	contentTokens,
+	entryTokens,
+	fmtTokens,
+	isProtectedTool,
+	newPlaceholder,
+	scanTextForBlockRanges,
+	textTokens,
+	toolResultText,
+} from './scanner.ts';
+import type { Block, BlockRange, Entry, PlanEdit, ShakeConfig, ThinkingBlock } from './types.ts';
+
+/** Last-op-wins over our logs; pi's own recovery targets stay off-limits forever. */
+export function activeEditTargets(branch: Entry[]): Set<string> {
+	const { stuck, shook } = shakeState(branch);
+	for (const entry of branch) {
+		if (entry.type === 'context_edit' && entry.targetId && !shook.has(entry.targetId)) {
+			stuck.add(entry.targetId);
+		}
+	}
+	return stuck;
+}
+
+/** Roles whose content pi allows us to overlay (`appendContextEdit` rejects others). */
+const EDITABLE_ROLES = new Set(['user', 'assistant', 'toolResult']);
+
+export function isEditableEntry(entry: Entry): boolean {
+	return entry.type === 'custom_message' || (entry.type === 'message' && EDITABLE_ROLES.has(entry.message?.role ?? ''));
+}
+
+export function rawContent(entry: Entry): string | Block[] | undefined {
+	if (entry.type === 'message' && entry.message) return entry.message.content as string | Block[];
+	if (entry.type === 'custom_message') return entry.content as string | Block[] | undefined;
+	return undefined;
+}
+
+/** First entry the model sees after compaction; missing kept-id → boundary = compaction index+1. */
+export function compactionBoundaryIndex(branch: Entry[]): number {
+	const latestCompaction = getLatestCompactionEntry(branch as never);
+	if (!latestCompaction) return 0;
+	const keptIndex = latestCompaction.firstKeptEntryId
+		? branch.findIndex((e) => e.id === latestCompaction.firstKeptEntryId)
+		: -1;
+	if (keptIndex >= 0) return keptIndex;
+	const compIndex = branch.findIndex((e) => e.id === latestCompaction.id);
+	return compIndex >= 0 ? compIndex + 1 : 0;
+}
+
+export function planElide(
+	branch: Entry[],
+	editedTargets: Set<string>,
+	config: ShakeConfig = PROFILES.default,
+): PlanEdit[] {
+	const n = branch.length;
+	if (n === 0) return [];
+	const accumulatedAfter = Array.from({ length: n }, () => 0);
+	let acc = 0;
+	for (let i = n - 1; i >= 0; i--) {
+		accumulatedAfter[i] = acc;
+		acc += entryTokens(branch[i]);
+	}
+
+	const boundaryIndex = compactionBoundaryIndex(branch);
+
+	const edits: PlanEdit[] = [];
+
+	for (let i = 0; i < n; i++) {
+		if (i < boundaryIndex) continue;
+		if (accumulatedAfter[i] < config.protectTokens) continue;
+		const entry = branch[i];
+		if (editedTargets.has(entry.id)) continue;
+
+		if (entry.type === 'message' && entry.message?.role === 'toolResult') {
+			const message = entry.message;
+			const toolName = typeof message.toolName === 'string' ? message.toolName : 'tool';
+			if (isProtectedTool(toolName)) continue;
+			const text = toolResultText(message);
+			if (!text) continue;
+			const blocksArr = Array.isArray(message.content) ? (message.content as Block[]) : [];
+			const nonText = blocksArr.filter((b) => b.type !== 'text');
+			const label = `tool result(${toolName})`;
+			const placeholder = `[${toolName} output omitted (~${fmtTokens(text.tokens)} tokens)]`;
+			const content: Block[] = [{ type: 'text', text: placeholder }, ...nonText];
+			const freed = text.tokens - textTokens(placeholder);
+			if (freed <= 0) continue;
+			edits.push({ targetId: entry.id, kind: 'toolResult', label, content, freed, count: 1 });
+			continue;
+		}
+
+		if (entry.type === 'message' || entry.type === 'custom_message') {
+			if (!isEditableEntry(entry)) continue;
+			const content = entry.type === 'message' ? (entry.message?.content as string | Block[]) : entry.content;
+			if (content === undefined) continue;
+			const label = entry.type === 'message' ? (entry.message?.role ?? 'message') : (entry.customType ?? 'custom');
+			const perBlock: Array<{ blockIndex: number; ranges: BlockRange[] }> = [];
+
+			if (typeof content === 'string') {
+				const ranges = scanTextForBlockRanges(content).filter((r) => r.end - r.start >= config.fenceMinChars);
+				if (ranges.length > 0) perBlock.push({ blockIndex: -1, ranges });
+			} else {
+				for (let bi = 0; bi < content.length; bi++) {
+					const block = content[bi];
+					if (block.type !== 'text') continue;
+					const ranges = scanTextForBlockRanges(block.text).filter((r) => r.end - r.start >= config.fenceMinChars);
+					if (ranges.length > 0) perBlock.push({ blockIndex: bi, ranges });
+				}
+			}
+			if (perBlock.length === 0) continue;
+
+			// Splice highest-start-first so earlier offsets stay valid.
+			const before = contentTokens(entry, content);
+			let rebuilt: string | Block[];
+			if (typeof content === 'string') {
+				let out = content;
+				const ranges = perBlock[0].ranges;
+				for (let r = ranges.length - 1; r >= 0; r--) {
+					const range = ranges[r];
+					out = out.slice(0, range.start) + newPlaceholder(range.kind, range.end - range.start) + out.slice(range.end);
+				}
+				rebuilt = out;
+			} else {
+				rebuilt = content.map((block, bi) => {
+					if (block.type !== 'text') return block;
+					const pb = perBlock.find((p) => p.blockIndex === bi);
+					if (!pb) return block;
+					let out = block.text;
+					for (let r = pb.ranges.length - 1; r >= 0; r--) {
+						const range = pb.ranges[r];
+						out =
+							out.slice(0, range.start) + newPlaceholder(range.kind, range.end - range.start) + out.slice(range.end);
+					}
+					return { type: 'text' as const, text: out };
+				});
+			}
+			const after = contentTokens(entry, rebuilt);
+			const freed = Math.max(0, before - after);
+			if (freed <= 0) continue;
+			const blockCount = perBlock.reduce((sum, p) => sum + p.ranges.length, 0);
+			edits.push({
+				targetId: entry.id,
+				kind: 'block',
+				label,
+				content: rebuilt,
+				freed,
+				count: blockCount,
+			});
+		}
+	}
+
+	return edits;
+}
+
+export function planImages(branch: Entry[], editedTargets: Set<string>): PlanEdit[] {
+	const edits: PlanEdit[] = [];
+	const boundary = compactionBoundaryIndex(branch);
+	for (let i = boundary; i < branch.length; i++) {
+		const entry = branch[i];
+		if (editedTargets.has(entry.id)) continue;
+		const content = entry.type === 'message' ? (entry.message?.content as string | Block[] | undefined) : entry.content;
+		if (content === undefined || typeof content === 'string') continue;
+		if (!isEditableEntry(entry)) continue;
+		const blocks = content as Block[];
+		const images = blocks.filter((b) => b.type === 'image');
+		if (images.length === 0) continue;
+		let kept = blocks.filter((b) => b.type !== 'image');
+		if (kept.length === 0) kept = [{ type: 'text', text: '[images omitted]' }]; // message must not vanish
+		const before = contentTokens(entry, content);
+		const after = contentTokens(entry, kept);
+		edits.push({
+			targetId: entry.id,
+			kind: 'image',
+			label: `${images.length} image${images.length === 1 ? '' : 's'}`,
+			content: kept,
+			freed: Math.max(0, before - after),
+			count: images.length,
+		});
+	}
+	return edits;
+}
+
+export function planThinking(branch: Entry[], editedTargets: Set<string>): PlanEdit[] {
+	const edits: PlanEdit[] = [];
+	const boundary = compactionBoundaryIndex(branch);
+	for (let i = boundary; i < branch.length; i++) {
+		const entry = branch[i];
+		if (editedTargets.has(entry.id)) continue;
+		if (entry.type !== 'message' || entry.message?.role !== 'assistant') continue;
+		const content = entry.message.content;
+		if (typeof content === 'string') continue;
+		const blocks = content as Block[];
+		const thinking = blocks.filter((b) => b.type === 'thinking') as ThinkingBlock[];
+		if (thinking.length === 0) continue;
+		let kept = blocks.filter((b) => b.type !== 'thinking');
+		if (kept.length === 0) {
+			const thinkingTokens = thinking.reduce((sum, b) => sum + textTokens(b.thinking), 0);
+			kept = [{ type: 'text', text: `[reasoning omitted (~${fmtTokens(thinkingTokens)} tokens)]` }];
+		}
+		const before = contentTokens(entry, content);
+		const after = contentTokens(entry, kept);
+		edits.push({
+			targetId: entry.id,
+			kind: 'thinking',
+			label: `${thinking.length} thinking block${thinking.length === 1 ? '' : 's'}`,
+			content: kept,
+			freed: Math.max(0, before - after),
+			count: thinking.length,
+		});
+	}
+	return edits;
+}
+
+export function describePlan(mode: string, plan: PlanEdit[]): { parts: string[]; freed: number } {
+	const freed = plan.reduce((sum, e) => sum + e.freed, 0);
+	if (mode === 'images') {
+		const images = plan.reduce((sum, e) => sum + e.count, 0);
+		return { parts: [`${images} image${images === 1 ? '' : 's'}`], freed };
+	}
+	if (mode === 'thinking') {
+		const blocks = plan.reduce((sum, e) => sum + e.count, 0);
+		return { parts: [`${blocks} thinking block${blocks === 1 ? '' : 's'}`], freed };
+	}
+	const toolResults = plan.filter((e) => e.kind === 'toolResult').length;
+	const blocks = plan.reduce((sum, e) => (e.kind === 'block' ? sum + e.count : sum), 0);
+	const parts: string[] = [];
+	if (toolResults > 0) parts.push(`${toolResults} tool result${toolResults === 1 ? '' : 's'}`);
+	if (blocks > 0) parts.push(`${blocks} block${blocks === 1 ? '' : 's'}`);
+	return { parts, freed };
+}
+
+/** Targets currently stuck (shake adds, undo removes). */
+export function shakeWall(branch: Entry[]): Set<string> {
+	return shakeState(branch).stuck;
+}
+
+function shakeState(branch: Entry[]): { stuck: Set<string>; shook: Set<string> } {
+	const stuck = new Set<string>();
+	const shook = new Set<string>();
+	for (const entry of branch) {
+		if (entry.type !== 'custom' || entry.customType !== LOG_TYPE) continue;
+		const log = entry.data as { action?: string; targets?: unknown } | undefined;
+		if (!log || !Array.isArray(log.targets)) continue;
+		for (const t of log.targets) {
+			const id = String(t);
+			if (log.action === 'shake') {
+				stuck.add(id);
+				shook.add(id);
+			} else if (log.action === 'undo') {
+				stuck.delete(id);
+			}
+		}
+	}
+	return { stuck, shook };
+}
+
+export function shakeLogs(
+	branch: Entry[],
+): Array<{ action: string; mode?: string; targets?: string[]; freed?: number }> {
+	const logs: Array<{ action: string; mode?: string; targets?: string[]; freed?: number }> = [];
+	for (const entry of branch) {
+		if (entry.type === 'custom' && entry.customType === LOG_TYPE && entry.data && typeof entry.data === 'object') {
+			logs.push(entry.data as { action: string; mode?: string; targets?: string[]; freed?: number });
+		}
+	}
+	return logs;
+}

package/src/scanner.ts

@@ -0,0 +1,163 @@
+import { estimateTokens } from '@earendil-works/pi-coding-agent';
+import { CHARS_PER_TOKEN, PROTECTED_TOOL_PREFIXES } from './constants.ts';
+import type { Block, BlockRange, Entry, Msg } from './types.ts';
+
+const OPENING_XML = /^<([a-z_-]+)(?:\s+[^>]*)?>$/;
+const CLOSING_XML = /^<\/([a-z_-]+)>$/;
+
+/** Conservative: unterminated fences/tags yield nothing; XML suppressed inside fences. */
+export function scanTextForBlockRanges(text: string): BlockRange[] {
+	const ranges: BlockRange[] = [];
+	let inFence = false;
+	let fenceDelim = '';
+	let fenceStart = -1;
+	const tagStack: string[] = [];
+	let xmlStart = -1;
+
+	let lineStart = 0;
+	for (let i = 0; i <= text.length; i++) {
+		if (i !== text.length && text[i] !== '\n') continue;
+		// Strip a trailing \r so CRLF text matches the same line grammar.
+		const line = text.slice(lineStart, i).replace(/\r$/, '');
+		const lineEnd = i;
+		const trimmedStart = line.trimStart();
+
+		if (inFence) {
+			// Closing must match the opening delimiter.
+			if (trimmedStart.startsWith(fenceDelim)) {
+				inFence = false;
+				ranges.push({ start: fenceStart, end: lineEnd, kind: 'fence' });
+				fenceStart = -1;
+				fenceDelim = '';
+			}
+			lineStart = i + 1;
+			continue;
+		}
+
+		// A fence-like line opens a fence only at top level; inside a top-level
+		// XML span it is content, not a fence.
+		if (tagStack.length === 0 && (trimmedStart.startsWith('```') || trimmedStart.startsWith('~~~'))) {
+			inFence = true;
+			fenceDelim = trimmedStart.slice(0, 3);
+			fenceStart = lineStart;
+			lineStart = i + 1;
+			continue;
+		}
+
+		const openMatch = xmlOpenMatch(trimmedStart, line);
+		if (openMatch) {
+			if (tagStack.length === 0) xmlStart = lineStart;
+			tagStack.push(openMatch[1]);
+		} else {
+			const closingMatch = CLOSING_XML.exec(trimmedStart);
+			if (closingMatch && tagStack.length > 0 && tagStack[tagStack.length - 1] === closingMatch[1]) {
+				tagStack.pop();
+				if (tagStack.length === 0 && xmlStart >= 0) {
+					ranges.push({ start: xmlStart, end: lineEnd, kind: 'xml' });
+					xmlStart = -1;
+				}
+			}
+		}
+
+		lineStart = i + 1;
+	}
+
+	return mergeRanges(ranges);
+}
+
+function mergeRanges(ranges: BlockRange[]): BlockRange[] {
+	if (ranges.length <= 1) return ranges;
+	const sorted = ranges.toSorted((a, b) => a.start - b.start);
+	const kept: BlockRange[] = [];
+	let lastEnd = -1;
+	for (const range of sorted) {
+		if (range.start < lastEnd) continue;
+		kept.push(range);
+		lastEnd = range.end;
+	}
+	return kept;
+}
+
+export function textTokens(text: string): number {
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+export function fmtTokens(n: number): string {
+	return n.toLocaleString('en-US');
+}
+
+export function entryTokens(entry: Entry): number {
+	if (entry.type === 'message' && entry.message) {
+		const content = entry.message.content;
+		const message =
+			typeof content === 'string' ? { ...entry.message, content: [{ type: 'text', text: content }] } : entry.message;
+		return estimateTokens(message as never);
+	}
+	if (entry.type === 'custom_message' && entry.content !== undefined) {
+		// pi's estimator weighs images in custom content (4,800 chars each).
+		return estimateTokens({ role: 'custom', content: entry.content } as never);
+	}
+	return 0;
+}
+
+function isProtectedTool(toolName: string): boolean {
+	return PROTECTED_TOOL_PREFIXES.some((prefix) => toolName.toLowerCase().startsWith(prefix));
+}
+
+/**
+ * Opening-tag line: column 0, not self-closing, not a void element (so `<br
+ * />`, `<hr>`, `<img>` never open a span). Returns the match for the name.
+ */
+function xmlOpenMatch(trimmedStart: string, line: string): RegExpExecArray | null {
+	if (line.length !== trimmedStart.length || trimmedStart.endsWith('/>')) return null;
+	const match = OPENING_XML.exec(trimmedStart);
+	if (!match || VOID_TAGS.has(match[1])) return null;
+	return match;
+}
+
+const VOID_TAGS = new Set([
+	'area',
+	'base',
+	'br',
+	'col',
+	'embed',
+	'hr',
+	'img',
+	'input',
+	'link',
+	'meta',
+	'param',
+	'source',
+	'track',
+	'wbr',
+]);
+
+function toolResultText(message: Msg): { originalText: string; tokens: number } | undefined {
+	const blocks = Array.isArray(message.content) ? (message.content as Block[]) : [];
+	const fragments: string[] = [];
+	for (const block of blocks) {
+		if (block.type === 'text' && block.text.length > 0) fragments.push(block.text);
+	}
+	if (fragments.length === 0) return undefined;
+	const originalText = fragments.join('\n');
+	return { originalText, tokens: textTokens(originalText) };
+}
+
+/** "omitted" reads as deliberate length-cut, not error/silence; never mentions mechanism. */
+export function newPlaceholder(kind: 'fence' | 'xml', chars: number): string {
+	const tokens = Math.max(1, Math.ceil(chars / CHARS_PER_TOKEN));
+	const label = kind === 'fence' ? 'code block' : 'XML block';
+	return `[${label} omitted (~${fmtTokens(tokens)} tokens)]`;
+}
+
+export function contentTokens(entry: Entry, content: string | Block[]): number {
+	// Normalize string content to blocks: pi's estimator scores assistant
+	// strings as 0 tokens, which would zero freed math for legacy rows.
+	const normalized: Block[] = typeof content === 'string' ? [{ type: 'text', text: content }] : content;
+	if (entry.type === 'custom_message') {
+		return estimateTokens({ role: 'custom', content: normalized } as never);
+	}
+	return estimateTokens({ role: entry.message?.role ?? 'user', content: normalized } as never);
+}
+
+export { isProtectedTool, toolResultText };

package/src/settings.ts

@@ -0,0 +1,90 @@
+/** No extension settings-write API exists; the popup writes the file, shake reads it per invocation. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { PROFILES } from './constants.ts';
+import type { ProfileName } from './constants.ts';
+
+/** Test seam: redirect project/agent dirs to temp roots. */
+let settingsRoots: { project: string; agent: string } | undefined;
+export function setSettingsRoots(project: string, agent: string): void {
+	settingsRoots = { project, agent };
+}
+export function clearSettingsRoots(): void {
+	settingsRoots = undefined;
+}
+
+function settingsPaths(): { projectPath: string; globalPath: string } {
+	if (settingsRoots) {
+		return {
+			projectPath: join(settingsRoots.project, 'settings.json'),
+			globalPath: join(settingsRoots.agent, 'settings.json'),
+		};
+	}
+	const cwd = process.cwd();
+	const home = process.env.HOME ?? '';
+	return {
+		projectPath: join(cwd, '.pi', 'settings.json'),
+		globalPath: join(home, '.pi', 'agent', 'settings.json'),
+	};
+}
+
+/** Distinguish missing from unparseable so corrupt files surface instead of silently defaulting. */
+function readJsonLoose(path: string): { data?: Record<string, unknown>; corrupt?: boolean } {
+	if (!existsSync(path)) return {};
+	try {
+		const parsed = JSON.parse(readFileSync(path, 'utf-8').replace(/^\uFEFF/, ''));
+		return parsed && typeof parsed === 'object' ? { data: parsed as Record<string, unknown> } : { corrupt: true };
+	} catch {
+		return { corrupt: true };
+	}
+}
+
+/** Accept junk like "aggressive:" (trailing colon/space) as "aggressive". */
+function normalizeProfile(value: unknown): ProfileName | undefined {
+	if (typeof value !== 'string') return undefined;
+	const cleaned = value.trim().replace(/:+$/, '');
+	return cleaned in PROFILES ? (cleaned as ProfileName) : undefined;
+}
+
+export function resolveProfileFromFiles(): { profile: ProfileName; source: string } {
+	const { projectPath, globalPath } = settingsPaths();
+	for (const [path, label] of [
+		[projectPath, 'settings.json (project)'],
+		[globalPath, 'settings.json (agent-directory)'],
+	] as const) {
+		const { data, corrupt } = readJsonLoose(path);
+		if (corrupt) return { profile: 'default', source: `default (${label} is not parseable JSON)` };
+		if (data === undefined) continue;
+		const rawProfile = (data as { shake?: { profile?: unknown } }).shake?.profile;
+		if (rawProfile === undefined) continue;
+		const p = normalizeProfile(rawProfile);
+		if (p !== undefined) return { profile: p, source: label };
+		return { profile: 'default', source: `default (invalid "${String(rawProfile)}" in ${label})` };
+	}
+	return { profile: 'default', source: 'default' };
+}
+
+/** Project settings if present, else agent-directory; merges, never clobbers an unparseable file. */
+export function writeProfileToSettings(
+	profile: ProfileName,
+): { tier: 'project' | 'agent-directory'; path: string } | undefined {
+	const { projectPath, globalPath } = settingsPaths();
+	const target = existsSync(projectPath) ? projectPath : globalPath;
+	const targetExists = existsSync(target);
+	const { data, corrupt } = targetExists ? readJsonLoose(target) : {};
+	if (corrupt || (targetExists && data === undefined)) return undefined;
+	try {
+		const current = data ?? {};
+		const shake =
+			typeof current.shake === 'object' && current.shake !== null && !Array.isArray(current.shake)
+				? (current.shake as Record<string, unknown>)
+				: {};
+		current.shake = { ...shake, profile };
+		const dir = dirname(target);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		writeFileSync(target, JSON.stringify(current, null, 2) + '\n', 'utf-8');
+		return { tier: target === projectPath ? 'project' : 'agent-directory', path: target };
+	} catch {
+		return undefined;
+	}
+}

package/src/types.ts

@@ -0,0 +1,61 @@
+/** Structural views of pi's session-entry shapes, kept untyped to compose with what pi hands us. */
+
+export interface TextBlock {
+	type: 'text';
+	text: string;
+}
+export interface ImageBlock {
+	type: 'image';
+	data: string;
+	mimeType: string;
+}
+export interface ThinkingBlock {
+	type: 'thinking';
+	thinking: string;
+	thinkingSignature?: string;
+	redacted?: boolean;
+}
+export interface ToolCallBlock {
+	type: 'toolCall';
+	id: string;
+	name: string;
+	arguments: Record<string, unknown>;
+}
+export type Block = TextBlock | ImageBlock | ThinkingBlock | ToolCallBlock;
+
+export interface Msg {
+	role: string;
+	content: string | Block[];
+	[k: string]: unknown;
+}
+
+export interface Entry {
+	id: string;
+	type: string;
+	message?: Msg;
+	content?: string | (TextBlock | ImageBlock)[];
+	customType?: string;
+	targetId?: string;
+	data?: unknown;
+}
+
+export interface PlanEdit {
+	targetId: string;
+	kind: 'toolResult' | 'block' | 'image' | 'thinking';
+	label: string;
+	content: string | Block[];
+	freed: number;
+	/** Count of dropped items for reporting. */
+	count: number;
+}
+
+export interface ShakeConfig {
+	protectTokens: number;
+	fenceMinChars: number;
+}
+
+export interface BlockRange {
+	start: number;
+	end: number;
+	kind: 'fence' | 'xml';
+}