@d3ara1n/pi-scout 1.0.1 → 1.1.0

package/README.md

@@ -2,12 +2,13 @@
 
 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:
+Before each conversation turn, scout 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
+3. **short-circuit** — Skips the side model entirely on trivial acknowledgments (`好的` / `ok` / `はい`), avoiding the per-turn latency and cost
 
-Both modules can be independently toggled on/off.
+All three modules can be independently toggled on/off.
 
 ## Why model-router is disabled by default
 
@@ -35,6 +36,14 @@ Or add to `settings.json` for persistent enablement:
 }
 ```
 
+## Short-circuit layer
+
+Short-circuit is a cost/latency optimization that lets scout **skip the side model entirely** on trivial acknowledgments. It mirrors OpenHuman's hybrid-gate pattern: cheap signals handle the obvious cases, the side model only handles the ambiguous middle — so there is no quality loss.
+
+**Trivial acknowledgment** — a short prompt that is *entirely* an ack (`好的` / `ok` / `はい` / `네`) routes to "no skills, no role change". Matched against a built-in 中/英/日/韓 phrase table. A trivial ack settles every module, so this is safe even with model-router on. Long prompts are never treated as acks even if they start with an ack word, so `好的，那我们重构整个模块` always reaches the side model.
+
+Anything that isn't a trivial ack falls through to the side model — that's what the model is for. When short-circuit fires, the status bar shows `✓ scout: (skipped) trivial ack` for transparency.
+
 ## How it works
 
 ```
@@ -43,7 +52,10 @@ User sends prompt
     ▼
 before_agent_start hook fires
     │
-    ├─ Side agent (cheap model) analyzes prompt + available skills + current role
+    ├─ [short-circuit] Trivial ack? → decide instantly, skip the side model
+    │     (status shows "✓ scout: (skipped) …")
+    │
+    ├─ otherwise → 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
@@ -72,7 +84,13 @@ Edit `~/.pi/agent/settings.json`:
     "maxSelectedSkills": 5,
     "modules": {
       "skillRouter": true,
-      "modelRouter": false
+      "modelRouter": false,
+      "shortCircuit": true
+    },
+    "shortCircuit": {
+      "trivialAck": true,
+      "maxAckLength": 12,
+      "ackPhrases": ["收到啦", "will do"]
     }
   }
 }
@@ -85,6 +103,10 @@ Edit `~/.pi/agent/settings.json`:
 | `maxSelectedSkills` | `5` | Max skills the side agent can select |
 | `modules.skillRouter` | `true` | Enable/disable skill routing |
 | `modules.modelRouter` | `false` | Enable/disable model routing (disabled by default to avoid cache inefficiency and extra costs) |
+| `modules.shortCircuit` | `true` | Enable/disable the short-circuit layer |
+| `shortCircuit.trivialAck` | `true` | Enable the trivial-acknowledgment rule |
+| `shortCircuit.maxAckLength` | `12` | Max prompt length (chars) for the trivial-ack rule |
+| `shortCircuit.ackPhrases` | `[]` | Extra ack phrases merged on top of the built-in 中/英/日/韓 table |
 
 ## Commands
 
@@ -93,6 +115,7 @@ Edit `~/.pi/agent/settings.json`:
 | `/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:short-circuit on/off` | Toggle short-circuit module |
 
 ## Performance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-scout",
-  "version": "1.0.1",
+  "version": "1.1.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",

package/src/config.ts

@@ -21,8 +21,7 @@ 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);
+		return JSON.parse(content);
 	} catch {
 		return {};
 	}
@@ -63,6 +62,14 @@ export function loadScoutConfig(cwd?: string): ScoutConfig {
 		modules: {
 			skillRouter: raw.modules?.skillRouter ?? DEFAULT_CONFIG.modules.skillRouter,
 			modelRouter: raw.modules?.modelRouter ?? DEFAULT_CONFIG.modules.modelRouter,
+			shortCircuit: raw.modules?.shortCircuit ?? DEFAULT_CONFIG.modules.shortCircuit,
+		},
+		shortCircuit: {
+			trivialAck: raw.shortCircuit?.trivialAck ?? DEFAULT_CONFIG.shortCircuit.trivialAck,
+			maxAckLength: raw.shortCircuit?.maxAckLength ?? DEFAULT_CONFIG.shortCircuit.maxAckLength,
+			ackPhrases: Array.isArray(raw.shortCircuit?.ackPhrases)
+				? raw.shortCircuit.ackPhrases.filter((p: any) => typeof p === "string")
+				: DEFAULT_CONFIG.shortCircuit.ackPhrases,
 		},
 	};
 }

package/src/index.ts

@@ -20,11 +20,16 @@ import { callSideAgent } from "./side-agent.ts";
 import { buildScoutSystemPrompt, buildScoutUserMessage } from "./scout-prompt.ts";
 import { filterSkillsBlock, resetSkillCache } from "./skill-inject.ts";
 import { switchToRole } from "./model-switch.ts";
+import { evaluateShortCircuit } from "./short-circuit.ts";
 
 const STATUS_KEY = "scout";
 
 /** Build a one-line status summary from a scout decision. */
 function formatDecisionStatus(decision: ScoutDecision, theme: any): string {
+	if (decision.source === "short-circuit") {
+		return theme.fg("success", "✓ scout:") + " " + theme.fg("dim", `(skipped) ${decision.reasoning}`);
+	}
+
 	const parts: string[] = [];
 
 	if (decision.skills.length > 0) {
@@ -77,6 +82,7 @@ export default function scoutExtension(pi: ExtensionAPI) {
 				`Modules:`,
 				`  skill-router: ${config.modules.skillRouter ? "on" : "off"}`,
 				`  model-router: ${config.modules.modelRouter ? "on" : "off"}`,
+				`  short-circuit: ${config.modules.shortCircuit ? "on" : "off"}`,
 			];
 
 			if (lastDecision) {
@@ -125,6 +131,23 @@ export default function scoutExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	// ── /scout:short-circuit on/off ─────────────────────────────────
+	pi.registerCommand("scout:short-circuit", {
+		description: "Toggle short-circuit module (on/off)",
+		handler: async (args, ctx) => {
+			const value = (args ?? "").trim().toLowerCase();
+			if (value === "on") {
+				config.modules.shortCircuit = true;
+				ctx.ui.notify("Scout: short-circuit enabled", "info");
+			} else if (value === "off") {
+				config.modules.shortCircuit = false;
+				ctx.ui.notify("Scout: short-circuit disabled", "info");
+			} else {
+				ctx.ui.notify("Usage: /scout:short-circuit on|off", "info");
+			}
+		},
+	});
+
 	// ── list_skills tool ───────────────────────────────────────────
 	let cachedAllSkills: Array<{ name: string; description: string; filePath: string }> = [];
 
@@ -192,6 +215,52 @@ export default function scoutExtension(pi: ExtensionAPI) {
 
 		const theme = ctx.ui.theme;
 
+		// Skills available this turn — used by both the short-circuit layer
+		// and the side-agent path.
+		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 skillEntries = skills.map((s: any) => ({
+			name: s.name,
+			description: s.description ?? "",
+			filePath: s.filePath,
+		}));
+
+		// ── Short-circuit layer ───────────────────────────────────
+		// Skip the side model on trivial acknowledgments. A trivial ack means
+		// "no skills, don't switch models" — both answers are certain, so this
+		// is safe even with model-router on. Runs before model resolution to
+		// save that cost too.
+		if (config.modules.shortCircuit) {
+			const skip = evaluateShortCircuit(event.prompt, config.shortCircuit);
+			if (skip) {
+				const decision: ScoutDecision = {
+					skills: [],
+					role: null,
+					reasoning: skip.reasoning,
+					source: "short-circuit",
+				};
+				lastDecision = decision;
+
+				let systemPrompt = event.systemPrompt;
+				if (config.modules.skillRouter) {
+					systemPrompt = filterSkillsBlock(systemPrompt, [], skillEntries);
+				}
+
+				// Keep prevTurn current so the next turn still has context.
+				prevTurn = { userPrompt: event.prompt, assistantSummary: "" };
+
+				ctx.ui.setStatus(STATUS_KEY, formatDecisionStatus(decision, theme));
+				if (systemPrompt !== event.systemPrompt) return { systemPrompt };
+				return;
+			}
+		}
+
 		// Show "Scouting..." indicator
 		ctx.ui.setStatus(STATUS_KEY, theme.fg("accent", "◎") + theme.fg("dim", " Scouting..."));
 
@@ -206,15 +275,7 @@ export default function scoutExtension(pi: ExtensionAPI) {
 		// 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,
-			}));
-		}
+		// 1. Build the skills list for the side agent prompt
 		const skillsList = skills
 			.map((s: any) => `- ${s.name}: ${s.description ?? "(no description)"}`)
 			.join("\n");
@@ -265,11 +326,7 @@ export default function scoutExtension(pi: ExtensionAPI) {
 
 		// 6. 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 })),
-			);
+			systemPrompt = filterSkillsBlock(systemPrompt, decision.skills, skillEntries);
 		}
 
 		// 7. model-router: switch model if side agent recommends a different role

package/src/short-circuit.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Tests for the short-circuit layer.
+ * Run: node --test packages/pi-scout/src/short-circuit.test.ts
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+	normalizeAckPrompt,
+	buildAckSet,
+	evaluateShortCircuit,
+} from "./short-circuit.ts";
+import type { ShortCircuitConfig } from "./types.ts";
+
+const CFG = (overrides: Partial<ShortCircuitConfig> = {}): ShortCircuitConfig => ({
+	trivialAck: true,
+	maxAckLength: 12,
+	ackPhrases: [],
+	...overrides,
+});
+
+// ── normalizeAckPrompt ─────────────────────────────────────────
+
+test("normalizeAckPrompt strips trailing CJK/Latin punctuation", () => {
+	assert.equal(normalizeAckPrompt("好的。"), "好的");
+	assert.equal(normalizeAckPrompt("OK!"), "ok");
+	assert.equal(normalizeAckPrompt("  嗯  "), "嗯");
+	assert.equal(normalizeAckPrompt("はい。"), "はい");
+	assert.equal(normalizeAckPrompt("네!"), "네");
+});
+
+test("normalizeAckPrompt preserves internal punctuation", () => {
+	assert.equal(normalizeAckPrompt("好的，那我们继续"), "好的，那我们继续");
+});
+
+test("normalizeAckPrompt lowercases", () => {
+	assert.equal(normalizeAckPrompt("OK"), "ok");
+	assert.equal(normalizeAckPrompt("Sure"), "sure");
+});
+
+test("normalizeAckPrompt empty for pure punctuation", () => {
+	assert.equal(normalizeAckPrompt("。。。"), "");
+	assert.equal(normalizeAckPrompt("   "), "");
+});
+
+// ── buildAckSet ────────────────────────────────────────────────
+
+test("buildAckSet includes defaults and user extras, normalized+deduped", () => {
+	const set = buildAckSet(["收到啦", "OK", "  custom  "]);
+	assert.ok(set.has("好的"));
+	assert.ok(set.has("ok"));
+	assert.ok(set.has("はい"));
+	assert.ok(set.has("네"));
+	assert.ok(set.has("收到啦"));
+	assert.ok(set.has("custom"));
+});
+
+test("buildAckSet ignores empty normalized entries", () => {
+	const set = buildAckSet(["。。。", ""]);
+	assert.equal(set.size > 0, true);
+	assert.ok(!set.has(""));
+});
+
+// ── evaluateShortCircuit ───────────────────────────────────────
+
+test("trivial ack short-circuits across 中/英/日/韓", () => {
+	const cfg = CFG();
+	for (const prompt of ["好的", "ok", "はい", "네", "嗯嗯", "sure", "了解"]) {
+		const r = evaluateShortCircuit(prompt, cfg);
+		assert.ok(r, `expected short-circuit for: ${prompt}`);
+		assert.equal(r!.reasoning, "trivial ack");
+	}
+});
+
+test("trivial ack tolerates trailing punctuation", () => {
+	const r = evaluateShortCircuit("好的。", CFG());
+	assert.ok(r);
+	assert.equal(r!.reasoning, "trivial ack");
+});
+
+test("long prompt starting with ack is NOT short-circuited", () => {
+	const r = evaluateShortCircuit("好的，那我们重构整个模块吧", CFG());
+	assert.equal(r, null);
+});
+
+test("prompt longer than maxAckLength is not an ack", () => {
+	assert.equal(
+		evaluateShortCircuit("understood thank you", CFG({ maxAckLength: 5 })),
+		null,
+	);
+});
+
+test("trivialAck disabled → ack falls through to model", () => {
+	const r = evaluateShortCircuit("好的", CFG({ trivialAck: false }));
+	assert.equal(r, null);
+});
+
+test("user ackPhrases extend the table", () => {
+	const r = evaluateShortCircuit("收到啦", CFG({ ackPhrases: ["收到啦"] }));
+	assert.ok(r);
+	assert.equal(r!.reasoning, "trivial ack");
+});
+
+test("empty / punctuation-only prompt is not an ack", () => {
+	assert.equal(evaluateShortCircuit("", CFG()), null);
+	assert.equal(evaluateShortCircuit("。。。", CFG()), null);
+});
+
+test("ordinary prompt falls through to model", () => {
+	assert.equal(
+		evaluateShortCircuit("帮我看看这个函数有没有性能问题", CFG()),
+		null,
+	);
+	assert.equal(
+		evaluateShortCircuit("what is the weather today", CFG()),
+		null,
+	);
+});

package/src/short-circuit.ts

@@ -0,0 +1,102 @@
+/**
+ * Short-circuit layer — skip the side model on trivial prompts.
+ *
+ * Borrowed from OpenHuman's hybrid-gate pattern (PR #775): cheap signals
+ * short-circuit the obvious cases, the model only handles the ambiguous
+ * middle. There is no quality loss — the short-circuit fires only when the
+ * routing decision is already certain, everything else falls through to the
+ * side model.
+ *
+ * One rule, multilingual by construction:
+ *
+ * **Trivial acknowledgment** — a short prompt that is *entirely* an ack
+ * ("好的" / "ok" / "はい" / "네"). Matched against a built-in 中/英/日/韓
+ * phrase table. A trivial ack means "no skills, don't switch models" — both
+ * module answers are certain, so skipping the side model is always safe, even
+ * with model-router on. Long prompts are never treated as acks even if they
+ * start with an ack word, so "好的，那我们重构整个模块" always reaches the model.
+ */
+
+import type { ShortCircuitConfig } from "./types.ts";
+
+/** Result of a successful short-circuit. */
+export interface ShortCircuitResult {
+	/** Short human-readable reason, surfaced in the status bar. */
+	reasoning: string;
+}
+
+/**
+ * Built-in trivial-acknowledgment phrases, 中/英/日/韓.
+ *
+ * High-precision only — every entry is unambiguously a pure ack. When unsure,
+ * prefer omission: a missed ack simply reaches the model, while a false ack
+ * would silently drop routing. User-supplied `ackPhrases` are merged on top.
+ */
+const DEFAULT_ACK_PHRASES: string[] = [
+	// 中文
+	"好的", "好", "嗯", "嗯嗯", "嗯呢", "行", "可以", "对", "对的", "是", "是的",
+	"继续", "继续吧", "往下", "没问题", "明白", "收到", "了解", "知道了", "晓得",
+	"中", "成", "行吧", "可以的", "好的呀", "好嘞", "妥", "妥了", "嗯哼",
+	// English
+	"ok", "okay", "oki", "okie", "okk", "k", "sure", "yes", "yeah", "yep",
+	"yup", "continue", "go", "ahead", "go ahead", "sounds good", "got it",
+	"understood", "will do", "agreed", "roger", "proceed", "ack",
+	"acknowledged", "fine",
+	// 日本語
+	"はい", "うん", "おk", "続けて", "了解", "承知", "わかった", "分かった",
+	"ええ", "継続", "進めて", "いいよ", "いいです", "オッケー", "おけ",
+	// 한국어
+	"네", "응", "응응", "계속", "알겠어", "알겠음", "좋아", "그래", "오키",
+];
+
+/**
+ * Normalize a prompt/phrase for ack matching: trim, lowercase, strip
+ * leading/trailing punctuation. Internal punctuation is preserved so that
+ * non-ack content keeps the string out of the ack set.
+ * @internal — exported for testing.
+ */
+export function normalizeAckPrompt(input: string): string {
+	return input
+		.trim()
+		.toLowerCase()
+		.replace(/^[。！？.!?,，、~～…·\s]+/, "")
+		.replace(/[。！？.!?,，、~～…·\s]+$/, "");
+}
+
+/**
+ * Build the full ack-phrase set: built-in defaults plus user extras,
+ * all normalized. Deduplicated via Set.
+ * @internal — exported for testing.
+ */
+export function buildAckSet(extra: string[]): Set<string> {
+	const all = [...DEFAULT_ACK_PHRASES, ...extra];
+	const set = new Set<string>();
+	for (const phrase of all) {
+		const n = normalizeAckPrompt(phrase);
+		if (n.length > 0) set.add(n);
+	}
+	return set;
+}
+
+/**
+ * Evaluate whether a prompt can be short-circuited as a trivial ack.
+ * Returns the decision when it can, `null` when the prompt must reach the
+ * side model.
+ *
+ * @param prompt - The user's prompt text
+ * @param config - Short-circuit tuning
+ */
+export function evaluateShortCircuit(
+	prompt: string,
+	config: ShortCircuitConfig,
+): ShortCircuitResult | null {
+	if (!config.trivialAck) return null;
+
+	const normalized = normalizeAckPrompt(prompt);
+	if (normalized.length === 0 || normalized.length > config.maxAckLength) {
+		return null;
+	}
+
+	const ackSet = buildAckSet(config.ackPhrases);
+	return ackSet.has(normalized) ? { reasoning: "trivial ack" } : null;
+}

package/src/side-agent.ts

@@ -31,7 +31,7 @@ export async function callSideAgent(
 	systemPrompt: string,
 	userMessage: string,
 ): Promise<ScoutDecision> {
-	const fallback: ScoutDecision = { skills: [], role: null, reasoning: "side agent error" };
+	const fallback: ScoutDecision = { skills: [], role: null, reasoning: "side agent error", source: "side-agent" };
 
 	const context: SideAgentContext = {
 		systemPrompt,
@@ -71,7 +71,7 @@ export async function callSideAgent(
  * Tolerant of markdown wrapping, extra whitespace, etc.
  */
 function parseDecision(raw: string): ScoutDecision {
-	const fallback: ScoutDecision = { skills: [], role: null, reasoning: "parse error" };
+	const fallback: ScoutDecision = { skills: [], role: null, reasoning: "parse error", source: "side-agent" };
 
 	// Strip markdown code fences if present
 	let text = raw.trim();
@@ -92,6 +92,7 @@ function parseDecision(raw: string): ScoutDecision {
 			reasoning: typeof parsed.reasoning === "string"
 				? parsed.reasoning
 				: "no reasoning provided",
+			source: "side-agent",
 		};
 	} catch {
 		console.warn("[pi-scout] Failed to parse side agent response:", raw.slice(0, 200));

package/src/types.ts

@@ -14,10 +14,35 @@ export interface ScoutConfig {
   modules: {
     skillRouter: boolean;
     modelRouter: boolean;
+    /** Short-circuit layer: skip the side LLM on high-confidence prompts */
+    shortCircuit: boolean;
   };
+  /** Tuning for the short-circuit module */
+  shortCircuit: ShortCircuitConfig;
 }
 
-/** Decision returned by the side agent. */
+/**
+ * Tuning for the short-circuit module.
+ *
+ * The short-circuit layer lets scout skip the side model entirely on
+ * trivial acknowledgments ("好的" / "ok" / "はい"). A trivial ack means
+ * "no skills, don't switch models" — both module answers are certain, so
+ * skipping the side model is always safe, even with model-router on.
+ * Ambiguous prompts always fall through to the side model, so there is no
+ * quality loss on hard cases.
+ */
+export interface ShortCircuitConfig {
+  /** Enable the trivial-acknowledgment rule */
+  trivialAck: boolean;
+  /** Max prompt length (chars) for the trivial-ack rule. Longer prompts are
+   *  never short-circuited as acks even if they begin with an ack word. */
+  maxAckLength: number;
+  /** Additional ack phrases merged on top of the built-in 中/英/日/韓 table.
+   *  Provide raw strings; they are normalized (trimmed, lowercased) at runtime. */
+  ackPhrases: string[];
+}
+
+/** Decision returned by the side agent or the short-circuit layer. */
 export interface ScoutDecision {
   /** Selected skill names */
   skills: string[];
@@ -25,6 +50,8 @@ export interface ScoutDecision {
   role: string | null;
   /** Brief reasoning */
   reasoning: string;
+  /** Where the decision came from — controls status-bar presentation */
+  source?: "side-agent" | "short-circuit";
 }
 
 export const DEFAULT_CONFIG: ScoutConfig = {
@@ -34,5 +61,11 @@ export const DEFAULT_CONFIG: ScoutConfig = {
   modules: {
     skillRouter: true,
     modelRouter: false,
+    shortCircuit: true,
+  },
+  shortCircuit: {
+    trivialAck: true,
+    maxAckLength: 12,
+    ackPhrases: [],
   },
 };