@sage-protocol/pi-adapter 0.3.7 → 0.3.9

package/dist/sage-pi-adapter.js

@@ -44,6 +44,18 @@ function sagePassthroughEnv() {
     }
     return env;
 }
+const SAGE_COMMAND_TIMEOUT_KILL_GRACE_MS = 500;
+const SAGE_SOFT_COMMAND_LOG_COOLDOWN_MS = 60_000;
+const SAGE_HOOK_TIMEOUTS = {
+    sessionContext: 4_000,
+    skillVisibility: 2_500,
+    suggest: 4_000,
+    capture: 1_500,
+    feedback: 1_500,
+    securityScan: 4_000,
+    resolveSkill: 4_000,
+    quality: 3_000,
+};
 function formatSageCommand(command, args) {
     const quoted = [command, ...args].map((part) => {
         if (!part)
@@ -160,6 +172,7 @@ const DOMAINLESS_ACTION_DOMAIN_HINTS = {
 };
 const DEFAULT_SEARCH_ACTION_BY_DOMAIN = {
     prompts: "list",
+    behaviors: "recommend",
     skills: "list",
     builder: "recommend",
     governance: "list_subdaos",
@@ -170,6 +183,8 @@ const DEFAULT_SEARCH_ACTION_BY_DOMAIN = {
     security: "scan",
     meta: "get_project_context",
     hub: "status",
+    activation: "active",
+    wallet: "balance",
     library: "get_active",
     help: "list",
     external: "list_servers",
@@ -425,15 +440,23 @@ export async function defaultSageCommandRunner(request) {
         let stderr = "";
         let timedOut = false;
         let settled = false;
+        let killEscalation = null;
         const timeout = setTimeout(() => {
             timedOut = true;
             proc.kill("SIGTERM");
+            killEscalation = setTimeout(() => {
+                if (settled)
+                    return;
+                proc.kill("SIGKILL");
+            }, SAGE_COMMAND_TIMEOUT_KILL_GRACE_MS);
         }, request.timeoutMs);
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timeout);
+            if (killEscalation)
+                clearTimeout(killEscalation);
             resolve(result);
         };
         const fail = (err) => {
@@ -441,6 +464,8 @@ export async function defaultSageCommandRunner(request) {
                 return;
             settled = true;
             clearTimeout(timeout);
+            if (killEscalation)
+                clearTimeout(killEscalation);
             reject(err);
         };
         proc.on("error", (err) => {
@@ -638,6 +663,53 @@ function formatOperationSubject(request) {
     }
     return `${request.domain}/${request.action}`;
 }
+function summarizeInventoryItem(value) {
+    if (typeof value === "string" && value.trim()) {
+        return truncateText(value.trim(), 96);
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const item = value;
+    const toolName = stringValue(item.tool_name);
+    const sessionId = stringValue(item.session_id);
+    const instanceId = stringValue(item.instance_id);
+    const serverId = stringValue(item.server_id) ?? stringValue(item.id) ?? instanceId;
+    if (toolName && serverId) {
+        return truncateText(`${toolName} @ ${serverId}`, 96);
+    }
+    if (instanceId) {
+        return truncateText(sessionId ? `${instanceId} (session ${sessionId})` : instanceId, 96);
+    }
+    const label = stringValue(item.title) ??
+        stringValue(item.name) ??
+        stringValue(item.key) ??
+        stringValue(item.id) ??
+        stringValue(item.url) ??
+        serverId;
+    if (!label)
+        return null;
+    const suffix = [];
+    if (typeof item.running === "boolean") {
+        suffix.push(item.running ? "running" : "stopped");
+    }
+    if (typeof item.enabled === "boolean") {
+        suffix.push(item.enabled ? "enabled" : "disabled");
+    }
+    if (typeof item.available === "boolean" && item.available === false) {
+        suffix.push("unavailable");
+    }
+    if (Array.isArray(item.tools)) {
+        suffix.push(`${item.tools.length} ${item.tools.length === 1 ? "tool" : "tools"}`);
+    }
+    else if (typeof item.tool_count === "number") {
+        suffix.push(`${item.tool_count} ${item.tool_count === 1 ? "tool" : "tools"}`);
+    }
+    const status = stringValue(item.status);
+    if (status && !suffix.includes(status))
+        suffix.push(status);
+    const decorated = suffix.length > 0 ? `${label} (${suffix.slice(0, 3).join(", ")})` : label;
+    return truncateText(decorated, 96);
+}
 function formatOperationDetails(request) {
     const details = [];
     if (request.domain === "external") {
@@ -659,6 +731,7 @@ function formatOperationDetails(request) {
     const query = stringValue(request.params.query);
     const key = stringValue(request.params.key) ?? stringValue(request.params.name);
     const serverId = stringValue(request.params.server_id);
+    const sessionId = stringValue(request.params.session_id);
     const library = stringValue(request.params.library);
     if (query)
         details.push(`query: ${quotedText(query)}`);
@@ -666,6 +739,8 @@ function formatOperationDetails(request) {
         details.push(`key: ${truncateText(key, 84)}`);
     if (serverId)
         details.push(`server: ${serverId}`);
+    if (sessionId)
+        details.push(`session: ${truncateText(sessionId, 84)}`);
     if (library)
         details.push(`library: ${truncateText(library, 84)}`);
     return details;
@@ -675,6 +750,8 @@ function summarizePayloadItems(payload) {
         ["results", "results"],
         ["tools", "tools"],
         ["servers", "servers"],
+        ["running_servers", "servers"],
+        ["sessions", "sessions"],
         ["skills", "skills"],
         ["prompts", "prompts"],
         ["libraries", "libraries"],
@@ -682,26 +759,12 @@ function summarizePayloadItems(payload) {
         ["rooms", "rooms"],
         ["messages", "messages"],
     ];
-    const getItemLabel = (value) => {
-        if (typeof value === "string" && value.trim())
-            return truncateText(value.trim(), 96);
-        if (!value || typeof value !== "object")
-            return null;
-        const item = value;
-        const label = stringValue(item.title) ??
-            stringValue(item.name) ??
-            stringValue(item.key) ??
-            stringValue(item.id) ??
-            stringValue(item.url) ??
-            stringValue(item.server_id);
-        return label ? truncateText(label, 96) : null;
-    };
     if (Array.isArray(payload)) {
         return {
             count: payload.length,
             label: payload.length === 1 ? "item" : "items",
             items: payload
-                .map(getItemLabel)
+                .map(summarizeInventoryItem)
                 .filter((item) => Boolean(item))
                 .slice(0, 4),
         };
@@ -717,7 +780,7 @@ function summarizePayloadItems(payload) {
             count: items.length,
             label: items.length === 1 ? label.replace(/s$/, "") : label,
             items: items
-                .map(getItemLabel)
+                .map(summarizeInventoryItem)
                 .filter((item) => Boolean(item))
                 .slice(0, 4),
         };
@@ -755,24 +818,55 @@ function summarizeRenderedResult(request, details, isError) {
         return { status: "failed", preview };
     }
     const payload = extractJsonFromMcpResult(details) ?? details;
-    const listSummary = summarizePayloadItems(payload);
-    if (listSummary) {
-        return {
-            status: `${listSummary.count} ${listSummary.label}`,
-            preview: listSummary.items,
-        };
-    }
     if (payload && typeof payload === "object") {
         const obj = payload;
+        const explicitStatus = stringValue(obj.status);
+        if (request?.domain === "hub" && request.action === "start") {
+            const tools = Array.isArray(obj.tools)
+                ? obj.tools
+                    .map((item) => summarizeInventoryItem(item))
+                    .filter((item) => Boolean(item))
+                    .slice(0, 3)
+                : [];
+            const preview = [
+                ...tools,
+                ...[
+                    stringValue(obj.hint),
+                    stringValue(obj.message),
+                    stringValue(obj.summary),
+                ]
+                    .filter((item) => Boolean(item))
+                    .map((item) => truncateText(item, 120)),
+            ].slice(0, 3);
+            return {
+                status: explicitStatus ?? defaultOperationStatus(request),
+                preview,
+            };
+        }
+        const listSummary = summarizePayloadItems(payload);
+        if (listSummary) {
+            const preview = listSummary.items.length
+                ? listSummary.items
+                : stringValue(obj.hint)
+                    ? [truncateText(stringValue(obj.hint) ?? "", 120)]
+                    : [];
+            return {
+                status: `${listSummary.count} ${listSummary.label}`,
+                preview,
+            };
+        }
         const message = stringValue(obj.message) ??
             stringValue(obj.summary) ??
-            stringValue(obj.status);
+            stringValue(obj.hint);
         if (message) {
             return {
-                status: defaultOperationStatus(request),
+                status: explicitStatus ?? defaultOperationStatus(request),
                 preview: [truncateText(message, 120)],
             };
         }
+        if (explicitStatus) {
+            return { status: explicitStatus, preview: [] };
+        }
         if (obj.ok === true) {
             return { status: defaultOperationStatus(request), preview: [] };
         }
@@ -1155,25 +1249,65 @@ export class SageMcpBridge {
 export class SageHookRuntime {
     config;
     commandRunner;
+    sessionContextCache = new Map();
+    skillVisibilityCache = null;
+    softFailureState = new Map();
     constructor(config) {
         this.config = config;
         this.commandRunner = config.commandRunner ?? defaultSageCommandRunner;
     }
+    getSoftTimeout(maxTimeoutMs) {
+        return Math.max(250, Math.min(this.config.timeoutMs, maxTimeoutMs));
+    }
+    clearSoftFailure(commandText) {
+        this.softFailureState.delete(commandText);
+    }
+    logSoftFailure(commandText, message) {
+        const now = Date.now();
+        const previous = this.softFailureState.get(commandText);
+        if (previous &&
+            now - previous.lastLoggedAt < SAGE_SOFT_COMMAND_LOG_COOLDOWN_MS) {
+            previous.suppressedCount += 1;
+            this.softFailureState.set(commandText, previous);
+            return;
+        }
+        const suffix = previous && previous.suppressedCount > 0
+            ? `\n[sage-pi-adapter] Suppressed ${previous.suppressedCount} similar timeout/error log(s) for ${commandText}`
+            : "";
+        this.softFailureState.set(commandText, {
+            lastLoggedAt: now,
+            suppressedCount: 0,
+        });
+        console.warn(`${message}${suffix}`);
+    }
     async getSessionContext(sessionId) {
-        const result = await this.run(["skill", "context", "--format", "pi"], { SAGE_SESSION_ID: sessionId ?? "" }, undefined, true);
-        return result?.stdout.trim() ?? "";
+        const cacheKey = sessionId?.trim() || "__default__";
+        const result = await this.run(["skill", "context", "--format", "pi"], { SAGE_SESSION_ID: sessionId ?? "" }, undefined, {
+            failurePolicy: "warn",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.sessionContext),
+        });
+        const context = result?.stdout.trim() ?? "";
+        if (context) {
+            this.sessionContextCache.set(cacheKey, context);
+            return context;
+        }
+        return this.sessionContextCache.get(cacheKey) ?? "";
     }
     /**
      * Gather skill visibility summary for user-facing display.
      *
      * Runs `sage library list` and `sage library active` in parallel to
      * produce a compact summary of active libraries with skill counts.
-     * Returns empty summary when the CLI is unavailable.
+     * Returns cached or empty summary when the CLI is unavailable.
      */
     async getSkillVisibilitySummary() {
+        const softRunOptions = {
+            failurePolicy: "warn",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.skillVisibility),
+        };
         const [libraryResult, activeResult] = await Promise.allSettled([
-            this.run(["library", "list"], {}, undefined, true),
-            this.run(["library", "active"], {}, undefined, true),
+            this.run(["library", "list"], {}, undefined, softRunOptions),
+            this.run(["library", "active"], {}, undefined, softRunOptions),
         ]);
         const libraries = [];
         const libraryOut = libraryResult.status === "fulfilled"
@@ -1192,7 +1326,6 @@ export class SageHookRuntime {
             }
         }
         const totalSkills = libraries.reduce((s, l) => s + l.skills, 0);
-        // --- Active libraries ---
         const activeOut = activeResult.status === "fulfilled"
             ? (activeResult.value?.stdout.trim() ?? "")
             : "";
@@ -1200,17 +1333,12 @@ export class SageHookRuntime {
         if (activeOut) {
             for (const line of activeOut.split("\n")) {
                 if (line.includes("Skill-activated libraries"))
-                    break; // stop at skill section
+                    break;
                 const numMatch = line.match(/^\s*\d+\.\s+(\S+)/);
                 if (numMatch)
                     activeNames.push(numMatch[1]);
             }
         }
-        // --- Build compact display ---
-        // Format: "zenith (48s) · sunago (4p)" using middle dot as separator.
-        // Unicode glyphs get ASCII fallback when SAGE_NO_UNICODE=1.
-        // Compact to 3 libs max, with "+N more" if exceeded.
-        // Falls back to totals when active data is unavailable.
         let summary = "";
         if (activeNames.length > 0) {
             const maxShow = 3;
@@ -1222,7 +1350,7 @@ export class SageHookRuntime {
                     return `${name} (${lib.prompts}p)`;
                 return name;
             });
-            const SEP = unicodeSafe("\u00B7"); // middle dot or |
+            const SEP = unicodeSafe("\u00B7");
             const suffix = activeNames.length > maxShow
                 ? ` ${SEP} +${activeNames.length - maxShow} more`
                 : "";
@@ -1232,7 +1360,16 @@ export class SageHookRuntime {
             summary = `${libraries.length} libs, ${totalSkills} skills`;
         }
         summary = summary ? `[Sage] ${summary}` : "";
-        return { summary, libraryCount: libraries.length, skillCount: totalSkills };
+        const current = {
+            summary,
+            libraryCount: libraries.length,
+            skillCount: totalSkills,
+        };
+        if (current.summary) {
+            this.skillVisibilityCache = current;
+            return current;
+        }
+        return this.skillVisibilityCache ?? current;
     }
     async suggestSkill(prompt, sessionId) {
         const trimmed = prompt.trim();
@@ -1252,7 +1389,10 @@ export class SageHookRuntime {
             SAGE_PROMPT: trimmed,
             SAGE_SOURCE: this.config.source ?? "pi",
             SAGE_SESSION_ID: sessionId ?? "",
-        }, JSON.stringify({ prompt: trimmed }), true);
+        }, JSON.stringify({ prompt: trimmed }), {
+            failurePolicy: "warn",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.suggest),
+        });
         return result?.stdout.trim() ?? "";
     }
     async capturePrompt(prompt, sessionId) {
@@ -1266,7 +1406,10 @@ export class SageHookRuntime {
             SAGE_PROMPT: trimmed,
             SAGE_SOURCE: this.config.source ?? "pi",
             SAGE_SESSION_ID: sessionId ?? "",
-        }, JSON.stringify({ prompt: trimmed }), true);
+        }, JSON.stringify({ prompt: trimmed }), {
+            failurePolicy: "silent",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.capture),
+        });
     }
     async captureResponse(response, usage, sessionId) {
         if (this.config.enableRlmFeedback === false)
@@ -1281,7 +1424,10 @@ export class SageHookRuntime {
             SAGE_SESSION_ID: sessionId ?? "",
             TOKENS_INPUT: usage.input ?? "",
             TOKENS_OUTPUT: usage.output ?? "",
-        }, JSON.stringify({ response: trimmed }), true);
+        }, JSON.stringify({ response: trimmed }), {
+            failurePolicy: "silent",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.capture),
+        });
     }
     async recordSuggestionUse(skillKeys, sessionId) {
         if (this.config.enableRlmFeedback === false)
@@ -1294,7 +1440,10 @@ export class SageHookRuntime {
         await this.run(["suggest", "feedback", "use", ...used.flatMap((key) => ["--used", key])], {
             SAGE_SOURCE: this.config.source ?? "pi",
             SAGE_SESSION_ID: sessionId ?? "",
-        }, undefined, true);
+        }, undefined, {
+            failurePolicy: "silent",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.feedback),
+        });
     }
     async recordSuggestionSkip(sessionId) {
         if (this.config.enableRlmFeedback === false)
@@ -1302,7 +1451,10 @@ export class SageHookRuntime {
         await this.run(["suggest", "feedback", "skip"], {
             SAGE_SOURCE: this.config.source ?? "pi",
             SAGE_SESSION_ID: sessionId ?? "",
-        }, undefined, true);
+        }, undefined, {
+            failurePolicy: "silent",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.feedback),
+        });
     }
     async recordExecutionOutcome(skillKey, status, queryPreview, sessionId, _model) {
         if (this.config.enableRlmFeedback === false)
@@ -1317,7 +1469,10 @@ export class SageHookRuntime {
         await this.run(args, {
             SAGE_SOURCE: this.config.source ?? "pi",
             SAGE_SESSION_ID: sessionId ?? "",
-        }, undefined, true);
+        }, undefined, {
+            failurePolicy: "silent",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.feedback),
+        });
     }
     async scanPreTool(toolName, toolInput, sessionId) {
         if (this.config.enableSecurityHooks === false)
@@ -1330,7 +1485,10 @@ export class SageHookRuntime {
         const result = await this.run(["security", "scan-hook"], {
             SAGE_SOURCE: this.config.source ?? "pi",
             SAGE_SESSION_ID: sessionId ?? "",
-        }, JSON.stringify(payload), true);
+        }, JSON.stringify(payload), {
+            failurePolicy: "warn",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.securityScan),
+        });
         return result ? parseSecurityDecision(result.stdout) : null;
     }
     async scanPostTool(toolName, toolInput, toolResult, sessionId) {
@@ -1345,7 +1503,10 @@ export class SageHookRuntime {
         const result = await this.run(["security", "scan-hook"], {
             SAGE_SOURCE: this.config.source ?? "pi",
             SAGE_SESSION_ID: sessionId ?? "",
-        }, JSON.stringify(payload), true);
+        }, JSON.stringify(payload), {
+            failurePolicy: "warn",
+            timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.securityScan),
+        });
         return result ? parseSecurityDecision(result.stdout) : null;
     }
     /**
@@ -1358,7 +1519,10 @@ export class SageHookRuntime {
         if (!names.length)
             return results;
         const settled = await Promise.allSettled(names.map(async (name) => {
-            const result = await this.run(["skill", "get", name, "--format", "raw"], { SAGE_SOURCE: this.config.source ?? "pi" }, undefined, true);
+            const result = await this.run(["skill", "get", name, "--format", "raw"], { SAGE_SOURCE: this.config.source ?? "pi" }, undefined, {
+                failurePolicy: "warn",
+                timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.resolveSkill),
+            });
             const content = result?.stdout.trim() ?? "";
             return { name, content };
         }));
@@ -1383,7 +1547,10 @@ export class SageHookRuntime {
         if (cached !== undefined)
             return cached;
         try {
-            const result = await this.run(["suggest", "feedback", "breakdown", skillKey, "--format", "json"], {}, undefined, true);
+            const result = await this.run(["suggest", "feedback", "breakdown", skillKey, "--format", "json"], {}, undefined, {
+                failurePolicy: "silent",
+                timeoutMs: this.getSoftTimeout(SAGE_HOOK_TIMEOUTS.quality),
+            });
             if (!result?.stdout) {
                 this.qualityCache.set(skillKey, null);
                 return null;
@@ -1416,8 +1583,9 @@ export class SageHookRuntime {
     async prefetchSkillQualities(keys) {
         await Promise.allSettled(keys.map((k) => this.querySkillQuality(k)));
     }
-    async run(args, env, stdin, ignoreFailures = false) {
+    async run(args, env, stdin, options = {}) {
         const commandText = formatSageCommand(this.config.sageBin, args);
+        const failurePolicy = options.failurePolicy ?? "throw";
         try {
             const commandEnv = {
                 HOME: process.env.HOME ?? "",
@@ -1434,33 +1602,39 @@ export class SageHookRuntime {
                 args,
                 env: commandEnv,
                 stdin,
-                timeoutMs: this.config.timeoutMs,
+                timeoutMs: options.timeoutMs ?? this.config.timeoutMs,
             });
             if (result.timedOut || result.exitCode !== 0) {
                 const detail = (result.stderr || result.stdout || "").trim();
                 const message = result.timedOut
                     ? `[sage-pi-adapter] Sage command timed out: ${commandText}`
                     : `[sage-pi-adapter] Sage command failed (${result.exitCode}): ${commandText}${detail ? `\n${detail}` : ""}`;
-                if (ignoreFailures) {
-                    console.error(message);
-                    return result;
+                if (failurePolicy === "throw") {
+                    throw new Error(message);
                 }
-                throw new Error(message);
+                if (failurePolicy === "warn") {
+                    this.logSoftFailure(commandText, message);
+                }
+                return null;
             }
+            this.clearSoftFailure(commandText);
             return result;
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
             const message = `[sage-pi-adapter] Sage command error: ${commandText}${detail ? `\n${detail}` : ""}`;
-            if (!ignoreFailures)
+            if (failurePolicy === "throw")
                 throw new Error(message);
-            console.error(message);
+            if (failurePolicy === "warn") {
+                this.logSoftFailure(commandText, message);
+            }
             return null;
         }
     }
 }
 const SageDomainType = Type.Union([
     Type.Literal("prompts"),
+    Type.Literal("behaviors"),
     Type.Literal("skills"),
     Type.Literal("builder"),
     Type.Literal("governance"),
@@ -1471,6 +1645,8 @@ const SageDomainType = Type.Union([
     Type.Literal("security"),
     Type.Literal("meta"),
     Type.Literal("hub"),
+    Type.Literal("activation"),
+    Type.Literal("wallet"),
     Type.Literal("library"),
     Type.Literal("help"),
     Type.Literal("external"),
@@ -1479,20 +1655,18 @@ export function createSageSearchTool(mcpBridge) {
     return {
         name: "sage_search",
         label: "Sage: Search",
-        promptSnippet: "Search the web, documentation, prompts, skills, and external services via Sage MCP bridge",
+        promptSnippet: "Route read-only Sage code-mode requests: discover domains/actions, inspect context, query hub/external tools, and search capabilities",
         promptGuidelines: [
-            "Use sage_search (NOT bash sage commands) for web searches, documentation lookups, and prompt/skill discovery",
-            "NEVER run 'sage' CLI via bash -- always use the sage_search or sage_execute tools instead",
-            "For web search: sage_search({ domain: 'external', action: 'search', params: { tool_name: 'web_search', tool_params: { query: '...' } } })",
-            "To list available tools: sage_search({ domain: 'external', action: 'list_servers' })",
+            "Use sage_search (NOT bash sage commands) for Sage read/discovery flows such as help.list, prompts.search, behaviors.show, meta.get_project_context, meta.suggest, hub.list_servers/status, wallet.balance/address, and external.search",
+            "Use sage_search({ domain: 'help', action: 'list', params: {} }) before guessing unknown Sage domains or actions",
+            "Use sage_search({ domain: 'hub', action: 'list_servers', params: {} }) for MCP server inventory; use domain='external', action='list_servers' only to inspect running external servers and tool exposure",
+            "If Sage says an action is a mutation or non-search inspect action, retry with sage_execute instead of falling back to bash",
         ],
-        description: "Search the web, find documentation, search prompts/skills, and query external services. " +
-            "For web search: domain='external', action='search', params={tool_name:'web_search', tool_params:{query:'your query'}}. " +
-            "For prompt search: domain='prompts', action='search', params={query:'search terms'}. " +
-            "For skill search: domain='skills', action='search', params={query:'search terms'}. " +
-            "For GitHub code search: domain='external', action='search', params={tool_name:'github_search_code', tool_params:{query:'...'}}. " +
-            "For library docs: domain='external', action='search', params={tool_name:'get_library_docs', tool_params:{context7CompatibleLibraryID:'/lib/id'}}. " +
-            "To list available external servers/tools: domain='external', action='list_servers'.",
+        description: "Route read-only Sage code-mode requests across prompts, behaviors, skills, builder, governance, chat, social, RLM, security, meta, hub, activation, wallet, library, help, and external services. " +
+            "Start with domain='help', action='list' when you do not know the route. " +
+            "Use domain='meta', action='get_project_context' for local Sage state and domain='meta', action='suggest' with params={goal:'...'} when you need route suggestions. " +
+            "Use domain='hub' for MCP hub inventory/status and domain='external' for external tool discovery/search. " +
+            "Some heavy inspect actions such as prompts.get and skills.get are classified by Sage as non-search and should use sage_execute.",
         parameters: Type.Object({
             domain: Type.Optional(SageDomainType),
             action: Type.Optional(Type.String()),
@@ -1543,16 +1717,15 @@ export function createSageExecuteTool(mcpBridge) {
     return {
         name: "sage_execute",
         label: "Sage: Execute",
-        promptSnippet: "Execute mutations: call external tools, use pi's hub-compat layer, create prompts, fetch URLs",
+        promptSnippet: "Execute Sage mutations and non-search inspect actions: activate skills, fetch full prompt/skill bodies, manage hub servers, and call external tools",
         promptGuidelines: [
-            "Use sage_execute (NOT bash sage commands) for calling external tools, fetching URLs, and managing MCP servers",
+            "Use sage_execute (NOT bash sage commands) for Sage mutations and for Sage actions that the code-mode router classifies as non-search, including prompts.get, skills.get/use, behaviors.run, activation.activate/deactivate, library writes, hub.start/stop, and external.call/execute",
+            "After starting an MCP server with sage_execute({ domain: 'hub', action: 'start', params: { server_id: '...' } }), call its tools through domain='external' with params { tool_name, tool_params } instead of invoking sage via bash",
             "To fetch a URL: sage_execute({ domain: 'external', action: 'call', params: { tool_name: 'fetch', tool_params: { url: 'https://...' } } })",
         ],
-        description: "Execute mutations: create prompts, use skills, send chat messages, call external tools, and manage external MCP servers through pi's hub-compat wrapper. " +
-            "Preferred raw MCP clients use direct hub_* tools; in pi use domain='hub', action='start', params={server_id:'duckduckgo'} when needed. " +
-            "To use a skill: domain='skills', action='use', params={name:'skill-name'}. " +
-            "To call an external tool: domain='external', action='call', params={tool_name:'tool_name', tool_params:{...}}. " +
-            "To fetch a URL: domain='external', action='call', params={tool_name:'fetch', tool_params:{url:'https://example.com'}}.",
+        description: "Execute Sage mutations and non-search inspect actions across prompts, behaviors, skills, builder, chat, library, activation, hub, and external tool surfaces. " +
+            "Use this for prompts.get, skills.get/use, behaviors.run, activation.activate, library.prompt_add/skill_add, hub.start/stop, and external.call/execute. " +
+            "Use domain='external', action='call' with params={tool_name:'fetch', tool_params:{url:'https://example.com'}} for URL fetches, and use domain='hub' to start or stop MCP servers before calling their tools.",
         parameters: Type.Object({
             domain: Type.Optional(SageDomainType),
             action: Type.Optional(Type.String()),
@@ -1585,34 +1758,7 @@ export function createSageExecuteTool(mcpBridge) {
                 return toToolResultText(result);
             }
             catch (error) {
-                let errorMsg = error instanceof Error ? error.message : String(error);
-                // Detect hub start failures due to missing credentials and add helpful context
-                try {
-                    const normalized = normalizeCodeModeRequest("execute", params);
-                    if (normalized.domain === "hub" &&
-                        normalized.action === "start" &&
-                        /EOF|empty|parse|unexpected end/i.test(errorMsg)) {
-                        const serverId = String(normalized.params.server_id ?? "unknown");
-                        const knownKeyRequirements = {
-                            "brave-search": "BRAVE_API_KEY",
-                            github: "GITHUB_TOKEN",
-                        };
-                        const requiredKey = knownKeyRequirements[serverId];
-                        if (requiredKey) {
-                            errorMsg +=
-                                `. Server '${serverId}' likely failed because ${requiredKey} is not configured. ` +
-                                    `Set it with: sage mcp hub env set ${serverId} ${requiredKey}=<your-key>`;
-                        }
-                        else {
-                            errorMsg +=
-                                `. Server '${serverId}' may require environment variables (API keys). ` +
-                                    `Check with: sage mcp hub env list ${serverId}`;
-                        }
-                    }
-                }
-                catch {
-                    // normalizeCodeModeRequest can throw -- ignore, keep original errorMsg
-                }
+                const errorMsg = augmentHubStartErrorMessage(params, error instanceof Error ? error.message : String(error));
                 return {
                     content: [
                         {
@@ -1627,21 +1773,269 @@ export function createSageExecuteTool(mcpBridge) {
     };
 }
 const SAGE_CLI_REFERENCE = `
-## Sage CLI Reference (on-demand)
+## Sage Code-Mode Reference
 
-### Skill Discovery
-- sage_search({ domain: "skills", action: "search", params: { query: "..." } })
-- sage_search({ domain: "skills", action: "get", params: { key: "..." } })
+### Route Discovery
+- List domains/actions: sage_search({ domain: "help", action: "list", params: {} })
+- Suggest the right route: sage_search({ domain: "meta", action: "suggest", params: { goal: "..." } })
+- Inspect local Sage state: sage_search({ domain: "meta", action: "get_project_context", params: {} })
 
-### External Tools
-- Web search: sage_search({ domain: "external", action: "search", params: { tool_name: "web_search", tool_params: { query: "..." } } })
-- URL fetch:  sage_execute({ domain: "external", action: "call", params: { tool_name: "fetch", tool_params: { url: "https://..." } } })
-- List tools:  sage_search({ domain: "external", action: "list_servers" })
+### Skills / Prompts / Behaviors
+- Search skills: sage_search({ domain: "skills", action: "search", params: { query: "..." } })
+- Inspect skill body: sage_execute({ domain: "skills", action: "get", params: { key: "..." } })
+- Activate skill: sage_execute({ domain: "skills", action: "use", params: { key: "..." } })
+- Search prompts: sage_search({ domain: "prompts", action: "search", params: { query: "..." } })
+- Inspect prompt body: sage_execute({ domain: "prompts", action: "get", params: { key: "..." } })
+- Inspect behavior: sage_search({ domain: "behaviors", action: "show", params: { key: "..." } })
 
-### Hub
-- Start server: sage_execute({ domain: "hub", action: "start", params: { server_id: "brave-search" } })
-- Stop server:  sage_execute({ domain: "hub", action: "stop", params: { server_id: "brave-search" } })
+### Hub / External Tools
+- List MCP servers: sage_search({ domain: "hub", action: "list_servers", params: {} })
+- Hub status: sage_search({ domain: "hub", action: "status", params: {} })
+- Start server: sage_execute({ domain: "hub", action: "start", params: { server_id: "github" } })
+- Running external servers/tools: sage_search({ domain: "external", action: "list_servers", params: {} })
+- Web search: sage_search({ domain: "external", action: "search", params: { tool_name: "web_search", tool_params: { query: "..." } } })
+- URL fetch: sage_execute({ domain: "external", action: "call", params: { tool_name: "fetch", tool_params: { url: "https://..." } } })
 `.trim();
+function buildHubRenderContext(action, params, context) {
+    return {
+        ...(context && typeof context === "object" ? context : {}),
+        args: {
+            domain: "hub",
+            action,
+            params,
+        },
+    };
+}
+function augmentHubStartErrorMessage(params, errorMsg) {
+    try {
+        const normalized = normalizeCodeModeRequest("execute", params);
+        if (normalized.domain === "hub" &&
+            normalized.action === "start" &&
+            /EOF|empty|parse|unexpected end/i.test(errorMsg)) {
+            const serverId = String(normalized.params.server_id ?? "unknown");
+            const knownKeyRequirements = {
+                "brave-search": "BRAVE_API_KEY",
+                github: "GITHUB_TOKEN",
+            };
+            const requiredKey = knownKeyRequirements[serverId];
+            if (requiredKey) {
+                return (errorMsg +
+                    `. Server '${serverId}' likely failed because ${requiredKey} is not configured. ` +
+                    `Set it with: sage mcp hub env set ${serverId} ${requiredKey}=<your-key>`);
+            }
+            return (errorMsg +
+                `. Server '${serverId}' may require environment variables (API keys). ` +
+                `Check with: sage mcp hub env list ${serverId}`);
+        }
+    }
+    catch {
+        // Keep original error text if normalization fails.
+    }
+    return errorMsg;
+}
+export function createHubListServersTool(mcpBridge) {
+    return {
+        name: "hub_list_servers",
+        label: "Hub: List Servers",
+        promptSnippet: "List Sage MCP servers directly when you need inventory/status without composing a generic sage_search call",
+        promptGuidelines: [
+            "Prefer hub_list_servers() for simple MCP server inventory in Pi; it is the direct convenience wrapper over domain='hub', action='list_servers'",
+            "Use sage_search({ domain: 'external', action: 'list_servers', params: {} }) only when you specifically need running external servers/tools rather than the full Sage hub inventory",
+        ],
+        description: "List all Sage MCP servers with running/available state. This is a Pi-native convenience wrapper for sage_search({ domain:'hub', action:'list_servers', params:{} }).",
+        parameters: Type.Object({}),
+        renderCall: (_args, theme) => renderSageToolCall("search", { domain: "hub", action: "list_servers", params: {} }, theme),
+        renderResult: (result, options, theme, context) => renderSageToolResult("search", result, options, theme, buildHubRenderContext("list_servers", {}, context)),
+        execute: async () => {
+            try {
+                const result = await callCodeModeWithWebResilience(mcpBridge, "search", {
+                    domain: "hub",
+                    action: "list_servers",
+                    params: {},
+                });
+                return toToolResultText(result);
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `hub_list_servers failed: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+export function createHubStatusTool(mcpBridge) {
+    return {
+        name: "hub_status",
+        label: "Hub: Status",
+        promptSnippet: "Inspect Sage MCP hub runtime status directly when you want running server state without composing a generic sage_search call",
+        promptGuidelines: [
+            "Prefer hub_status() for simple MCP runtime status in Pi; it is the direct convenience wrapper over domain='hub', action='status'",
+            "Use sage_status() when you need full adapter health plus Sage context, not just hub runtime state",
+        ],
+        description: "Inspect Sage MCP hub runtime status. This is a Pi-native convenience wrapper for sage_search({ domain:'hub', action:'status', params:{} }).",
+        parameters: Type.Object({}),
+        renderCall: (_args, theme) => renderSageToolCall("search", { domain: "hub", action: "status", params: {} }, theme),
+        renderResult: (result, options, theme, context) => renderSageToolResult("search", result, options, theme, buildHubRenderContext("status", {}, context)),
+        execute: async () => {
+            try {
+                const result = await callCodeModeWithWebResilience(mcpBridge, "search", {
+                    domain: "hub",
+                    action: "status",
+                    params: {},
+                });
+                return toToolResultText(result);
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `hub_status failed: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+export function createHubSessionListTool(mcpBridge) {
+    return {
+        name: "hub_session_list",
+        label: "Hub: Session List",
+        promptSnippet: "List active Sage MCP hub sessions directly when you need isolated instance visibility without composing a generic sage_search call",
+        promptGuidelines: [
+            "Prefer hub_session_list() for simple hub session inspection in Pi; it wraps domain='hub', action='session_list'",
+            "Pass server_id when you want to filter sessions for one server, and use hub_stop_server with server_id plus session_id to stop a specific isolated session",
+        ],
+        description: "List active Sage MCP hub sessions, optionally filtered by server_id. This is a Pi-native convenience wrapper for sage_search({ domain:'hub', action:'session_list', params:{ server_id? } }).",
+        parameters: Type.Object({
+            server_id: Type.Optional(Type.String({
+                description: "Optional hub server identifier to filter sessions",
+            })),
+        }),
+        renderCall: (args, theme) => renderSageToolCall("search", {
+            domain: "hub",
+            action: "session_list",
+            params: normalizeParams(args),
+        }, theme),
+        renderResult: (result, options, theme, context) => renderSageToolResult("search", result, options, theme, buildHubRenderContext("session_list", normalizeParams(context?.args), context)),
+        execute: async (_toolCallId, params) => {
+            try {
+                const payload = normalizeParams(params);
+                const result = await callCodeModeWithWebResilience(mcpBridge, "search", {
+                    domain: "hub",
+                    action: "session_list",
+                    params: payload,
+                });
+                return toToolResultText(result);
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `hub_session_list failed: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+export function createHubStopServerTool(mcpBridge) {
+    return {
+        name: "hub_stop_server",
+        label: "Hub: Stop Server",
+        promptSnippet: "Stop a Sage MCP server directly when you know the server_id and want to end its runtime cleanly",
+        promptGuidelines: [
+            "Prefer hub_stop_server({ server_id: '...' }) for simple MCP server shutdown in Pi; it wraps domain='hub', action='stop'",
+            "Use hub_status() or hub_list_servers() after stopping a server if you need to confirm the resulting hub state",
+        ],
+        description: "Stop a Sage MCP server by server_id. This is a Pi-native convenience wrapper for sage_execute({ domain:'hub', action:'stop', params:{ server_id:'...' } }).",
+        parameters: Type.Object({
+            server_id: Type.String({
+                description: "Hub server identifier to stop, such as github or brave-search",
+            }),
+            session_id: Type.Optional(Type.String({
+                description: "Optional hub session identifier for isolated instances",
+            })),
+        }),
+        renderCall: (args, theme) => renderSageToolCall("execute", { domain: "hub", action: "stop", params: normalizeParams(args) }, theme),
+        renderResult: (result, options, theme, context) => renderSageToolResult("execute", result, options, theme, buildHubRenderContext("stop", normalizeParams(context?.args), context)),
+        execute: async (_toolCallId, params) => {
+            try {
+                const payload = normalizeParams(params);
+                const result = await callCodeModeWithWebResilience(mcpBridge, "execute", {
+                    domain: "hub",
+                    action: "stop",
+                    params: payload,
+                });
+                return toToolResultText(result);
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `hub_stop_server failed: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+export function createHubStartServerTool(mcpBridge) {
+    return {
+        name: "hub_start_server",
+        label: "Hub: Start Server",
+        promptSnippet: "Start a Sage MCP server directly when you already know the server_id and want Pi to expose its tools",
+        promptGuidelines: [
+            "Prefer hub_start_server({ server_id: '...' }) for simple MCP server startup in Pi; it wraps domain='hub', action='start'",
+            "After starting an external MCP server, call its tools through sage_execute/sage_search with domain='external' and params { tool_name, tool_params }",
+        ],
+        description: "Start a Sage MCP server by server_id. This is a Pi-native convenience wrapper for sage_execute({ domain:'hub', action:'start', params:{ server_id:'...' } }).",
+        parameters: Type.Object({
+            server_id: Type.String({
+                description: "Hub server identifier to start, such as github or brave-search",
+            }),
+            session_id: Type.Optional(Type.String({
+                description: "Optional hub session identifier for isolated instances",
+            })),
+        }),
+        renderCall: (args, theme) => renderSageToolCall("execute", { domain: "hub", action: "start", params: normalizeParams(args) }, theme),
+        renderResult: (result, options, theme, context) => renderSageToolResult("execute", result, options, theme, buildHubRenderContext("start", normalizeParams(context?.args), context)),
+        execute: async (_toolCallId, params) => {
+            try {
+                const payload = normalizeParams(params);
+                const result = await callCodeModeWithWebResilience(mcpBridge, "execute", {
+                    domain: "hub",
+                    action: "start",
+                    params: payload,
+                });
+                return toToolResultText(result);
+            }
+            catch (error) {
+                const errorMsg = augmentHubStartErrorMessage({ domain: "hub", action: "start", params }, error instanceof Error ? error.message : String(error));
+                return {
+                    content: [
+                        { type: "text", text: `hub_start_server failed: ${errorMsg}` },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
 export function createSageStatusTool(mcpBridge) {
     return {
         name: "sage_status",
@@ -1791,6 +2185,11 @@ export function createSageExtensions(options) {
         console.error("[sage-pi-adapter] failed to start MCP bridge:", error);
     });
     const sageTools = [
+        createHubListServersTool(mcpBridge),
+        createHubStatusTool(mcpBridge),
+        createHubSessionListTool(mcpBridge),
+        createHubStartServerTool(mcpBridge),
+        createHubStopServerTool(mcpBridge),
         createSageSearchTool(mcpBridge),
         createSageExecuteTool(mcpBridge),
         createSageStatusTool(mcpBridge),