@sage-protocol/pi-adapter 0.3.7 → 0.3.8

package/dist/sage-pi-adapter.js

@@ -160,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",
@@ -170,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",
@@ -638,6 +641,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 +709,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 +717,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 +728,8 @@ function summarizePayloadItems(payload) {
         ["results", "results"],
         ["tools", "tools"],
         ["servers", "servers"],
+        ["running_servers", "servers"],
+        ["sessions", "sessions"],
         ["skills", "skills"],
         ["prompts", "prompts"],
         ["libraries", "libraries"],
@@ -682,26 +737,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 +758,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 +796,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: [] };
         }
@@ -1461,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"),
@@ -1471,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"),
@@ -1479,20 +1554,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 +1616,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 +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: [
                         {
@@ -1627,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",
@@ -1791,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),