pi-soly 1.11.2 → 1.12.0

package/deck/index.ts

@@ -0,0 +1,113 @@
+// =============================================================================
+// index.ts — pi-deck extension entry point
+// =============================================================================
+//
+// Registers one LLM tool: `decision_deck`. Presents a single design/architecture
+// decision as a full-screen stack of cards (one per option) that the user flips
+// through and picks from. Each card carries a title, summary, optional code
+// snippet, and pros/cons — so the user compares concrete shapes, not just labels.
+//
+// When to reach for it over ask_pro: the choice hinges on seeing the code/structure
+// of each option side-by-side, and a thin preview column isn't enough. Native TUI
+// (no browser, no server). Returns the chosen option index in one call.
+// =============================================================================
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { highlightCode } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { DeckComponent, type DeckResult } from "./deck.ts";
+
+export default function piDeckExtension(pi: ExtensionAPI) {
+	// Usage guidance lives in the soly-framework skill + the main soly prompt
+	// pointer — not injected here.
+	pi.registerTool({
+		name: "decision_deck",
+		label: "soly · decision_deck",
+		description:
+			"Present ONE design/architecture decision as a full-screen deck of cards (one per option) the user flips through (←/→ or 1-N) and picks with Enter. Use instead of ask_pro when the choice hinges on comparing each option's concrete code shape, not a label. 2-6 options. The user can attach a free-text note (rationale, caveats) via `n`; it's returned in the result. Native TUI. Returns the chosen option.",
+		parameters: Type.Object({
+			title: Type.Optional(Type.String({ description: "Decision title." })),
+			prompt: Type.Optional(Type.String({ description: "Question shown above the cards." })),
+			options: Type.Array(
+				Type.Object({
+					title: Type.String({ description: "Card title." }),
+					summary: Type.Optional(Type.String({ description: "1-3 sentence explanation." })),
+					code: Type.Optional(
+						Type.String({ description: "Raw code snippet (no fences); set `lang` to highlight." }),
+					),
+					lang: Type.Optional(Type.String({ description: "Highlight language (e.g. 'ts')." })),
+					pros: Type.Optional(Type.Array(Type.String(), { description: "Upsides (+)." })),
+					cons: Type.Optional(Type.Array(Type.String(), { description: "Downsides (−)." })),
+					recommended: Type.Optional(
+						Type.Boolean({ description: "⭐ recommended (cursor starts here, at most one)." }),
+					),
+				}),
+				{ description: "2-6 options to compare." },
+			),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "decision_deck requires a UI-capable session (TUI). Run from the interactive pi TUI.",
+						},
+					],
+					details: { error: "no_ui", mode: ctx.mode },
+				};
+			}
+			if (params.options.length < 2 || params.options.length > 6) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `decision_deck: ${params.options.length} options, need 2-6.`,
+						},
+					],
+					details: { error: "bad_option_count", count: params.options.length },
+				};
+			}
+			const recommended = params.options.filter((o) => o.recommended).length;
+			if (recommended > 1) {
+				return {
+					content: [
+						{ type: "text", text: `decision_deck: ${recommended} recommended, at most 1 allowed.` },
+					],
+					details: { error: "multiple_recommended" },
+				};
+			}
+
+			const result = await ctx.ui.custom<DeckResult>((_tui, theme, keybindings, done) => {
+				const deckTheme = theme as unknown as ConstructorParameters<typeof DeckComponent>[0]["theme"];
+				return new DeckComponent({
+					options: params.options,
+					theme: deckTheme,
+					keybindings,
+					done,
+					title: params.title ?? "decision",
+					prompt: params.prompt,
+					highlight: highlightCode,
+				});
+			});
+
+			if (result.cancelled || result.chosen === undefined) {
+				return {
+					content: [{ type: "text", text: "(user cancelled the deck — no choice made)" }],
+					details: { cancelled: true },
+				};
+			}
+
+			const chosen = result.chosen;
+			const opt = params.options[chosen];
+			const note = result.note?.trim() ?? "";
+			const text = note
+				? `User chose option ${chosen + 1}: "${opt?.title ?? "?"}".  // note: "${note}"`
+				: `User chose option ${chosen + 1}: "${opt?.title ?? "?"}".`;
+			return {
+				content: [{ type: "text", text }],
+				details: { chosen, title: opt?.title, note: note || undefined },
+			};
+		},
+	});
+}

package/index.ts

@@ -22,7 +22,7 @@
 import * as os from "node:os";
 import * as path from "node:path";
 import * as fs from "node:fs";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import {
 	analyzeRules,
@@ -48,7 +48,6 @@ import {
 	type SourceSpec,
 } from "./core.ts";
 import { buildIntegrationsSection } from "./integrations.ts";
-import { installSolyAssets } from "./agents-install.ts";
 import {
 	DEFAULT_CONFIG,
 	loadConfig,
@@ -56,6 +55,7 @@ import {
 	type SolyConfig,
 } from "./config.ts";
 import { classifyTaskHeuristics, buildNudgeSection } from "./nudge.ts";
+import { detectToolHints, buildToolHintSection } from "./tool-hints.ts";
 import { notifyNudge, notifyDeprecation } from "./notification.ts";
 import { registerCommands, type CommandUI } from "./commands.ts";
 import { registerTools } from "./tools.ts";
@@ -66,9 +66,35 @@ import { detectEnv, buildEnvSection, type EnvSummary } from "./env.ts";
 import { buildCodeMap, buildCodeMapSection, type CodeMap } from "./codemap.ts";
 import { loadIntentDocs, buildIntentSection, loadInlineIntentBodies, type IntentDoc } from "./intent.ts";
 
+import { createChrome, readWelcomeMeta } from "./visual/index.ts";
+import { createContextManager } from "./context-manager.ts";
+
 // Built-in sub-features (merged from former pi-asked, pi-agented packages):
 import piAskExtension from "./ask/index.ts";
+import piDeckExtension from "./deck/index.ts";
+import piArtifactExtension from "./artifact/index.ts";
+import { getArtifactServer } from "./artifact/session.ts";
+
+/** Compact phase label for the chrome top bar, e.g. "plan 2/5". Null when idle. */
+function phaseLabelFromState(s: SolyState): string | null {
+	if (!s.exists) return null;
+	const cur = s.currentPhase;
+	const total = s.phases.length;
+	if (cur) return total > 0 ? `${cur.slug || cur.name} ${cur.number}/${total}` : `${cur.slug || cur.name}`;
+	return null;
+}
+
 
+/** Tiny always-on pointer to soly's interactive/visual tools. The detailed
+ *  "when / when-not / params" guidance lives in the soly-framework skill
+ *  (loaded on demand) so it doesn't cost tokens every turn. */
+const SOLY_TOOLS_POINTER = `
+## soly — interactive & visual tools
+
+When terminal text isn't the best medium, reach for these (details + when-NOT in the soly-framework skill):
+- \`ask_pro\` — multi-question picker (single/multi-select, free-text, per-option previews).
+- \`decision_deck\` — full-screen cards comparing design options by their concrete code shape.
+- \`html_artifact\` — render HTML to a self-contained, browseable per-project gallery.`;
 
 export default function solyExtension(pi: ExtensionAPI) {
 	// ============================================================================
@@ -154,6 +180,13 @@ export default function solyExtension(pi: ExtensionAPI) {
 	let intentDocs: IntentDoc[] = [];
 	let lastIntentSection = "";
 
+	// Visual chrome (top bar + custom footer + working spinner). Config-gated.
+	const chrome = createChrome(() => getActiveConfig().chrome);
+
+	// Single owner of pi's `context` channel (used by the /verify fresh-context
+	// mode; future context strategies plug in here too).
+	const contextManager = createContextManager(pi);
+
 	// ============================================================================
 	// Loaders
 	// ============================================================================
@@ -297,6 +330,35 @@ export default function solyExtension(pi: ExtensionAPI) {
 		}
 	};
 
+	// Refresh the chrome's live data snapshot (cwd, model, ctx%, git, phase)
+	// from the current context + project state, then request a re-render.
+	const updateChromeData = (ctx: ExtensionContext) => {
+		if (!getActiveConfig().chrome.enabled) return;
+		const d = chrome.data;
+		d.cwd = sessionCwd || ctx.cwd || "";
+		d.home = os.homedir();
+		const model = ctx.model as { id?: string; provider?: string; reasoning?: boolean } | undefined;
+		d.modelId = model?.id ?? null;
+		d.modelProvider = model?.provider ?? null;
+		d.reasoning = Boolean(model?.reasoning);
+		try {
+			d.thinkingLevel = pi.getThinkingLevel();
+		} catch {
+			d.thinkingLevel = null;
+		}
+		const usage = ctx.getContextUsage();
+		d.ctxPercent = usage?.percent ?? null;
+		d.ctxTokens = usage?.tokens ?? null;
+		d.contextWindow = usage?.contextWindow ?? null;
+		d.gitDirty = gitContext.statusShort
+			? gitContext.statusShort.split(/\r?\n/).filter(Boolean).length
+			: 0;
+		d.rulesActive = combinedRules().length;
+		d.phaseLabel = phaseLabelFromState(state);
+		d.artifactCount = getArtifactServer()?.count ?? 0;
+		chrome.poke();
+	};
+
 	// ============================================================================
 	// Register sub-features
 	// ============================================================================
@@ -327,6 +389,15 @@ export default function solyExtension(pi: ExtensionAPI) {
 		getActiveTools: () => pi.getActiveTools(),
 		getConfig: getActiveConfig,
 		onWorkflowUsed: resetSolyDrift,
+		contextManager,
+		onVerifyState: (s) => {
+			chrome.data.verbLabel = s.active ? (s.iteration > 0 ? `verify ${s.iteration}/${s.max}` : "verify") : null;
+			chrome.poke();
+		},
+		setVerbLabel: (verb) => {
+			chrome.data.verbLabel = verb;
+			chrome.poke();
+		},
 	});
 
 	// ============================================================================
@@ -336,7 +407,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 	pi.on("session_start", async (event, ctx) => {
 		// Deprecation warning: if the project still uses `.soly/`, nudge the
 		// user toward `.agents/`. One-time per session.
-		if (activeConfig.agent.useSolyWorkerSubagents && isLegacySolyDir(ctx.cwd)) {
+		if (isLegacySolyDir(ctx.cwd)) {
 			notifyDeprecation(
 				ctx.ui,
 				`.soly/ (legacy)`,
@@ -387,42 +458,13 @@ export default function solyExtension(pi: ExtensionAPI) {
 			}
 		}
 
-		// Auto-install soly user-scope assets (soly-framework skill only,
-		// since 1.3.0 we don't ship a subagent) to ~/.pi/agent/skills/ on
-		// first run. Opt-in via config `agent.useSolyWorkerSubagents`
-		// (kept for backward compat, now a no-op for the skill install).
-		// Idempotent — respects any existing user-customized copies.
-		if (activeConfig.agent.useSolyWorkerSubagents) {
-			const extRoot = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
-			const assets = installSolyAssets(extRoot);
-			const installed = assets.skills.installed.map((s) => `skill:${s}`);
-			if (installed.length > 0) {
-				ctx.ui.notify(
-					`soly: installed (${installed.join(", ")}) — pi will discover on next session`,
-					"info",
-				);
-			}
-			for (const e of assets.skills.errors) {
-				ctx.ui.notify(`soly: install error — ${e}`, "warning");
-			}
-		}
+		// (The soly-framework skill now ships via the package `pi.skills`
+		// manifest — pi discovers it natively, no home-dir copy needed.)
 
 		// Phase-scoped rules: if a phase is currently active, load its
 		// per-phase rules on top of the always-on rule set.
 		reloadPhaseRules();
 
-		// Restore agent from .soly/agent (if present) — survives session restart
-		if (state.exists) {
-			const agentFile = path.join(state.solyDir, "agent");
-			try {
-				if (fs.existsSync(agentFile)) {
-					const raw = fs.readFileSync(agentFile, "utf-8").trim();
-					if (raw && /^[a-zA-Z0-9_-]{1,64}$/.test(raw)) {
-						(globalThis as { __PI_SWITCH_AGENT__?: string }).__PI_SWITCH_AGENT__ = raw;
-					}
-				}
-			} catch { /* best-effort */ }
-		}
 
 		// Capture rule mtimes for the "rules changed since last session" diff
 		captureLastSessionRuleMtimes();
@@ -534,19 +576,45 @@ export default function solyExtension(pi: ExtensionAPI) {
 		}
 
 		updateStatus(ctx);
+
+		// Install the visual chrome (top bar + custom footer + snowflake spinner).
+		chrome.install(ctx.ui);
+		updateChromeData(ctx);
+
+		// Startup header snapshot (version + recent changes + project state).
+		try {
+			const extRoot = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
+			const meta = readWelcomeMeta(extRoot);
+			chrome.setWelcome({
+				version: meta.version,
+				hasProject: state.exists,
+				phaseLabel: phaseLabelFromState(state),
+				nextHint: buildNextHint(state) || null,
+				rulesActive: combinedRules().length,
+				docsCount: intentDocs.length,
+				recent: meta.recent,
+			});
+		} catch {
+			/* header is best-effort; never block session start */
+		}
 	});
 
-	pi.on("session_shutdown", async (_event, _ctx) => {
+	pi.on("session_shutdown", async (_event, ctx) => {
 		// Stop hot-reload watcher — fs.watch handles hold OS resources
 		if (hotReload) {
 			hotReload.stop();
 			hotReload = null;
 		}
+		// Restore pi's native footer/widgets/indicator before teardown
+		chrome.dispose(ctx.ui);
 		// Persist rule mtimes so the next session can show the diff
 		persistRuleMtimes();
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => {
+		// Keep the chrome (ctx%, model, phase) current for the upcoming turn.
+		updateChromeData(ctx);
+
 		const sections: string[] = [];
 		let totalRulesTokens = 0;
 
@@ -590,6 +658,9 @@ export default function solyExtension(pi: ExtensionAPI) {
 			sections.push(integrationSection);
 		}
 
+		// 2.6. Interactive/visual tools pointer (lean — detail lives in the skill).
+		sections.push(SOLY_TOOLS_POINTER);
+
 		// 3.5. Project intent (zero-point docs) — always injected when present
 		if (lastIntentSection) {
 			sections.push(lastIntentSection);
@@ -618,7 +689,19 @@ export default function solyExtension(pi: ExtensionAPI) {
 
 		// 7. Behavioral nudge
 		const heuristics = classifyTaskHeuristics(event.prompt);
-		sections.push(buildNudgeSection(heuristics));
+		sections.push(
+			buildNudgeSection(heuristics, {
+				hasProject: state.exists,
+				confirmBeforeCode: getActiveConfig().agent.confirmBeforeCode,
+			}),
+		);
+
+		// 7.1 Interactive-tool affordance hints (examples → html_artifact, options
+		// → decision_deck, …) — only on turns whose wording mentions them.
+		if (getActiveConfig().agent.toolHints) {
+			const toolHint = buildToolHintSection(detectToolHints(event.prompt));
+			if (toolHint) sections.push(toolHint);
+		}
 
 		// 7.5 Soly drift reminder — injected when the user has been doing
 		// non-soly work for several turns. Throttled: at most once per
@@ -662,7 +745,11 @@ export default function solyExtension(pi: ExtensionAPI) {
 		const angle =
 			heuristics.suggestedAngles[0] ?? "want me to confirm assumptions before I start?";
 
-		notifyNudge(ctx.ui, heuristics.researchHeavy ? "research" : "nonTrivial", angle);
+		// The visible chat box is opt-in (default off — it was noisy). The
+		// system-prompt nudge still guides the LLM on every turn regardless.
+		if (getActiveConfig().agent.nudgeNotify) {
+			notifyNudge(ctx.ui, heuristics.researchHeavy ? "research" : "nonTrivial", angle);
+		}
 		nudgeActiveForTask = true;
 		lastNudgePromptKey = text.slice(0, 200);
 
@@ -719,6 +806,9 @@ export default function solyExtension(pi: ExtensionAPI) {
 			updateStatus(ctx);
 		}
 
+		// Chrome reflects fresh ctx%, session tokens, git dirty count, phase.
+		updateChromeData(ctx);
+
 		// Post-work rules check: surface applicable rules for files edited
 		// in this turn. Tracking is kept silent (no chat notify — user feedback:
 		// "spammy") but data is preserved for /why to show last-turn rule context.
@@ -744,8 +834,34 @@ export default function solyExtension(pi: ExtensionAPI) {
 		}
 	});
 
+	// ============================================================================
+	// Chrome: working-indicator telemetry lifecycle + reactive data refresh
+	// ============================================================================
+	pi.on("agent_start", async (_event, ctx) => {
+		updateChromeData(ctx); // snapshot ctx tokens (↑) before generation starts
+		chrome.startWorking(ctx.ui);
+	});
+
+	pi.on("message_update", async (event, ctx) => {
+		const msg = event.message as { role?: string; usage?: { output?: number } };
+		if (msg.role === "assistant" && typeof msg.usage?.output === "number") {
+			chrome.updateWorking(ctx.ui, msg.usage.output);
+		}
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		chrome.stopWorking(ctx.ui);
+		updateChromeData(ctx);
+	});
+
+	pi.on("model_select", async (_event, ctx) => {
+		updateChromeData(ctx);
+	});
+
 	// Mount built-in sub-features
 	piAskExtension(pi);
+	piDeckExtension(pi);
+	piArtifactExtension(pi, getActiveConfig);
 
 	// MCP adapter (was: separate pi-mcp-adapter plugin by nicobailon).
 	// Bundled into pi-soly as of v1.11.0 with UE5 session-retry fix + framed

package/iteration.ts

@@ -579,16 +579,8 @@ export function buildIterationContent(input: IterationInput): string {
 	}
 
 	if ((input.kind === "plan" || input.kind === "exec") && phaseDir) {
-		// Section 3: Phase CONTEXT
-		const ctxPath = findPhaseContextPath(phaseDir);
-		sections.push("## 3. Phase CONTEXT");
-		sections.push("");
-		sections.push(`_Source: \`${ctxPath ? rel(projectRoot, ctxPath) : "(missing)"}\`_`);
-		sections.push("");
-		sections.push(loadPhaseContext(phaseDir, SECTION_BUDGETS.context));
-		sections.push("");
-
 		// Section 4: Phase RESEARCH
+		// (Section 3 Phase CONTEXT is emitted by the plan|exec|discuss block above.)
 		const resPath = findPhaseResearchPath(phaseDir);
 		sections.push("## 4. Phase RESEARCH");
 		sections.push("");

package/mcp/commands.ts

@@ -58,6 +58,18 @@ export async function showStatus(state: McpExtensionState, ctx: ExtensionContext
     lines.push("Run /mcp setup to adopt imports or scaffold a starter .mcp.json");
   }
 
+  // Tool result cache stats — appended after the per-server list. Hidden if
+  // the cache has not seen any traffic yet (fresh session, no calls made).
+  const cacheStats = state.toolCache?.stats();
+  if (cacheStats && (cacheStats.hits > 0 || cacheStats.misses > 0 || cacheStats.expirations > 0 || cacheStats.size > 0)) {
+    const total = cacheStats.hits + cacheStats.misses;
+    const hitRate = total > 0 ? Math.round((cacheStats.hits / total) * 100) : 0;
+    lines.push("");
+    lines.push(
+      `Cache: ${cacheStats.size} entries · ${cacheStats.hits} hits · ${cacheStats.misses} misses · ${cacheStats.expirations} expired (${hitRate}% hit rate)`,
+    );
+  }
+
   ctx.ui.notify(lines.join("\n"), "info");
 }
 

package/mcp/direct-tools.ts

@@ -12,6 +12,7 @@ import { formatToolName, isToolExcluded } from "./types.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
 import { authenticate, supportsOAuth } from "./mcp-auth-flow.ts";
 import { formatAuthRequiredMessage } from "./utils.ts";
+import { ToolCache, cacheKey } from "./tool-cache.ts";
 
 const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 
@@ -274,9 +275,19 @@ type DirectToolExecute = (
 export function createDirectToolExecutor(
   getState: () => McpExtensionState | null,
   getInitPromise: () => Promise<McpExtensionState> | null,
-  spec: DirectToolSpec
+  spec: DirectToolSpec,
+  cache?: ToolCache,
 ): DirectToolExecute {
   return async function execute(_toolCallId, params) {
+    // Cache fast-path: skip connect/init/auth on hit. UI tools and resources
+    // are never cached (UI has side effects, user asked for tools only).
+    if (cache && !spec.resourceUri && !spec.uiResourceUri) {
+      const hit = cache.get(cacheKey(spec.serverName, spec.originalName, params));
+      if (hit !== undefined) {
+        return hit as Awaited<ReturnType<DirectToolExecute>>;
+      }
+    }
+
     let state = getState();
     const initPromise = getInitPromise();
 
@@ -402,10 +413,16 @@ export function createDirectToolExecutor(
         };
       }
 
-      return {
+      const successResult: Awaited<ReturnType<DirectToolExecute>> = {
         content: content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }],
         details: { server: spec.serverName, tool: spec.originalName },
       };
+      // Cache only plain (non-UI) tool success; resources and UI tools are
+      // never cached (see fast-path above for the matching skip condition).
+      if (cache) {
+        cache.set(cacheKey(spec.serverName, spec.originalName, params), successResult);
+      }
+      return successResult;
     } catch (error) {
       if (error instanceof UrlElicitationRequiredError) {
         const action = await state.manager.handleUrlElicitationRequired(spec.serverName, error);