@sage-protocol/pi-adapter

Sage integration for the pi coding agent runtime.

• Pi agent: earendil-works/pi — extensible terminal coding harness
• Sage Protocol: sage-protocol/sage — decentralized skill/library layer for AI agents

What It Does

• Sage MCP tools (hub_list_servers, hub_status, hub_session_list, hub_start_server, hub_stop_server, sage_search, sage_execute, sage_status, sage_behavior)
• Compact tool UX — Sage hub/external operations render concise inventory/session/start/search summaries in Pi instead of dumping raw JSON payloads
• Runtime-first hub helpers — common hub runtime flows are Pi-native; admin hub mutations like adding custom servers remain generic sage_execute operations
• Visible skill loading — shows loaded library/skill count at session start
• Dynamic session context — wallet, libraries, and skill routing injected via sage skill context --format pi
• Skill suggestions, RLM capture, and optional security scanning
• Thin harness packaging — Sage-owned skills live under packages/sage/skills/ and the curated Pi export surface, not inside this adapter package

Install

# pi CLI extension (no source changes)
pi install npm:@sage-protocol/pi-adapter

# SDK embedding
npm install @sage-protocol/pi-adapter

Quick Start

import { createAgentSession, createCodingTools } from '@earendil-works/pi-coding-agent';
import { createSageSessionConfig } from '@sage-protocol/pi-adapter';

const sage = await createSageSessionConfig({ source: 'pi-agent-core' });
const { session } = await createAgentSession({
  tools: sage.wrapToolsWithSecurity(createCodingTools(process.cwd())),
  customTools: sage.customTools,
});
const disposeSageHooks = sage.setupHooks(session);

API

createSageSessionConfig(config) returns:

{
  customTools: ToolDefinition[];           // hub_list_servers, hub_status, hub_session_list, hub_start_server, hub_stop_server, sage_search, sage_execute, sage_status, sage_behavior
  mcpBridge: SageMcpBridge;               // MCP process lifecycle
  setupHooks: (session: AgentSession) => () => void;  // hooks + teardown
  wrapToolsWithSecurity: (tools: ToolDefinition[]) => ToolDefinition[]; // security wrap
}

Config:

interface SageP2Config {
  sageBin?: string;           // default: "sage"
  sageProfile?: string;       // Sage config profile
  suggestLimit?: number;      // default: 3
  suggestDebounceMs?: number; // default: 800
  timeoutMs?: number;         // default: 20_000
  enableRlmFeedback?: boolean;
  enableSecurityHooks?: boolean;
  source?: string;            // default: "pi"
  env?: Record<string, string>;
}

Docs

• Usage Guide — env vars, integration modes, project config
• Setup — install and verify
• Developer Guide — build, test, CI contract
• SKILL.md — agent-driven integration skill

Validate

npm run build
npm test

License

MIT