@d3ara1n/pi-scout 1.0.2 → 1.1.1

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.2",
+  "version": "1.1.1",
   "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

@@ -12,56 +12,52 @@ 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");
+  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");
-		return JSON.parse(content);
-	} catch {
-		return {};
-	}
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content);
+  } 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;
+/** Read the `scout` block from a settings file. */
+function readScout(filePath: string): Record<string, any> | undefined {
+  const raw = readSettingsFile(filePath)?.scout;
+  return raw && typeof raw === "object" ? raw : undefined;
 }
 
 /**
- * Load scout config from merged settings.
+ * Load scout config. Project overrides global wholesale; per-field `??
+ * DEFAULT` fills any gap. (No field-level merge — project replaces global.)
  * @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 globalRaw = readScout(path.join(getAgentDir(), "settings.json"));
+  const projectRaw = cwd ? readScout(path.join(cwd, ".pi", "settings.json")) : undefined;
+  const raw = projectRaw ?? globalRaw;
+  if (!raw) return DEFAULT_CONFIG;
 
-	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,
-		},
-	};
+  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,
+      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,
+    },
+  };
 }