@sage-protocol/pi-adapter 0.1.0 → 0.1.1

package/README.md

@@ -15,18 +15,62 @@ For model-driven patching, see `packages/sage-pi-adapter/SKILL.md`.
 - Node project using `@mariozechner/pi-coding-agent`
 - Sage CLI installed and on `PATH` (`sage`)
 
+## Choose the Right Integration Mode
+
+There are two different scenarios:
+
+1. You own harness source code (SDK embedding with `createAgentSession`) -> use this package directly.
+2. You only run installed `pi` CLI (`npm i -g @mariozechner/pi-coding-agent`) -> install this package with `pi install`.
+
+This package now ships a pi extension entrypoint, so CLI users do not need to patch harness internals.
+
 ## Install
 
 ```bash
 npm install @sage-protocol/pi-adapter
 ```
 
+For pi CLI extension mode:
+
+```bash
+pi install npm:@sage-protocol/pi-adapter
+```
+
 For local development from this monorepo:
 
 ```bash
 npm link /path/to/sage-protocol/packages/sage-pi-adapter
 ```
 
+Verify extension mode:
+
+```bash
+pi list
+# should include npm:@sage-protocol/pi-adapter
+```
+
+## pi CLI Mode (No Harness Source Changes)
+
+After `pi install npm:@sage-protocol/pi-adapter`, restart `pi` and use it normally.
+
+What loads automatically in extension mode:
+
+- custom tools: `sage_search`, `sage_execute`, `sage_status`
+- prompt hooks: `sage suggest hook skill`
+- capture hooks: `sage capture hook prompt/response`
+- security hooks: `sage security scan-hook` on tool pre/post
+
+Optional environment overrides:
+
+```bash
+export SAGE_BIN=sage
+export SAGE_PROFILE=testnet
+export SAGE_SUGGEST_LIMIT=3
+export SAGE_SUGGEST_DEBOUNCE_MS=800
+export SAGE_SECURITY_HOOKS=1
+export SAGE_RLM_FEEDBACK=1
+```
+
 ## Harness Integration (Recommended)
 
 ```typescript
@@ -64,6 +108,15 @@ export async function createSessionWithSage(model: any, cwd = process.cwd()) {
 
 If this package is on npm, you can ask a coding model to patch your harness directly.
 
+Important: make sure the model is operating in the harness repository (for example `pi-mono`), not in `sage-protocol/packages/sage-pi-adapter`.
+
+Preflight checks to include in your instruction:
+
+```bash
+npm view @sage-protocol/pi-adapter version
+npm config get registry
+```
+
 Use this instruction block as-is:
 
 ```text
@@ -74,6 +127,7 @@ Install @sage-protocol/pi-adapter and patch the session bootstrap to:
 4) call const disposeSageHooks = sage.setupHooks(session) after createAgentSession
 5) call disposeSageHooks() during teardown
 6) keep existing model/provider/settings behavior unchanged
+7) if current workspace is not the harness repo, switch to it first and patch there
 ```
 
 Helpful search targets for the model:
@@ -81,6 +135,8 @@ Helpful search targets for the model:
 ```bash
 rg "createAgentSession|createCodingTools|customTools|tools:" src
 rg "dispose|shutdown|teardown|cleanup" src
+rg "createAgentSession|createCodingTools|customTools|tools:" packages/coding-agent
+rg "dispose|shutdown|teardown|cleanup" packages/coding-agent
 ```
 
 Typical patch shape:

package/SKILL.md

@@ -0,0 +1,141 @@
+# Sage Pi Adapter Integration Skill
+
+Use this skill when a repository uses `@mariozechner/pi-coding-agent` and needs Sage integrated into its session bootstrap/plugin layer.
+
+## Preflight (Do This First)
+
+1. Verify npm package availability:
+   - `npm view @sage-protocol/pi-adapter version`
+2. Ensure you are patching the harness repo (not this package repo):
+   - For pi-mono target: `https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent`
+3. If current workspace does not contain harness sources, switch/clone first, then patch there.
+
+## Hard-Stop Conditions
+
+Stop and report immediately (do not keep searching random directories) if any of these are true:
+
+- `npm view @sage-protocol/pi-adapter version` fails after retrying once
+- Current workspace does not contain harness paths like `packages/coding-agent`
+- You cannot find a session bootstrap path (`createAgentSession` call sites)
+
+When stopping, report what is missing and ask for the harness repo path.
+
+## Goal
+
+Apply the Sage integration contract exactly:
+
+1. For pi CLI users: `pi install npm:@sage-protocol/pi-adapter` (no harness code edits)
+2. For source-owned harness users: apply SDK patch (`createSageSessionConfig`, `customTools`, `wrapToolsWithSecurity`, `setupHooks`)
+
+## Integration Modes (Important)
+
+- Installed pi CLI only (no harness source): run `pi install npm:@sage-protocol/pi-adapter`, restart pi, and verify Sage tools are present.
+- Source-owned harness (editable repo): apply the patch pattern in this skill.
+
+## CLI-Only Flow (No Source Edits)
+
+```bash
+pi install npm:@sage-protocol/pi-adapter
+pi list
+```
+
+Then restart `pi` and verify `sage_status` is callable.
+
+## Required Patch Pattern
+
+```ts
+import { createSageSessionConfig } from '@sage-protocol/pi-adapter';
+
+const sage = await createSageSessionConfig({
+  source: 'pi-agent-core',
+  enableSecurityHooks: true,
+  enableRlmFeedback: true,
+  suggestLimit: 3,
+});
+
+const { session } = await createAgentSession({
+  ...existingConfig,
+  tools: sage.wrapToolsWithSecurity(existingTools),
+  customTools: sage.customTools,
+});
+
+const disposeSageHooks = sage.setupHooks(session);
+```
+
+## Plugin Setup (If Harness Uses Plugins)
+
+- Put this in the plugin/bootstrap setup path, not in random feature code.
+- Return or register a disposer that calls:
+  - `disposeSageHooks()`
+  - `await sage.mcpBridge.stop()` (optional but recommended for owned lifecycle)
+
+## Where to Search
+
+Find patch points with:
+
+```bash
+rg "createAgentSession|createCodingTools|customTools|tools:" src
+rg "dispose|shutdown|teardown|cleanup" src
+rg "createAgentSession|createCodingTools|customTools|tools:" packages/coding-agent
+rg "dispose|shutdown|teardown|cleanup" packages/coding-agent
+```
+
+Install in the harness repo root:
+
+```bash
+npm install @sage-protocol/pi-adapter
+```
+
+If npm lookup fails unexpectedly:
+
+```bash
+npm config get registry
+npm view @sage-protocol/pi-adapter version
+```
+
+## Guardrails
+
+- Keep existing model/provider/settings behavior unchanged.
+- Do not remove existing tools; wrap them.
+- Do not duplicate hook setup in multiple places.
+- Ensure cleanup path is wired for long-running processes.
+- Do not stop after patching this package's own examples; patch the actual harness bootstrap.
+
+## Copy-Paste Agent Prompt
+
+```text
+If the user only has pi CLI access, run:
+- pi install npm:@sage-protocol/pi-adapter
+- verify with pi list
+- restart pi and verify sage_status tool is available
+
+If the user has harness source access (target repo: pi-mono/packages/coding-agent), patch Sage into bootstrap.
+
+Preflight:
+1) npm view @sage-protocol/pi-adapter version
+2) npm config get registry
+3) ensure current workspace contains packages/coding-agent
+
+Then implement:
+- const sage = await createSageSessionConfig(...)
+- customTools: sage.customTools
+- tools: sage.wrapToolsWithSecurity(existingTools)
+- const disposeSageHooks = sage.setupHooks(session)
+- teardown calls disposeSageHooks() (and sage.mcpBridge.stop() if lifecycle owned)
+
+Do not change existing model/provider behavior. Run build/tests for touched package and report changed files.
+```
+
+## Verification Checklist
+
+- `customTools` includes Sage tools
+- Base tools are wrapped with `wrapToolsWithSecurity`
+- `setupHooks(session)` is called once per session
+- Teardown calls `disposeSageHooks()`
+- Build/tests pass for touched repo
+
+## Source of Truth
+
+For the latest contract and examples, see:
+
+- `packages/sage-pi-adapter/README.md`

package/dist/index.d.ts

@@ -5,14 +5,21 @@
  *
  * @example
  * ```typescript
+ * import { createAgentSession, createCodingTools } from '@mariozechner/pi-coding-agent'
  * import { createSageSessionConfig } from '@sage-protocol/pi-adapter'
  *
+ * const sage = await createSageSessionConfig({
+ *   sageBin: 'sage',
+ *   source: 'pi-agent-core',
+ *   suggestLimit: 3,
+ * })
+ *
  * const { session } = await createAgentSession({
- *   ...(await createSageSessionConfig({
- *     sageBin: 'sage',
- *     suggestLimit: 3
- *   }))
+ *   tools: sage.wrapToolsWithSecurity(createCodingTools(process.cwd())),
+ *   customTools: sage.customTools,
  * })
+ *
+ * const disposeSageHooks = sage.setupHooks(session)
  * ```
  */
 export * from './sage-pi-adapter.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -5,14 +5,21 @@
  *
  * @example
  * ```typescript
+ * import { createAgentSession, createCodingTools } from '@mariozechner/pi-coding-agent'
  * import { createSageSessionConfig } from '@sage-protocol/pi-adapter'
  *
+ * const sage = await createSageSessionConfig({
+ *   sageBin: 'sage',
+ *   source: 'pi-agent-core',
+ *   suggestLimit: 3,
+ * })
+ *
  * const { session } = await createAgentSession({
- *   ...(await createSageSessionConfig({
- *     sageBin: 'sage',
- *     suggestLimit: 3
- *   }))
+ *   tools: sage.wrapToolsWithSecurity(createCodingTools(process.cwd())),
+ *   customTools: sage.customTools,
  * })
+ *
+ * const disposeSageHooks = sage.setupHooks(session)
  * ```
  */
 // Re-export everything from the main module

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4CAA4C;AAC5C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,4CAA4C;AAC5C,cAAc,sBAAsB,CAAC"}

package/extensions/index.ts

@@ -0,0 +1,244 @@
+import {
+  SageHookRuntime,
+  SageMcpBridge,
+  createSageExecuteTool,
+  createSageSearchTool,
+  createSageStatusTool,
+  type SageP2Config,
+} from '../dist/index.js';
+
+type ExtensionApi = {
+  on: (eventName: string, handler: (event: any, ctx: any) => Promise<any> | any) => void;
+  registerTool: (tool: any) => void;
+  sendMessage: (message: any, options?: any) => void;
+};
+
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if (['0', 'false', 'off', 'no'].includes(normalized)) return false;
+  if (['1', 'true', 'on', 'yes'].includes(normalized)) return true;
+  return fallback;
+}
+
+function parseNumber(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+
+function getSessionId(ctx: any): string | undefined {
+  const sessionManager = ctx?.sessionManager;
+  if (!sessionManager) return undefined;
+
+  const sessionFile =
+    typeof sessionManager.getSessionFile === 'function' ? sessionManager.getSessionFile() : undefined;
+  if (typeof sessionFile === 'string' && sessionFile.trim()) {
+    return sessionFile;
+  }
+
+  const leafId = typeof sessionManager.getLeafId === 'function' ? sessionManager.getLeafId() : undefined;
+  if (typeof leafId === 'string' && leafId.trim()) {
+    return leafId;
+  }
+
+  return undefined;
+}
+
+function extractText(input: unknown): string {
+  if (typeof input === 'string') return input.trim();
+  if (!input || typeof input !== 'object') return '';
+
+  const obj = input as Record<string, unknown>;
+  if (typeof obj.text === 'string' && obj.text.trim()) {
+    return obj.text.trim();
+  }
+
+  const content = obj.content;
+  if (Array.isArray(content)) {
+    const text = content
+      .map((block) => {
+        if (!block || typeof block !== 'object') return '';
+        const textValue = (block as Record<string, unknown>).text;
+        return typeof textValue === 'string' ? textValue : '';
+      })
+      .filter(Boolean)
+      .join('\n')
+      .trim();
+    if (text) return text;
+  }
+
+  return '';
+}
+
+function extractUsage(message: any): { input?: string; output?: string } {
+  const usage =
+    message?.usage && typeof message.usage === 'object'
+      ? (message.usage as Record<string, unknown>)
+      : {};
+
+  const normalize = (value: unknown): string | undefined => {
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    return undefined;
+  };
+
+  return {
+    input:
+      normalize(usage.tokens_input) ??
+      normalize(usage.input_tokens) ??
+      normalize(usage.inputTokens),
+    output:
+      normalize(usage.tokens_output) ??
+      normalize(usage.output_tokens) ??
+      normalize(usage.outputTokens),
+  };
+}
+
+export default function sagePiAdapterExtension(pi: ExtensionApi): void {
+  const config: SageP2Config = {
+    sageBin: process.env.SAGE_BIN ?? 'sage',
+    sageProfile: process.env.SAGE_PROFILE,
+    suggestLimit: parseNumber(process.env.SAGE_SUGGEST_LIMIT, 3),
+    suggestDebounceMs: parseNumber(process.env.SAGE_SUGGEST_DEBOUNCE_MS, 800),
+    timeoutMs: parseNumber(process.env.SAGE_TIMEOUT_MS, 20_000),
+    enableProvision: parseBoolean(process.env.SAGE_SUGGEST_PROVISION, true),
+    enableRlmFeedback: parseBoolean(process.env.SAGE_RLM_FEEDBACK, true),
+    enableSecurityHooks: parseBoolean(process.env.SAGE_SECURITY_HOOKS, true),
+    source: process.env.SAGE_SOURCE ?? 'pi-extension',
+  };
+
+  const bridge = new SageMcpBridge(
+    config.sageBin ?? 'sage',
+    ['mcp', 'start'],
+    {
+      HOME: process.env.HOME ?? '',
+      PATH: process.env.PATH ?? '',
+    },
+    config.timeoutMs
+  );
+
+  const hookRuntime = new SageHookRuntime({
+    sageBin: config.sageBin ?? 'sage',
+    timeoutMs: config.timeoutMs ?? 20_000,
+    ...config,
+  });
+
+  void bridge.start().catch((error) => {
+    console.error('[sage-pi-adapter] failed to start MCP bridge:', error);
+  });
+
+  pi.registerTool(createSageSearchTool(bridge));
+  pi.registerTool(createSageExecuteTool(bridge));
+  pi.registerTool(createSageStatusTool(bridge));
+
+  let lastPrompt = '';
+  let lastSuggestionAt = 0;
+  pi.on('session_start', async (_event, ctx) => {
+    const sessionId = getSessionId(ctx);
+    const context = await hookRuntime.getSessionContext(sessionId);
+    if (!context.trim()) return;
+
+    pi.sendMessage(
+      {
+        customType: 'sage-session-context',
+        content: context,
+        display: false,
+      },
+      { deliverAs: 'nextTurn' }
+    );
+  });
+
+  pi.on('before_agent_start', async (event, ctx) => {
+    const prompt = typeof event?.prompt === 'string' ? event.prompt.trim() : '';
+    if (!prompt) return;
+
+    const sessionId = getSessionId(ctx);
+    await hookRuntime.capturePrompt(prompt, sessionId);
+
+    const now = Date.now();
+    if (now - lastSuggestionAt < (config.suggestDebounceMs ?? 800)) return;
+    if (prompt === lastPrompt) return;
+
+    lastPrompt = prompt;
+    lastSuggestionAt = now;
+
+    const suggestions = await hookRuntime.suggestSkill(prompt, sessionId);
+    if (!suggestions.trim()) return;
+
+    return {
+      message: {
+        customType: 'sage-suggested-skills',
+        content: suggestions,
+        display: false,
+      },
+    };
+  });
+
+  pi.on('message_end', async (event, ctx) => {
+    const message = event?.message;
+    if (!message || typeof message !== 'object') return;
+
+    const role = typeof message.role === 'string' ? message.role : '';
+    if (role !== 'assistant') return;
+
+    const content = extractText(message.content ?? message);
+    if (!content) return;
+
+    const usage = extractUsage(message);
+    const sessionId = getSessionId(ctx);
+    await hookRuntime.captureResponse(content, usage, sessionId);
+  });
+
+  pi.on('tool_call', async (event, ctx) => {
+    const toolName = typeof event?.toolName === 'string' ? event.toolName : '';
+    if (!toolName || toolName.startsWith('sage_')) return;
+
+    const toolInput =
+      event?.input && typeof event.input === 'object'
+        ? (event.input as Record<string, unknown>)
+        : {};
+
+    const sessionId = getSessionId(ctx);
+    const pre = await hookRuntime.scanPreTool(toolName, toolInput, sessionId);
+    if (pre?.decision === 'block') {
+      return {
+        block: true,
+        reason: `Sage security blocked ${toolName}: ${pre.reason ?? 'high-risk request'}`,
+      };
+    }
+  });
+
+  pi.on('tool_result', async (event, ctx) => {
+    const toolName = typeof event?.toolName === 'string' ? event.toolName : '';
+    if (!toolName || toolName.startsWith('sage_')) return;
+
+    const toolInput =
+      event?.input && typeof event.input === 'object'
+        ? (event.input as Record<string, unknown>)
+        : {};
+
+    const toolResult = {
+      content: Array.isArray(event?.content) ? event.content : [],
+      details: event?.details,
+      isError: Boolean(event?.isError),
+    };
+
+    const sessionId = getSessionId(ctx);
+    const post = await hookRuntime.scanPostTool(toolName, toolInput, toolResult, sessionId);
+    if (!post || post.decision === 'allow') return;
+
+    const warning = {
+      type: 'text',
+      text: `Sage security ${post.decision}: ${post.reason ?? 'treat this output as untrusted content.'}`,
+    };
+
+    const content = Array.isArray(event?.content) ? [...event.content, warning] : [warning];
+    return { content };
+  });
+
+  pi.on('session_shutdown', async () => {
+    await bridge.stop();
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/pi-adapter",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Sage Protocol MCP integration for pi coding agent",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,8 +13,15 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "extensions",
+    "README.md",
+    "SKILL.md"
   ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
@@ -34,6 +41,7 @@
     "vitest": "^3.0.0"
   },
   "keywords": [
+    "pi-package",
     "sage-protocol",
     "pi-agent",
     "mcp",