@d3ara1n/pi-scout 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @d3ara1n/pi-scout
+
+Per-turn side agent decision framework for [pi](https://github.com/earendil-works/pi).
+
+Before each conversation turn, a cheap side agent model analyzes the user's prompt and makes routing decisions:
+
+1. **skill-router** — Selects which skills to activate and injects their full content (replacing pi's default skill metadata list)
+2. **model-router** — Automatically switches the active model role based on task complexity
+
+Both modules can be independently toggled on/off.
+
+## How it works
+
+```
+User sends prompt
+    │
+    ▼
+before_agent_start hook fires
+    │
+    ├─ Side agent (cheap model) analyzes prompt + available skills + current role
+    ├─ Returns: { skills: [...], role: "...", reasoning: "..." }
+    │
+    ├─ [skill-router] Strips <available_skills> XML, injects selected skill SKILL.md content
+    └─ [model-router] Switches model if a different role is recommended
+```
+
+## 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
+
+## Installation
+
+```bash
+pi extension add @d3ara1n/pi-scout
+```
+
+## Configuration
+
+Edit `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "scout": {
+    "enabled": true,
+    "sideAgentRole": "fast",
+    "maxSelectedSkills": 5,
+    "modules": {
+      "skillRouter": true,
+      "modelRouter": true
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `true` | Global on/off |
+| `sideAgentRole` | `"fast"` | 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 |
+
+## 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 |
+
+## Performance
+
+Side agent adds ~0.5–2s latency per turn. Output is limited to 256 tokens.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@d3ara1n/pi-scout",
+  "version": "0.1.0",
+  "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": [
+    "pi-package",
+    "pi"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@d3ara1n/pi-model-roles": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@d3ara1n/pi-model-roles": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@d3ara1n/pi-model-roles": "^0.1.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/d3ara1n/pi-extensions",
+    "directory": "packages/pi-scout"
+  },
+  "license": "MIT"
+}

package/src/config.ts

@@ -0,0 +1,68 @@
+/**
+ * Read scout configuration from settings files.
+ *
+ * Global (~/.pi/agent/settings.json) + project (.pi/settings.json),
+ * project overrides global.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ScoutConfig } from "./types.ts";
+import { DEFAULT_CONFIG } from "./types.ts";
+
+function getAgentDir(): string {
+	const envDir = process.env.PI_AGENT_DIR;
+	if (envDir) return envDir;
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+function readSettingsFile(filePath: string): any {
+	try {
+		if (!fs.existsSync(filePath)) return {};
+		const content = fs.readFileSync(filePath, "utf-8");
+		const stripped = content.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+		return JSON.parse(stripped);
+	} catch {
+		return {};
+	}
+}
+
+function merge(target: any, source: any): any {
+	if (!source || typeof source !== "object") return target;
+	if (!target || typeof target !== "object") return source;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
+			result[key] = merge(result[key], source[key]);
+		} else {
+			result[key] = source[key];
+		}
+	}
+	return result;
+}
+
+/**
+ * Load scout config from merged settings.
+ * @param cwd - Project working directory
+ */
+export function loadScoutConfig(cwd?: string): ScoutConfig {
+	const globalSettings = readSettingsFile(path.join(getAgentDir(), "settings.json"));
+	const projectSettings = cwd
+		? readSettingsFile(path.join(cwd, ".pi", "settings.json"))
+		: {};
+	const settings = merge(globalSettings, projectSettings);
+
+	const raw = settings?.scout;
+	if (!raw) return DEFAULT_CONFIG;
+
+	return {
+		enabled: raw.enabled ?? DEFAULT_CONFIG.enabled,
+		sideAgentRole: raw.sideAgentRole ?? DEFAULT_CONFIG.sideAgentRole,
+		maxSelectedSkills: raw.maxSelectedSkills ?? DEFAULT_CONFIG.maxSelectedSkills,
+		modules: {
+			skillRouter: raw.modules?.skillRouter ?? DEFAULT_CONFIG.modules.skillRouter,
+			modelRouter: raw.modules?.modelRouter ?? DEFAULT_CONFIG.modules.modelRouter,
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,252 @@
+/**
+ * pi-scout — Per-turn side agent decision framework.
+ *
+ * Before each conversation turn, a cheap side agent model analyzes the user prompt
+ * and decides:
+ * 1. Which skills to inject (skill-router module)
+ * 2. Whether to switch model roles (model-router module)
+ *
+ * Both modules can be independently toggled via /scout:* commands.
+ * Scout progress and results are shown in the status bar.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelRolesAPI } from "@d3ara1n/pi-model-roles";
+import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
+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 { filterSkillsBlock, resetSkillCache } from "./skill-inject.ts";
+import { switchToRole } from "./model-switch.ts";
+
+const STATUS_KEY = "scout";
+
+/** Build a one-line status summary from a scout decision. */
+function formatDecisionStatus(decision: ScoutDecision, theme: any): string {
+	const parts: string[] = [];
+
+	if (decision.skills.length > 0) {
+		const names = decision.skills.length <= 3
+			? decision.skills.join(", ")
+			: `${decision.skills.slice(0, 2).join(", ")} +${decision.skills.length - 2}`;
+		parts.push(theme.fg("accent", `skills: ${names}`));
+	}
+	if (decision.role) {
+		parts.push(theme.fg("warning", `→ ${decision.role}`));
+	}
+
+	if (parts.length === 0) {
+		return theme.fg("dim", "✓ scout: no changes");
+	}
+
+	return theme.fg("success", "✓ scout:") + " " + parts.join(" | ");
+}
+
+export default function scoutExtension(pi: ExtensionAPI) {
+	let config: ScoutConfig = DEFAULT_CONFIG;
+	let lastDecision: ScoutDecision | undefined;
+
+	function tryGetRolesApi(ctx: ExtensionContext): ModelRolesAPI | undefined {
+		try {
+			return getModelRolesAPI();
+		} catch {
+			ctx.ui.notify(
+				"pi-model-roles not loaded. Ensure @d3ara1n/pi-model-roles is in extensions and restart.",
+				"error",
+			);
+			return undefined;
+		}
+	}
+
+	// ── /scout — show status ────────────────────────────────────────
+	pi.registerCommand("scout", {
+		description: "Show scout status and last decision",
+		handler: async (_args, ctx) => {
+			const rolesApi = tryGetRolesApi(ctx);
+			const sideRole = rolesApi?.getRole(config.sideAgentRole);
+			const theme = ctx.ui.theme;
+			const lines = [
+				`Scout: ${config.enabled ? "enabled" : "disabled"}`,
+				`Side agent role: ${config.sideAgentRole} (${sideRole?.model ?? "current model"})`,
+				``,
+				`Modules:`,
+				`  skill-router: ${config.modules.skillRouter ? "on" : "off"}`,
+				`  model-router: ${config.modules.modelRouter ? "on" : "off"}`,
+			];
+
+			if (lastDecision) {
+				lines.push(``);
+				lines.push(`Last decision:`);
+				lines.push(`  skills: ${lastDecision.skills.length > 0 ? lastDecision.skills.join(", ") : "(none)"}`);
+				lines.push(`  role: ${lastDecision.role ?? "(no change)"}`);
+				lines.push(`  reasoning: ${lastDecision.reasoning}`);
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	// ── /scout:skill-router on/off ──────────────────────────────────
+	pi.registerCommand("scout:skill-router", {
+		description: "Toggle skill-router module (on/off)",
+		handler: async (args, ctx) => {
+			const value = (args ?? "").trim().toLowerCase();
+			if (value === "on") {
+				config.modules.skillRouter = true;
+				ctx.ui.notify("Scout: skill-router enabled", "info");
+			} else if (value === "off") {
+				config.modules.skillRouter = false;
+				ctx.ui.notify("Scout: skill-router disabled", "info");
+			} else {
+				ctx.ui.notify("Usage: /scout:skill-router on|off", "info");
+			}
+		},
+	});
+
+	// ── /scout:model-router on/off ──────────────────────────────────
+	pi.registerCommand("scout:model-router", {
+		description: "Toggle model-router module (on/off)",
+		handler: async (args, ctx) => {
+			const value = (args ?? "").trim().toLowerCase();
+			if (value === "on") {
+				config.modules.modelRouter = true;
+				ctx.ui.notify("Scout: model-router enabled", "info");
+			} else if (value === "off") {
+				config.modules.modelRouter = false;
+				ctx.ui.notify("Scout: model-router disabled", "info");
+			} else {
+				ctx.ui.notify("Usage: /scout:model-router on|off", "info");
+			}
+		},
+	});
+
+	// ── list_skills tool ───────────────────────────────────────────
+	let cachedAllSkills: Array<{ name: string; description: string; filePath: string }> = [];
+
+	pi.registerTool({
+		name: "list_skills",
+		label: "List all skills",
+		description: "List all available skills with name and description. Use this when the user asks what skills are installed or you need to discover skills beyond those currently active.",
+		parameters: { type: "object", properties: {}, required: [] } as any,
+		async execute() {
+			if (cachedAllSkills.length === 0) {
+				return { content: [{ type: "text", text: "No skills available." }] };
+			}
+			const lines = cachedAllSkills.map((s) => `- **${s.name}**: ${s.description}`);
+			return { content: [{ type: "text", text: lines.join("\n") }] };
+		},
+	});
+
+	// ── session_start: load config ──────────────────────────────────
+	pi.on("session_start", async (_event, ctx) => {
+		config = loadScoutConfig(ctx.cwd);
+		resetSkillCache();
+	});
+
+	// ── Clear status at turn start ──────────────────────────────────
+	pi.on("turn_start", async () => {
+		// Will be overwritten by before_agent_start if scout runs
+	});
+
+	// ── before_agent_start: core scout logic ────────────────────────
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!config.enabled) return;
+		if (!config.modules.skillRouter && !config.modules.modelRouter) return;
+
+		let rolesApi: ModelRolesAPI;
+		try {
+			rolesApi = getModelRolesAPI();
+		} catch {
+			console.warn("[pi-scout] pi-model-roles not initialized — skipping scout");
+			return;
+		}
+
+		const theme = ctx.ui.theme;
+
+		// Show "Scouting..." indicator
+		ctx.ui.setStatus(STATUS_KEY, theme.fg("accent", "◎") + theme.fg("dim", " Scouting..."));
+
+		// Resolve side agent model
+		const sideResolved = await rolesApi.resolveRoleAsync(config.sideAgentRole);
+		if (!sideResolved.model) {
+			ctx.ui.setStatus(STATUS_KEY, theme.fg("warning", "◎ scout: side model unavailable"));
+			console.warn(`[pi-scout] Side agent role "${config.sideAgentRole}" not available — skipping`);
+			return;
+		}
+
+		// Update status: resolving
+		ctx.ui.setStatus(STATUS_KEY, theme.fg("accent", "◎") + theme.fg("dim", ` Scouting via ${sideResolved.model.provider}/${sideResolved.model.id}...`));
+
+		// 1. Get available skills from systemPromptOptions
+		const skills = event.systemPromptOptions?.skills ?? [];
+		if (cachedAllSkills.length === 0 && skills.length > 0) {
+			cachedAllSkills = skills.map((s: any) => ({
+				name: s.name,
+				description: s.description ?? "",
+				filePath: s.filePath,
+			}));
+		}
+		const skillsList = skills
+			.map((s: any) => `- ${s.name}: ${s.description ?? "(no description)"}`)
+			.join("\n");
+
+		// 2. Determine current role
+		const currentModel = ctx.model;
+		const currentRole = currentModel
+			? (rolesApi.findRoleByModel(`${currentModel.provider}/${currentModel.id}`) ?? "unknown")
+			: "unknown";
+
+		// 3. Call side agent
+		const scoutSystemPrompt = buildScoutSystemPrompt(config);
+		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");
+		const decision = await callSideAgent(
+			sideResolved.model,
+			sideResolved.apiKey,
+			sideResolved.headers,
+			scoutSystemPrompt,
+			event.prompt,
+			skillsList,
+			currentRole,
+			rolesList,
+		);
+
+		lastDecision = decision;
+
+		let systemPrompt = event.systemPrompt;
+		let switchedRole: string | undefined;
+
+		// 4. skill-router: filter skills XML to only selected ones
+		if (config.modules.skillRouter) {
+			systemPrompt = filterSkillsBlock(
+				systemPrompt,
+				decision.skills,
+				skills.map((s: any) => ({ name: s.name, description: s.description ?? "", filePath: s.filePath })),
+			);
+		}
+
+		// 5. 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) {
+				switchedRole = decision.role;
+				const newModel = await rolesApi.resolveRoleAsync(decision.role);
+				if (newModel?.model) {
+					systemPrompt += `\n\n<current_model>${newModel.model.provider}/${newModel.model.id} (role: ${decision.role})</current_model>`;
+				}
+			}
+		}
+
+		// 6. Show result in status bar
+		ctx.ui.setStatus(STATUS_KEY, formatDecisionStatus(decision, theme));
+
+		// 7. Return modified system prompt
+		if (systemPrompt !== event.systemPrompt) {
+			return { systemPrompt };
+		}
+	});
+}

package/src/model-switch.ts

@@ -0,0 +1,37 @@
+/**
+ * Model role switching logic.
+ *
+ * Caller only needs to check resolved.model — it's always a real model or undefined.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ModelRolesAPI } from "@d3ara1n/pi-model-roles";
+
+/**
+ * Switch the active model to the given role.
+ * @returns true if the switch was successful
+ */
+export async function switchToRole(
+	pi: ExtensionAPI,
+	roleName: string,
+	rolesApi: ModelRolesAPI,
+): Promise<boolean> {
+	const resolved = await rolesApi.resolveRoleAsync(roleName);
+
+	if (!resolved.model) {
+		console.warn(`[pi-scout] Role "${roleName}" could not be resolved — model not available`);
+		return false;
+	}
+
+	const success = await pi.setModel(resolved.model);
+	if (!success) {
+		console.warn(`[pi-scout] setModel() returned false for role "${roleName}" — no API key?`);
+		return false;
+	}
+
+	if (resolved.config.thinking) {
+		pi.setThinkingLevel(resolved.config.thinking);
+	}
+
+	return true;
+}

package/src/scout-prompt.ts

@@ -0,0 +1,63 @@
+/**
+ * Side agent system prompt — instructs the model to return a structured JSON decision.
+ */
+
+import type { ScoutConfig } from "./types.ts";
+
+/**
+ * Build the user message for the side agent.
+ */
+export function buildScoutUserMessage(
+	userPrompt: string,
+	skillsList: string,
+	currentRole: string,
+	rolesList: string,
+): string {
+	return [
+		`User prompt:`,
+		userPrompt,
+		``,
+		`Available skills:`,
+		skillsList || "(none)",
+		``,
+		`Current role: ${currentRole}`,
+		``,
+		`Available roles:`,
+		rolesList,
+	].join("\n");
+}
+
+/**
+ * Build the system prompt for the side agent.
+ */
+export function buildScoutSystemPrompt(config: ScoutConfig): string {
+	const parts: string[] = [];
+
+	parts.push(`You are a scout. Analyze the user's request and decide which skills and model role to use.`);
+	parts.push(``);
+	parts.push(`## Response Format`);
+	parts.push(`Respond with ONLY a JSON object, no markdown, no explanation outside the JSON:`);
+	parts.push(`{`);
+	parts.push(`  "skills": ["skill-name-1", "skill-name-2"],`);
+	parts.push(`  "role": "role-name-or-null",`);
+	parts.push(`  "reasoning": "one sentence explanation"`);
+	parts.push(`}`);
+	parts.push(``);
+	parts.push(`## Rules`);
+	parts.push(`- Select at most ${config.maxSelectedSkills} skills. Select 0 if none are relevant.`);
+	parts.push(`- Only select skills that will materially help with the task.`);
+	parts.push(`- If the task is trivial (simple question, acknowledgment), select 0 skills.`);
+	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.`);
+
+	if (!config.modules.modelRouter) {
+		parts.push(`- IMPORTANT: model routing is disabled. Always return role: null.`);
+	}
+
+	if (!config.modules.skillRouter) {
+		parts.push(`- IMPORTANT: skill routing is disabled. Always return skills: [].`);
+	}
+
+	return parts.join("\n");
+}

package/src/side-agent.ts

@@ -0,0 +1,104 @@
+/**
+ * Side agent invocation logic.
+ *
+ * Calls the side agent model using pi-ai's complete() function
+ * and parses the JSON decision response.
+ */
+
+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. */
+interface SideAgentContext {
+	systemPrompt?: string;
+	messages: Array<{ role: string; content: string }>;
+}
+
+/**
+ * Call the side agent and return its decision.
+ *
+ * @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
+ * @returns Parsed ScoutDecision, or a safe fallback on error
+ */
+export async function callSideAgent(
+	sideModel: any,
+	apiKey: string | undefined,
+	headers: Record<string, string> | undefined,
+	systemPrompt: string,
+	userPrompt: string,
+	skillsList: string,
+	currentRole: string,
+	rolesList: string,
+): Promise<ScoutDecision> {
+	const fallback: ScoutDecision = { skills: [], role: null, reasoning: "side agent error" };
+
+	const context: SideAgentContext = {
+		systemPrompt,
+		messages: [
+			{
+				role: "user",
+				content: buildScoutUserMessage(userPrompt, skillsList, currentRole, rolesList),
+			},
+		],
+	};
+
+	const options: Record<string, any> = {
+		maxTokens: 256,
+	};
+
+	if (apiKey) options.apiKey = apiKey;
+	if (headers) options.headers = headers;
+
+	try {
+		const result = await complete(sideModel, context, options);
+		const text = result.content
+			?.filter((block: any) => block.type === "text")
+			?.map((block: any) => block.text)
+			?.join("") ?? "";
+
+		return parseDecision(text);
+	} catch (err) {
+		console.warn("[pi-scout] Side agent call failed:", err);
+		return fallback;
+	}
+}
+
+/**
+ * Parse the side agent's JSON response into a ScoutDecision.
+ * Tolerant of markdown wrapping, extra whitespace, etc.
+ */
+function parseDecision(raw: string): ScoutDecision {
+	const fallback: ScoutDecision = { skills: [], role: null, reasoning: "parse error" };
+
+	// Strip markdown code fences if present
+	let text = raw.trim();
+	if (text.startsWith("```")) {
+		text = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
+	}
+
+	try {
+		const parsed = JSON.parse(text);
+
+		return {
+			skills: Array.isArray(parsed.skills)
+				? parsed.skills.filter((s: any) => typeof s === "string")
+				: [],
+			role: typeof parsed.role === "string" && parsed.role !== "null"
+				? parsed.role
+				: null,
+			reasoning: typeof parsed.reasoning === "string"
+				? parsed.reasoning
+				: "no reasoning provided",
+		};
+	} catch {
+		console.warn("[pi-scout] Failed to parse side agent response:", raw.slice(0, 200));
+		return fallback;
+	}
+}

package/src/skill-inject.ts

@@ -0,0 +1,83 @@
+/**
+ * Skill interception and injection with description caching.
+ *
+ * Replaces pi's default skills section (verbose intro + all skills)
+ * with a compact version containing only scout-selected skills.
+ *
+ * Description caching: skills already shown in a previous turn omit
+ * their description (the LLM already has it in conversation history).
+ * This significantly reduces per-turn token usage for recurring skills.
+ */
+
+/** Match pi's entire skills section: intro paragraph + XML block. */
+const SKILLS_SECTION_RE = /\n\nThe following skills provide specialized instructions[\s\S]*?<\/available_skills>/;
+
+/** Track skill names already shown to the LLM in this session. */
+let shownSkills: Set<string> = new Set();
+
+/** Reset the cache — called on session_start. */
+export function resetSkillCache(): void {
+	shownSkills = new Set();
+}
+
+/**
+ * Replace pi's default skills section with a compact, cached version.
+ *
+ * - First appearance of a skill: includes description
+ * - Subsequent appearances: description omitted (LLM already has it)
+ * - No skills selected: entire section removed
+ *
+ * @param systemPrompt - Full system prompt
+ * @param selectedSkills - Skill names chosen by the side agent
+ * @param allSkills - All loaded skills with their metadata
+ * @returns Modified system prompt
+ */
+export function filterSkillsBlock(
+	systemPrompt: string,
+	selectedSkills: string[],
+	allSkills: Array<{ name: string; description: string; filePath: string }>,
+): string {
+	if (selectedSkills.length === 0) {
+		return systemPrompt.replace(SKILLS_SECTION_RE, "");
+	}
+
+	const skillMap = new Map(allSkills.map((s) => [s.name, s]));
+	const entries: string[] = [];
+	const newlyShown: string[] = [];
+
+	for (const name of selectedSkills) {
+		const skill = skillMap.get(name);
+		if (!skill) continue;
+
+		if (shownSkills.has(name)) {
+			// Already introduced — compact form
+			entries.push(`  <skill name="${esc(skill.name)}" location="${esc(skill.filePath)}" />`);
+		} else {
+			// First time — include description
+			entries.push(`  <skill name="${esc(skill.name)}" location="${esc(skill.filePath)}">${esc(skill.description)}</skill>`);
+			newlyShown.push(name);
+		}
+	}
+
+	if (entries.length === 0) {
+		return systemPrompt.replace(SKILLS_SECTION_RE, "");
+	}
+
+	// Update cache
+	for (const name of newlyShown) {
+		shownSkills.add(name);
+	}
+
+	const compact = `\n\nActive skills (use \`read\` to load a skill's file):\n<available_skills>\n${entries.join("\n")}\n</available_skills>`;
+
+	return systemPrompt.replace(SKILLS_SECTION_RE, compact);
+}
+
+function esc(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared types for pi-scout.
+ */
+
+/** Configuration for the scout extension, stored in settings.json. */
+export interface ScoutConfig {
+  /** Whether scout is enabled globally */
+  enabled: boolean;
+  /** pi-model-roles role name to use for the side agent */
+  sideAgentRole: string;
+  /** Maximum number of skills the side agent can select */
+  maxSelectedSkills: number;
+  /** Module toggles */
+  modules: {
+    skillRouter: boolean;
+    modelRouter: boolean;
+  };
+}
+
+/** Decision returned by the side agent. */
+export interface ScoutDecision {
+  /** Selected skill names */
+  skills: string[];
+  /** Suggested role name, or null if no change */
+  role: string | null;
+  /** Brief reasoning */
+  reasoning: string;
+}
+
+export const DEFAULT_CONFIG: ScoutConfig = {
+  enabled: true,
+  sideAgentRole: "fast",
+  maxSelectedSkills: 5,
+  modules: {
+    skillRouter: true,
+    modelRouter: true,
+  },
+};