@d3ara1n/pi-scout 0.1.0 → 1.0.0

package/README.md

@@ -9,6 +9,32 @@ Before each conversation turn, a cheap side agent model analyzes the user's prom
 
 Both modules can be independently toggled on/off.
 
+## Why model-router is disabled by default
+
+Model-router switches the active model role based on task complexity, which can:
+
+- **Break prompt caching**: Different models don't share cache, causing cache write costs on each switch
+- **Increase API costs**: Frequent model switching adds ~118% overhead in typical workloads
+- **Reduce performance**: Cache misses mean re-uploading system prompt and tools each time
+
+We recommend keeping model-router disabled unless you specifically need it. Enable it via:
+
+```bash
+/scout:model-router on        # Temporary (current session)
+```
+
+Or add to `settings.json` for persistent enablement:
+
+```jsonc
+{
+  "scout": {
+    "modules": {
+      "modelRouter": true
+    }
+  }
+}
+```
+
 ## How it works
 
 ```
@@ -27,7 +53,7 @@ before_agent_start hook fires
 ## Requirements
 
 - **@d3ara1n/pi-model-roles** must be installed and configured
-- A cheap role must be defined in `modelRoles` configuration or use default(may be much more expansive) instead
+- A cheap role must be defined in `modelRoles` configuration or use the default (may be much more expensive) instead
 
 ## Installation
 
@@ -47,7 +73,7 @@ Edit `~/.pi/agent/settings.json`:
     "maxSelectedSkills": 5,
     "modules": {
       "skillRouter": true,
-      "modelRouter": true
+      "modelRouter": false
     }
   }
 }
@@ -56,18 +82,18 @@ Edit `~/.pi/agent/settings.json`:
 | Field | Default | Description |
 |-------|---------|-------------|
 | `enabled` | `true` | Global on/off |
-| `sideAgentRole` | `"fast"` | pi-model-roles role for the side agent |
+| `sideAgentRole` | `"utility"` | pi-model-roles role for the side agent |
 | `maxSelectedSkills` | `5` | Max skills the side agent can select |
 | `modules.skillRouter` | `true` | Enable/disable skill routing |
-| `modules.modelRouter` | `true` | Enable/disable model routing |
+| `modules.modelRouter` | `false` | Enable/disable model routing (disabled by default to avoid cache inefficiency and extra costs) |
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `/scout` | Show scout status and last decision |
-| `/scout skill-router on/off` | Toggle skill-router module |
-| `/scout model-router on/off` | Toggle model-router module |
+| `/scout:skill-router on/off` | Toggle skill-router module |
+| `/scout:model-router on/off` | Toggle model-router module |
 
 ## Performance
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@d3ara1n/pi-scout",
-  "version": "0.1.0",
+  "version": "1.0.0",
+  "type": "module",
   "description": "Per-turn side agent decision framework for pi — uses a cheap model to select skills and route models before each conversation turn",
   "main": "src/index.ts",
   "keywords": [

package/src/index.ts

@@ -17,7 +17,7 @@ import type { ScoutConfig, ScoutDecision } from "./types.ts";
 import { DEFAULT_CONFIG } from "./types.ts";
 import { loadScoutConfig } from "./config.ts";
 import { callSideAgent } from "./side-agent.ts";
-import { buildScoutSystemPrompt } from "./scout-prompt.ts";
+import { buildScoutSystemPrompt, buildScoutUserMessage } from "./scout-prompt.ts";
 import { filterSkillsBlock, resetSkillCache } from "./skill-inject.ts";
 import { switchToRole } from "./model-switch.ts";
 
@@ -48,6 +48,9 @@ export default function scoutExtension(pi: ExtensionAPI) {
 	let config: ScoutConfig = DEFAULT_CONFIG;
 	let lastDecision: ScoutDecision | undefined;
 
+	/** Cache of previous turn context for better routing decisions. */
+	let prevTurn: { userPrompt: string; assistantSummary: string } | undefined;
+
 	function tryGetRolesApi(ctx: ExtensionContext): ModelRolesAPI | undefined {
 		try {
 			return getModelRolesAPI();
@@ -132,10 +135,10 @@ export default function scoutExtension(pi: ExtensionAPI) {
 		parameters: { type: "object", properties: {}, required: [] } as any,
 		async execute() {
 			if (cachedAllSkills.length === 0) {
-				return { content: [{ type: "text", text: "No skills available." }] };
+				return { content: [{ type: "text", text: "No skills available." }], details: undefined as any };
 			}
 			const lines = cachedAllSkills.map((s) => `- **${s.name}**: ${s.description}`);
-			return { content: [{ type: "text", text: lines.join("\n") }] };
+			return { content: [{ type: "text", text: lines.join("\n") }], details: undefined as any };
 		},
 	});
 
@@ -143,11 +146,35 @@ export default function scoutExtension(pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		config = loadScoutConfig(ctx.cwd);
 		resetSkillCache();
+		prevTurn = undefined;
 	});
 
-	// ── Clear status at turn start ──────────────────────────────────
-	pi.on("turn_start", async () => {
-		// Will be overwritten by before_agent_start if scout runs
+	// ── turn_end: cache assistant response for next turn's context ──
+	pi.on("turn_end", async (event) => {
+		const msg = event.message;
+		if (msg.role !== "assistant") return;
+
+		// Extract text content, skip thinking blocks and tool calls
+		const textParts: string[] = [];
+		for (const block of msg.content) {
+			if ("type" in block && block.type === "text" && "text" in block) {
+				textParts.push(block.text);
+			}
+		}
+		const fullText = textParts.join("");
+		if (!fullText.trim()) return;
+
+		// Truncate to avoid bloating the side agent context
+		const MAX_SUMMARY = 500;
+		const assistantSummary = fullText.length > MAX_SUMMARY
+			? fullText.slice(0, MAX_SUMMARY) + "..."
+			: fullText;
+
+		// before_agent_start already created/updated prevTurn with the user prompt.
+		// We just fill in the assistant summary here.
+		if (prevTurn) {
+			prevTurn.assistantSummary = assistantSummary;
+		}
 	});
 
 	// ── before_agent_start: core scout logic ────────────────────────
@@ -198,29 +225,43 @@ export default function scoutExtension(pi: ExtensionAPI) {
 			? (rolesApi.findRoleByModel(`${currentModel.provider}/${currentModel.id}`) ?? "unknown")
 			: "unknown";
 
-		// 3. Call side agent
-		const scoutSystemPrompt = buildScoutSystemPrompt(config);
+		// 3. Build roles list
 		const visibleRoles = rolesApi.getVisibleRoles();
 		const rolesList = Object.entries(visibleRoles)
 			.map(([name, cfg]: [string, any]) => `- ${name}: ${cfg.description ?? "(no description)"}${cfg.model ? ` (model: ${cfg.model})` : " (current model)"}`)
 			.join("\n");
+
+		// 4. Build user message with conversation context
+		const prevTurnContext = prevTurn?.assistantSummary
+			? { userPrompt: prevTurn.userPrompt, assistantSummary: prevTurn.assistantSummary }
+			: undefined;
+		const userMessage = buildScoutUserMessage(event.prompt, currentRole, prevTurnContext);
+
+		// Reset prevTurn for the current turn — user prompt now, assistant filled by turn_end
+		prevTurn = { userPrompt: event.prompt, assistantSummary: "" };
+
+		// 5. Call side agent
+		const scoutSystemPrompt = buildScoutSystemPrompt(config, skillsList, rolesList);
 		const decision = await callSideAgent(
 			sideResolved.model,
 			sideResolved.apiKey,
 			sideResolved.headers,
 			scoutSystemPrompt,
-			event.prompt,
-			skillsList,
-			currentRole,
-			rolesList,
+			userMessage,
 		);
 
+		// Enforce module toggles at the application layer, regardless of what
+		// the side agent returned. A disabled module's decision field is zeroed
+		// so the status bar, /scout command, and apply logic all see clean
+		// values (no misleading "→ fast" when model-router is off).
+		if (!config.modules.modelRouter) decision.role = null;
+		if (!config.modules.skillRouter) decision.skills = [];
 		lastDecision = decision;
 
 		let systemPrompt = event.systemPrompt;
 		let switchedRole: string | undefined;
 
-		// 4. skill-router: filter skills XML to only selected ones
+		// 6. skill-router: filter skills XML to only selected ones
 		if (config.modules.skillRouter) {
 			systemPrompt = filterSkillsBlock(
 				systemPrompt,
@@ -229,7 +270,7 @@ export default function scoutExtension(pi: ExtensionAPI) {
 			);
 		}
 
-		// 5. model-router: switch model if side agent recommends a different role
+		// 7. model-router: switch model if side agent recommends a different role
 		if (config.modules.modelRouter && decision.role && decision.role !== currentRole) {
 			const switched = await switchToRole(pi, decision.role, rolesApi);
 			if (switched) {
@@ -241,10 +282,10 @@ export default function scoutExtension(pi: ExtensionAPI) {
 			}
 		}
 
-		// 6. Show result in status bar
+		// 8. Show result in status bar
 		ctx.ui.setStatus(STATUS_KEY, formatDecisionStatus(decision, theme));
 
-		// 7. Return modified system prompt
+		// 9. Return modified system prompt
 		if (systemPrompt !== event.systemPrompt) {
 			return { systemPrompt };
 		}

package/src/scout-prompt.ts

@@ -1,36 +1,61 @@
 /**
- * Side agent system prompt — instructs the model to return a structured JSON decision.
+ * Side agent prompt construction — system prompt and user message.
  */
 
 import type { ScoutConfig } from "./types.ts";
 
+/** Previous turn context for better routing decisions. */
+export interface PrevTurnContext {
+	userPrompt: string;
+	assistantSummary: string;
+}
+
 /**
  * Build the user message for the side agent.
+ *
+ * Includes previous turn context (when available) so the side agent can
+ * understand follow-up prompts like "continue", "change that", etc.
  */
 export function buildScoutUserMessage(
 	userPrompt: string,
-	skillsList: string,
 	currentRole: string,
-	rolesList: string,
+	prevTurn?: PrevTurnContext,
 ): string {
-	return [
-		`User prompt:`,
-		userPrompt,
-		``,
-		`Available skills:`,
-		skillsList || "(none)",
-		``,
-		`Current role: ${currentRole}`,
-		``,
-		`Available roles:`,
-		rolesList,
-	].join("\n");
+	const parts: string[] = [];
+
+	parts.push(`Current role: ${currentRole}`);
+
+	if (prevTurn && (prevTurn.userPrompt || prevTurn.assistantSummary)) {
+		parts.push(``);
+		parts.push(`## Previous Turn`);
+		if (prevTurn.userPrompt) {
+			parts.push(`User: ${prevTurn.userPrompt}`);
+		}
+		if (prevTurn.assistantSummary) {
+			parts.push(`Assistant: ${prevTurn.assistantSummary}`);
+		}
+	}
+
+	parts.push(``);
+	parts.push(`## Current User Prompt`);
+	parts.push(userPrompt);
+
+	return parts.join("\n");
 }
 
 /**
  * Build the system prompt for the side agent.
+ *
+ * Stable per-session data (skills, roles) is embedded here rather than in the
+ * user message so that the entire system prompt forms a large, cacheable prefix.
+ * This is critical for Anthropic which requires a 1024-token minimum for
+ * prompt caching to activate.
  */
-export function buildScoutSystemPrompt(config: ScoutConfig): string {
+export function buildScoutSystemPrompt(
+	config: ScoutConfig,
+	skillsList: string,
+	rolesList: string,
+): string {
 	const parts: string[] = [];
 
 	parts.push(`You are a scout. Analyze the user's request and decide which skills and model role to use.`);
@@ -50,13 +75,24 @@ export function buildScoutSystemPrompt(config: ScoutConfig): string {
 	parts.push(`- "role" should be null if the current role is appropriate.`);
 	parts.push(`- Only suggest a role change when the task clearly benefits from a different model.`);
 	parts.push(`- Be conservative: prefer fewer skills and no role change when uncertain.`);
+	parts.push(`- Use the Previous Turn context to understand follow-up requests (e.g. "continue", "change that", "no, the other one").`);
 
-	if (!config.modules.modelRouter) {
-		parts.push(`- IMPORTANT: model routing is disabled. Always return role: null.`);
+	// Stable prefix ends here. Sections below are injected conditionally per
+	// module toggle: a disabled module contributes no candidates, so the side
+	// agent has nothing to choose from for it (and the application layer zeros
+	// out its field regardless). The longer section (skills) comes first so
+	// toggling the later module (roles) only invalidates the cache tail —
+	// Anthropic prefix-cache matches the longest common prefix.
+	if (config.modules.skillRouter) {
+		parts.push(``);
+		parts.push(`## Available Skills`);
+		parts.push(skillsList || "(none)");
 	}
 
-	if (!config.modules.skillRouter) {
-		parts.push(`- IMPORTANT: skill routing is disabled. Always return skills: [].`);
+	if (config.modules.modelRouter) {
+		parts.push(``);
+		parts.push(`## Available Roles`);
+		parts.push(rolesList);
 	}
 
 	return parts.join("\n");

package/src/side-agent.ts

@@ -7,12 +7,11 @@
 
 import { complete } from "@earendil-works/pi-ai";
 import type { ScoutDecision } from "./types.ts";
-import { buildScoutUserMessage } from "./scout-prompt.ts";
 
-/** Minimal type for side agent context — avoids importing pi-ai types directly. */
+/** Minimal type for side agent context — matches pi-ai's Context interface. */
 interface SideAgentContext {
 	systemPrompt?: string;
-	messages: Array<{ role: string; content: string }>;
+	messages: Array<{ role: "user"; content: string; timestamp: number }>;
 }
 
 /**
@@ -21,10 +20,8 @@ interface SideAgentContext {
  * @param sideModel - The Model instance to use (from pi-model-roles "side" role)
  * @param apiKey - API key for the side model
  * @param headers - Custom headers for the side model
- * @param systemPrompt - Scout system prompt
- * @param userPrompt - The user's original prompt text
- * @param skillsList - Formatted list of available skills for the prompt
- * @param currentRole - Current active role name
+ * @param systemPrompt - Scout system prompt (includes skills/roles for cache friendliness)
+ * @param userMessage - Fully assembled user message (includes context, current role, user prompt)
  * @returns Parsed ScoutDecision, or a safe fallback on error
  */
 export async function callSideAgent(
@@ -32,10 +29,7 @@ export async function callSideAgent(
 	apiKey: string | undefined,
 	headers: Record<string, string> | undefined,
 	systemPrompt: string,
-	userPrompt: string,
-	skillsList: string,
-	currentRole: string,
-	rolesList: string,
+	userMessage: string,
 ): Promise<ScoutDecision> {
 	const fallback: ScoutDecision = { skills: [], role: null, reasoning: "side agent error" };
 
@@ -44,13 +38,15 @@ export async function callSideAgent(
 		messages: [
 			{
 				role: "user",
-				content: buildScoutUserMessage(userPrompt, skillsList, currentRole, rolesList),
+				content: userMessage,
+				timestamp: Date.now(),
 			},
 		],
 	};
 
 	const options: Record<string, any> = {
 		maxTokens: 256,
+		cacheRetention: "short",
 	};
 
 	if (apiKey) options.apiKey = apiKey;

package/src/types.ts

@@ -29,10 +29,10 @@ export interface ScoutDecision {
 
 export const DEFAULT_CONFIG: ScoutConfig = {
   enabled: true,
-  sideAgentRole: "fast",
+  sideAgentRole: "utility",
   maxSelectedSkills: 5,
   modules: {
     skillRouter: true,
-    modelRouter: true,
+    modelRouter: false,
   },
 };