@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/docs/intercom.md

@@ -30,6 +30,13 @@ a parent. A child uses its main's ID for both. An offline parent does not erase
 sibling membership. Presence updates cannot change the registered group. Legacy
 or remote peers without lineage are standalone mains.
 
+Pi launches a child with both `PI_INTERCOM_ROOT_SESSION_ID` and
+`PI_INTERCOM_PARENT_SESSION_ID` set to its main's exact native ID. With neither
+set, the session is a main. Any other combination (one missing, empty, padded
+with whitespace, or different values) stops the package from loading, so that
+session gets neither delegation nor Intercom. Values are never trimmed into a
+different identity.
+
 ### Identity and targeting
 
 Use a target returned by `list`. Native peer IDs are `pi-` plus the first 32
@@ -43,6 +50,61 @@ when needed to distinguish collisions. A project-filtered peer can still be
 addressed by its known target; a topology-forbidden peer cannot. A hidden peer
 does not leak through duplicate-name ambiguity or disconnect notifications.
 
+### Conditional native context targeting
+
+Ordinary `intercom` names and asks are unchanged. Integrations can negotiate
+guarded-delivery version 1 with the native broker client. Discovery then exposes
+`rootSessionId`, `incarnation`, `guardedDelivery:1` and the optional opaque
+`applicationGuard`. The lifecycle mints the incarnation on native startup, reload
+or session replacement, not on transport reconnect. Peer IDs still belong to
+the broker. Two current mains for one root make guarded sends ambiguous.
+
+A guarded send requires an exact peer ID, a caller-recorded original message ID,
+`expectsReply:false`, and
+`guard:{rootSessionId,peerId,incarnation,applicationGuard}`. The broker checks
+the complete binding before routing; the native recipient checks again before
+initial admission, before its first checkpoint or immediate placement. Children
+are not guarded command targets. Missing capability, stale context, changed
+consent or an ambiguous root fails closed for new admission, never selecting a
+similarly named main. A broker acceptance still does not prove
+recipient admission. Lost responses remain uncertain; no automatic replay is added.
+The supported non-model package client below uses these same native protocols.
+
+Withdrawing the guard stops new admission; it does not cancel already-admitted
+input. The original native session remains the recovery owner after a checkpoint,
+including across reload or process recovery. A fork or new root cannot adopt its
+pending inputs. Native queueing or placement is not proof of model consumption.
+
+An original-main companion uses the existing process-local `pi.events` bus:
+
+- Emit `pi-intercom:context-query` with `{version:1,respond(snapshot)}` for late
+  attachment. Unknown versions return `{error:"unsupported_version"}`.
+- Observe `pi-intercom:context-state` for subsequent lifecycle, connection and
+  application-guard changes. Snapshots contain `version:1`, exact root, optional
+  parent, actual `peerId`, `incarnation`, `connected`, negotiated
+  `guardedDelivery:1|null`, and optional `applicationGuard`. Unavailable identities
+  are null. Query after subscribing; state events are not replayed.
+- Emit `pi-intercom:application-guard` with
+  `{version:1,target:{rootSessionId,peerId,incarnation},revision,respond(result)}`.
+  The companion owns this opaque nonempty string revision; null withdraws it.
+  A stale target returns `{error:"context_changed"}`. It is cleared on context
+  replacement and retained on transport reconnect. This handshake is not consent
+  itself, does not persist a policy, and grants no human-origin authority.
+
+Callbacks are process-local, synchronous observations. They are not socket frames
+or a generic registry. Old owners have no handshake; treat them as unsupported.
+Old brokers do not acknowledge guarded delivery, so updated clients refuse before
+sending. Old ordinary clients and recipients continue using ordinary messages;
+they are not advertised as conditional targets.
+
+Guarded nonblocking messages may include
+`replyHint:{tool,commandId,commandFingerprint?}`. Tool names are validated identifiers and command IDs
+are immutable UUIDs supplied by the sender. An optional lowercase SHA-256
+`commandFingerprint` is opaque to Intercom; its caller owns the fingerprint
+contract. The native message renders a generic
+publication hint separately from an ordinary ask. No product-specific tool is
+hard-coded, no pending ask is created, and a hint does not prove a reply exists.
+
 ## Send, ask, and reply
 
 ```js
@@ -56,7 +118,9 @@ intercom({
 });
 ```
 
-- Default **steer** wakes an idle recipient or reaches busy work at a tool boundary.
+- Default **steer**, for both sends and incoming asks, wakes an idle recipient or
+  reaches busy work at a tool boundary. Print-mode recipients use the same rule;
+  they do not replace an ordinary ask with a canned busy reply.
 - Explicit **queue** defers delivery. Optional `queueMode:"replace"` with a nonempty
   `threadId` coalesces still-staged updates for that thread; messages already handed
   to Pi's native queue cannot be keyed-replaced.
@@ -67,10 +131,13 @@ recipient journal persistence, model consumption, reply, or task completion. A
 lost transport response can be uncertain; do not blindly replay side effects.
 
 `ask` waits for a correlated reply and has a bounded timeout. Prefer `send` unless
-the sender genuinely must remain alive waiting for a decision. A busy peer may
-report that it cannot answer immediately. `reply` uses the active or sole pending
-ask when unambiguous; otherwise specify `replyTo` and the intended sender. Inspect
-`pending` for the exact correlation rather than guessing from text.
+the sender genuinely must remain alive waiting for a decision. If an ordinary ask
+finds a peer advertising `acceptsAsks:false`, the sender still reports `peer_busy`
+without waiting; recipient steering does not claim that a reply has arrived.
+Explicit steer/queue asks retain their bounded correlated wait. `reply` uses the
+active or sole pending ask when unambiguous; otherwise specify `replyTo` and the
+intended sender. Inspect `pending` for the exact correlation rather than guessing
+from text.
 
 This ordinary request/reply mechanism does not recreate the retired durable
 supervisor approval/revival workflow. An expired wait is not an answered question
@@ -99,6 +166,140 @@ identity. Reads settle on response, disconnect, or timeout. Old peers/brokers
 without the capability report unsupported reads instead of receiving unknown
 message frames. Broker correlation does not grant access to another group.
 
+## Native-owned receipts and publication provenance
+
+Receipt reads are non-waking and distinct from `last`. The native client
+negotiates `receiptReads:1` with the broker, which also checks the recipient's
+capability before forwarding `{rootSessionId,messageId}`. Old brokers or owners
+are unavailable, not a reason to send an unknown frame or parse their journals.
+Receipt and last reads share the broker's private token, answering-peer,
+timeout and disconnect owner. A receipt response must match the exact requested
+native root and message ID. No model-facing receipt action is added.
+
+A companion in the original main emits `pi-intercom:provenance-query` on
+`pi.events` with `{version:1,rootSessionId,messageId,respond(result)}`. The loaded
+Intercom owner reads its own readonly native SessionManager and responds
+synchronously with `{receipt}` or `{error}`. Unknown versions, an inactive owner
+or a different root return `publication_unavailable`. An absent checkpoint
+returns `receipt_not_found`, which proves neither no effect nor task success.
+Missing handlers are unsupported; there is no packaged parser fallback.
+
+The version-1 receipt contains the exact root and message ID, original sender
+peer/root/incarnation where recorded, requested delivery, received timestamp,
+checkpoint entry ID, selected guard and publication-hint fields, and
+`textSha256`. That hash is lowercase SHA-256 of the exact raw sender text encoded
+as UTF-8, before banners, hints, or newline/Unicode normalization. It is computed
+independently of the caller's opaque `commandFingerprint`. No input text,
+attachments, thoughts, cwd, model settings or native journal path is returned.
+
+Facts remain separate:
+
+- `checkpointEntryId` observes the original owner's appended delivery record.
+  It is not a per-entry fsync or power-loss durability receipt.
+- `queued` records an observed extension staging checkpoint.
+- `nativeHandoff` records the native-handoff checkpoint, written before calling
+  Pi's send API. It does not prove that call succeeded or the provider accepted
+  input.
+- `placementEntryId` identifies the actual native custom-message entry, or null
+  when no placement was observed. Placement is not semantic model consumption.
+- `discarded` records an explicit discard checkpoint when one exists.
+
+These are historical positive observations, not a claim that an input is still
+queued. Provider-input admission and model consumption remain unknown. Finals,
+settlement and ordinary replies are not fabricated command publications.
+
+Receipt reads inspect the exact original session's journal, including its other
+branches. They retain the immutable original sender after ordinary departure,
+reload, compaction and cold reopen. They never depend on a live pending ask.
+Copied history in a fork/new root cannot attest the original root's checkpoint.
+This is separate from `last`, which remains active-branch-only and keeps pinned
+entry paging semantics.
+
+## Supported non-model client
+
+Install this package as a normal Node.js dependency and import its supported
+subpath. Pi and TypeBox peers are optional; a companion needs neither them nor
+provider credentials. Importing this entry does not load the extension, CLI,
+TUI, session manager, journal parser or model SDK.
+
+```js
+import { connectIntercom } from "@fitchmultz/pi-subagents/intercom-client";
+
+const client = await connectIntercom({
+  spawn: false,
+  session: {
+    name: "my-companion",
+    cwd: process.cwd(),
+    model: "non-model-client", // A registration label, not a model to initialize.
+    rootSessionId: savedSenderRoot,
+    incarnation: savedSenderIncarnation,
+  },
+});
+try {
+  const peers = await client.listSessions();
+  // Join selected consent to one exact advertised main; do not select by name.
+  const target = peers.find((peer) => peer.id === savedTarget.peerId);
+  if (!target) throw new Error("Original target unavailable");
+  const result = await client.send(savedTarget.peerId, {
+    messageId: savedMessageId,
+    text: savedText,
+    expectsReply: false,
+    delivery: "steer",
+    guard: savedTarget, // rootSessionId, peerId, incarnation, applicationGuard
+    replyHint: {
+      tool: "my_publication_tool",
+      commandId: savedCommandId,
+      commandFingerprint: savedCommandFingerprint,
+    },
+  });
+  // result describes broker acceptance, not native or provider admission.
+  const receipt = await client.receipt(savedTarget.peerId, {
+    rootSessionId: savedTarget.rootSessionId,
+    messageId: savedMessageId,
+  });
+  const page = await client.last(savedTarget.peerId, { limit: 16384 });
+  // Keep page.entryId and page.nextOffset for subsequent pages.
+} finally {
+  await client.disconnect();
+}
+```
+
+The example's saved values belong to the caller's immutable command record, not
+to this client. Persist that record and the actual `client.sessionId` before the
+attempt. `requestedId` is optional and can collide; only the returned current
+identity attests this connection. The client creates no ledger, consent, second
+session or model loop. Registration does not grant human-origin authority.
+
+`connectIntercom` requires literal `spawn:false` and never starts a missing or
+old broker. It uses the normal same-user namespace or the caller's explicit
+`PI_INTERCOM_RUNTIME_DIR`; it does not change global Pi configuration or infer a
+fallback namespace. Connection failure rejects. `sendTimeoutMs` and
+`listTimeoutMs` bound native requests; optional `onError(error)` observes socket
+errors. Outstanding operations reject on loss. `isConnected()` and `sessionId`
+report current transport state, not recipient activity or successful work.
+`disconnect()` closes this socket and joins its cleanup; reconnect explicitly
+with a new `connectIntercom` call. There are no reconnect or resend timers.
+
+Public sends require an original message ID, explicit delivery, `expectsReply:false`
+and the complete exact guard. Concurrent sends with one pending ID reject rather
+than replacing its acknowledgement waiter. Invalid inputs, old capability
+negotiation, stale consent/context and ambiguous roots never downgrade to an
+ordinary send. The generic hint and opaque fingerprint are optional native
+metadata, not an ordinary ask or a guaranteed reply.
+
+After any unconfirmed send, keep the original ID and target. Reconcile only with
+`receipt`; never generate another UUID, reroute or assume that missing means
+unsent. A later explicit new operation is the caller's decision, not an automatic
+retry. Receipt facts retain the original sender after departure. Unsupported old
+brokers or owners fail closed; `publication_unavailable` and `receipt_not_found`
+do not establish no effects. `last` is separately non-waking and pinned by entry
+ID; it is not a correlated command reply. Ordinary local Intercom name resolution,
+asks and topology are unchanged.
+
+Only `./intercom-client` and `./package.json` are public package subpaths.
+Private transport, broker, extension and parser paths are not supported imports.
+The Pi resource manifest still loads its compiled extension independently.
+
 ## Persistence and lifecycle
 
 Inbound state is checkpointed in the recipient's native session journal. Native
@@ -107,6 +308,19 @@ Queued, admitted, consumed, and replied are distinct states. Reload, compaction,
 branch changes, shutdown, and fresh-process recovery must not fabricate receipts
 or adopt another native session's pending messages.
 
+An already-admitted message ID cannot publish a second copy or revive an answered
+ask. The same applies to replies received by a blocking ask and to deliberately
+replaced/discarded queued messages, including native journal restoration. A new ID
+is a new input even if its text is identical. This recipient-side deduplication is
+not an end-to-end exactly-once guarantee for arbitrary tool side effects.
+
+Idle recovery preserves admission order within the non-passive backlog and wakes
+once on its last item; passive breadcrumbs are appended before that waking work.
+The first eligible ask remains the implicit reply target, independently of which
+message triggers the turn. A busy recipient's steer is handed to Pi's native
+queue and consumed at its next tool boundary; no extension probe asks another
+tool to give up the turn.
+
 Shutdown joins admitted inbound work before detaching its native owner. Stale
 runtime generations must not checkpoint or deliver into a replacement session.
 The native tests own these contracts; neither a timer nor a source-string test is
@@ -120,9 +334,16 @@ Default files on macOS/Linux:
 - `/tmp/pi-intercom-<uid>/broker.pid`
 - `/tmp/pi-intercom-<uid>/broker.spawn.lock`
 
+Native Android/Termux uses `$PREFIX/tmp/pi-intercom-<uid>` instead of `/tmp`.
+This is shared across the app's sessions, not derived from a session's HOME,
+agent directory, or TMPDIR. Android without a Termux PREFIX uses Node's native
+temporary directory. The separate read-only child observation endpoints use
+the same runtime-root policy.
+
 The runtime directory is owned by the OS user, nonsymlink, and mode 0700; the
 socket is mode 0600. The broker starts on first use and exits after five seconds
-without connected sessions. Concurrent startup uses the shared spawn lock.
+without connected sessions, unless a parked child still holds admitted input; that
+input waits for its main to return and wake the child. Concurrent startup uses the shared spawn lock.
 
 `PI_INTERCOM_RUNTIME_DIR` explicitly selects an isolated deployment. It must be
 an absolute private directory with a socket path within 100 UTF-8 bytes. Invalid
@@ -142,7 +363,7 @@ then verify the expected exact peers from both mains and the helper. The warning
 only detects old brokers for the current agent directory; it cannot certify that
 all old sessions elsewhere have migrated.
 
-The predictable `/tmp` namespace is independent of caller HOME/TMPDIR, which is
+The predictable macOS/Linux `/tmp` namespace is independent of caller HOME/TMPDIR, which is
 needed for same-user discovery across differently configured sessions. A foreign
 user who pre-creates that path can deny availability, but cannot be adopted as the
 broker owner: startup refuses foreign or symlink directories. It must not delete

package/docs/performance.md

@@ -2,8 +2,8 @@
 
 ## Rebuild measurements
 
-The baseline and enforced size ceilings are in
-[the rebuild evidence](single-agent-rebuild.md). `node scripts/measure-size.mjs`
+The baseline is in [the rebuild evidence](single-agent-rebuild.md); the only
+enforced ceiling is the 1 MiB total production bytes. `node scripts/measure-size.mjs`
 measures production source, schemas, generated code and scripts; tests are separate.
 Line/byte reductions are not measurements of latency, resident memory, provider
 cost, or throughput.
@@ -33,9 +33,16 @@ These measure extension factory loading, not interactive startup, completion
 latency, or steady-state memory. The minimum decreased, but the delta is smaller
 than the baseline's observed first-run spread: this small sample is not a general
 speedup claim. The long-lived costs remain explicit: a main reconciles receipts
-on a 200 ms timer, native actors poll their durable command/attachment state, and
-the broker maintains connections/presence. Completed actors stay messageable
-while attached; observed owner detachment ends their lifetime. Native lifecycle
+when watched completion inputs change and stats those inputs each second, native
+actors check their parent each second and scan durable commands on change, and the
+broker maintains connections/presence. Completed actors stay messageable
+while attached; observed owner detachment ends their lifetime. On the fork, when native
+working-session capture and broker parking support are both available, a child
+idle for five minutes parks its exact working state and exits, releasing its
+process and heap. On official Pi, or with an older broker that lacks parking
+support, idle children stay resident. A genuine message or continuation restores that exact
+state at the cost of one cold actor start. No retained measurement quantifies
+the memory released or the wake latency. Native lifecycle
 and live acceptance checks verify disposal/exit, rather than inferring cleanup
 from a timer or package size.
 
@@ -71,6 +78,93 @@ conversation per scan, not for completed idle actors. The open watch polls at
 display lines. Those are display limits, not truncation of the native journal.
 Children and print/RPC sessions do not install the watcher.
 
+### TypeBox host-instance startup (#234)
+
+In runtime-only installs without a resolvable package-local or ancestor TypeBox,
+the extension now uses Pi's aliased/virtual `typebox` and `typebox/value` modules
+in the host. Only detached runners resolve absolute imports from the selected
+host package. The Type/Assert export contracts are unchanged; there is no
+package-local runtime TypeBox dependency.
+
+An isolated Linux x86_64 RPC probe compared `ae4c363713a6c4b75092b5f15927957e915cf050`
+with the same tree plus the conditional imports in `src/agent/typebox.ts`. Both
+full package copies contained compiled `dist` and only the production stream
+dependencies, with no TypeBox/Pi in their own `node_modules` or ancestors. The
+host was the lockfile's official npm Pi 1.4.0, bundled `dist/bundle/cli.js` SHA-256
+`e79626f2dd6f94aa45d30f3fa63cd84319a6eefcd150b353cfaf274366926774`, using
+`/usr/local/bin/node` v24.22.0. This is not a measurement of the maintained fork.
+
+Each fresh process had a private empty HOME/agent/runtime directory, offline
+mode, telemetry disabled, resource discovery disabled, and `PI_TIMING=1`.
+The CLI arguments were `--mode rpc --no-session -ne -ns -np -nc --no-themes
+--approve --offline --tools delegate,agent_runs,intercom -e <package>/dist/index.js
+-e <observer.mjs>`. The observer recorded the active tools and shut down at
+`session_start`; the harness asserted all three tools were registered. No
+subagent or model request was launched. After warming each
+snapshot once, seven A/B rounds alternated execution order (B/A, A/B, ...).
+
+| Metric (median; observed range)            | Before                 | After                  |
+| ------------------------------------------ | ---------------------- | ---------------------- |
+| `dist/index.js` module import, `PI_TIMING` | 241 ms (227–267)       | 86 ms (76–102)         |
+| Whole-process wall clock                   | 730.75 ms (617–754)    | 571.10 ms (546–595)    |
+| Whole-process user + system CPU            | 803.89 ms (771–834)    | 610.57 ms (581–627)    |
+| Peak RSS (`wait4`, MiB)                    | 141.87 (137.50–146.20) | 127.63 (120.89–129.46) |
+
+Individual import times were before `239, 236, 251, 227, 267, 241, 259` ms and
+after `78, 87, 76, 87, 81, 102, 86` ms. The median import dropped 155 ms (64%);
+these are local warm-cache startup observations, not cold-cache, interactive,
+model-latency, or universal performance guarantees. The package smoke separately
+checks host Type/Assert identity through Pi's loader, detached Type/Assert
+identity against the selected host in a production-only install, and actual
+native child execution. The bundled-host identity check rejects the pre-fix
+adapter. Native-loaded development or consumer graphs with independently
+installed or hoisted TypeBox can resolve that copy before Jiti applies aliases;
+this change does not force aliasing in those layouts. Their parent-side adapter
+can now use that copy instead of the host's on-disk copy. Those graphs are outside
+this production-only measurement; the full checkout functional smoke still runs.
+
+### Session attach inventory (#248)
+
+Session attachment no longer scans retained completions before returning. It still
+publishes the same durable process identity and generation before ordinary SDK or
+RPC startup completes. A one-shot recovery scan and explicit reconciliation
+paths perform recovery afterward. Managed launcher attachment remains gated on
+accepted host readiness.
+
+An isolated official Pi 1.4.0 CLI probe on Linux compared current-main source
+`4906e67` with this change. Five alternating pairs switched into a synthetic
+42.6 MB, 5,180-entry journal with 1,000 completed runs. The median wait from the
+switch request through an immediate successful `get_state` response changed from
+755.43 ms to 189.56 ms. The first `agent_runs list` itself became slower because
+it now pays for cold receipt indexing. This is a change to when recovery work
+runs, not an installed macOS or general delegation-latency claim.
+
+The [issue 248 evidence](evidence/issue-248/README.md) includes both waits,
+switch-to-first-tool measurements, ranges, profiler results, exact runtime and
+build identities, reproducible commands, and retained synthetic RPC transcripts.
+
+### Empty-owner idle CPU (#238)
+
+The issue 238 idle ceiling of 30 ms CPU per 10 s still fails against the
+observer-only floor on official Pi 1.4.0 and the maintained fork. No runtime
+change or waiver is claimed. In the sampled configurations, most of the
+increment is a one-shot pair of V8 memory-reducer collections about 8 s after
+`session_start`. An isolated package that only imports `typebox` showed a
+128,968-byte C++ heap reading at `session_start`, followed by the same pair of
+collections. That is consistent with Pi's bundled Jiti 2.7.0 loader compiling it
+through `vm.runInThisContext`, which allocates on the C++ heap. Jiti
+can try a native ESM import first when no transformation is needed, so this is
+not a rule for every extension or host import. That two-line package added
+38–41 ms in the same campaign. Against it,
+the measured `bb38f682` artifact (build `fc084c36`) added 20.7 ms on official
+Pi and 15.0 ms on the fork. Most of that difference is one-shot work right
+after `session_start`, chiefly the intercom broker and owner attachment. In two
+official-host 40 s floor/`0b6da9b` pairs, the later windows of about 10 s each
+stayed within 1.1 ms of the paired floor. There is no fork long run, and this
+is not an indefinite-idle bound. The
+[issue 238 evidence](evidence/issue-238-idle/README.md) has the samples, host
+hashes, native causal chain and limits.
+
 ## Necessary costs
 
 - Native Pi owns context loading and model execution. The extension cannot remove
@@ -84,22 +178,32 @@ Children and print/RPC sessions do not install the watcher.
   with the parent's inference; there is no implicit daily spend limit.
 - Completed answers and inbound messages can enlarge later prompts. Passive
   messages and out-of-band `last` reads do not request model inference.
-- Owner recovery must verify journal publication and process identity. Stat-only
-  caches, elapsed time, and mere queue admission cannot replace those checks.
+- Owner recovery must verify journal publication and process identity. Elapsed
+  time and mere queue admission cannot replace those checks. Completion-receipt
+  and child-usage indexes parse physical LF-published bytes. For native v3
+  journals, same-inode growth follows the native append-only writer contract and
+  reads from the previous LF boundary; it does not revalidate old bytes. An outside
+  edit to old bytes followed by an append on the same inode between observations
+  is outside that contract. Changed-stamp same-size edits, shrink, inode replacement,
+  and legacy/unclassified headers rebuild the index. Failed scans discard cached
+  state. Native load-time migration is covered separately: official Pi 1.4.0
+  rewrites in place, whereas fork core `7bc005fa` replaces the inode atomically.
 - Paged output bounds each response, not all storage or history work. Keep the
   returned cursor/offset when reading large responses rather than assuming a
   preview is the full result.
 
 ## Accounting
 
-Native child journals are the underlying execution record. Parent attribution
-must use finalized native tool-result usage receipts, excluding inherited launch
-baseline entries and already attributed child contributions. Read-only inspection
-and custom completion notifications are not finalized nested-model charges.
-Preparing or discarding a result must not reserve usage as if it were published.
+Native child journals are the underlying execution record. Each child result
+records its direct native contributions once, excluding inherited launch baseline
+entries and contributions already recorded by a predecessor. New calls do not
+attribute child usage to the parent: completion notices, inspection and reload
+are observations, not nested-model charges.
 
-Do not sum a parent's attributed child usage and the same child's journal as two
-independent provider requests. An incomplete accounting record does not erase a
+Historical parent journals can retain child usage forwarded by the retired
+foreground and `wait` collectors. When calculating workflow spend, count shared
+continuation journals once and exclude child contributions already included in
+historical parent tool results. An incomplete accounting record does not erase a
 real completed answer or authorize fabricated usage. Preserve optional reasoning
 and cache fields according to native Pi semantics rather than adding them twice.