@sage-protocol/pi-adapter 0.4.3 → 0.5.1

package/README.md

@@ -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
 
@@ -96,6 +97,13 @@ interface SageP2Config {
   enableRlmFeedback?: boolean;
   enableSecurityHooks?: boolean;
   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 +149,16 @@ git diff --check
 ## License
 
 MIT
+
+## 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/USAGE.md

@@ -84,6 +84,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));
@@ -147,6 +157,17 @@ registration API. Do not put definitions in a `tools` option.
 | `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/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"}