@xynogen/pix-core 0.6.1 → 0.6.3

package/README.md

@@ -51,6 +51,21 @@ Pi activates extensions per installed package via each package's `pi.extensions`
 | `pix-subagent` | `agent` / `agent_control` — planner-driven sub-agents with live widget |
 | `compaction` | Built into pix-core: replaces pi's built-in context compaction with two levers. **Summary prompt is always pix's** — every compaction (manual `/compact`, threshold, overflow) generates the summary with the current conversation model (no silent routing) from an editable source prompt. **Trigger is pix's when `compaction.triggerPercent > 0`** — after each settled turn pix reads live context usage and compacts at `max(contextWindow × triggerPercent, compaction.minimumTokens)`. The default 100K floor prevents low percentages from compacting too early (for example, 10% of a 300K model waits for 100K rather than 30K); `0` disables pix's trigger and lets pi decide, while pix's summary prompt still applies. After a pix-triggered compaction pix sends a short, visible "resume" user message so the agent continues on its own. Every trigger, resume, and summary run emits a notify line (reason, model, token counts). |
 
+## Plan mode
+
+Use `/plan` to create, edit, execute, or delete saved plans in `<project>/.pi/plans/`.
+Use `Shift+Tab` or `Ctrl+Alt+P` to toggle plan mode.
+Use `Tab` in an empty prompt to cycle the thinking level.
+
+Plan mode keeps the available tools unchanged.
+Only `edit` and `write` are restricted to files inside the current project's `.pi/plans/`.
+The guard rejects other project paths, path traversal outside this directory, and symlink targets or parents.
+The same restrictions apply when a session restores plan mode.
+
+Other tools, including shell commands, are not sandboxed by plan mode.
+The visible plan guide asks the agent to explore without changing project files.
+Use `pix-gate` for command restrictions.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@xynogen/pix-core",
-	"version": "0.6.1",
-	"description": "Pi extension bundle — installs and activates all core pix-* extensions",
+	"version": "0.6.3",
+	"description": "Pi extension bundle \u2014 installs and activates all core pix-* extensions",
 	"type": "module",
 	"main": "src/extension.ts",
 	"exports": {
@@ -43,32 +43,32 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@xynogen/pix-runtime": "^0.12.2",
-		"@xynogen/pix-data": "^0.5.3",
-		"@xynogen/pix-pretty": "^1.29.0",
-		"@xynogen/pix-welcome": "^0.2.5",
-		"@xynogen/pix-footer": "^0.2.7",
-		"@xynogen/pix-diagnostics": "^0.3.5",
-		"@xynogen/pix-display": "^0.3.0",
-		"@xynogen/pix-prompts": "^0.5.4",
-		"@xynogen/pix-skills": "^0.9.1",
-		"@xynogen/pix-models": "^0.3.0",
-		"@xynogen/pix-update": "^0.2.4",
-		"@xynogen/pix-commands": "^0.6.8",
-		"@xynogen/pix-nudge": "^0.3.2",
-		"@xynogen/pix-read": "^0.4.2",
-		"@xynogen/pix-write": "^0.2.7",
-		"@xynogen/pix-edit": "^0.2.7",
-		"@xynogen/pix-find": "^0.3.3",
-		"@xynogen/pix-grep": "^0.3.3",
-		"@xynogen/pix-ls": "^0.3.3",
-		"@xynogen/pix-bash": "^0.2.9",
-		"@xynogen/pix-powershell": "^0.1.0",
-		"@xynogen/pix-todo": "^0.4.5",
-		"@xynogen/pix-ask": "^0.3.0",
-		"@xynogen/pix-optimizer": "^1.3.0",
-		"@xynogen/pix-gate": "^0.4.0",
-		"@xynogen/pix-subagent": "^0.10.5"
+		"@xynogen/pix-runtime": "^0.13.0",
+		"@xynogen/pix-data": "^0.5.4",
+		"@xynogen/pix-pretty": "^1.30.0",
+		"@xynogen/pix-welcome": "^0.2.7",
+		"@xynogen/pix-footer": "^0.2.8",
+		"@xynogen/pix-diagnostics": "^0.3.6",
+		"@xynogen/pix-display": "^0.3.1",
+		"@xynogen/pix-prompts": "^0.5.6",
+		"@xynogen/pix-skills": "^0.9.2",
+		"@xynogen/pix-models": "^0.3.1",
+		"@xynogen/pix-update": "^0.2.5",
+		"@xynogen/pix-commands": "^0.6.9",
+		"@xynogen/pix-nudge": "^0.3.3",
+		"@xynogen/pix-read": "^0.4.3",
+		"@xynogen/pix-write": "^0.2.8",
+		"@xynogen/pix-edit": "^0.2.8",
+		"@xynogen/pix-find": "^0.3.4",
+		"@xynogen/pix-grep": "^0.3.4",
+		"@xynogen/pix-ls": "^0.3.4",
+		"@xynogen/pix-bash": "^0.2.10",
+		"@xynogen/pix-powershell": "^0.1.1",
+		"@xynogen/pix-todo": "^0.4.6",
+		"@xynogen/pix-ask": "^0.3.2",
+		"@xynogen/pix-optimizer": "^1.3.2",
+		"@xynogen/pix-gate": "^0.4.1",
+		"@xynogen/pix-subagent": "^0.10.7"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/src/compaction.ts

@@ -26,7 +26,7 @@
  */
 
 import { complete } from "@earendil-works/pi-ai/compat";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ContextEditableContent, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
 import { getErrorMessage } from "@xynogen/pix-pretty/utils";
 import { config } from "@xynogen/pix-runtime/config";
@@ -95,6 +95,43 @@ export function resumeDecisionAfterCompaction(args: {
 	return "resume";
 }
 
+// Pi cuts compaction only at message boundaries, so one huge message (a pasted
+// HAR/log, a giant tool result) can't be summarized away: "Nothing to compact".
+// Over threshold we instead trim oversized text to head+tail via a visible,
+// append-only context_edit — the original stays in the session file.
+// ponytail: fixed char limits (~20k tok kept per message); make them config if
+// someone needs to tune per model.
+const MAX_MESSAGE_CHARS = 80_000;
+const KEEP_CHARS = 20_000;
+
+type TextOrImage = { type: string; text?: string };
+
+/** Head+tail trim of oversized text. Undefined when the text already fits. */
+export function truncateLargeText(text: string): string | undefined {
+	if (text.length <= MAX_MESSAGE_CHARS) return undefined;
+	const cut = text.length - 2 * KEEP_CHARS;
+	return `${text.slice(0, KEEP_CHARS)}\n\n[… ${cut.toLocaleString()} chars trimmed by pix compaction (original kept in session file) …]\n\n${text.slice(-KEEP_CHARS)}`;
+}
+
+/** Trimmed copy of user/tool-result content, or undefined when nothing is oversized. */
+export function shrinkContent(
+	content: string | TextOrImage[],
+): { content: string | TextOrImage[]; saved: number } | undefined {
+	if (typeof content === "string") {
+		const t = truncateLargeText(content);
+		return t === undefined ? undefined : { content: t, saved: content.length - t.length };
+	}
+	let saved = 0;
+	const next = content.map((part) => {
+		if (part.type !== "text" || typeof part.text !== "string") return part;
+		const t = truncateLargeText(part.text);
+		if (t === undefined) return part;
+		saved += part.text.length - t.length;
+		return { ...part, text: t };
+	});
+	return saved > 0 ? { content: next, saved } : undefined;
+}
+
 // Sent as a user message after a self-triggered compaction so the agent picks
 // its task back up on its own. Kept short — the freshly written summary already
 // carries the goal, progress, and next steps. Edit to taste.
@@ -181,6 +218,44 @@ export default function registerCompaction(pi: ExtensionAPI): void {
 	// agent_settled re-fires, and we compact again every turn. Reset by /compact or
 	// a new session; a session-scoped bool is the smallest fix.
 	let triggerDisabled = false;
+
+	// Runs before agent_settled; committed edits shrink the context the trigger
+	// below measures, so a single oversized message no longer blocks compaction.
+	pi.on("agent_before_settle", (event, ctx) => {
+		const { triggerPercent, minimumTokens } = config(compactionSection);
+		if (triggerPercent <= 0) return;
+		const usage = ctx.getContextUsage?.();
+		if (!usage || usage.tokens === null) return;
+		if (
+			usage.tokens < compactionThresholdTokens(usage.contextWindow, triggerPercent, minimumTokens)
+		)
+			return;
+
+		const edits: typeof event.entries = [];
+		let saved = 0;
+		for (const { sourceEntry, messages } of event.context.contextEntries) {
+			const msg = messages[0];
+			const editable =
+				sourceEntry.type === "custom_message" ||
+				(sourceEntry.type === "message" && (msg?.role === "user" || msg?.role === "toolResult"));
+			if (!editable || !msg || !("content" in msg)) continue;
+			const shrunk = shrinkContent(msg.content as string | TextOrImage[]);
+			if (!shrunk) continue;
+			saved += shrunk.saved;
+			edits.push({
+				type: "context_edit",
+				targetId: sourceEntry.id,
+				replacement: { content: shrunk.content as ContextEditableContent },
+			});
+		}
+		if (edits.length === 0) return;
+		ctx.ui.notify(
+			`Compaction: trimmed ${edits.length} oversized message(s), ~${Math.round(saved / 4).toLocaleString()} tok (head+tail kept; originals stay in session file)`,
+			"info",
+		);
+		return { entries: [...event.entries, ...edits] };
+	});
+
 	pi.on("agent_settled", (_event, ctx) => {
 		if (compacting || triggerDisabled) return;
 		const { triggerPercent, minimumTokens } = config(compactionSection);
@@ -259,7 +334,16 @@ export default function registerCompaction(pi: ExtensionAPI): void {
 			},
 			onError: (err) => {
 				compacting = false;
-				ctx.ui.notify(`Compaction trigger failed: ${err.message}`, "error");
+				// Pi already reported the failure (compaction_end). "Nothing to compact" /
+				// "Already compacted" will fail identically next turn, so latch off instead
+				// of re-firing every agent_settled. Oversized messages are trimmed in
+				// agent_before_settle, so this is now only a backstop.
+				if (!/nothing to compact|already compacted/i.test(err.message)) return;
+				triggerDisabled = true;
+				ctx.ui.notify(
+					`Compaction: ${tokens.toLocaleString()} tok but nothing older to summarize. Auto-trigger disabled for this session; start a new session if context keeps growing.`,
+					"warning",
+				);
 			},
 		});
 	});

package/src/extension.ts

@@ -42,7 +42,7 @@ import registerCompaction from "./compaction.ts";
 import deferNonCoreTools from "./defer-tools.ts";
 import registerPlanMode from "./plan-mode.ts";
 
-type PixExtension = (pi: ExtensionAPI) => void;
+type PixExtension = (pi: ExtensionAPI) => void | Promise<void>;
 
 // Compile-time boundary: every member must accept the Pi host contract.
 const MEMBERS = [
@@ -89,6 +89,6 @@ const MEMBERS = [
 	registerPlanMode,
 ] satisfies readonly PixExtension[];
 
-export default function (pi: ExtensionAPI): void {
-	for (const register of MEMBERS) register(pi);
+export default async function (pi: ExtensionAPI): Promise<void> {
+	for (const register of MEMBERS) await register(pi);
 }

package/src/plan-modal.ts

@@ -31,6 +31,16 @@ export type PlanModalResult =
 	| { kind: "toggle" };
 
 const LIST_ROWS = 10;
+const relativeTime = new Intl.RelativeTimeFormat("en", { numeric: "always" });
+
+export function planAge(updated_at: number | undefined, now = Date.now()): string {
+	if (updated_at === undefined || !Number.isFinite(updated_at)) return "";
+	const seconds = Math.max(0, Math.floor((now - updated_at) / 1000));
+	if (seconds < 60) return "just now";
+	if (seconds < 3600) return relativeTime.format(-Math.floor(seconds / 60), "minute");
+	if (seconds < 86400) return relativeTime.format(-Math.floor(seconds / 3600), "hour");
+	return relativeTime.format(-Math.floor(seconds / 86400), "day");
+}
 
 type View = "list" | "plan" | "confirm";
 
@@ -56,7 +66,16 @@ export class PlanModal {
 				label: "+ New plan",
 				description: "Plan mode on + plan guide in the prompt bar",
 			},
-			...plans.map((p, i) => ({ value: String(i), label: p.title, description: p.description })),
+			...plans.map((p, i) => ({
+				value: String(i),
+				label: p.title,
+				description: [
+					p.updated_at === undefined ? "" : `Updated ${planAge(p.updated_at)}`,
+					p.description,
+				]
+					.filter(Boolean)
+					.join(" · "),
+			})),
 		];
 		this.list = new SelectList(items, LIST_ROWS, selectListTheme(theme));
 		this.list.onSelect = (item) => {
@@ -164,6 +183,7 @@ export class PlanModal {
 				confirm ? t.fg("warning", t.bold(`Delete ${plan.file}?`)) : title(plan.title),
 				...(plan.description ? [t.fg("dim", plan.description)] : []),
 				hint(`${this.planDir}/${plan.file}`),
+				...(plan.updated_at === undefined ? [] : [hint(`Updated ${planAge(plan.updated_at)}`)]),
 			];
 			body = plan.body.split("\n");
 			footer = [

package/src/plan-mode.ts

@@ -5,8 +5,8 @@
  * Tab in an empty prompt cycles the thinking level (Pi's default Shift+Tab action).
  *
  * While plan mode is on:
- *   - active tools shrink to `read` + `write` + `bash` (previous set restored on exit);
- *   - `write` may only target `.pi/plans/` (tool_call guard, visible block);
+ *   - available tools stay unchanged;
+ *   - `edit` and `write` may only target this project's `.pi/plans/`;
  *   - no hidden prompt: "+ New plan" pastes PLAN_GUIDE into the prompt bar as a chip (sent as <paste>).
  *
  * Plan file format: YAML-ish frontmatter (`title`, `description`) + markdown
@@ -14,7 +14,7 @@
  * message — no hidden automation.
  */
 
-import { mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { CustomEditor, isToolCallEventType } from "@earendil-works/pi-coding-agent";
@@ -23,19 +23,19 @@ import { chipTag } from "@xynogen/pix-pretty/chips";
 import { icon } from "@xynogen/pix-pretty/icon-catalog";
 import { modalOverlayOptions } from "@xynogen/pix-pretty/modal-frame";
 import { projectDir } from "@xynogen/pix-runtime/paths";
+import { validateOutputPath } from "@xynogen/pix-runtime/safe-path";
 import { PlanModal, type PlanModalResult } from "./plan-modal.ts";
 
-// ponytail: bash is not sandboxed here; PLAN_GUIDE asks for read-only use and pix-gate
-// still guards destructive commands. Add an allowlist guard if the model abuses it.
-const PLAN_TOOLS = ["read", "write", "bash"];
+// ponytail: only edit/write paths are guarded here. Other tools are not sandboxed.
+// PLAN_GUIDE asks for read-only use. Use pix-gate for command restrictions.
 const PLAN_DIR = `${projectDir()}/plans`; // "/" so prompts and hints read the same on Windows
 const STATE_ENTRY = "pix-plan-mode";
 
 // Visible guide: /plan → "+ New plan" pastes this into the prompt bar as a chip for the user
 // to read, edit, and send. Nothing is injected into the system prompt.
 export const PLAN_GUIDE = `[PLAN MODE] Write an implementation plan. Do not change project code.
-Explore with \`read\` and read-only \`bash\` (git log/status/diff, ls, rg, --help). Never use bash to edit, install, commit, or delete.
-Save ONE plan with \`write\` to \`.pi/plans/YYYY-MM-DD-<feature-name>.md\` (writes elsewhere are blocked).
+Use any available tool to explore without changing project files. Never use tools to edit project code, install, commit, or delete.
+Save ONE plan with \`write\` to \`.pi/plans/YYYY-MM-DD-<feature-name>.md\`. Use \`edit\` or \`write\` to revise it. Both tools are restricted to this project's \`.pi/plans/\`.
 
 Format:
 ---
@@ -60,6 +60,7 @@ When done, say: "Plan saved to <path>. Use /plan to run it."
 The goal follows this guide.`;
 
 export interface Plan {
+	updated_at?: number;
 	file: string;
 	title: string;
 	description: string;
@@ -85,7 +86,7 @@ export function isPlanPath(cwd: string, path: string): boolean {
 	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
 }
 
-function listPlans(cwd: string): Plan[] {
+export function listPlans(cwd: string): Plan[] {
 	const dir = resolve(cwd, PLAN_DIR);
 	let files: string[];
 	try {
@@ -94,9 +95,11 @@ function listPlans(cwd: string): Plan[] {
 		return [];
 	}
 	return files
-		.sort()
-		.reverse()
-		.map((f) => parsePlan(f, readFileSync(join(dir, f), "utf-8")));
+		.map((f) => ({
+			...parsePlan(f, readFileSync(join(dir, f), "utf-8")),
+			updated_at: statSync(join(dir, f)).mtimeMs,
+		}))
+		.sort((a, b) => b.updated_at - a.updated_at || b.file.localeCompare(a.file));
 }
 
 /**
@@ -129,16 +132,10 @@ export function modeStatus(
 
 export default function registerPlanMode(pi: ExtensionAPI): void {
 	let enabled = false;
-	let toolsBefore: string[] | undefined;
 
 	function apply(ctx: ExtensionContext, on: boolean): void {
 		if (on && !enabled) {
-			toolsBefore = pi.getActiveTools();
-			pi.setActiveTools(PLAN_TOOLS);
 			mkdirSync(resolve(ctx.cwd, PLAN_DIR), { recursive: true });
-		} else if (!on && enabled) {
-			if (toolsBefore) pi.setActiveTools(toolsBefore);
-			toolsBefore = undefined;
 		}
 		const changed = enabled !== on;
 		enabled = on;
@@ -146,12 +143,12 @@ export default function registerPlanMode(pi: ExtensionAPI): void {
 			"plan",
 			modeStatus(on, (r, t) => ctx.ui.theme.fg(r, t)),
 		);
-		pi.appendEntry(STATE_ENTRY, { enabled, toolsBefore });
+		pi.appendEntry(STATE_ENTRY, { enabled });
 		if (changed) {
 			ctx.ui.notify(
 				on
-					? "Plan mode on: read + bash + write (.pi/plans only)."
-					: "Plan mode off: tools restored.",
+					? "Plan mode on: all tools available. Edit/write only inside this project's .pi/plans/."
+					: "Plan mode off: edit/write restrictions removed.",
 			);
 		}
 	}
@@ -230,19 +227,16 @@ export default function registerPlanMode(pi: ExtensionAPI): void {
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (!enabled) return;
-		if (!PLAN_TOOLS.includes(event.toolName)) {
+		if (!isToolCallEventType("edit", event) && !isToolCallEventType("write", event)) return;
+		const path = event.input.path;
+		if (typeof path !== "string" || !isPlanPath(ctx.cwd, path)) {
 			return {
 				block: true,
-				reason:
-					"Plan mode: only read, bash, and write are allowed. Toggle off with Shift+Tab or ctrl+alt+p.",
-			};
-		}
-		if (isToolCallEventType("write", event) && !isPlanPath(ctx.cwd, event.input.path)) {
-			return {
-				block: true,
-				reason: `Plan mode: write only inside ${PLAN_DIR}/. Got: ${event.input.path}`,
+				reason: `Plan mode: ${event.toolName} only inside ${resolve(ctx.cwd, PLAN_DIR)}/. Got: ${path}`,
 			};
 		}
+		const checked = await validateOutputPath(resolve(ctx.cwd, path));
+		if (!checked.ok) return { block: true, reason: `Plan mode: ${checked.reason}` };
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
@@ -252,12 +246,8 @@ export default function registerPlanMode(pi: ExtensionAPI): void {
 				(e: { type: string; customType?: string }) =>
 					e.type === "custom" && e.customType === STATE_ENTRY,
 			)
-			.pop() as { data?: { enabled?: boolean; toolsBefore?: string[] } } | undefined;
-		if (entry?.data?.enabled) {
-			toolsBefore = entry.data.toolsBefore;
-			enabled = true;
-			pi.setActiveTools(PLAN_TOOLS);
-		}
+			.pop() as { data?: { enabled?: boolean } } | undefined;
+		enabled = entry?.data?.enabled === true;
 		ctx.ui.setStatus(
 			"plan",
 			modeStatus(enabled, (r, t) => ctx.ui.theme.fg(r, t)),