@d3ara1n/pi-scout 1.0.2 → 1.1.1

package/src/model-switch.ts

@@ -12,26 +12,26 @@ import type { ModelRolesAPI } from "@d3ara1n/pi-model-roles";
  * @returns true if the switch was successful
  */
 export async function switchToRole(
-	pi: ExtensionAPI,
-	roleName: string,
-	rolesApi: ModelRolesAPI,
+  pi: ExtensionAPI,
+  roleName: string,
+  rolesApi: ModelRolesAPI,
 ): Promise<boolean> {
-	const resolved = await rolesApi.resolveRoleAsync(roleName);
+  const resolved = await rolesApi.resolveRoleAsync(roleName);
 
-	if (!resolved.model) {
-		console.warn(`[pi-scout] Role "${roleName}" could not be resolved — model not available`);
-		return false;
-	}
+  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;
-	}
+  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);
-	}
+  if (resolved.config.thinking) {
+    pi.setThinkingLevel(resolved.config.thinking);
+  }
 
-	return true;
+  return true;
 }

package/src/scout-prompt.ts

@@ -6,8 +6,8 @@ import type { ScoutConfig } from "./types.ts";
 
 /** Previous turn context for better routing decisions. */
 export interface PrevTurnContext {
-	userPrompt: string;
-	assistantSummary: string;
+  userPrompt: string;
+  assistantSummary: string;
 }
 
 /**
@@ -17,30 +17,30 @@ export interface PrevTurnContext {
  * understand follow-up prompts like "continue", "change that", etc.
  */
 export function buildScoutUserMessage(
-	userPrompt: string,
-	currentRole: string,
-	prevTurn?: PrevTurnContext,
+  userPrompt: string,
+  currentRole: string,
+  prevTurn?: PrevTurnContext,
 ): string {
-	const parts: string[] = [];
+  const parts: string[] = [];
 
-	parts.push(`Current role: ${currentRole}`);
+  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}`);
-		}
-	}
+  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);
+  parts.push(``);
+  parts.push(`## Current User Prompt`);
+  parts.push(userPrompt);
 
-	return parts.join("\n");
+  return parts.join("\n");
 }
 
 /**
@@ -52,48 +52,52 @@ export function buildScoutUserMessage(
  * prompt caching to activate.
  */
 export function buildScoutSystemPrompt(
-	config: ScoutConfig,
-	skillsList: string,
-	rolesList: string,
+  config: ScoutConfig,
+  skillsList: string,
+  rolesList: string,
 ): string {
-	const parts: 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.`);
-	parts.push(`- Use the Previous Turn context to understand follow-up requests (e.g. "continue", "change that", "no, the other one").`);
+  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.`);
+  parts.push(
+    `- Use the Previous Turn context to understand follow-up requests (e.g. "continue", "change that", "no, the other one").`,
+  );
 
-	// 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)");
-	}
+  // 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.modelRouter) {
-		parts.push(``);
-		parts.push(`## Available Roles`);
-		parts.push(rolesList);
-	}
+  if (config.modules.modelRouter) {
+    parts.push(``);
+    parts.push(`## Available Roles`);
+    parts.push(rolesList);
+  }
 
-	return parts.join("\n");
+  return parts.join("\n");
 }

package/src/short-circuit.test.ts

@@ -0,0 +1,105 @@
+/**
+ * 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,170 @@
+/**
+ * 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

@@ -1,69 +1,67 @@
 /**
  * Side agent invocation logic.
  *
- * Calls the side agent model using pi-ai's complete() function
+ * Calls the side agent via model-roles' complete() (auth resolved internally)
  * and parses the JSON decision response.
  */
 
-import { complete } from "@earendil-works/pi-ai";
+import type { ModelRolesAPI } from "@d3ara1n/pi-model-roles";
 import type { ScoutDecision } from "./types.ts";
 
 /** Minimal type for side agent context — matches pi-ai's Context interface. */
 interface SideAgentContext {
-	systemPrompt?: string;
-	messages: Array<{ role: "user"; content: string; timestamp: number }>;
+  systemPrompt?: string;
+  messages: Array<{ role: "user"; content: string; timestamp: number }>;
 }
 
 /**
  * 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 rolesApi - ModelRolesAPI (provides complete() with auth resolved internally)
+ * @param roleName - Role name whose model + auth to use (from scout config)
  * @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(
-	sideModel: any,
-	apiKey: string | undefined,
-	headers: Record<string, string> | undefined,
-	systemPrompt: string,
-	userMessage: string,
+  rolesApi: ModelRolesAPI,
+  roleName: string,
+  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,
-		messages: [
-			{
-				role: "user",
-				content: userMessage,
-				timestamp: Date.now(),
-			},
-		],
-	};
+  const context: SideAgentContext = {
+    systemPrompt,
+    messages: [
+      {
+        role: "user",
+        content: userMessage,
+        timestamp: Date.now(),
+      },
+    ],
+  };
 
-	const options: Record<string, any> = {
-		maxTokens: 256,
-		cacheRetention: "short",
-	};
+  try {
+    const result = await rolesApi.complete(roleName, context, {
+      cacheRetention: "short",
+    });
+    const text =
+      result.content
+        ?.filter((block: any) => block.type === "text")
+        ?.map((block: any) => block.text)
+        ?.join("") ?? "";
 
-	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;
-	}
+    return parseDecision(text);
+  } catch (err) {
+    console.warn("[pi-scout] Side agent call failed:", err);
+    return fallback;
+  }
 }
 
 /**
@@ -71,30 +69,32 @@ 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();
-	if (text.startsWith("```")) {
-		text = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
-	}
+  // 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);
+  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;
-	}
+    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",
+      source: "side-agent",
+    };
+  } catch {
+    console.warn("[pi-scout] Failed to parse side agent response:", raw.slice(0, 200));
+    return fallback;
+  }
 }