@sage-protocol/pi-adapter 0.3.12 → 0.4.3

package/README.md

@@ -1,24 +1,32 @@
 # @sage-protocol/pi-adapter
 
-Sage integration for the pi coding agent runtime.
+Sage integration for the Pi coding agent runtime.
 
 - **Pi agent**: [earendil-works/pi](https://github.com/earendil-works/pi) — extensible terminal coding harness
-- **Sage Protocol**: [sage-protocol/sage](https://github.com/sage-protocol/sage) — decentralized skill/library layer for AI agents
+- **Compatibility**: tested with Pi `0.84.1`; package peer range `>=0.64.0 <0.85.0`
+- **Sage Protocol**: [sage-protocol/sage](https://github.com/sage-protocol/sage) — decentralized capability/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
+- Exposes Sage MCP tools (`hub_list_servers`, `hub_status`, `hub_session_list`, `hub_start_server`, `hub_stop_server`, `sage_search`, `sage_execute`, `sage_status`, and `sage_behavior`)
+- Lets Pi own skill discovery and loading through native `<available_skills>`, `/skill:<name>`, and full `SKILL.md` reads
+- Injects SessionStart Sage context and shows the loaded library/skill inventory
+- Captures prompts and responses for RLM feedback
+- Observes truthful full native skill loads and writes source- and session-qualified load receipts
+- Exposes `sage_mark_guided_use` in the packaged Pi extension so an agent can bind actually loaded, actually applied skills to the exact prompt capture through Sage's native-use daemon path
+- Preserves optional security hooks and explicit subagent skill resolution
+- Keeps Sage-owned skills under `packages/sage/skills/` and the curated Pi export surface rather than bundling copies in this adapter
+
+The adapter does **not** call `sage suggest hook skill` for each prompt, inject
+`sage-suggested-skills`, or render a suggestion-quality widget. It has no
+suggestion auto-skip or auto-reject lifecycle. Manual `sage suggest skill
+"<task>"` remains available when a person or agent explicitly wants CLI
+ranking, but it is not automatic Pi injection.
 
 ## Install
 
 ```bash
-# pi CLI extension (no source changes)
+# Pi CLI extension (no source changes)
 pi install npm:@sage-protocol/pi-adapter
 
 # SDK embedding
@@ -28,49 +36,95 @@ npm install @sage-protocol/pi-adapter
 ## Quick Start
 
 ```typescript
-import { createAgentSession, createCodingTools } from '@earendil-works/pi-coding-agent';
-import { createSageSessionConfig } from '@sage-protocol/pi-adapter';
+import {
+  createAgentSession,
+  createCodingTools,
+  type ToolDefinition as PiToolDefinition,
+} from '@earendil-works/pi-coding-agent';
+import {
+  createSageSessionConfig,
+  type ToolDefinition as SageToolDefinition,
+} from '@sage-protocol/pi-adapter';
+
+function asPiCustomTools(tools: SageToolDefinition[]): PiToolDefinition[] {
+  // Type-shape compatibility across supported Pi minors; no runtime conversion.
+  return tools as unknown as PiToolDefinition[];
+}
 
 const sage = await createSageSessionConfig({ source: 'pi-agent-core' });
+const cwd = process.cwd();
+const securedTools = sage.wrapToolsWithSecurity(createCodingTools(cwd));
 const { session } = await createAgentSession({
-  tools: sage.wrapToolsWithSecurity(createCodingTools(process.cwd())),
-  customTools: sage.customTools,
+  cwd,
+  noTools: 'builtin',
+  customTools: asPiCustomTools([...securedTools, ...sage.customTools]),
 });
 const disposeSageHooks = sage.setupHooks(session);
 ```
 
+In current Pi, `tools` is a string allowlist. Tool definitions belong in
+`customTools`; `noTools: 'builtin'` prevents duplicate unwrapped built-ins. The
+single helper cast is only the TypeScript peer-version boundary between the
+adapter's cross-minor tool shape and Pi's generic `ToolDefinition`—it does not
+convert anything at runtime.
+
+Pi presents its native skill catalog separately. When a skill applies, load it
+with `/skill:<name>` or read its complete `SKILL.md`, follow the procedure, then
+call `sage_mark_guided_use` only if the loaded procedure actually guided the
+current turn. Loading alone is not use.
+
 ## API
 
 `createSageSessionConfig(config)` returns:
 
 ```typescript
 {
-  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
+  customTools: ToolDefinition[];           // Sage hub and code-mode bridge tools
+  mcpBridge: SageMcpBridge;                 // MCP process lifecycle
+  setupHooks: (session: AgentSession) => () => void;  // SessionStart + capture hooks
+  wrapToolsWithSecurity: (tools: ToolDefinition[]) => ToolDefinition[];
 }
 ```
 
-Config:
+Recommended configuration:
 
 ```typescript
 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>;
+
+  /** @deprecated Low-level legacy suggestion compatibility; ignored by the default Pi path. */
+  suggestLimit?: number;
+  /** @deprecated Low-level legacy suggestion compatibility; ignored by the default Pi path. */
+  suggestDebounceMs?: number;
+  /** @deprecated Low-level legacy suggestion compatibility; ignored by the default Pi path. */
+  enableProvision?: boolean;
 }
 ```
 
+## Migrating to 0.4
+
+Version 0.4 moves Pi skill discovery and loading to Pi's native skill surface.
+The legacy `sageInjectSuggestion(...)` method is retained as a no-op for
+compatibility, and default setup no longer performs automatic suggestions. Do
+not call `sageInjectSuggestion`; use Pi's native skill load flow and call
+`sage_mark_guided_use` after an actually loaded skill guides the current prompt.
+
+The guided-use write requires both the Sage CLI command
+`sage suggest feedback native-use` and daemon capability `native_skill_use_v1`.
+Version 0.4.2 reports which runtime half is stale instead of collapsing either
+case into a generic write failure. It never falls back to weaker suggestion
+feedback. Update the CLI when it lacks the command; update and restart `saged`
+when the daemon lacks the capability. Then retry the same declaration.
+
 ## Docs
 
-- [Usage Guide](./USAGE.md) — env vars, integration modes, project config
+- [Usage Guide](./USAGE.md) — native skill flow, integration modes, env vars
 - [Setup](./docs/setup.md) — install and verify
 - [Developer Guide](./docs/developer.md) — build, test, CI contract
 - [SKILL.md](./SKILL.md) — agent-driven integration skill
@@ -78,8 +132,10 @@ interface SageP2Config {
 ## Validate
 
 ```bash
-npm run build
 npm test
+npm run typecheck
+npm run build
+git diff --check
 ```
 
 ## License

package/SKILL.md

@@ -1,222 +1,199 @@
 # Sage Pi Adapter Integration Skill
 
-Use this skill when a repository uses `@earendil-works/pi-coding-agent` (formerly `@mariozechner/pi-coding-agent`) and needs Sage integrated into its session bootstrap/plugin layer.
+Use this skill when a repository uses `@earendil-works/pi-coding-agent`
+(formerly `@mariozechner/pi-coding-agent`) and needs Sage integrated into its
+session bootstrap or Pi extension layer.
 
-## Preflight (Do This First)
+## Preflight
 
-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.
+1. Verify npm package availability: `npm view @sage-protocol/pi-adapter version`.
+2. Confirm whether the target uses the installed Pi CLI extension or owns a
+   harness bootstrap containing `createAgentSession`.
+3. If source integration is requested but the workspace has no harness source,
+   stop and ask for the harness repo path instead of editing unrelated files.
 
-## 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.
-
-> **Pi upstream:** [earendil-works/pi](https://github.com/earendil-works/pi) — `@earendil-works/pi-coding-agent`
+> **Pi upstream:** [earendil-works/pi](https://github.com/earendil-works/pi)
+>
 > **Sage upstream:** [sage-protocol/sage](https://github.com/sage-protocol/sage)
 
-## Goal
-
-Apply the Sage integration contract exactly:
+## Integration Contract
 
-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`)
- 3. Package name: `@earendil-works/pi-coding-agent` (formerly `@mariozechner/pi-coding-agent`)
+Sage 0.4 uses Pi-native skill ownership:
 
-## Integration Modes (Important)
+- Pi discovers skills from `<available_skills>`.
+- Pi loads a selected procedure through `/skill:<name>` or a complete
+  `SKILL.md` read.
+- The adapter does not call `sage suggest hook skill` for each prompt, inject
+  `sage-suggested-skills`, or infer use from a suggestion.
+- Manual `sage suggest skill "<task>"` remains an explicit CLI ranking tool; it
+  is not automatic Pi injection.
+- The adapter keeps SessionStart Sage context, MCP tools, behaviors, security
+  hooks, prompt/response capture, and explicit subagent resolution.
+- The packaged Pi extension observes truthful complete native loads, writes
+  source- and session-qualified load receipts, and exposes
+  `sage_mark_guided_use` to bind actually applied loaded skills to the exact
+  prompt capture through Sage's native-use daemon path.
+- Pi has no suggestion auto-skip, auto-reject, or suggestion-quality widget
+  lifecycle.
 
-- 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.
+## Integration Modes
 
-## CLI-Only Flow (No Source Edits)
+### Pi CLI Extension
 
 ```bash
 pi install npm:@sage-protocol/pi-adapter
 pi list
 ```
 
-Then restart `pi` and verify `sage_status` is callable.
-
-Bridge health expectation:
-
-- Pi exposes Sage through `sage_search`, `sage_execute`, and `sage_status`.
-- `sage_status` is the user-facing health surface. When the MCP bridge is
-  degraded, surface a readable bridge error and recovery hint instead of silent
-  retry exhaustion.
-- Inside bridge startup/health code, probe low-level MCP (`tools/list` or a
-  minimal Sage MCP call). Do not recursively call the adapter-level
-  `sage_status` tool from inside the bridge.
-- Recovery wording should point at the Sage MCP bridge (`sage mcp start`,
-  restart Pi/Sage bridge) unless the failing path is specifically the daemon.
-
-For project-local monorepo development, prefer an explicit `.pi/settings.json` that
-keeps pi thin and points at the Sage Pi export surface:
-
-```json
-{
-  "packages": [
-    "../packages/sage-pi-adapter",
-    {
-      "source": "../packages/sage-pi-export",
-      "skills": ["skills/*/SKILL.md"],
-      "extensions": [],
-      "prompts": [],
-      "themes": []
-    },
-    {
-      "source": "npm:oh-pi",
-      "extensions": ["!**"]
-    }
-  ],
-  "skills": [
-    "-../.agents/skills/frontend-design/SKILL.md",
-    "-~/.pi/agent/skills/prompt-builder/SKILL.md",
-    "-~/.pi/agent/skills/sage/SKILL.md",
-    "-~/.pi/agent/skills/sage-workflow/SKILL.md"
-  ],
-  "enableSkillCommands": true
-}
-```
-
-This keeps the harness responsible for transport and tool exposure while Sage skills
-and libraries own the routing and behavior layer.
-
-The package-filtered `../packages/sage-pi-export` entry is intentional: it exposes a Pi-safe,
-curated Sage surface without scanning broad runtime roots such as `~/.local/share/sage/skills`,
-which often contain backup directories, version snapshots, and third-party installs that are valid
-for Sage runtime use but noisy for Pi skill validation.
-
-Architectural posture:
-
-- pi/OpenClaw = transport and tool surface
-- `sage` = router and tool-aware base skill
-- repo-authored entrypoint definitions = authoring layer
-- on-chain libraries = shared distribution and sync/pull layer
-- local sync = development convenience
-
-The entrypoint layer should stay thin. It should dispatch into stable Sage-owned dependency
-libraries by key, not duplicate them. For example, a review or planning entrypoint can route into
-`code-review`, `ceo-plan-review`, or `vc-office-hours` from `sage-review-foundations` without
-copying those skill bodies.
-
-Pi export surface rule:
-
-- author real skills under `packages/sage/skills/`
-- declare Pi-visible skills in `packages/sage/pi-export.manifest.json`
-- materialize the Pi-safe surface with `node scripts/util/sync-sage-pi-export.mjs`
-- point `.pi/settings.json` at `../packages/sage-pi-export`, not at the raw authoring tree
+Restart Pi and verify that `sage_status` is callable. Pi's native skill catalog
+and `/skill:<name>` command own skill discovery and loading.
 
-Hook command semantics:
-
-- `sage suggest hook skill` reads prompt from env/stdin (for IDE/agent hooks)
-- It does not accept positional query text
-- Manual query testing uses `sage suggest skill "..."`
-
-## Required Patch Pattern
+### Source-Owned Harness
 
 ```ts
-import { createSageSessionConfig } from '@sage-protocol/pi-adapter';
+import {
+  createAgentSession,
+  createCodingTools,
+  type ToolDefinition as PiToolDefinition,
+} from '@earendil-works/pi-coding-agent';
+import {
+  createSageSessionConfig,
+  type ToolDefinition as SageToolDefinition,
+} from '@sage-protocol/pi-adapter';
+
+function asPiCustomTools(tools: SageToolDefinition[]): PiToolDefinition[] {
+  // Type-shape compatibility across supported Pi minors; no runtime conversion.
+  return tools as unknown as PiToolDefinition[];
+}
 
 const sage = await createSageSessionConfig({
   source: 'pi-agent-core',
   enableSecurityHooks: true,
   enableRlmFeedback: true,
-  suggestLimit: 3,
 });
-
+const cwd = process.cwd();
+const securedTools = sage.wrapToolsWithSecurity(createCodingTools(cwd));
 const { session } = await createAgentSession({
   ...existingConfig,
-  tools: sage.wrapToolsWithSecurity(existingTools),
-  customTools: sage.customTools,
+  cwd,
+  noTools: 'builtin',
+  customTools: asPiCustomTools([...securedTools, ...sage.customTools]),
 });
 
 const disposeSageHooks = sage.setupHooks(session);
 ```
 
-## Plugin Setup (If Harness Uses Plugins)
+Current Pi treats `tools` as a string allowlist. Definitions belong in
+`customTools`, and `noTools: 'builtin'` avoids registering an unwrapped built-in
+set as well. Keep the one cast isolated at the supported Pi peer-version type
+boundary; it is not a runtime conversion.
 
-- 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)
+Wire teardown to `disposeSageHooks()` and, when the harness owns bridge
+lifecycle, `await sage.mcpBridge.stop()`.
 
-## Where to Search
+The packaged extension owns Pi event-level full-load observation and
+`sage_mark_guided_use` registration. A custom SDK host that bypasses it must add
+equivalent Pi event wiring if those extension features are required.
 
-Find patch points with:
+## Native Skill Use Contract
 
-```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
-```
+When a skill applies:
 
-Install in the harness repo root:
+1. Select it from Pi's native `<available_skills>` catalog.
+2. Load its complete procedure with `/skill:<name>` or a full `SKILL.md` read.
+3. Follow the procedure.
+4. Call `sage_mark_guided_use({ skills: ["<loaded-key>"] })` in the same turn
+   only if at least one instruction, constraint, or output structure guided the
+   work.
 
-```bash
-npm install @sage-protocol/pi-adapter
-```
+The declaration is additive for multiple loaded skills. Loading alone is not
+use. Partial reads do not establish a load. Unloaded keys, ambiguous bare
+names, a missing current capture, or a failed daemon write fail closed. The
+adapter attaches the exact Pi session and active prompt capture; agents should
+not invent or copy correlation identifiers. Compaction and session
+replacement clear load eligibility.
 
-If npm lookup fails unexpectedly:
+There is no automatic suggestion settlement in Pi. Do not add skip/reject
+bookkeeping, suggestion-quality annotations, or a suggestion widget.
 
-```bash
-npm config get registry
-npm view @sage-protocol/pi-adapter version
-```
+Captures and native-use feedback stay in Sage's local capture/RLM stores.
+Never copy raw session text directly into a `SKILL.md`; examples must be
+reviewed and sanitized through the capture/example workflow.
+
+## SessionStart, Tools, and Behaviors
+
+Keep these surfaces intact:
 
-## Guardrails
+- SessionStart output from `sage skill context --format pi`
+- `hub_list_servers`, `hub_status`, `hub_session_list`,
+  `hub_start_server`, and `hub_stop_server`
+- `sage_search`, `sage_execute`, and `sage_status`
+- `sage_behavior` controller plans
+- pre/post-tool security hooks
+- explicit subagent skill resolution for subagents that do not inherit Pi's
+  native skill catalog
 
-- 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.
+Bridge health must use low-level MCP probes, not recursively call the
+adapter-level `sage_status` tool. Recovery wording should point to the Sage MCP
+bridge unless the daemon itself is the failing component.
 
-## Copy-Paste Agent Prompt
+## Project-Local Pi Skills
+
+For monorepo development, keep Pi thin and use the curated Pi export surface:
+
+```json
+{
+  "packages": [
+    "../packages/sage-pi-adapter",
+    {
+      "source": "../packages/sage-pi-export",
+      "skills": ["skills/*/SKILL.md"],
+      "extensions": [],
+      "prompts": [],
+      "themes": []
+    }
+  ],
+  "enableSkillCommands": true
+}
+```
 
-```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
+Author real skills under `packages/sage/skills/`, declare Pi-visible entries in
+`packages/sage/pi-export.manifest.json`, and materialize the curated surface
+with `node scripts/util/sync-sage-pi-export.mjs`. Do not point Pi at broad Sage
+runtime roots containing backups, snapshots, and third-party installs.
 
-If the user has harness source access (target repo: pi-mono/packages/coding-agent), patch Sage into bootstrap.
+## Deprecated Compatibility
 
-Preflight:
-1) npm view @sage-protocol/pi-adapter version
-2) npm config get registry
-3) ensure current workspace contains packages/coding-agent
+Do not use `sageInjectSuggestion(...)`; version 0.4 retains it only as a no-op.
+`suggestLimit`, `suggestDebounceMs`, and `enableProvision` remain exported for
+low-level legacy compatibility but are ignored by the default Pi path and
+should not appear in new examples.
 
-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)
+## Where to Patch
 
-Do not change existing model/provider behavior. Run build/tests for touched package and report changed files.
+```bash
+rg "createAgentSession|createCodingTools|customTools|tools:" src packages/coding-agent
+rg "dispose|shutdown|teardown|cleanup" src packages/coding-agent
 ```
 
+Put setup in the bootstrap/plugin path, call it once per session, preserve
+existing model/provider behavior, and do not remove existing tools.
+
 ## Verification Checklist
 
-- `customTools` includes Sage tools
-- Base tools are wrapped with `wrapToolsWithSecurity`
-- `setupHooks(session)` is called once per session
-- Teardown calls `disposeSageHooks()`
-- `sage_status` reports bridge health; broken bridge paths return a structured,
-  user-readable error quickly
-- Build/tests pass for touched repo
+- Pi native `<available_skills>` and `/skill:<name>` remain enabled.
+- No per-prompt `sage suggest hook skill` call or `sage-suggested-skills`
+  injection exists.
+- SessionStart context, MCP tools, behavior plans, security hooks, capture, and
+  explicit subagent resolution remain available.
+- Complete native loads produce source/session-qualified receipts.
+- `sage_mark_guided_use` accepts only actually loaded procedures and uses the
+  exact prompt capture.
+- No suggestion auto-skip/reject or quality widget exists.
+- Teardown disposes hooks and owned bridge lifecycle.
+- Build and tests pass.
 
 ## Source of Truth
 
-For the latest contract and examples, see:
-
-- `packages/sage-pi-adapter/README.md`
+See `packages/sage-pi-adapter/README.md` and `USAGE.md` for the current
+contract and examples.