supipowers 1.5.2 → 2.0.0

package/src/tool-catalog/active-tool-controller.ts

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { getMetricsStore, getSessionId } from "../context-mode/hooks.js";
+import { getProjectStateDir } from "../workspace/state-paths.js";
+import type { Platform } from "../platform/types.js";
+import { normalizeSystemPromptBlocks, systemPromptText } from "../platform/system-prompt.js";
+import type { McpRegistry } from "../mcp/types.js";
+import type { SupipowersConfig } from "../types.js";
+import { planActiveTools } from "./active-tool-planner.js";
+import { detectContextMode } from "../context-mode/detector.js";
+import { getShadowedNativeTools } from "../context-mode/routing.js";
+
+export interface ActiveToolControllerDeps {
+  loadMcpRegistryForCwd(cwd: string): McpRegistry;
+  consumePendingTags(): string[];
+}
+
+type BeforeAgentStartEventLike = {
+  prompt?: string;
+  systemPrompt?: string | string[];
+};
+
+type BeforeAgentStartContextLike = {
+  cwd?: string;
+  getSystemPrompt?: () => unknown;
+  getContextUsage?: () => {
+    tokens?: number | null;
+    contextWindow?: number | null;
+    percent?: number | null;
+  } | null;
+};
+
+export function registerActiveToolController(
+  platform: Platform,
+  config: SupipowersConfig,
+  _deps: ActiveToolControllerDeps,
+): void {
+  if (!config.contextMode.enabled || !config.contextMode.lazyTools.enabled) return;
+
+  platform.on("before_agent_start", async (
+    event: BeforeAgentStartEventLike,
+    ctx: BeforeAgentStartContextLike = {},
+  ) => {
+    if (typeof platform.getAllTools !== "function") return undefined;
+    if (typeof platform.setActiveTools !== "function") return undefined;
+    if (typeof ctx.getSystemPrompt !== "function") return undefined;
+
+    const cwd = typeof ctx.cwd === "string" && ctx.cwd.length > 0 ? ctx.cwd : process.cwd();
+    let registry: McpRegistry = { schemaVersion: 1, servers: {} };
+    try {
+      registry = _deps.loadMcpRegistryForCwd(cwd);
+    } catch (error) {
+      (platform as any).logger?.warn?.("supi-lazy-tools: failed to load MCP registry", error);
+    }
+
+    let pendingTags: string[] = [];
+    try {
+      pendingTags = _deps.consumePendingTags();
+    } catch (error) {
+      (platform as any).logger?.warn?.("supi-lazy-tools: failed to consume MCP tags", error);
+    }
+
+    let plan;
+    try {
+      plan = planActiveTools({
+        prompt: event.prompt ?? "",
+        currentActive: platform.getActiveTools(),
+        allTools: platform.getAllTools(),
+        lazyTools: config.contextMode.lazyTools,
+        mcpServers: registry.servers,
+        pendingTags,
+        cacheHandlesEnabled: config.contextMode.cacheHandles.enabled,
+      });
+    } catch (error) {
+      (platform as any).logger?.warn?.("supi-lazy-tools: active-tool planning failed", error);
+      return { systemPrompt: normalizeSystemPromptBlocks(event.systemPrompt) };
+    }
+
+    // Hide native tools fully shadowed by an active ctx_* replacement.
+    // Without this, the LLM sees Search/Find/Fetch in the tool catalog and
+    // routinely tries them, only to receive routing-block errors. Filtering
+    // here removes them from the system prompt that OMP rebuilds below.
+    if (config.contextMode.enforceRouting) {
+      const status = detectContextMode(plan.activeTools);
+      const shadowed = new Set(getShadowedNativeTools(status));
+      if (shadowed.size > 0) {
+        plan.activeTools = plan.activeTools.filter((tool) => !shadowed.has(tool));
+      }
+    }
+
+    if (plan.activeTools.length === 0 || arraysEqual(plan.activeTools, platform.getActiveTools())) {
+      return undefined;
+    }
+
+    try {
+      await platform.setActiveTools(plan.activeTools);
+    } catch (error) {
+      (platform as any).logger?.warn?.("supi-lazy-tools: setActiveTools failed", error);
+      return { systemPrompt: normalizeSystemPromptBlocks(event.systemPrompt) };
+    }
+
+    const rebuiltPrompt = ctx.getSystemPrompt();
+    const rebuiltPromptBlocks = normalizeSystemPromptBlocks(rebuiltPrompt);
+    recordLazyToolsMetric({
+      platform,
+      cwd,
+      beforePrompt: systemPromptText(event.systemPrompt),
+      afterPrompt: systemPromptText(rebuiltPrompt),
+      activeTools: plan.activeTools,
+      contextUsage: ctx.getContextUsage?.() ?? null,
+    });
+
+    return { systemPrompt: rebuiltPromptBlocks };
+  });
+}
+
+function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((value, index) => value === b[index]);
+}
+
+
+function recordLazyToolsMetric(opts: {
+  platform: Platform;
+  cwd: string;
+  beforePrompt: string;
+  afterPrompt: string;
+  activeTools: string[];
+  contextUsage: { tokens?: number | null; contextWindow?: number | null; percent?: number | null } | null;
+}): void {
+  const store = getMetricsStore();
+  if (!store) return;
+
+  try {
+    const projectSlug = basename(getProjectStateDir(opts.platform.paths, opts.cwd));
+    const sortedActiveTools = [...opts.activeTools].sort();
+    const sourceHash = createHash("sha256")
+      .update(projectSlug)
+      .update("\0")
+      .update(sortedActiveTools.join("\0"))
+      .digest("hex");
+
+    store.record({
+      session_id: getSessionId(),
+      ts: Date.now(),
+      layer: "L7",
+      tool: "(system)",
+      processor: "lazy-tools",
+      before_bytes: byteLength(opts.beforePrompt),
+      after_bytes: byteLength(opts.afterPrompt),
+      cache_hit: 0,
+      unique_source_hash: sourceHash,
+      context_tokens: opts.contextUsage?.tokens ?? null,
+      context_window: opts.contextUsage?.contextWindow ?? null,
+      context_percent: opts.contextUsage?.percent ?? null,
+    });
+  } catch (error) {
+    (opts.platform as any).logger?.warn?.("supi-lazy-tools: metrics record failed", error);
+  }
+}
+
+function byteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}

package/src/tool-catalog/active-tool-planner.ts

@@ -0,0 +1,212 @@
+import { computeActiveServers } from "../mcp/activation.js";
+import type { ServerConfig } from "../mcp/types.js";
+import type { ContextModeLazyToolsConfig } from "../types.js";
+import {
+  BALANCED_KEYWORD_TOOLS,
+  CONTEXT_MODE_TOOL_NAMES,
+  MCPC_MANAGER_TOOL_NAME,
+  isSupiOwnedTool,
+  orderOwnedTools,
+} from "./tool-groups.js";
+
+export interface ActiveToolPlannerDiagnostics {
+  unknownConfiguredTools: string[];
+  unavailableTools: string[];
+  unmatchedTags: string[];
+  missingMcpGatewayTools: string[];
+}
+
+export interface PlanActiveToolsInput {
+  prompt: string;
+  currentActive: string[];
+  allTools: string[];
+  lazyTools: ContextModeLazyToolsConfig;
+  mcpServers?: Record<string, ServerConfig>;
+  pendingTags?: string[];
+  cacheHandlesEnabled?: boolean;
+}
+
+export interface ActiveToolPlan {
+  activeTools: string[];
+  activated: string[];
+  deactivated: string[];
+  diagnostics: ActiveToolPlannerDiagnostics;
+}
+
+const RARE_CONTEXT_TOOLS = new Set(["ctx_stats", "ctx_purge"]);
+
+export function planActiveTools(input: PlanActiveToolsInput): ActiveToolPlan {
+  const registeredOwnedTools = new Set(input.allTools.filter(isSupiOwnedTool));
+  const selectedOwnedTools = new Set<string>();
+  const diagnostics: ActiveToolPlannerDiagnostics = {
+    unknownConfiguredTools: [],
+    unavailableTools: [],
+    unmatchedTags: [],
+    missingMcpGatewayTools: [],
+  };
+
+  const addRegisteredTool = (toolName: string, source: "config" | "policy"): void => {
+    if (!isSupiOwnedTool(toolName)) {
+      if (source === "config") diagnostics.unknownConfiguredTools.push(toolName);
+      return;
+    }
+    if (!registeredOwnedTools.has(toolName)) {
+      if (source === "config") diagnostics.unavailableTools.push(toolName);
+      return;
+    }
+    selectedOwnedTools.add(toolName);
+  };
+
+  for (const toolName of input.lazyTools.alwaysKeep) {
+    addRegisteredTool(toolName, "config");
+  }
+
+  if (input.cacheHandlesEnabled) {
+    addRegisteredTool("ctx_open_cached", "policy");
+  }
+
+  if (input.lazyTools.mode === "conservative") {
+    for (const toolName of CONTEXT_MODE_TOOL_NAMES) {
+      if (!RARE_CONTEXT_TOOLS.has(toolName)) addRegisteredTool(toolName, "policy");
+    }
+    addRegisteredTool(MCPC_MANAGER_TOOL_NAME, "policy");
+  }
+
+  for (const toolName of getTriggeredTools(input.prompt, BALANCED_KEYWORD_TOOLS)) {
+    addRegisteredTool(toolName, "policy");
+  }
+
+  for (const toolName of getTriggeredTools(input.prompt, input.lazyTools.keywordTools)) {
+    addRegisteredTool(toolName, "config");
+  }
+
+
+  const mcpServers = input.mcpServers ?? {};
+  const pendingTags = input.pendingTags ?? [];
+  const knownServerNames = new Set(Object.keys(mcpServers));
+  for (const tag of pendingTags) {
+    if (!knownServerNames.has(tag)) diagnostics.unmatchedTags.push(tag);
+  }
+  for (const serverName of computeActiveServers(mcpServers, input.prompt, pendingTags)) {
+    const gatewayToolName = `mcpc_${serverName}`;
+    if (registeredOwnedTools.has(gatewayToolName)) {
+      selectedOwnedTools.add(gatewayToolName);
+    } else {
+      diagnostics.missingMcpGatewayTools.push(gatewayToolName);
+    }
+  }
+  for (const toolName of getCommandAllowlistTools(input.prompt, input.lazyTools.commandAllowlist)) {
+    addRegisteredTool(toolName, "config");
+  }
+
+  const activeTools = orderPlannedTools({
+    currentActive: input.currentActive,
+    selectedOwnedTools,
+  });
+
+  return {
+    activeTools,
+    activated: activeTools.filter((toolName) => !input.currentActive.includes(toolName)),
+    deactivated: input.currentActive.filter((toolName) => !activeTools.includes(toolName)),
+    diagnostics: dedupeDiagnostics(diagnostics),
+  };
+}
+
+function orderPlannedTools(input: {
+  currentActive: string[];
+  selectedOwnedTools: Set<string>;
+}): string[] {
+  const activeTools: string[] = [];
+  const push = (toolName: string): void => {
+    if (!activeTools.includes(toolName)) activeTools.push(toolName);
+  };
+
+  for (const toolName of input.currentActive) {
+    if (!isSupiOwnedTool(toolName)) push(toolName);
+  }
+
+  for (const toolName of input.currentActive) {
+    if (input.selectedOwnedTools.has(toolName)) push(toolName);
+  }
+
+  const newlySelectedOwnedTools = [...input.selectedOwnedTools].filter(
+    (toolName) => !input.currentActive.includes(toolName),
+  );
+  for (const toolName of orderOwnedTools(newlySelectedOwnedTools)) {
+    push(toolName);
+  }
+
+  return activeTools;
+}
+
+function getTriggeredTools(prompt: string, keywordTools: Record<string, string[]>): string[] {
+  const normalizedPrompt = normalizePrompt(prompt);
+  const triggeredTools: string[] = [];
+
+  if (/https?:\/\/\S+/i.test(prompt)) {
+    triggeredTools.push("ctx_fetch_and_index");
+  }
+  if (/cache:\/\/[a-f0-9]{8,}/i.test(prompt)) {
+    triggeredTools.push("ctx_open_cached");
+  }
+
+  for (const [term, tools] of Object.entries(keywordTools)) {
+    if (literalTermMatches(normalizedPrompt, term)) {
+      triggeredTools.push(...tools);
+    }
+  }
+
+  return triggeredTools;
+}
+
+function getCommandAllowlistTools(
+  prompt: string,
+  commandAllowlist: Record<string, string[]>,
+): string[] {
+  const commandName = parseLeadingCommandName(prompt);
+  if (!commandName) return [];
+  return commandAllowlist[commandName] ?? [];
+}
+
+function parseLeadingCommandName(prompt: string): string | null {
+  const trimmed = prompt.trimStart();
+  if (!trimmed.startsWith("/")) return null;
+  const command = trimmed.slice(1).split(/\s+/, 1)[0]?.toLowerCase();
+  return command || null;
+}
+
+function literalTermMatches(normalizedPrompt: string, rawTerm: string): boolean {
+  const normalizedTerm = normalizePrompt(rawTerm);
+  if (!normalizedTerm) return false;
+  if (/\s/.test(normalizedTerm)) return normalizedPrompt.includes(normalizedTerm);
+  return containsSingleTokenLiteral(normalizedPrompt, normalizedTerm);
+}
+
+function containsSingleTokenLiteral(normalizedPrompt: string, normalizedTerm: string): boolean {
+  let start = normalizedPrompt.indexOf(normalizedTerm);
+  while (start !== -1) {
+    const before = start === 0 ? "" : normalizedPrompt[start - 1];
+    const afterIndex = start + normalizedTerm.length;
+    const after = afterIndex >= normalizedPrompt.length ? "" : normalizedPrompt[afterIndex];
+    if (!isAsciiWordChar(before) && !isAsciiWordChar(after)) return true;
+    start = normalizedPrompt.indexOf(normalizedTerm, start + 1);
+  }
+  return false;
+}
+
+function isAsciiWordChar(char: string): boolean {
+  return /^[A-Za-z0-9_]$/.test(char);
+}
+
+function normalizePrompt(value: string): string {
+  return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function dedupeDiagnostics(diagnostics: ActiveToolPlannerDiagnostics): ActiveToolPlannerDiagnostics {
+  return {
+    unknownConfiguredTools: [...new Set(diagnostics.unknownConfiguredTools)],
+    unavailableTools: [...new Set(diagnostics.unavailableTools)],
+    unmatchedTags: [...new Set(diagnostics.unmatchedTags)],
+    missingMcpGatewayTools: [...new Set(diagnostics.missingMcpGatewayTools)],
+  };
+}

package/src/tool-catalog/tool-groups.ts

@@ -0,0 +1,102 @@
+export const CONTEXT_MODE_TOOL_NAMES = [
+  "ctx_execute",
+  "ctx_execute_file",
+  "ctx_batch_execute",
+  "ctx_index",
+  "ctx_search",
+  "ctx_open_cached",
+  "ctx_fetch_and_index",
+  "ctx_stats",
+  "ctx_purge",
+  "ctx_repomap",
+  "ctx_symbol",
+] as const;
+
+export type ContextModeToolName = (typeof CONTEXT_MODE_TOOL_NAMES)[number];
+
+export const MCPC_MANAGER_TOOL_NAME = "mcpc_manager";
+export const MCPC_TOOL_PREFIX = "mcpc_";
+
+export const OWNED_TOOL_PRIORITY = [
+  "ctx_execute",
+  "ctx_search",
+  "ctx_open_cached",
+  "ctx_batch_execute",
+  "ctx_execute_file",
+  "ctx_fetch_and_index",
+  "ctx_index",
+  "ctx_stats",
+  "ctx_purge",
+  "ctx_repomap",
+  "ctx_symbol",
+  MCPC_MANAGER_TOOL_NAME,
+] as const;
+
+const CONTEXT_MODE_TOOL_SET = new Set<string>(CONTEXT_MODE_TOOL_NAMES);
+const OWNED_PRIORITY_INDEX = new Map<string, number>(
+  OWNED_TOOL_PRIORITY.map((name, index) => [name, index]),
+);
+
+export const BALANCED_KEYWORD_TOOLS: Record<string, string[]> = {
+  search: ["ctx_batch_execute"],
+  grep: ["ctx_batch_execute"],
+  find: ["ctx_batch_execute"],
+  scan: ["ctx_batch_execute"],
+  inspect: ["ctx_batch_execute"],
+  explore: ["ctx_batch_execute"],
+  "analyze repo": ["ctx_batch_execute"],
+  "project-wide": ["ctx_batch_execute"],
+  todo: ["ctx_batch_execute"],
+  references: ["ctx_batch_execute"],
+  "large file": ["ctx_execute_file"],
+  "summarize file": ["ctx_execute_file"],
+  "extract from file": ["ctx_execute_file"],
+  "process file without reading": ["ctx_execute_file"],
+  http: ["ctx_fetch_and_index"],
+  https: ["ctx_fetch_and_index"],
+  curl: ["ctx_fetch_and_index"],
+  wget: ["ctx_fetch_and_index"],
+  "fetch docs": ["ctx_fetch_and_index"],
+  "web page": ["ctx_fetch_and_index"],
+  "index this": ["ctx_index"],
+  "store in knowledge": ["ctx_index"],
+  "make searchable": ["ctx_index"],
+  "context stats": ["ctx_stats"],
+  "token usage": ["ctx_stats"],
+  savings: ["ctx_stats"],
+  "ctx stats": ["ctx_stats"],
+  "ctx purge": ["ctx_purge"],
+  "purge knowledge": ["ctx_purge"],
+  "reset knowledge index": ["ctx_purge"],
+  "open cached": ["ctx_open_cached"],
+  "cached handle": ["ctx_open_cached"],
+  ctx_open_cached: ["ctx_open_cached"],
+  repomap: ["ctx_repomap"],
+  "repo map": ["ctx_repomap"],
+  symbol: ["ctx_symbol"],
+  symbols: ["ctx_symbol"],
+};
+
+export function isContextModeTool(name: string): boolean {
+  return CONTEXT_MODE_TOOL_SET.has(name);
+}
+
+export function isMcpcGatewayTool(name: string): boolean {
+  return name.startsWith(MCPC_TOOL_PREFIX) && /^mcpc_[^_].+/.test(name);
+}
+
+export function isSupiOwnedTool(name: string): boolean {
+  return isContextModeTool(name) || name === MCPC_MANAGER_TOOL_NAME || isMcpcGatewayTool(name);
+}
+
+export function orderOwnedTools(names: Iterable<string>): string[] {
+  return [...new Set([...names].filter(isSupiOwnedTool))].sort((a, b) => {
+    const aPriority = OWNED_PRIORITY_INDEX.get(a);
+    const bPriority = OWNED_PRIORITY_INDEX.get(b);
+
+    if (aPriority !== undefined && bPriority !== undefined) return aPriority - bPriority;
+    if (aPriority !== undefined) return -1;
+    if (bPriority !== undefined) return 1;
+    return a.localeCompare(b);
+  });
+}