@sage-protocol/pi-adapter 0.2.2 → 0.3.0

package/dist/sage-pi-adapter.js

@@ -1,6 +1,22 @@
 import { Type } from "@sinclair/typebox";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+const SAGE_ENV_PASSTHROUGH = [
+    "SAGE_FILTER_EXECUTION",
+    "SAGE_SKILL_USED",
+    "SAGE_SKILL_OUTCOME",
+    "SAGE_SOURCE",
+    "SAGE_SESSION_ID",
+];
+function sagePassthroughEnv() {
+    const env = {};
+    for (const key of SAGE_ENV_PASSTHROUGH) {
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
 function formatSageCommand(command, args) {
     const quoted = [command, ...args].map((part) => {
         if (!part)
@@ -582,6 +598,10 @@ export class SageMcpBridge {
     stopped = false;
     startPromise = null;
     stderrBuffer = "";
+    degraded = false;
+    lastHealthError = null;
+    lastHealthCheckedAt = null;
+    cachedToolNames = [];
     constructor(command, args, env = {}, requestTimeoutMs = 20_000) {
         this.command = command;
         this.args = args;
@@ -591,6 +611,19 @@ export class SageMcpBridge {
     isReady() {
         return this.ready && this.proc !== null && !this.stopped;
     }
+    isDegraded() {
+        return this.degraded;
+    }
+    getHealthSnapshot() {
+        return {
+            bridgeConnected: this.isReady(),
+            degraded: this.degraded,
+            lastHealthError: this.lastHealthError,
+            lastHealthCheckedAt: this.lastHealthCheckedAt,
+            availableToolCount: this.cachedToolNames.length,
+            availableToolNames: [...this.cachedToolNames],
+        };
+    }
     async start() {
         if (this.isReady())
             return;
@@ -600,6 +633,10 @@ export class SageMcpBridge {
             this.stopped = false;
             await this.spawn();
             await this.initialize();
+            // Fail-open health probe: mark degraded if tools/list fails post-init,
+            // but never throw from start(). Tool-use call sites surface the
+            // structured degraded error when the bridge is unreachable.
+            await this.probeHealth(Math.min(this.requestTimeoutMs, 2_000));
         })();
         try {
             await this.startPromise;
@@ -608,6 +645,22 @@ export class SageMcpBridge {
             this.startPromise = null;
         }
     }
+    async probeHealth(timeoutMs = Math.min(this.requestTimeoutMs, 2_000)) {
+        this.lastHealthCheckedAt = Date.now();
+        try {
+            const tools = await this.listTools(timeoutMs);
+            this.cachedToolNames = tools.map((t) => t.name).filter(Boolean);
+            this.degraded = false;
+            this.lastHealthError = null;
+            return true;
+        }
+        catch (error) {
+            this.degraded = true;
+            this.lastHealthError =
+                error instanceof Error ? error.message : String(error);
+            return false;
+        }
+    }
     async stop() {
         this.stopped = true;
         this.ready = false;
@@ -617,8 +670,8 @@ export class SageMcpBridge {
             this.proc = null;
         }
     }
-    async listTools() {
-        const result = (await this.request("tools/list", {}));
+    async listTools(timeoutMs) {
+        const result = (await this.request("tools/list", {}, timeoutMs));
         return result.tools ?? [];
     }
     async callTool(name, args) {
@@ -636,10 +689,45 @@ export class SageMcpBridge {
         return result;
     }
     async callCodeModeSearch(args) {
-        return this.callWithFallback(CODE_MODE_SEARCH_TOOLS, args);
+        this.assertReadyForToolCall();
+        try {
+            return await this.callWithFallback(CODE_MODE_SEARCH_TOOLS, args);
+        }
+        catch (error) {
+            this.markDegradedFromError(error);
+            throw error;
+        }
     }
     async callCodeModeExecute(args) {
-        return this.callWithFallback(CODE_MODE_EXECUTE_TOOLS, args);
+        this.assertReadyForToolCall();
+        try {
+            return await this.callWithFallback(CODE_MODE_EXECUTE_TOOLS, args);
+        }
+        catch (error) {
+            this.markDegradedFromError(error);
+            throw error;
+        }
+    }
+    assertReadyForToolCall() {
+        if (!this.isReady() || this.degraded) {
+            const detail = this.lastHealthError
+                ? ` Last health error: ${this.lastHealthError}.`
+                : "";
+            throw new Error(`Sage MCP bridge unavailable; restart Pi or verify 'sage mcp start' works.${detail}`);
+        }
+    }
+    markDegradedFromError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Only flip degraded on transport-level failures, not on known MCP-level
+        // errors (for example `tools/list` returning an unknown tool). Transport
+        // failures surface as "not running", "stopped", or plain JSON-RPC errors
+        // from dead processes.
+        const looksTransportFailure = /bridge stopped|not running|failed to spawn|request timed out|EPIPE|ECONNRESET|closed/i.test(message);
+        if (!looksTransportFailure)
+            return;
+        this.degraded = true;
+        this.lastHealthError = message;
+        this.lastHealthCheckedAt = Date.now();
     }
     async callWithFallback(candidates, args) {
         let lastUnknownError = null;
@@ -714,7 +802,7 @@ export class SageMcpBridge {
             resolve();
         });
     }
-    request(method, params) {
+    request(method, params, timeoutMs = this.requestTimeoutMs) {
         return new Promise((resolve, reject) => {
             if (!this.proc?.stdin?.writable) {
                 reject(new Error("MCP process not running"));
@@ -724,7 +812,7 @@ export class SageMcpBridge {
             const timeout = setTimeout(() => {
                 this.pending.delete(id);
                 reject(new Error(this.withRecentStderr(`MCP request timed out: ${method}`)));
-            }, this.requestTimeoutMs);
+            }, timeoutMs);
             this.pending.set(id, { resolve, reject, timeout });
             const req = { jsonrpc: "2.0", id, method, params };
             this.proc.stdin.write(JSON.stringify(req) + "\n", (err) => {
@@ -793,72 +881,26 @@ export class SageHookRuntime {
         this.commandRunner = config.commandRunner ?? defaultSageCommandRunner;
     }
     async getSessionContext(sessionId) {
-        const result = await this.run(["skill", "context", "--format", "opencode"], { SAGE_SESSION_ID: sessionId ?? "" }, undefined, true);
+        const result = await this.run(["skill", "context", "--format", "pi"], { SAGE_SESSION_ID: sessionId ?? "" }, undefined, true);
         return result?.stdout.trim() ?? "";
     }
     /**
-     * Gather dynamic Sage Protocol identity context for system prompt injection.
-     *
-     * Fetches wallet, library, and skill information in parallel and returns a
-     * compact block suitable for appending to the system prompt. Returns an empty
-     * string if the sage CLI is unavailable or all queries fail.
+     * Gather skill visibility summary for user-facing display.
      *
-     * The result is cached for `identityCacheTtlMs` (default 60 s) to avoid
-     * redundant CLI calls on every turn.
+     * Runs `sage library list` and `sage library active` in parallel to
+     * produce a concise one-line summary of what libraries and skills are
+     * available. Returns empty string when the CLI is unavailable.
      */
-    identityCache = null;
-    identityCacheTtlMs = 60_000;
-    async getIdentityContext() {
-        const now = Date.now();
-        if (this.identityCache && now < this.identityCache.expiresAt) {
-            return this.identityCache.value;
-        }
-        const [walletResult, libraryResult, activeResult] = await Promise.allSettled([
-            this.run(["wallet", "current"], {}, undefined, true),
+    async getSkillVisibilitySummary() {
+        const [libraryResult, activeResult] = await Promise.allSettled([
             this.run(["library", "list"], {}, undefined, true),
             this.run(["library", "active"], {}, undefined, true),
         ]);
-        const lines = [];
-        // --- Wallet ---
-        const walletOut = walletResult.status === "fulfilled" ? walletResult.value?.stdout.trim() ?? "" : "";
-        if (walletOut) {
-            const addrMatch = walletOut.match(/Address:\s*(0x[a-fA-F0-9]+)/i);
-            const typeMatch = walletOut.match(/Type:\s*(\S+)/i);
-            const delegationMatch = walletOut.match(/Active on-chain delegation:\s*(.+)/i);
-            const delegatorMatch = walletOut.match(/Delegator:\s*(0x[a-fA-F0-9]+)/i);
-            const delegateSignerMatch = walletOut.match(/Delegate signer:\s*(0x[a-fA-F0-9]+)/i);
-            const profileMatch = walletOut.match(/Profile:\s*(\S+)/i);
-            const networkMatch = walletOut.match(/Network:\s*(.+)/i);
-            const chainMatch = walletOut.match(/Chain(?:\s*ID)?:\s*(\S+)/i);
-            if (addrMatch) {
-                const addr = addrMatch[1];
-                const walletType = typeMatch?.[1] ?? "unknown";
-                const network = networkMatch?.[1]?.trim() ?? (chainMatch?.[1] === "8453" ? "Base Mainnet" : chainMatch?.[1] === "84532" ? "Base Sepolia" : chainMatch?.[1] ?? "");
-                lines.push(`- Wallet: ${addr.slice(0, 10)}...${addr.slice(-4)} (${walletType}${network ? `, ${network}` : ""})`);
-            }
-            if (delegationMatch && delegatorMatch && delegateSignerMatch) {
-                const delegator = delegatorMatch[1];
-                const delegate = delegateSignerMatch[1];
-                lines.push(`- On-chain delegation: ${delegationMatch[1].trim()} via ${delegate.slice(0, 10)}...${delegate.slice(-4)} for ${delegator.slice(0, 10)}...${delegator.slice(-4)}`);
-            }
-        }
-        // --- Counts only — agent can query details via tools ---
-        const activeOut = activeResult.status === "fulfilled" ? activeResult.value?.stdout.trim() ?? "" : "";
-        if (activeOut) {
-            let activeCount = 0;
-            for (const line of activeOut.split("\n")) {
-                if (/^\s*\d+\.\s+/.test(line))
-                    activeCount++;
-            }
-            if (activeCount > 0) {
-                lines.push(`- ${activeCount} active libraries`);
-            }
-        }
+        let totalSkills = 0;
+        let totalPrompts = 0;
+        let libraryCount = 0;
         const libraryOut = libraryResult.status === "fulfilled" ? libraryResult.value?.stdout.trim() ?? "" : "";
         if (libraryOut) {
-            let totalSkills = 0;
-            let totalPrompts = 0;
-            let libraryCount = 0;
             for (const line of libraryOut.split("\n")) {
                 const m = line.match(/\((\d+)\s+prompts?,\s*(\d+)\s+skills?\)/);
                 if (m) {
@@ -867,31 +909,29 @@ export class SageHookRuntime {
                     totalSkills += Number.parseInt(m[2], 10);
                 }
             }
-            if (libraryCount > 0) {
-                lines.push(`- ${libraryCount} libraries, ${totalSkills} skills, ${totalPrompts} prompts installed`);
+        }
+        const activeOut = activeResult.status === "fulfilled" ? activeResult.value?.stdout.trim() ?? "" : "";
+        let activeCount = 0;
+        if (activeOut) {
+            for (const line of activeOut.split("\n")) {
+                if (/^\s*\d+\.\s+/.test(line))
+                    activeCount++;
             }
         }
-        const PROTOCOL_DESC = "Sage Protocol is a decentralized network for curating prompts, skills, and knowledge on Base (L2).\n" +
-            "Libraries are like gardens — cultivated by communities around shared interests, taste, and tooling preferences.\n" +
-            "Users follow creators, tip valuable work, and post bounties for skills they need.\n" +
-            "Skills stay valuable when kept current with tooling and documentation — different knowledge bases and context work together to provide compounding value.\n" +
-            "SXXX is the governance token: vote, create DAOs, stake on proposals, shape the protocol. Burns from activity create deflationary pressure.\n" +
-            "Credits are the utility currency for IPFS storage and API services.\n" +
-            "The more skills published and curated, the more valuable discovery becomes for every user and agent — a compounding network effect.\n" +
-            "Use sage_search, sage_execute, and sage_status to interact with the protocol.";
-        const KEY_COMMANDS = "### Key Commands\n" +
-            "- Search: `sage_search({ domain: \"skills\", action: \"search\", params: { query: \"...\" } })` or `sage search \"...\" --search-type skills`\n" +
-            "- Use skill: `sage_execute({ domain: \"skills\", action: \"use\", params: { key: \"...\" } })`\n" +
-            "- Tip: `sage tip <address> <amount>` or `sage social tip ...`\n" +
-            "- Bounty: `sage bounties create --title \"...\" --reward <amount>`\n" +
-            "- DAOs: `sage governance dao discover`\n" +
-            "- Publish: `sage library push <name>`\n" +
-            "- Follow: `sage social follow <address>`";
-        const block = lines.length > 0
-            ? `## Sage Protocol Context\n${PROTOCOL_DESC}\n\n${lines.join("\n")}\n\n${KEY_COMMANDS}`
-            : "";
-        this.identityCache = { value: block, expiresAt: now + this.identityCacheTtlMs };
-        return block;
+        const parts = [];
+        if (libraryCount > 0) {
+            parts.push(`${libraryCount} libraries`);
+        }
+        if (totalSkills > 0) {
+            parts.push(`${totalSkills} skills`);
+        }
+        if (totalPrompts > 0) {
+            parts.push(`${totalPrompts} prompts`);
+        }
+        if (activeCount > 0) {
+            parts.push(`${activeCount} active`);
+        }
+        return parts.length > 0 ? `[Sage] ${parts.join(", ")} loaded` : "";
     }
     async suggestSkill(prompt, sessionId) {
         const trimmed = prompt.trim();
@@ -936,6 +976,32 @@ export class SageHookRuntime {
             TOKENS_OUTPUT: usage.output ?? "",
         }, JSON.stringify({ response: trimmed }), true);
     }
+    async recordSuggestionUse(skillKeys, sessionId) {
+        if (this.config.enableRlmFeedback === false)
+            return;
+        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])], {
+            SAGE_SOURCE: this.config.source ?? "pi",
+            SAGE_SESSION_ID: sessionId ?? "",
+        }, undefined, true);
+    }
+    async recordExecutionOutcome(skillKey, status, queryPreview, sessionId) {
+        if (this.config.enableRlmFeedback === false)
+            return;
+        const key = skillKey.trim();
+        if (!key)
+            return;
+        const args = ["suggest", "feedback", "outcome", key, "--status", status];
+        const preview = queryPreview?.trim();
+        if (preview)
+            args.push("--query-preview", preview.slice(0, 240));
+        await this.run(args, {
+            SAGE_SOURCE: this.config.source ?? "pi",
+            SAGE_SESSION_ID: sessionId ?? "",
+        }, undefined, true);
+    }
     async scanPreTool(toolName, toolInput, sessionId) {
         if (this.config.enableSecurityHooks === false)
             return null;
@@ -992,6 +1058,7 @@ export class SageHookRuntime {
             const commandEnv = {
                 HOME: process.env.HOME ?? "",
                 PATH: process.env.PATH ?? "",
+                ...sagePassthroughEnv(),
                 ...(this.config.env ?? {}),
                 ...env,
             };
@@ -1188,39 +1255,21 @@ export function createSageExecuteTool(mcpBridge) {
         },
     };
 }
-// Tier 3: Complete CLI reference — available on-demand via sage_status().
-// Not injected into system prompt; model requests it when needed.
 const SAGE_CLI_REFERENCE = `
-## Sage CLI Reference (Tier 3 — on-demand)
+## Sage CLI Reference (on-demand)
 
-### Skill Trigger Workflow
-1) Discover: sage_search({ domain: "skills", action: "search", params: { query: "..." } })
-2) Inspect:  sage_search({ domain: "skills", action: "get", params: { key: "..." } })
-3) Activate: sage_execute({ domain: "skills", action: "use", params: { key: "..." } })
-4) Hook mode: sage suggest hook skill --limit 3 --provision (reads PROMPT env/stdin)
+### Skill Discovery
+- sage_search({ domain: "skills", action: "search", params: { query: "..." } })
+- sage_search({ domain: "skills", action: "get", params: { key: "..." } })
 
-### Rust CLI Fallback (when user asks for terminal commands)
-- Discovery: sage search "<query>" --search-type skills --scope both
-- Suggest:   sage suggest skill "<intent>" --limit 3 --provision
-- Inspect:   sage skill get <key>
-- Libraries: sage library list | sage library discover | sage library sync
-- Gov:       sage governance dao discover | sage governance proposals list --dao <addr>
-- MCP:       sage mcp start | sage mcp hub list | sage mcp hub status
+### 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" })
 
-### Library / DAO / Bounty Recipes
-- Library: sage library create <name>; sage library skill add <path> -l <library>; sage library prompt add <name> -l <library> --file <path>; sage library push <library>; sage library promote <library> --dao 0x... --collection default
-- DAO:     sage governance dao create --name "My DAO" --description "..." --governance personal|team|community [--operator 0x...|--burn 1500]
-- Bounty:  sage bounties create --title "Task" --description "..." --reward 100 --deadline 7d --subdao 0x...
-
-### Hub Management
-- Start: sage_execute({ domain: "hub", action: "start", params: { server_id: "brave-search" } })
-- Stop:  sage_execute({ domain: "hub", action: "stop", params: { server_id: "brave-search" } })
-- List:  sage_search({ domain: "external", action: "list_servers" })
-
-### Guardrails
-- Verify uncertain syntax with sage --help / sage <group> --help.
-- Prefer sage search --search-type skills when sage skill search is unavailable.
-- Do not use legacy removed top-level commands: sage dao ..., sage proposals ..., sage ipfs ...
+### 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" } })
 `.trim();
 export function createSageStatusTool(mcpBridge) {
     return {
@@ -1231,7 +1280,8 @@ export function createSageStatusTool(mcpBridge) {
             "Call this to see what external tools (web search, GitHub, fetch, browser automation, etc.) are available.",
         parameters: Type.Object({}),
         execute: async () => {
-            const bridgeConnected = mcpBridge.isReady();
+            const health = mcpBridge.getHealthSnapshot();
+            const bridgeConnected = health.bridgeConnected && !health.degraded;
             if (bridgeConnected) {
                 try {
                     const context = await mcpBridge.callCodeModeSearch({
@@ -1245,7 +1295,10 @@ export function createSageStatusTool(mcpBridge) {
                                 type: "text",
                                 text: JSON.stringify({
                                     bridgeConnected,
+                                    degraded: false,
                                     sageAdapterVersion: "0.2.0",
+                                    availableToolCount: health.availableToolCount,
+                                    availableToolNames: health.availableToolNames,
                                     context: extractJsonFromMcpResult(context) ?? context,
                                 }, null, 2),
                             },
@@ -1256,8 +1309,27 @@ export function createSageStatusTool(mcpBridge) {
                         ],
                     };
                 }
-                catch {
-                    // no-op, fallback below
+                catch (error) {
+                    // Tool call failed even though the bridge claims ready; surface as
+                    // degraded rather than falling back silently.
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    bridgeConnected,
+                                    degraded: true,
+                                    sageAdapterVersion: "0.2.0",
+                                    lastHealthError: error instanceof Error ? error.message : String(error),
+                                }, null, 2),
+                            },
+                            {
+                                type: "text",
+                                text: SAGE_CLI_REFERENCE,
+                            },
+                        ],
+                        details: { bridgeConnected, degraded: true },
+                    };
                 }
             }
             return {
@@ -1266,7 +1338,12 @@ export function createSageStatusTool(mcpBridge) {
                         type: "text",
                         text: JSON.stringify({
                             bridgeConnected,
+                            degraded: health.degraded,
                             sageAdapterVersion: "0.2.0",
+                            lastHealthError: health.lastHealthError,
+                            lastHealthCheckedAt: health.lastHealthCheckedAt,
+                            availableToolCount: health.availableToolCount,
+                            availableToolNames: health.availableToolNames,
                         }, null, 2),
                     },
                     {
@@ -1274,7 +1351,11 @@ export function createSageStatusTool(mcpBridge) {
                         text: SAGE_CLI_REFERENCE,
                     },
                 ],
-                details: { bridgeConnected },
+                details: {
+                    bridgeConnected,
+                    degraded: health.degraded,
+                    lastHealthError: health.lastHealthError,
+                },
             };
         },
     };
@@ -1419,6 +1500,7 @@ export async function createSageSessionConfig(config = {}) {
         wrapToolsWithSecurity: wrapTools,
         setupHooks: (session) => {
             activeSessionId = session.sessionId;
+            // Inject Sage session context (skill context from CLI).
             hookRuntime
                 .getSessionContext(activeSessionId)
                 .then(async (context) => {
@@ -1429,16 +1511,16 @@ export async function createSageSessionConfig(config = {}) {
                 .catch((error) => {
                 console.error("[sage-pi-adapter] failed to inject session context:", error);
             });
-            // Inject dynamic identity context (wallet, libraries, skills) at session start.
+            // Show loaded skills/libraries summary to the user.
             hookRuntime
-                .getIdentityContext()
-                .then(async (identity) => {
-                if (!identity)
+                .getSkillVisibilitySummary()
+                .then(async (summary) => {
+                if (!summary)
                     return;
-                await injectHookMessage(session, "sage-identity-context", identity, false);
+                await injectHookMessage(session, "sage-loaded", summary, true);
             })
                 .catch((error) => {
-                console.error("[sage-pi-adapter] failed to inject identity context:", error);
+                console.error("[sage-pi-adapter] failed to get skill summary:", error);
             });
             const unsubscribe = session.subscribe((event) => {
                 const parsed = parseMessageEndEvent(event);