remote-pi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Moura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,384 @@
+# Remote Pi
+
+> Extend the [Pi coding agent](https://github.com/earendil-works/pi) with two
+> superpowers: agents that talk to each other on the same machine, and a mobile
+> app that drives Pi from your phone.
+
+`/remote-pi` is a single slash command that wires both at once. Run it; the
+first time it asks a couple of questions and you are done.
+
+---
+
+## Quick start
+
+Install the extension (one-time):
+
+```bash
+pi install npm:@jacobmoura7/remote-pi
+```
+
+Then in any Pi terminal:
+
+```text
+/remote-pi
+```
+
+The first run shows a short interactive wizard (agent name, default session,
+whether to auto-start the relay). On every following run, `/remote-pi` joins
+the local agent session and starts the relay automatically — no extra typing.
+
+### Try the agent network in 30 seconds
+
+Open **two** Pi terminals in the same directory and run `/remote-pi` in each.
+Both join the same session. Now just talk to the LLM — it has the tools.
+
+In terminal A (say it ended up named `agent-A`):
+
+```text
+Who else is connected in our agent session? List them.
+```
+
+The LLM calls `agent_send` to `broker` with `{ type: "list_peers" }` and
+replies with the names it sees.
+
+Then, still in terminal A:
+
+```text
+Send a ping to agent-B and wait for a reply.
+```
+
+Pi calls `agent_request({ to: "agent-B", body: { type: "ping" } })`. The
+message arrives in terminal B as a user-facing turn — terminal B's LLM
+answers, and the reply lands back in terminal A. Two agents, one prompt
+each, full round trip.
+
+(Replace `agent-B` with whatever name terminal B reports for itself — the
+wizard's default is the directory name plus a `#N` suffix on collision.)
+
+---
+
+## What it does
+
+Remote Pi adds two independent layers on top of Pi. You can use either, or
+both:
+
+### 1) Agent network (local, same machine)
+
+Several Pi instances running side-by-side in different terminals can discover
+each other and exchange messages. Each instance is a peer in a named
+*session* and gets two tools the LLM can call directly:
+
+- `agent_send` — fire-and-forget message to another agent
+- `agent_request` — send and await a reply (correlated by message id)
+
+This is purely local: the agents talk over a Unix domain socket at
+`~/.pi/remote/sessions/<session-name>/broker.sock`. No network involved.
+Useful for splitting work across roles (`backend`, `frontend`, `tests`,
+`orchestrator`, …) and letting them coordinate.
+
+The first agent to enter a session becomes the *leader* (hosts the broker);
+the rest are *followers*. If the leader exits, a follower automatically takes
+over — the failover is invisible to the LLMs.
+
+### 2) Mobile app (over the relay)
+
+The companion mobile app lets you send prompts to Pi and read its responses
+from your phone. The phone and the Pi process find each other through a
+**relay**: a small WebSocket server that ferries end-to-end encrypted
+messages between them. Pairing is one-time and per device, via QR code.
+
+Encryption uses Curve25519 key agreement + ChaCha20-Poly1305 (libsodium).
+The relay sees only ciphertext.
+
+App downloads:
+
+- **Google Play** — *coming soon*
+- **App Store** — *coming soon*
+
+Until the public releases land, follow
+[the repo](https://github.com/jacobmoura7/remote-pi) for build/beta info.
+
+---
+
+## Install
+
+Requirements: Node 20+, Pi (the host coding agent).
+
+```bash
+pi install npm:@jacobmoura7/remote-pi
+```
+
+The extension self-registers the `/remote-pi` slash command and deploys an
+agent skill that teaches the LLM how to use `agent_send` / `agent_request`.
+
+To verify:
+
+```text
+/remote-pi config
+```
+
+It should print the effective relay URL and where it came from
+(`env` / `config` / `default`).
+
+---
+
+## Using `/remote-pi`
+
+The bare command is the everyday entry point:
+
+```text
+/remote-pi
+```
+
+Behavior depends on whether there's a local config for this directory:
+
+| State | What happens |
+|---|---|
+| First run (no `.pi/remote-pi/config.json`) | Interactive wizard → saves config → joins agent session → starts relay (if you opted in) |
+| Returning user, auto-start enabled | Joins agent session + starts relay automatically, then prints status |
+| Returning user, auto-start disabled | Prints status only; join/relay must be run manually |
+
+The wizard asks three questions:
+
+1. **Agent name** — how other agents will address you in `agent_send` /
+   `agent_request`. Defaults to the directory name.
+2. **Default session** — the name of the agent-network room for this
+   directory. Multiple terminals in the same directory join the same session.
+3. **Auto-start relay (for mobile app access)?** — `Yes` if you want
+   `/remote-pi` to also connect to the relay so the mobile app can reach this
+   Pi. `No` for local-only use (agent network without mobile access).
+
+Re-run the wizard later with `/remote-pi setup`.
+
+---
+
+## Pairing a mobile device
+
+Once the relay is up (`/remote-pi relay status` shows `started` or `paired`):
+
+```text
+/remote-pi pair
+```
+
+A QR code is printed in the terminal. Scan it with the Remote Pi mobile app.
+Pairing is **per machine** — once a device is paired, every Pi process on
+this machine accepts it (it lives in `~/.pi/remote/peers.json`).
+
+To list paired devices:
+
+```text
+/remote-pi devices
+```
+
+To remove one:
+
+```text
+/remote-pi revoke <shortid>
+```
+
+The shortid is the first 8 chars shown by `devices`.
+
+---
+
+## The relay
+
+The relay is the only network-touching piece of Remote Pi. It does **not**
+read messages — payloads are end-to-end encrypted between the Pi and the
+paired device — but it sees connection metadata: which keypair is online,
+which room/cwd identifiers exist, message timing, sizes.
+
+You have two options:
+
+### Option A — Use the community relay
+
+`wss://relay.remote-pi.dev` (default). Zero setup. Good for trying things
+out or for casual use.
+
+Caveats:
+
+- Shared infrastructure — availability is best-effort.
+- The operator could observe connection metadata as described above.
+- TLS + per-message encryption is the only protection; **there is no IP
+  allow-listing or VPN gating**.
+
+### Option B — Self-host (recommended for privacy)
+
+Run the relay yourself in Docker and put it behind a VPN like
+[Tailscale](https://tailscale.com), [WireGuard](https://www.wireguard.com),
+or your own VPC. Because the relay's network-level protection is just TLS +
+keypair authentication, layering a VPN on top means **only your devices** can
+even reach the WebSocket port — defense in depth.
+
+Quick Docker outline (see the
+[relay README](https://github.com/jacobmoura7/remote-pi/blob/main/relay/README.md#self-hosted-relay-recommended-for-privacy)
+for the full setup, environment variables, and reverse-proxy guidance):
+
+```bash
+docker run -d \
+  --name remote-pi-relay \
+  -p 3000:3000 \
+  --restart unless-stopped \
+  ghcr.io/jacobmoura7/remote-pi-relay:latest
+```
+
+Bind the container to your VPN interface, terminate TLS in a reverse proxy,
+and point both your Pi and your phone at the resulting `wss://…` URL.
+
+### Pointing Pi at your own relay
+
+Once your relay is reachable, tell the extension:
+
+```text
+/remote-pi relay url wss://relay.yourdomain.tld
+```
+
+This writes `~/.pi/remote/config.json` with `{ "relay": "..." }`. Resolution
+order (highest precedence first):
+
+1. `REMOTE_PI_RELAY` environment variable (CI / one-off overrides)
+2. `~/.pi/remote/config.json`
+3. The built-in default (`wss://relay.remote-pi.dev`)
+
+Verify the active URL and its source with:
+
+```text
+/remote-pi config
+```
+
+If you change the URL while connected, run `/remote-pi relay stop` then
+`/remote-pi relay start` (or `/remote-pi relay` to toggle).
+
+The mobile app has its own relay-URL setting in its preferences pane — keep
+both pointing at the same relay.
+
+---
+
+## Agent network: deeper look
+
+Each session is one Unix-domain-socket broker plus N peers. The broker
+multiplexes messages by `to` name and broadcasts system events
+(`peer_joined`, `peer_left`).
+
+Inside the LLM, the agent skill registers two tools:
+
+```jsonc
+// Fire-and-forget
+agent_send({
+  to: "backend",      // peer name (or array for multicast)
+  body: { task: "add /healthz endpoint" },
+  re: "<id>"          // optional — set when replying to a previous request
+})
+
+// Send + await reply (default 30s timeout)
+agent_request({
+  to: "backend",
+  body: { question: "is the migration applied?" }
+})
+```
+
+The wire format is a 5-field envelope `{ from, to, id, re, body }` serialized
+as one JSON line per message. The leader's broker writes an `audit.jsonl`
+log at `~/.pi/remote/sessions/<name>/audit.jsonl` for postmortem inspection.
+
+Useful commands:
+
+| Command | What it does |
+|---|---|
+| `/remote-pi join [name]` | Join (or create) a session — only needed manually if `auto_start_relay=false` |
+| `/remote-pi leave` | Leave the current session |
+| `/remote-pi sessions` | List local sessions and which are live |
+| `/remote-pi rename <new>` | Rename this agent in the current session |
+
+Name collisions inside a session get a numeric suffix automatically
+(`backend`, `backend#2`, `backend#3`). The broker assigns it and returns the
+real name to the peer.
+
+---
+
+## Command reference
+
+| Command | Description |
+|---|---|
+| `/remote-pi` | Connect (join session + start relay), or run setup on first use |
+| `/remote-pi setup` | Run the setup wizard and update local config |
+| `/remote-pi join [name]` | Join (or create) a local agent session |
+| `/remote-pi leave` | Leave the current agent session |
+| `/remote-pi rename <name>` | Rename this agent in the current session |
+| `/remote-pi sessions` | List local agent sessions |
+| `/remote-pi relay` | Toggle the relay connection on/off |
+| `/remote-pi relay start` | Connect to the relay |
+| `/remote-pi relay stop` | Disconnect from the relay |
+| `/remote-pi relay status` | Show current relay status |
+| `/remote-pi relay url <url>` | Set the relay URL (alias of `/remote-pi set-relay`) |
+| `/remote-pi pair` | Show a QR code to pair a new mobile device |
+| `/remote-pi devices` | List paired mobile devices |
+| `/remote-pi revoke <shortid>` | Revoke a paired device by its shortid |
+| `/remote-pi set-relay <url>` | Persist a new relay URL to user config |
+| `/remote-pi config` | Show the effective relay URL and its source |
+
+The footer in the Pi TUI reflects state live:
+
+- `📡 <session> (N)` — current agent session and peer count
+- `🟢 relay` — relay connected, at least one device paired
+- `🟡 relay waiting for pairing` — relay connected, no device paired yet
+- `📱 <shortid>` — a mobile device is actively connected right now
+
+The window title becomes `<agent-name> · <session> · relay` so you can tell
+your terminals apart at a glance.
+
+---
+
+## Configuration files
+
+| Path | Scope | What's in it |
+|---|---|---|
+| `<cwd>/.pi/remote-pi/config.json` | Per-directory | `agent_name`, `session_name`, `auto_start_relay` |
+| `~/.pi/remote/config.json` | Per-user | `relay` URL |
+| `~/.pi/remote/peers.json` | Per-machine | Paired mobile devices |
+| `~/.pi/remote/sessions/<name>/` | Per-session | Broker socket + `audit.jsonl` |
+| `~/.pi/remote/skills/agent-network/SKILL.md` | Per-user | Agent skill the LLM reads |
+
+Override the relay for a single run without persisting:
+
+```bash
+REMOTE_PI_RELAY=wss://staging.example.tld pi
+```
+
+---
+
+## Troubleshooting
+
+**Footer says `🟡 relay waiting for pairing` even though I paired a device.**
+The icon reflects whether *any* device has been paired on this machine, not
+whether one is connected right now. If you really have a paired device in
+`/remote-pi devices`, restart Pi — the cache may be stale (fixed in current
+release; report a bug if it recurs).
+
+**Mobile app times out connecting.** Verify the same relay URL is configured
+on both sides. If you self-host behind a VPN, your phone must also be on the
+VPN (Tailscale on iOS/Android works fine).
+
+**`agent_request` keeps timing out.** Default timeout is 30 s. For tasks
+that legitimately take longer, the receiver should reply with `agent_send`
+including `re: "<original-id>"` so the requester can correlate. The skill
+explains this to the LLM automatically.
+
+**Multiple terminals in the same directory.** Supported. They share the same
+agent-network session (UDS broker) and the relay handles each Pi process
+independently. If the relay refuses with `RoomAlreadyOpenError`, stop the
+other terminal first.
+
+---
+
+## Links
+
+- Source: <https://github.com/jacobmoura7/remote-pi>
+- Pi coding agent: <https://github.com/earendil-works/pi>
+- Relay (self-hosting guide): <https://github.com/jacobmoura7/remote-pi/blob/main/relay/README.md>
+- Issues / bugs: <https://github.com/jacobmoura7/remote-pi/issues>
+
+---
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export declare const kDefaultRelayUrl = "wss://relay.remote-pi.dev";
+export type RemotePiConfig = {
+    relay?: string;
+};
+export declare function loadConfig(): RemotePiConfig;
+export declare function saveConfig(patch: Partial<RemotePiConfig>): void;
+export type RelayResolution = {
+    url: string;
+    source: "env" | "config" | "default";
+};
+/**
+ * Resolves the effective relay URL. Precedence:
+ *   1. process.env.REMOTE_PI_RELAY (escape hatch for ops/CI)
+ *   2. ~/.pi/remote/config.json `relay` field (set via /remote-pi set-relay)
+ *   3. kDefaultRelayUrl (production default)
+ */
+export declare function resolveRelayUrl(): RelayResolution;
+export declare function isValidRelayUrl(url: string): boolean;

package/dist/config.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const CONFIG_DIR = path.join(os.homedir(), ".pi", "remote");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export const kDefaultRelayUrl = "wss://relay.remote-pi.dev";
+export function loadConfig() {
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(patch) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const current = loadConfig();
+    const next = { ...current, ...patch };
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2));
+}
+/**
+ * Resolves the effective relay URL. Precedence:
+ *   1. process.env.REMOTE_PI_RELAY (escape hatch for ops/CI)
+ *   2. ~/.pi/remote/config.json `relay` field (set via /remote-pi set-relay)
+ *   3. kDefaultRelayUrl (production default)
+ */
+export function resolveRelayUrl() {
+    const env = process.env["REMOTE_PI_RELAY"];
+    if (env && env.length > 0)
+        return { url: env, source: "env" };
+    const cfg = loadConfig();
+    if (cfg.relay && cfg.relay.length > 0)
+        return { url: cfg.relay, source: "config" };
+    return { url: kDefaultRelayUrl, source: "default" };
+}
+export function isValidRelayUrl(url) {
+    if (!url || (!url.startsWith("ws://") && !url.startsWith("wss://")))
+        return false;
+    try {
+        new URL(url);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAEzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,2BAA2B,CAAC;AAI5D,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACrD,OAAO,MAAwB,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAA8B;IACvD,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;IACtC,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAID;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC9D,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnF,OAAO,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAClF,IAAI,CAAC;QAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AAC5D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * pi-extension — remote-pi slash commands + AgentBridge wiring
+ *
+ * Exported as ExtensionFactory (default export) to be loaded by Pi SDK:
+ *   pi -e $(pwd)/dist/index.js
+ *
+ * State machine:  idle → started → paired
+ *   /remote-pi start   connects to relay (idle → started)
+ *   /remote-pi pair    shows QR for new peers (started, async → paired via auto-listener)
+ *   /remote-pi stop    closes everything (any → idle)
+ *
+ * Pairing (post plano 06 — sem Noise XX):
+ *   App envia inner `pair_request` (id, token, device_name) sobre canal opaco.
+ *   Pi valida o token via qrSession.consumeToken, salva peer em peers.json
+ *   {name, remote_epk, paired_at} e responde com `pair_ok` (ou `pair_error`).
+ *   `ct` é base64(JSON.stringify(inner)) — sem cifra, sem MAC.
+ *
+ * Reconexão de peer conhecido:
+ *   Se uma mensagem chega em estado `started` vinda de um epk presente em
+ *   peers.json, o auto-listener promove direto pra `paired` sem novo
+ *   pair_request, criando o PlainPeerChannel e roteando a mensagem.
+ *
+ * Architecture note — why we don't use AgentBridge directly here:
+ *   AgentBridge.beforeToolCallHook is designed to be passed to createAgentSession().
+ *   Inside an extension Pi already owns the AgentSession, so we can't re-bind
+ *   beforeToolCall after the fact. The equivalent is pi.on("tool_call", …) which
+ *   fires BEFORE execution and supports { block: true }.
+ *   AgentBridge (src/session/agent_bridge.ts) remains the tested, mockable unit
+ *   for integration tests.
+ */
+import type { ExtensionContext, ExtensionFactory } from "@mariozechner/pi-coding-agent";
+import type { ClientMessage, SessionHistoryEvent } from "./protocol/types.js";
+export type RemoteState = "idle" | "started" | "paired";
+type BufferMsg = {
+    role: "user" | "assistant" | "toolResult" | string;
+    content?: unknown;
+    timestamp?: number;
+    toolCallId?: string;
+    toolName?: string;
+    isError?: boolean;
+    usage?: {
+        input?: number;
+        output?: number;
+    };
+};
+/** Test-only override of the message buffer. */
+export declare function _setMessageBufferForTest(msgs: unknown[]): void;
+/** Test-only accessor: returns a defensive copy of the buffer. */
+export declare function _getMessageBufferForTest(): unknown[];
+/** Test-only override of session started timestamp. */
+export declare function _setSessionStartedAtForTest(ts: number | null): void;
+/** Test-only: reset the cached model name (between tests). */
+export declare function _setCurrentModelForTest(name: string | undefined): void;
+/** Test-only: exposes pending reconnect timer state. */
+export declare function _hasPendingReconnect(): boolean;
+/** Exported for tests. */
+export declare function _getState(): RemoteState;
+/**
+ * App-level peer disconnect (relay still up).
+ * Transitions paired → started and re-installs the auto-listener.
+ * Exported so tests can trigger it directly; in production it will be
+ * called when the relay sends a peer-disconnect notification (future).
+ */
+export declare function _onPeerDisconnect(): void;
+declare const extension: ExtensionFactory;
+export default extension;
+export declare function routeClientMessage(msg: ClientMessage, ctx: Pick<ExtensionContext, "abort">): void;
+/**
+ * Maps SDK AgentMessage[] (UserMessage / AssistantMessage / ToolResultMessage)
+ * into the flat SessionHistoryEvent[] shape consumed by the app.
+ *
+ * Caveats (see report): in_reply_to of agent_message is the *last* user_input
+ * id seen in a linear scan — fine for typical conversational flow but not
+ * a perfect reconstruction of multi-turn ordering when tools interleave.
+ * Stable id for user_input is `sync_<timestamp>`.
+ */
+export declare function _mapAgentMessagesToEvents(messages: BufferMsg[]): SessionHistoryEvent[];