@sage-protocol/pi-adapter 0.3.6 → 0.3.8

package/dist/sage-pi-adapter.js

@@ -1,6 +1,8 @@
 import { Type } from "@sinclair/typebox";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
 // ── Unicode glyph fallback ──
 // Some terminals lack glyph support for arrows, checkmarks, and dotted separators.
 // Set SAGE_NO_UNICODE=1 to force ASCII-safe output in widget, summary, and quality icons.
@@ -46,9 +48,7 @@ function formatSageCommand(command, args) {
     const quoted = [command, ...args].map((part) => {
         if (!part)
             return "''";
-        return /[\s"'`$\\]/.test(part)
-            ? JSON.stringify(part)
-            : part;
+        return /[\s"'`$\\]/.test(part) ? JSON.stringify(part) : part;
     });
     return quoted.join(" ");
 }
@@ -101,7 +101,10 @@ const EXTERNAL_EXECUTE_ACTIONS = new Set(["execute", "call"]);
 const EXTERNAL_TOOL_ALIASES = {
     web_search: "duckduckgo_web_search",
 };
-const WEB_SEARCH_PROVIDER_TOOLS = new Set(["duckduckgo_web_search", "brave_web_search"]);
+const WEB_SEARCH_PROVIDER_TOOLS = new Set([
+    "duckduckgo_web_search",
+    "brave_web_search",
+]);
 const WEB_SEARCH_RETRY_PATTERNS = [
     /ddg detected an anomaly/i,
     /too quickly/i,
@@ -119,7 +122,8 @@ const WEB_SEARCH_MIN_INTERVAL_MS = 250;
 const WEB_SEARCH_RETRY_BASE_MS = 250;
 const LAST_WEB_SEARCH_CALL_BY_PROVIDER = new Map();
 const DAEMON_IPC_MAX_ATTEMPTS = Math.max(1, Number.parseInt(process.env.SAGE_DAEMON_IPC_MAX_ATTEMPTS || "3", 10) || 3);
-const DAEMON_IPC_RETRY_BASE_MS = Math.max(50, Number.parseInt(process.env.SAGE_DAEMON_IPC_RETRY_BASE_MS || "350", 10) || 350);
+const DAEMON_IPC_RETRY_BASE_MS = Math.max(50, Number.parseInt(process.env.SAGE_DAEMON_IPC_RETRY_BASE_MS || "350", 10) ||
+    350);
 const DOMAINLESS_ACTION_DOMAIN_HINTS = {
     search: "prompts",
     list: "prompts",
@@ -156,6 +160,7 @@ const DOMAINLESS_ACTION_DOMAIN_HINTS = {
 };
 const DEFAULT_SEARCH_ACTION_BY_DOMAIN = {
     prompts: "list",
+    behaviors: "recommend",
     skills: "list",
     builder: "recommend",
     governance: "list_subdaos",
@@ -166,6 +171,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",
@@ -280,7 +287,9 @@ async function callWithDaemonRetry(call, args) {
             await wait(daemonRetryBackoffMs(attempt));
         }
     }
-    throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "unknown daemon IPC failure"));
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(String(lastError ?? "unknown daemon IPC failure"));
 }
 function withExternalToolName(request, toolName) {
     return {
@@ -310,7 +319,8 @@ async function callCodeModeWithWebResilience(mcpBridge, mode, request) {
             }
             catch (error) {
                 failures.push(`${provider} (attempt ${attempt}): ${toErrorMessage(error)}`);
-                const shouldRetry = isTransientWebSearchError(error) && attempt < WEB_SEARCH_MAX_ATTEMPTS_PER_PROVIDER;
+                const shouldRetry = isTransientWebSearchError(error) &&
+                    attempt < WEB_SEARCH_MAX_ATTEMPTS_PER_PROVIDER;
                 if (shouldRetry) {
                     await wait(retryBackoffMs(attempt));
                     continue;
@@ -346,7 +356,8 @@ function normalizeCodeModeRequest(mode, args) {
     if (!rawAction) {
         if (mode === "search") {
             const fallbackDomain = rawDomain || "help";
-            const fallbackAction = DEFAULT_SEARCH_ACTION_BY_DOMAIN[fallbackDomain] || DEFAULT_SEARCH_ACTION_BY_DOMAIN.help;
+            const fallbackAction = DEFAULT_SEARCH_ACTION_BY_DOMAIN[fallbackDomain] ||
+                DEFAULT_SEARCH_ACTION_BY_DOMAIN.help;
             return {
                 domain: fallbackDomain,
                 action: fallbackAction,
@@ -585,8 +596,314 @@ function appendText(result, text) {
     existing.push({ type: "text", text });
     return { ...result, content: existing };
 }
+function createTextComponent(text) {
+    for (const moduleName of ["@earendil-works/pi-tui", "@mariozechner/pi-tui"]) {
+        try {
+            const mod = require(moduleName);
+            if (mod.Text)
+                return new mod.Text(text, 0, 0);
+        }
+        catch (_error) {
+            void _error;
+        }
+    }
+    return {
+        text,
+        setText(next) {
+            this.text = next;
+        },
+    };
+}
+function truncateText(text, max = 80) {
+    return text.length > max ? `${text.slice(0, Math.max(0, max - 3))}...` : text;
+}
+function quotedText(text, max = 72) {
+    return `"${truncateText(text, max)}"`;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function toolParamValue(request) {
+    return normalizeParams(request.params.tool_params);
+}
+function normalizeRenderRequest(mode, args) {
+    try {
+        return normalizeCodeModeRequest(mode, normalizeParams(args));
+    }
+    catch {
+        return null;
+    }
+}
+function formatOperationSubject(request) {
+    if (request.domain === "external") {
+        const toolName = stringValue(request.params.tool_name) ?? "tool";
+        return `${request.action} ${toolName}`;
+    }
+    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") {
+        const toolName = stringValue(request.params.tool_name);
+        const toolParams = toolParamValue(request);
+        const query = stringValue(toolParams.query);
+        const url = stringValue(toolParams.url);
+        const libraryId = stringValue(toolParams.context7CompatibleLibraryID);
+        if (toolName)
+            details.push(`tool: ${toolName}`);
+        if (query)
+            details.push(`query: ${quotedText(query)}`);
+        if (url)
+            details.push(`url: ${truncateText(url, 84)}`);
+        if (libraryId)
+            details.push(`library: ${truncateText(libraryId, 84)}`);
+        return details;
+    }
+    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)}`);
+    if (key)
+        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;
+}
+function summarizePayloadItems(payload) {
+    const namedArrays = [
+        ["results", "results"],
+        ["tools", "tools"],
+        ["servers", "servers"],
+        ["running_servers", "servers"],
+        ["sessions", "sessions"],
+        ["skills", "skills"],
+        ["prompts", "prompts"],
+        ["libraries", "libraries"],
+        ["items", "items"],
+        ["rooms", "rooms"],
+        ["messages", "messages"],
+    ];
+    if (Array.isArray(payload)) {
+        return {
+            count: payload.length,
+            label: payload.length === 1 ? "item" : "items",
+            items: payload
+                .map(summarizeInventoryItem)
+                .filter((item) => Boolean(item))
+                .slice(0, 4),
+        };
+    }
+    if (!payload || typeof payload !== "object")
+        return null;
+    const obj = payload;
+    for (const [key, label] of namedArrays) {
+        const items = obj[key];
+        if (!Array.isArray(items))
+            continue;
+        return {
+            count: items.length,
+            label: items.length === 1 ? label.replace(/s$/, "") : label,
+            items: items
+                .map(summarizeInventoryItem)
+                .filter((item) => Boolean(item))
+                .slice(0, 4),
+        };
+    }
+    return null;
+}
+function defaultOperationStatus(request) {
+    switch (request?.action) {
+        case "search":
+            return "searched";
+        case "list":
+            return "loaded";
+        case "get":
+            return "opened";
+        case "use":
+            return "activated";
+        case "sync":
+            return "synced";
+        case "start":
+            return "started";
+        case "stop":
+            return "stopped";
+        case "status":
+            return "status loaded";
+        default:
+            return "completed";
+    }
+}
+function summarizeRenderedResult(request, details, isError) {
+    if (isError) {
+        const errorText = extractText(details);
+        const preview = errorText
+            ? [truncateText(errorText.split(/\r?\n/)[0] ?? errorText, 120)]
+            : [];
+        return { status: "failed", preview };
+    }
+    const payload = extractJsonFromMcpResult(details) ?? details;
+    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.hint);
+        if (message) {
+            return {
+                status: explicitStatus ?? defaultOperationStatus(request),
+                preview: [truncateText(message, 120)],
+            };
+        }
+        if (explicitStatus) {
+            return { status: explicitStatus, preview: [] };
+        }
+        if (obj.ok === true) {
+            return { status: defaultOperationStatus(request), preview: [] };
+        }
+    }
+    return { status: defaultOperationStatus(request), preview: [] };
+}
+function renderSageToolCall(mode, args, theme) {
+    const request = normalizeRenderRequest(mode, args);
+    const toolName = mode === "search" ? "sage_search " : "sage_execute ";
+    if (!request) {
+        return createTextComponent(theme.fg("toolTitle", theme.bold(toolName)) +
+            theme.fg("warning", "(invalid request)"));
+    }
+    const lines = [
+        theme.fg("toolTitle", theme.bold(toolName)) +
+            theme.fg("accent", formatOperationSubject(request)),
+    ];
+    for (const detail of formatOperationDetails(request).slice(0, 3)) {
+        lines.push(theme.fg("dim", `  ${detail}`));
+    }
+    return createTextComponent(lines.join("\n"));
+}
+function renderSageToolResult(mode, result, options, theme, context) {
+    if (options.isPartial) {
+        return createTextComponent(theme.fg("warning", mode === "search" ? "Searching..." : "Executing..."));
+    }
+    const request = normalizeRenderRequest(mode, context?.args);
+    const summary = summarizeRenderedResult(request, result.details, Boolean(context?.isError ?? result.isError));
+    const statusColor = summary.status === "failed" ? "error" : "success";
+    const lines = [
+        theme.fg(statusColor, summary.status) +
+            theme.fg("muted", " · ") +
+            theme.fg("accent", request
+                ? formatOperationSubject(request)
+                : mode === "search"
+                    ? "search"
+                    : "execute"),
+    ];
+    for (const detail of request
+        ? formatOperationDetails(request).slice(0, 2)
+        : []) {
+        lines.push(theme.fg("dim", `  ${detail}`));
+    }
+    if (options.expanded) {
+        if (summary.preview.length > 0) {
+            for (const line of summary.preview) {
+                lines.push(theme.fg("muted", `  ${line}`));
+            }
+        }
+        else if (!(context?.isError ?? result.isError)) {
+            lines.push(theme.fg("dim", "  raw payload hidden"));
+        }
+    }
+    return createTextComponent(lines.join("\n"));
+}
 function looksUnknownToolError(error) {
-    const msg = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    const msg = error instanceof Error
+        ? error.message.toLowerCase()
+        : String(error).toLowerCase();
     return (msg.includes("unknown tool") ||
         msg.includes("not found") ||
         msg.includes("no such tool") ||
@@ -614,8 +931,8 @@ function parseSecurityDecision(stdout) {
             if (rawDecision === "allow")
                 return { decision: "allow", reason };
         }
-        catch {
-            continue;
+        catch (_error) {
+            void _error;
         }
     }
     return null;
@@ -771,7 +1088,8 @@ export class SageMcpBridge {
             catch (error) {
                 if (!looksUnknownToolError(error))
                     throw error;
-                lastUnknownError = error instanceof Error ? error : new Error(String(error));
+                lastUnknownError =
+                    error instanceof Error ? error : new Error(String(error));
             }
         }
         if (lastUnknownError)
@@ -807,7 +1125,7 @@ export class SageMcpBridge {
             proc.on("exit", (code) => {
                 if (this.stopped)
                     return;
-                const message = this.withRecentStderr(`MCP process exited${this.ready ? '' : ' before initialization'} (code ${code ?? -1})`);
+                const message = this.withRecentStderr(`MCP process exited${this.ready ? "" : " before initialization"} (code ${code ?? -1})`);
                 this.ready = false;
                 this.rejectAllPending(message);
                 rejectOnce(new Error(message));
@@ -930,7 +1248,9 @@ export class SageHookRuntime {
             this.run(["library", "active"], {}, undefined, true),
         ]);
         const libraries = [];
-        const libraryOut = libraryResult.status === "fulfilled" ? libraryResult.value?.stdout.trim() ?? "" : "";
+        const libraryOut = libraryResult.status === "fulfilled"
+            ? (libraryResult.value?.stdout.trim() ?? "")
+            : "";
         if (libraryOut) {
             for (const line of libraryOut.split("\n")) {
                 const m = line.match(/^\s*(.+?)\s+\((\d+)\s+prompts?,\s*(\d+)\s+skills?\)/);
@@ -945,7 +1265,9 @@ export class SageHookRuntime {
         }
         const totalSkills = libraries.reduce((s, l) => s + l.skills, 0);
         // --- Active libraries ---
-        const activeOut = activeResult.status === "fulfilled" ? activeResult.value?.stdout.trim() ?? "" : "";
+        const activeOut = activeResult.status === "fulfilled"
+            ? (activeResult.value?.stdout.trim() ?? "")
+            : "";
         const activeNames = [];
         if (activeOut) {
             for (const line of activeOut.split("\n")) {
@@ -973,7 +1295,9 @@ export class SageHookRuntime {
                 return name;
             });
             const SEP = unicodeSafe("\u00B7"); // middle dot or |
-            const suffix = activeNames.length > maxShow ? ` ${SEP} +${activeNames.length - maxShow} more` : "";
+            const suffix = activeNames.length > maxShow
+                ? ` ${SEP} +${activeNames.length - maxShow} more`
+                : "";
             summary = shown.join(` ${SEP} `) + suffix;
         }
         else if (libraries.length > 0) {
@@ -986,7 +1310,13 @@ export class SageHookRuntime {
         const trimmed = prompt.trim();
         if (!trimmed)
             return "";
-        const args = ["suggest", "hook", "skill", "--limit", String(this.config.suggestLimit ?? 3)];
+        const args = [
+            "suggest",
+            "hook",
+            "skill",
+            "--limit",
+            String(this.config.suggestLimit ?? 3),
+        ];
         if (this.config.enableProvision !== false)
             args.push("--provision");
         const result = await this.run(args, {
@@ -1028,7 +1358,9 @@ export class SageHookRuntime {
     async recordSuggestionUse(skillKeys, sessionId) {
         if (this.config.enableRlmFeedback === false)
             return;
-        const used = [...new Set(skillKeys.map((key) => key.trim()).filter(Boolean))];
+        const used = [
+            ...new Set(skillKeys.map((key) => key.trim()).filter(Boolean)),
+        ];
         if (used.length === 0)
             return;
         await this.run(["suggest", "feedback", "use", ...used.flatMap((key) => ["--used", key])], {
@@ -1044,7 +1376,7 @@ export class SageHookRuntime {
             SAGE_SESSION_ID: sessionId ?? "",
         }, undefined, true);
     }
-    async recordExecutionOutcome(skillKey, status, queryPreview, sessionId, model) {
+    async recordExecutionOutcome(skillKey, status, queryPreview, sessionId, _model) {
         if (this.config.enableRlmFeedback === false)
             return;
         const key = skillKey.trim();
@@ -1201,6 +1533,7 @@ export class SageHookRuntime {
 }
 const SageDomainType = Type.Union([
     Type.Literal("prompts"),
+    Type.Literal("behaviors"),
     Type.Literal("skills"),
     Type.Literal("builder"),
     Type.Literal("governance"),
@@ -1211,6 +1544,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"),
@@ -1219,32 +1554,33 @@ 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()),
             params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
         }),
+        renderCall: (args, theme) => renderSageToolCall("search", args, theme),
+        renderResult: (result, options, theme, context) => renderSageToolResult("search", result, options, theme, context),
         execute: async (_toolCallId, params) => {
             try {
                 const normalized = normalizeCodeModeRequest("search", params);
                 const domain = normalized.domain;
                 const action = normalized.action;
                 const payload = normalized.params;
-                if (domain === "external" && !["list_servers", "search"].includes(action)) {
+                if (domain === "external" &&
+                    !["list_servers", "search"].includes(action)) {
                     return {
                         content: [
                             {
@@ -1280,21 +1616,22 @@ 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()),
             params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
         }),
+        renderCall: (args, theme) => renderSageToolCall("execute", args, theme),
+        renderResult: (result, options, theme, context) => renderSageToolResult("execute", result, options, theme, context),
         execute: async (_toolCallId, params) => {
             try {
                 const normalized = normalizeCodeModeRequest("execute", params);
@@ -1320,32 +1657,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: [
                         {
@@ -1360,21 +1672,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",
@@ -1480,7 +2040,11 @@ export function wrapToolsWithSageSecurity(tools, options) {
                                 text: `Sage security blocked ${tool.name}: ${pre.reason ?? "high-risk payload detected"}`,
                             },
                         ],
-                        details: { blockedBySageSecurity: true, reason: pre.reason, tool: tool.name },
+                        details: {
+                            blockedBySageSecurity: true,
+                            reason: pre.reason,
+                            tool: tool.name,
+                        },
                         isError: true,
                     };
                 }
@@ -1520,6 +2084,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),
@@ -1635,7 +2204,9 @@ export async function createSageSessionConfig(config = {}) {
                     const content = parsed.content.trim();
                     if (!content)
                         return;
-                    void hookRuntime.capturePrompt(content, activeSessionId).catch((error) => {
+                    void hookRuntime
+                        .capturePrompt(content, activeSessionId)
+                        .catch((error) => {
                         console.error("[sage-pi-adapter] prompt capture failed:", error);
                     });
                     void extension.sageInjectSuggestion(content, session, activeSessionId);
@@ -1646,7 +2217,9 @@ export async function createSageSessionConfig(config = {}) {
                     if (!response)
                         return;
                     const usage = extractUsage(parsed.usage);
-                    void hookRuntime.captureResponse(response, usage, activeSessionId).catch((error) => {
+                    void hookRuntime
+                        .captureResponse(response, usage, activeSessionId)
+                        .catch((error) => {
                         console.error("[sage-pi-adapter] response capture failed:", error);
                     });
                 }