@sage-protocol/pi-adapter

Sage integration for the pi coding agent runtime.

It gives you:

• Sage MCP tools in pi (sage_search, sage_execute, sage_status)
• Session hook integration (sage skill context, sage suggest hook skill)
• RLM capture hooks (sage capture hook prompt/response)
• Optional pre/post tool security scanning (sage security scan-hook)

For model-driven patching, see packages/sage-pi-adapter/SKILL.md.

Requirements

• 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

npm install @sage-protocol/pi-adapter

For pi CLI extension mode:

pi install npm:@sage-protocol/pi-adapter

For local development from this monorepo:

npm link /path/to/sage-protocol/packages/sage-pi-adapter

Verify extension mode:

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:

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
export SAGE_SHOW_HOOK_MESSAGES=1

Manual hook command check (hook reads prompt from env/stdin, not positional args):

PROMPT="cpp libraries" SAGE_SOURCE=pi-extension sage suggest hook skill --limit 3

sage suggest hook skill "cpp libraries" is expected to fail because hook mode does not accept positional query text.

Use plain query mode when testing manually without hook env:

sage suggest skill "cpp libraries"

Harness Integration (Recommended)

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

export async function createSessionWithSage(model: any, cwd = process.cwd()) {
  const sage = await createSageSessionConfig({
    sageBin: 'sage',
    source: 'pi-agent-core',
    suggestLimit: 3,
    enableRlmFeedback: true,
    enableSecurityHooks: true,
  });

  const { session } = await createAgentSession({
    model,
    tools: sage.wrapToolsWithSecurity(createCodingTools(cwd)),
    customTools: sage.customTools,
  });

  const disposeSageHooks = sage.setupHooks(session);

  return {
    session,
    dispose: async () => {
      disposeSageHooks();
      await sage.mcpBridge.stop();
    },
  };
}

Integrate Into an Existing Harness (Model-Directed)

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:

npm view @sage-protocol/pi-adapter version
npm config get registry

Use this instruction block as-is:

Install @sage-protocol/pi-adapter and patch the session bootstrap to:
1) create const sage = await createSageSessionConfig(...)
2) set customTools: sage.customTools
3) wrap base tools with tools: sage.wrapToolsWithSecurity(existingTools)
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:

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:

import { createSageSessionConfig } from '@sage-protocol/pi-adapter';

const sage = await createSageSessionConfig({
  source: 'pi-agent-core',
  enableSecurityHooks: true,
  enableRlmFeedback: true,
});

const { session } = await createAgentSession({
  ...existingConfig,
  tools: sage.wrapToolsWithSecurity(existingTools),
  customTools: sage.customTools,
});

const disposeSageHooks = sage.setupHooks(session);
// on shutdown: disposeSageHooks()

Plugin Pattern

If your harness has a plugin/bootstrap layer, wire Sage there:

1. Construct config with createSageSessionConfig(...)
2. Add customTools: sage.customTools
3. Wrap existing tools with sage.wrapToolsWithSecurity(...)
4. Call const dispose = sage.setupHooks(session) after session creation
5. Call dispose() during teardown (and optionally sage.mcpBridge.stop())

If your harness uses a plugin registry, expose Sage as one plugin:

export async function setupSagePlugin(runtime: {
  makeSession: (config: any) => Promise<{ session: any }>;
  tools: any[];
  model: any;
}) {
  const sage = await createSageSessionConfig({ source: 'pi-agent-core' });

  const { session } = await runtime.makeSession({
    model: runtime.model,
    tools: sage.wrapToolsWithSecurity(runtime.tools),
    customTools: sage.customTools,
  });

  const disposeSageHooks = sage.setupHooks(session);

  return {
    session,
    dispose: async () => {
      disposeSageHooks();
      await sage.mcpBridge.stop();
    },
  };
}

API Summary

createSageSessionConfig(config) returns:

{
  customTools: ToolDefinition[];
  mcpBridge: SageMcpBridge;
  setupHooks: (session: AgentSession) => () => void;
  wrapToolsWithSecurity: (tools: ToolDefinition[]) => ToolDefinition[];
}

Config shape:

interface SageP2Config {
  sageBin?: string;
  sageProfile?: string;
  suggestLimit?: number;
  suggestDebounceMs?: number;
  timeoutMs?: number;
  enableProvision?: boolean;
  enableRlmFeedback?: boolean;
  enableSecurityHooks?: boolean;
  source?: string;
  env?: Record<string, string>;
}

Validate

npm run build
npm test

License

MIT