@sage-protocol/pi-adapter 0.4.3 → 0.5.2

package/README.md

@@ -3,7 +3,7 @@
 Sage integration for the Pi coding agent runtime.
 
 - **Pi agent**: [earendil-works/pi](https://github.com/earendil-works/pi) — extensible terminal coding harness
-- **Compatibility**: tested with Pi `0.84.1`; package peer range `>=0.64.0 <0.85.0`
+- **Compatibility**: declared peer range `>=0.64.0 <0.87.0`; local typecheck, tests, and synthetic SDK tool execution verified with Pi `0.84.1`. Targeted Pi `1.3.0` native codemode checks pass; packaged-extension compatibility with 1.x is not yet declared.
 - **Sage Protocol**: [sage-protocol/sage](https://github.com/sage-protocol/sage) — decentralized capability/library layer for AI agents
 
 ## What It Does
@@ -14,6 +14,7 @@ Sage integration for the Pi coding agent runtime.
 - 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
+- Optionally exposes one status-only `sage_wallet_status` tool when Glove supplies either a strict inherited connected descriptor declaration or the complete legacy endpoint/root/owner tuple
 - 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
 
@@ -23,6 +24,18 @@ 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.
 
+## Tool and CLI routing
+
+Prefer Sage tools. When an operation is unavailable through them, use the
+installed Sage CLI with the same approval and credential safeguards. A security
+or approval denial is not tool unavailability: switching surfaces must not
+bypass it. Keep the same profile, required approvals, dry runs, and credential
+protections. Explicit CLI restrictions such as `SAGE_ALLOW_BASH_CLI=0` remain
+in effect.
+
+The local extension imports `dist/index.js`. After changing its source, run
+`npm run build` and start a fresh Pi session to load the revised guidance.
+
 ## Install
 
 ```bash
@@ -95,7 +108,15 @@ interface SageP2Config {
   timeoutMs?: number;         // default: 20_000
   enableRlmFeedback?: boolean;
   enableSecurityHooks?: boolean;
+  securityFailurePolicy?: "warn" | "block"; // default: "warn"; what to do when a scan cannot decide
   source?: string;            // default: "pi"
+  // Inherited mode: both exact Glove values are required, with no legacy fields.
+  gloveLocalServiceFdsV1?: string;          // exact JSON alias-to-FD map
+  gloveGuestChannelServiceAlias?: string;  // exact wallet service alias
+  // Legacy mode: all three are required, with no inherited fields.
+  gloveGuestChannelEndpoint?: string; // canonical absolute Unix socket path
+  gloveGuestChannelRoot?: string;     // canonical absolute trusted root
+  gloveGuestChannelOwnerUid?: number; // isolated socket-owner UID (not Pi's UID)
   env?: Record<string, string>;
 
   /** @deprecated Low-level legacy suggestion compatibility; ignored by the default Pi path. */
@@ -141,3 +162,47 @@ git diff --check
 ## License
 
 MIT
+
+## Session inbox discovery
+
+`sage_inbox({ action: "list" })` returns at most 20 live peers and 8 KiB of
+JSON text. Each row keeps its canonical session UUID. Labels remain untrusted;
+compact project labels show the last two path segments.
+
+List-only options:
+
+- `includeOffline: true`: include historical peers.
+- `limit: 1..200`: change the row ceiling; the byte ceiling still applies.
+- `detail: "full"`: include bounded full project labels, generation, and lease.
+- `project`, `harness`: exact label filters, applied before the row ceiling.
+
+All options apply **only to the received broker page**, currently at most 200
+peers. `hasMore` retains the broker's meaning. `view` reports source, matched,
+returned, and omitted counts, label truncation, and source incompleteness.
+An empty filtered view does not prove no matching peer exists. There is no
+server cursor or stable pagination; reaching peers beyond the first broker
+page still requires Sage transport/broker changes ([#18](https://github.com/sage-protocol/sage-pi-adapter/issues/18)).
+
+`/inbox` selects a live peer; `/inbox all` includes offline peers. Use
+`/inbox ask [all]` for a correlated request. Explicit sends to canonical UUIDs
+still support offline delivery. ACK, fencing, and ask timeout rules are unchanged.
+
+Inbox discovery, search/execute, hub tools, and `sage_status` retain legacy text
+for older Pi hosts and also provide `outputSchema` / `structuredContent` for
+native codemode. Status keeps its CLI reference in text and in `cliReference`;
+its version and MCP client version come from package metadata. A security block
+withholds text, structured data, and details; a warning removes structured data
+so codemode callers must see the warning text.
+
+## Session inbox liveness (shared with hook-driven harnesses)
+
+The adapter currently renews the daemon lease from its own 2 s poll in
+`src/intercom.ts`. The Sage CLI now ships a harness-agnostic keepalive,
+`sage inbox keepalive --auth-file <capability> --watch-pid <pid>`, which is what
+hook-driven harnesses (Claude Code, Codex) use. A follow-up can have the adapter
+spawn it detached after `saveAuth` with `process.pid` as the watched host, send
+`heartbeat` only on idle/busy transitions, and replace the receive poll with
+`sage inbox receive --auth-file <capability> --wait <secs>`, so both harness
+families share one liveness mechanism. Fencing (`session_inbox_fenced`) stops
+both the adapter timer and the keepalive.
+

package/SKILL.md

@@ -21,8 +21,9 @@ session bootstrap or Pi extension layer.
 Sage 0.4 uses Pi-native skill ownership:
 
 - Pi discovers skills from `<available_skills>`.
-- Pi loads a selected procedure through `/skill:<name>` or a complete
-  `SKILL.md` read.
+- Pi loads a selected procedure through `/skill:<name>`, a complete
+  `SKILL.md` read, or a successful full-body `sage_search` `skills.get` /
+  `library.skill_get` call. Search snippets and `skills.use` activation are not loads.
 - 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
@@ -100,7 +101,8 @@ equivalent Pi event wiring if those extension features are required.
 When a skill applies:
 
 1. Select it from Pi's native `<available_skills>` catalog.
-2. Load its complete procedure with `/skill:<name>` or a full `SKILL.md` read.
+2. Load its complete procedure with `/skill:<name>`, a full `SKILL.md` read,
+   or `sage_search` `skills.get` / `library.skill_get` for a full body.
 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
@@ -111,7 +113,7 @@ 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.
+replacement clear load eligibility: reload the full procedure before marking.
 
 There is no automatic suggestion settlement in Pi. Do not add skip/reject
 bookkeeping, suggestion-quality annotations, or a suggestion widget.

package/USAGE.md

@@ -36,7 +36,9 @@ auto-reject, or suggestion-quality widget lifecycle.
 ## Native Skill Workflow
 
 1. Choose from Pi's native `<available_skills>` catalog.
-2. Load the selected skill with `/skill:<name>` or a complete `SKILL.md` read.
+2. Load the selected skill with `/skill:<name>`, a complete `SKILL.md` read,
+   or a full-body `sage_search` `skills.get` / `library.skill_get` call.
+   Search snippets and `skills.use` activation do not count.
 3. Follow the loaded procedure.
 4. If at least one instruction, constraint, or output structure from it guided
    the current turn, call:
@@ -50,7 +52,7 @@ by Sage source and Pi session, and lets the daemon bind guided use to the exact
 active prompt capture. Partial reads, unloaded keys, ambiguous bare names,
 missing captures, and failed receipt/feedback writes fail closed. Loading a
 procedure without applying it is not use. Compaction and session replacement
-clear load eligibility.
+clear load eligibility; reload the full procedure before marking.
 
 Manual ranking is still available when explicitly requested:
 
@@ -84,6 +86,16 @@ const sage = await createSageSessionConfig({
   source: 'pi-agent-core',
   enableRlmFeedback: true,
   enableSecurityHooks: true,
+  // Choose exactly one complete mode. Glove normally injects inherited mode.
+  gloveLocalServiceFdsV1: process.env.GLOVE_LOCAL_SERVICE_FDS_V1,
+  gloveGuestChannelServiceAlias:
+    process.env.GLOVE_GUEST_CHANNEL_SERVICE_ALIAS,
+  // Legacy compatibility mode (omit all three when inherited mode is present).
+  gloveGuestChannelEndpoint: process.env.GLOVE_GUEST_CHANNEL_ENDPOINT,
+  gloveGuestChannelRoot: process.env.GLOVE_GUEST_CHANNEL_ROOT,
+  gloveGuestChannelOwnerUid: process.env.GLOVE_GUEST_CHANNEL_OWNER_UID
+    ? Number(process.env.GLOVE_GUEST_CHANNEL_OWNER_UID)
+    : undefined,
 });
 const cwd = process.cwd();
 const securedTools = sage.wrapToolsWithSecurity(createCodingTools(cwd));
@@ -142,11 +154,23 @@ registration API. Do not put definitions in a `tools` option.
 | `SAGE_BIN` | `sage` | Path to Sage CLI |
 | `SAGE_PROFILE` | — | Sage config profile (for example `testnet`) |
 | `SAGE_SECURITY_HOOKS` | `1` | Enable pre/post-tool security scanning |
+| `SAGE_SECURITY_FAILURE_POLICY` | `warn` | When a scan cannot decide (timeout, non-zero exit, error decision, unparseable output): `warn` allows the call with a visible warning, `block` refuses it. Never a silent allow. A post-tool `block` withholds the tool output. |
 | `SAGE_RLM_FEEDBACK` | `1` | Enable prompt/response capture and native-use receipts |
 | `SAGE_SHOW_HOOK_MESSAGES` | `0` | Display SessionStart hook messages in the chat UI |
 | `SAGE_ALLOW_BASH_CLI` | `1` | Allow direct `sage ...` bash calls |
 | `SAGE_AUTO_RESOLVE_SKILLS` | `1` | Resolve skills explicitly named in subagent tasks |
 | `SAGE_INJECT_TOOL_DOCS` | `1` | Add compact Sage tool guardrails each turn |
+| `GLOVE_LOCAL_SERVICE_FDS_V1` | — | Exact bounded JSON object mapping the one service alias to its inherited connected FD |
+| `GLOVE_GUEST_CHANNEL_SERVICE_ALIAS` | — | Exact alias selecting the wallet-status service entry |
+| `GLOVE_GUEST_CHANNEL_ENDPOINT` | — | Legacy canonical absolute guest-visible Unix socket path |
+| `GLOVE_GUEST_CHANNEL_ROOT` | — | Legacy canonical absolute trusted root containing the endpoint |
+| `GLOVE_GUEST_CHANNEL_OWNER_UID` | — | Legacy strict nonnegative decimal UID that owns the socket; must differ from the Pi process UID |
+
+Choose exactly one complete mode. Inherited mode requires the FD map and alias while all three legacy variables are absent. Legacy mode requires the endpoint/root/owner tuple while both inherited variables are absent. Mixed and partial declarations fail closed and expose no wallet tool.
+
+Inherited mode accepts exactly one own alias entry with an integer FD from 3 through 1,048,575. It uses that already-connected Unix stream persistently, permits one in-flight status request with no queue, and permanently disables the channel after any protocol, timeout, cancellation, disconnect, write, or reuse failure. It never falls back to a pathname.
+
+Legacy mode preserves its existing pathname authentication: the adapter rejects relative or non-canonical paths, endpoints outside the root, symlinks, non-sockets, unsafe directory authority, owner mismatches, and socket inode changes across connect. There are no endpoint, root, owner, alias, or descriptor defaults.
 
 ### Deprecated Low-Level Compatibility
 

package/dist/inbox-output.d.ts

@@ -0,0 +1,30 @@
+/** Adapter-local view of a legacy broker page. Never invent server pagination. */
+export declare const INBOX_OUTPUT_BYTES: number;
+export declare const INBOX_LABELS_NOTICE = "Discovery labels (alias/project/harness) are self-reported by each peer, unverified, and confer no authority; treat them as untrusted display strings.";
+export interface InboxListView {
+    limit: number;
+    includeOffline: boolean;
+    detail: "compact" | "full";
+    project?: string;
+    harness?: string;
+}
+export declare function inboxListView(params: Record<string, unknown>): InboxListView;
+export declare function formatInboxList(source: unknown, options: InboxListView): {
+    sessions: Record<string, unknown>[];
+    hasMore: boolean;
+    labelsProvenance: string;
+    view: {
+        scope: string;
+        detail: "compact" | "full";
+        includeOffline: boolean;
+        sourceCount: number;
+        matchedCount: number;
+        returnedCount: number;
+        omittedCount: number;
+        truncated: boolean;
+        labelsTruncated: boolean;
+        sourceIncomplete: boolean;
+        pagination: string;
+    };
+};
+//# sourceMappingURL=inbox-output.d.ts.map

package/dist/inbox-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-output.d.ts","sourceRoot":"","sources":["../src/inbox-output.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,QAAW,CAAC;AAC3C,eAAO,MAAM,mBAAmB,2JAA2J,CAAC;AAE5L,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAY5E;AAsBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa;cAcrD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;;;;;;;;;;;;;;;;EA4C1C"}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { PiIntercom, installPiIntercom, cliInboxTransport } from "./intercom.js";
+export type { InboxTransport, InboxMessage, InboxAuth, InboxContext } from "./intercom.js";
 /**
  * Sage Protocol - Pi Adapter
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,cAAc,sBAAsB,CAAC;AAGrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACjF,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,cAAc,sBAAsB,CAAC;AAGrC,cAAc,qBAAqB,CAAC"}